fix: credential loading

* Enhance ToolRegistry type inference for function parameters

- Add _infer_schema() helper to handle Union types (Union[T, U] and T | U)
- Support Optional[T] and Union[T, None] with correct optional flag
- Infer generic types: list[T] -> array with items schema, dict[K, V] -> object with additionalProperties
- Detect Pydantic BaseModel parameters and use model_json_schema()
- Correctly mark parameters as required/optional based on type annotations
- Add comprehensive test suite covering all type inference scenarios
- Maintain backward compatibility for unannotated parameters

* Fix asyncio.run crash in GraphBuilder.run_test

* Revert "Enhance ToolRegistry type inference for function parameters"

This reverts commit dacd0fa8b926e01d3f29e7c9b2ff5101b4a52c3b.

.claude/skills/hive-create/SKILL.md

@@ -492,7 +492,7 @@ AskUserQuestion(questions=[{
 - node_id (kebab-case)
 - name
 - description
-- node_type: `"event_loop"` (recommended for all LLM work) or `"function"` (deterministic, no LLM)
+- node_type: `"event_loop"` (the only valid type; use `client_facing: True` for HITL)
 - input_keys (what data this node receives)
 - output_keys (what data this node produces)
 - tools (ONLY tools that exist from Step 1 — empty list if no tools needed)
@@ -852,8 +852,7 @@ cd /home/timothy/oss/hive && PYTHONPATH=exports uv run python -m AGENT_NAME vali
 
 | Type         | tools param             | Use when                                |
 | ------------ | ----------------------- | --------------------------------------- |
-| `event_loop` | `'["tool1"]'` or `'[]'` | LLM-powered work with or without tools  |
-| `function`   | N/A                     | Deterministic Python operations, no LLM |
+| `event_loop` | `'["tool1"]'` or `'[]'` | All agent work (with or without tools, HITL via client_facing) |
 
 ---
 
@@ -1008,7 +1007,7 @@ Use this reference during STEP 2 to give accurate, honest assessments.
 | Sub-second responses | LLM latency is inherent | Traditional code, no LLM |
 | Processing millions of items | Context windows and rate limits | Batch processing + sampling |
 | Real-time streaming data | No built-in pub/sub or streaming input | Custom MCP server + agent |
-| Guaranteed determinism | LLM outputs vary | Function nodes for deterministic parts |
+| Guaranteed determinism | LLM outputs vary | Traditional code for deterministic parts |
 | Offline/air-gapped | Requires LLM API access | Local models (not currently supported) |
 | Multi-user concurrency | Single-user session model | Separate agent instances per user |
 

.gitignore

@@ -46,6 +46,7 @@ coverage/
 
 # TypeScript
 *.tsbuildinfo
+vite.config.d.ts
 
 # Python
 __pycache__/

CHANGELOG.md

@@ -0,0 +1,207 @@
+# Release Notes
+
+**Release Date:** February 18, 2026
+**Tag:** v0.5.1
+
+## The Hive Gets a Brain
+
+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.
+
+---
+
+## Highlights
+
+### Hive Coder -- The Agent That Builds Agents
+
+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
+
+# Or escalate from any running agent (TUI)
+Ctrl+E  # or /coder in chat
+```
+
+The Coder ships with:
+
+- **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()`
+
+### Multi-Graph Agent Runtime
+
+`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

CONTRIBUTING.md

@@ -126,6 +126,8 @@ 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:

Makefile

@@ -1,4 +1,4 @@
-.PHONY: lint format check test install-hooks help
+.PHONY: lint format check test install-hooks help frontend-dev frontend-build
 
 help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
@@ -26,3 +26,9 @@ test: ## Run all tests
 install-hooks: ## Install pre-commit hooks
 	uv pip install pre-commit
 	pre-commit 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

README.md

@@ -87,6 +87,11 @@ Use Hive when you need:
 
 ### 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
@@ -119,8 +124,11 @@ hive tui
 # Or run directly
 hive run exports/your_agent_name --input '{"key": "value"}'
 ```
-##  Coding Agent Support
+
+## Coding Agent Support
+
 ### Codex CLI
+
 Hive includes native support for [OpenAI Codex CLI](https://github.com/openai/codex) (v0.101.0+).
 
 1. **Config:** `.codex/config.toml` with `agent-builder` MCP server (tracked in git)
@@ -128,17 +136,19 @@ Hive includes native support for [OpenAI Codex CLI](https://github.com/openai/co
 3. **Launch:** Run `codex` in the repo root, then type `use hive`
 
 Example:
+
 ```
 codex> use hive
 ```
 
-### Opencode 
+### Opencode
+
 Hive includes native support for [Opencode](https://github.com/opencode-ai/opencode).
 
-1. **Setup:** Run the quickstart script 
+1. **Setup:** Run the quickstart script
 2. **Launch:** Open Opencode in the project root.
 3. **Activate:** Type `/hive` in the chat to switch to the Hive Agent.
-4. **Verify:** Ask the agent *"List your tools"* to confirm the connection.
+4. **Verify:** Ask the agent _"List your tools"_ to confirm the connection.
 
 The agent has access to all Hive skills and can scaffold agents, add tools, and debug workflows directly from the chat.
 
@@ -175,7 +185,6 @@ 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.
@@ -268,93 +277,124 @@ See [environment-setup.md](docs/environment-setup.md) for complete setup instruc
 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"]
-        j5["Codex CLI"]
-    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

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

@@ -103,31 +103,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 +124,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 +187,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 +241,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 +268,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 +278,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 +307,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

@@ -73,7 +73,7 @@ To use the agent builder with Claude Desktop or other MCP clients, add this to y
 The MCP server provides tools for:
 - Creating agent building sessions
 - Defining goals with success criteria
-- Adding nodes (llm_generate, llm_tool_use, router, function)
+- Adding nodes (event_loop only)
 - Connecting nodes with edges
 - Validating and exporting agent graphs
 - Testing nodes and full agent graphs

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:
@@ -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/examples/manual_agent.py

@@ -4,8 +4,8 @@ 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:
@@ -16,22 +16,33 @@ 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

@@ -122,7 +122,7 @@ async def example_4_custom_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",
         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"],
@@ -133,7 +133,7 @@ async def example_4_custom_agent_with_mcp_tools():
         node_id="summarizer",
         name="Summarize Results",
         description="Summarize the search results",
-        node_type="llm_generate",
+        node_type="event_loop",
         system_prompt="Summarize the following search results in 2-3 sentences: {search_results}",
         input_keys=["search_results"],
         output_keys=["summary"],

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,621 @@
+"""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=[],
+        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 = []  # Forever-alive: loops until user exits
+
+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": 10,
+    "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=[],
+            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": 10,
+                "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

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

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

@@ -0,0 +1,84 @@
+"""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=[],
+        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/hive_coder/__init__.py

@@ -0,0 +1,44 @@
+"""
+Hive Coder — Native coding agent that builds Hive agent packages.
+
+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 (
+    HiveCoderAgent,
+    conversation_mode,
+    default_agent,
+    edges,
+    entry_node,
+    entry_points,
+    goal,
+    identity_prompt,
+    loop_config,
+    nodes,
+    pause_nodes,
+    terminal_nodes,
+)
+from .config import AgentMetadata, RuntimeConfig, default_config, metadata
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "HiveCoderAgent",
+    "default_agent",
+    "goal",
+    "nodes",
+    "edges",
+    "entry_node",
+    "entry_points",
+    "pause_nodes",
+    "terminal_nodes",
+    "conversation_mode",
+    "identity_prompt",
+    "loop_config",
+    "RuntimeConfig",
+    "AgentMetadata",
+    "default_config",
+    "metadata",
+]

core/framework/agents/hive_coder/__main__.py

@@ -1,16 +1,13 @@
-"""
-CLI entry point for Gmail Inbox Guardian.
-
-Uses AgentRuntime for multi-entry-point support with event-driven triggers.
-"""
+"""CLI entry point for Hive Coder agent."""
 
 import asyncio
 import json
 import logging
 import sys
+
 import click
 
-from .agent import default_agent, GmailInboxGuardianAgent
+from .agent import HiveCoderAgent, default_agent
 
 
 def setup_logging(verbose=False, debug=False):
@@ -28,27 +25,22 @@ def setup_logging(verbose=False, debug=False):
 @click.group()
 @click.version_option(version="1.0.0")
 def cli():
-    """Gmail Inbox Guardian - Event-driven email triage with user-defined rules."""
+    """Hive Coder — Build Hive agent packages from natural language."""
     pass
 
 
-@click.command()
-@click.option("--rules", "-r", type=str, help="Email triage rules in plain language")
-@click.option("--max-emails", "-n", type=int, default=10, help="Max emails per batch")
+@cli.command()
+@click.option("--request", "-r", type=str, required=True, help="What agent to build")
 @click.option("--mock", is_flag=True, help="Run in mock mode")
 @click.option("--quiet", "-q", is_flag=True, help="Only output result JSON")
 @click.option("--verbose", "-v", is_flag=True, help="Show execution details")
 @click.option("--debug", is_flag=True, help="Show debug logging")
-def run(rules, max_emails, mock, quiet, verbose, debug):
-    """Execute inbox triage with the given rules."""
+def run(request, mock, quiet, verbose, debug):
+    """Execute agent building from a request."""
     if not quiet:
         setup_logging(verbose=verbose, debug=debug)
 
-    context = {}
-    if rules:
-        context["rules"] = rules
-    if max_emails:
-        context["max_emails"] = str(max_emails)
+    context = {"user_request": request}
 
     result = asyncio.run(default_agent.run(context, mock_mode=mock))
 
@@ -64,23 +56,18 @@ def run(rules, max_emails, mock, quiet, verbose, debug):
     sys.exit(0 if result.success else 1)
 
 
-cli.add_command(run)
-
-
 @cli.command()
 @click.option("--mock", is_flag=True, help="Run in mock mode")
 @click.option("--verbose", "-v", is_flag=True, help="Show execution details")
 @click.option("--debug", is_flag=True, help="Show debug logging")
 def tui(mock, verbose, debug):
-    """Launch the TUI dashboard for interactive inbox management."""
+    """Launch the TUI dashboard for interactive agent building."""
     setup_logging(verbose=verbose, debug=debug)
 
     try:
         from framework.tui.app import AdenTUI
     except ImportError:
-        click.echo(
-            "TUI requires the 'textual' package. Install with: pip install textual"
-        )
+        click.echo("TUI requires the 'textual' package. Install with: pip install textual")
         sys.exit(1)
 
     from pathlib import Path
@@ -88,15 +75,14 @@ def tui(mock, verbose, debug):
     from framework.llm import LiteLLMProvider
     from framework.runner.tool_registry import ToolRegistry
     from framework.runtime.agent_runtime import create_agent_runtime
-    from framework.runtime.event_bus import EventBus
     from framework.runtime.execution_stream import EntryPointSpec
 
     async def run_with_tui():
-        agent = GmailInboxGuardianAgent()
+        agent = HiveCoderAgent()
 
         agent._tool_registry = ToolRegistry()
 
-        storage_path = Path.home() / ".hive" / "agents" / "gmail_inbox_guardian"
+        storage_path = Path.home() / ".hive" / "agents" / "hive_coder"
         storage_path.mkdir(parents=True, exist_ok=True)
 
         mcp_config_path = Path(__file__).parent / "mcp_servers.json"
@@ -122,30 +108,10 @@ def tui(mock, verbose, debug):
             entry_points=[
                 EntryPointSpec(
                     id="start",
-                    name="Rule Setup",
-                    entry_node="intake",
+                    name="Build Agent",
+                    entry_node="coder",
                     trigger_type="manual",
-                    isolation_level="shared",
-                ),
-                EntryPointSpec(
-                    id="email-event",
-                    name="Email Event Handler",
-                    entry_node="fetch-emails",
-                    trigger_type="event",
-                    trigger_config={
-                        "event_types": ["webhook_received"],
-                    },
-                    isolation_level="shared",
-                    max_concurrent=10,
-                ),
-                EntryPointSpec(
-                    id="email-timer",
-                    name="Scheduled Inbox Check",
-                    entry_node="fetch-emails",
-                    trigger_type="timer",
-                    trigger_config={"interval_minutes": 20},
-                    isolation_level="shared",
-                    max_concurrent=1,
+                    isolation_level="isolated",
                 ),
             ],
             llm=llm,
@@ -178,7 +144,7 @@ def info(output_json):
         click.echo(f"\nNodes: {', '.join(info_data['nodes'])}")
         click.echo(f"Client-facing: {', '.join(info_data['client_facing_nodes'])}")
         click.echo(f"Entry: {info_data['entry_node']}")
-        click.echo(f"Terminal: {', '.join(info_data['terminal_nodes'])}")
+        click.echo(f"Terminal: {', '.join(info_data['terminal_nodes']) or '(forever-alive)'}")
 
 
 @cli.command()
@@ -200,7 +166,7 @@ def validate():
 @cli.command()
 @click.option("--verbose", "-v", is_flag=True)
 def shell(verbose):
-    """Interactive inbox guardian session (CLI, no TUI)."""
+    """Interactive agent building session (CLI, no TUI)."""
     asyncio.run(_interactive_shell(verbose))
 
 
@@ -208,43 +174,38 @@ async def _interactive_shell(verbose=False):
     """Async interactive shell."""
     setup_logging(verbose=verbose)
 
-    click.echo("=== Gmail Inbox Guardian ===")
-    click.echo("Define your email triage rules (or 'quit' to exit):\n")
+    click.echo("=== Hive Coder ===")
+    click.echo("Describe the agent you want to build (or 'quit' to exit):\n")
 
-    agent = GmailInboxGuardianAgent()
+    agent = HiveCoderAgent()
     await agent.start()
 
     try:
         while True:
             try:
-                rules = await asyncio.get_event_loop().run_in_executor(
-                    None, input, "Rules> "
-                )
-                if rules.lower() in ["quit", "exit", "q"]:
+                request = await asyncio.get_event_loop().run_in_executor(None, input, "Build> ")
+                if request.lower() in ["quit", "exit", "q"]:
                     click.echo("Goodbye!")
                     break
 
-                if not rules.strip():
+                if not request.strip():
                     continue
 
-                click.echo("\nProcessing inbox...\n")
+                click.echo("\nBuilding agent...\n")
 
-                result = await agent.trigger_and_wait(
-                    "default", {"rules": rules, "max_emails": "10"}
-                )
+                result = await agent.trigger_and_wait("default", {"user_request": request})
 
                 if result is None:
                     click.echo("\n[Execution timed out]\n")
                     continue
 
                 if result.success:
-                    output = result.output
-                    if "summary_report" in output:
-                        click.echo("\n--- Report ---\n")
-                        click.echo(output["summary_report"])
-                        click.echo("\n")
+                    output = result.output or {}
+                    agent_name = output.get("agent_name", "unknown")
+                    validation = output.get("validation_result", "unknown")
+                    click.echo(f"\nAgent '{agent_name}' built. Validation: {validation}\n")
                 else:
-                    click.echo(f"\nProcessing failed: {result.error}\n")
+                    click.echo(f"\nBuild failed: {result.error}\n")
 
             except KeyboardInterrupt:
                 click.echo("\nGoodbye!")

core/framework/agents/hive_coder/agent.py

@@ -0,0 +1,357 @@
+"""Agent graph construction for Hive Coder."""
+
+from pathlib import Path
+
+from framework.graph import Constraint, Goal, 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, metadata
+from .nodes import coder_node, queen_node
+
+# ticket_receiver is no longer needed — the queen runs as an independent
+# GraphExecutor and receives escalation tickets via inject_event().
+# Keeping the import commented for reference:
+# from .ticket_receiver import TICKET_RECEIVER_ENTRY_POINT
+
+# Goal definition
+goal = Goal(
+    id="agent-builder",
+    name="Hive Agent Builder",
+    description=(
+        "Build complete, validated Hive agent packages from natural language "
+        "specifications. Produces production-ready Python packages with goals, "
+        "nodes, edges, system prompts, MCP configuration, and tests."
+    ),
+    success_criteria=[
+        SuccessCriterion(
+            id="valid-package",
+            description="Generated agent package passes structural validation",
+            metric="validation_pass",
+            target="true",
+            weight=0.30,
+        ),
+        SuccessCriterion(
+            id="complete-files",
+            description=(
+                "All required files generated: agent.py, config.py, "
+                "nodes/__init__.py, __init__.py, __main__.py, mcp_servers.json"
+            ),
+            metric="file_count",
+            target=">=6",
+            weight=0.25,
+        ),
+        SuccessCriterion(
+            id="user-satisfaction",
+            description="User reviews and approves the generated agent",
+            metric="user_approval",
+            target="true",
+            weight=0.25,
+        ),
+        SuccessCriterion(
+            id="framework-compliance",
+            description=(
+                "Generated code follows framework patterns: STEP 1/STEP 2 "
+                "for client-facing, correct imports, entry_points format"
+            ),
+            metric="pattern_compliance",
+            target="100%",
+            weight=0.20,
+        ),
+    ],
+    constraints=[
+        Constraint(
+            id="dynamic-tool-discovery",
+            description=(
+                "Always discover available tools dynamically via "
+                "discover_mcp_tools before referencing tools in agent designs"
+            ),
+            constraint_type="hard",
+            category="correctness",
+        ),
+        Constraint(
+            id="no-fabricated-tools",
+            description="Only reference tools that exist in hive-tools MCP",
+            constraint_type="hard",
+            category="correctness",
+        ),
+        Constraint(
+            id="valid-python",
+            description="All generated Python files must be syntactically correct",
+            constraint_type="hard",
+            category="correctness",
+        ),
+        Constraint(
+            id="self-verification",
+            description="Run validation after writing code; fix errors before presenting",
+            constraint_type="hard",
+            category="quality",
+        ),
+    ],
+)
+
+# Nodes: primary coder node only.  The queen runs as an independent
+# GraphExecutor with queen_node — not as part of this graph.
+nodes = [coder_node]
+
+# No edges needed — single forever-alive event_loop node
+edges = []
+
+# Graph configuration
+entry_node = "coder"
+entry_points = {"start": "coder"}
+pause_nodes = []
+terminal_nodes = []  # Forever-alive: loops until user exits
+
+# No async entry points needed — the queen is now an independent executor,
+# not a secondary graph receiving events via add_graph().
+async_entry_points = []
+
+# Module-level variables read by AgentRunner.load()
+conversation_mode = "continuous"
+identity_prompt = (
+    "You are Hive Coder, the best agent-building coding agent on the planet. "
+    "You deeply understand the Hive agent framework at the source code level "
+    "and produce production-ready agent packages from natural language. "
+    "You can dynamically discover available framework tools, inspect runtime "
+    "sessions and checkpoints from agents you build, and run their test suites. "
+    "You follow coding agent discipline: read before writing, verify "
+    "assumptions by reading actual code, adhere to project conventions, "
+    "self-verify with validation, and fix your own errors. You are concise, "
+    "direct, and technically rigorous. No emojis. No fluff."
+)
+loop_config = {
+    "max_iterations": 100,
+    "max_tool_calls_per_turn": 20,
+    "max_history_tokens": 32000,
+}
+
+
+# ---------------------------------------------------------------------------
+# Queen graph — runs as an independent persistent conversation in the TUI.
+# Loaded by _load_judge_and_queen() in app.py, 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": 200,
+        "max_tool_calls_per_turn": 10,
+        "max_history_tokens": 32000,
+    },
+)
+
+
+class HiveCoderAgent:
+    """
+    Hive Coder — builds Hive agent packages from natural language.
+
+    Single-node architecture: the coder runs in a continuous while(true) loop.
+    The queen runs as an independent GraphExecutor (loaded by the TUI via
+    _load_judge_and_queen), not as part of this graph.
+    """
+
+    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.async_entry_points = async_entry_points
+        self._graph: GraphSpec | None = None
+        self._agent_runtime: AgentRuntime | None = None
+        self._tool_registry: ToolRegistry | None = None
+        self._storage_path: Path | None = None
+
+    def _build_graph(self) -> GraphSpec:
+        """Build the GraphSpec."""
+        return GraphSpec(
+            id="hive-coder-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,
+            async_entry_points=self.async_entry_points,
+        )
+
+    def _setup(self, mock_mode=False) -> None:
+        """Set up the agent runtime."""
+        self._storage_path = Path.home() / ".hive" / "agents" / "hive_coder"
+        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)
+
+        llm = None
+        if not mock_mode:
+            llm = LiteLLMProvider(
+                model=self.config.model,
+                api_key=self.config.api_key,
+                api_base=self.config.api_base,
+            )
+
+        tool_executor = self._tool_registry.get_executor()
+        tools = list(self._tool_registry.get_tools().values())
+
+        self._graph = self._build_graph()
+
+        checkpoint_config = CheckpointConfig(
+            enabled=True,
+            checkpoint_on_node_start=False,
+            checkpoint_on_node_complete=True,
+            checkpoint_max_age_days=7,
+            async_checkpoint=True,
+        )
+
+        entry_point_specs = [
+            EntryPointSpec(
+                id="default",
+                name="Default",
+                entry_node=self.entry_node,
+                trigger_type="manual",
+                isolation_level="shared",
+            ),
+        ]
+
+        self._agent_runtime = create_agent_runtime(
+            graph=self._graph,
+            goal=self.goal,
+            storage_path=self._storage_path,
+            entry_points=entry_point_specs,
+            llm=llm,
+            tools=tools,
+            tool_executor=tool_executor,
+            checkpoint_config=checkpoint_config,
+            graph_id="hive_coder",
+        )
+
+    async def start(self, mock_mode=False) -> None:
+        """Set up and start the agent runtime."""
+        if self._agent_runtime is None:
+            self._setup(mock_mode=mock_mode)
+        if not self._agent_runtime.is_running:
+            await self._agent_runtime.start()
+
+    async def stop(self) -> None:
+        """Stop the agent runtime and clean up."""
+        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: str = "default",
+        input_data: dict | None = None,
+        timeout: float | None = None,
+        session_state: dict | None = None,
+    ) -> ExecutionResult | None:
+        """Execute the graph and wait for completion."""
+        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: dict, mock_mode=False, session_state=None) -> ExecutionResult:
+        """Run the agent (convenience method for single execution)."""
+        await self.start(mock_mode=mock_mode)
+        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):
+        """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,
+            "client_facing_nodes": [n.id for n in self.nodes if n.client_facing],
+        }
+
+    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 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 = HiveCoderAgent()

core/framework/agents/hive_coder/config.py

@@ -0,0 +1,51 @@
+"""Runtime configuration for Hive Coder 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) 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 = "Hive Coder"
+    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 Hive Coder — 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/hive_coder/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/hive_coder/nodes/__init__.py

@@ -0,0 +1,721 @@
+"""Node definitions for Hive Coder agent."""
+
+from framework.graph import NodeSpec
+
+# Single node — like opencode's while(true) loop.
+# One continuous context handles the entire workflow:
+# discover → design → implement → verify → present → iterate.
+coder_node = NodeSpec(
+    id="coder",
+    name="Hive Coder",
+    description=(
+        "Autonomous coding agent that builds Hive agent packages. "
+        "Handles the full lifecycle: understanding user intent, "
+        "designing architecture, writing code, validating, and "
+        "iterating on feedback — all in one continuous conversation."
+    ),
+    node_type="event_loop",
+    client_facing=True,
+    max_node_visits=0,
+    input_keys=["user_request"],
+    output_keys=["agent_name", "validation_result"],
+    success_criteria=(
+        "A complete, validated Hive agent package exists at "
+        "exports/{agent_name}/ and passes structural validation."
+    ),
+    system_prompt="""\
+You are Hive Coder, the best agent-building coding agent. You build \
+production-ready Hive agent packages from natural language.
+
+# Core Mandates
+
+- **Read before writing.** NEVER write code from assumptions. Read \
+reference agents and templates first. Read every file before editing.
+- **Conventions first.** Follow existing project patterns exactly. \
+Analyze imports, structure, and style in reference agents.
+- **Verify assumptions.** Never assume a class, import, or pattern \
+exists. Read actual source to confirm. Search if unsure.
+- **Discover tools dynamically.** NEVER reference tools from static \
+docs. Always run list_agent_tools() to see what actually exists.
+- **Professional objectivity.** If a use case is a poor fit for the \
+framework, say so. Technical accuracy over validation.
+- **Concise.** No emojis. No preambles. No postambles. Substance only.
+- **Self-verify.** After writing code, run validation and tests. Fix \
+errors yourself. Don't declare success until validation passes.
+
+# Tools
+
+## File I/O
+- read_file(path, offset?, limit?) — read with line numbers
+- write_file(path, content) — create/overwrite, auto-mkdir
+- edit_file(path, old_text, new_text, replace_all?) — fuzzy-match edit
+- list_directory(path, recursive?) — list contents
+- search_files(pattern, path?, include?) — regex search
+- run_command(command, cwd?, timeout?) — shell execution
+- undo_changes(path?) — restore from git snapshot
+
+## Meta-Agent
+- list_agent_tools(server_config_path?) — list all tool names available \
+for agent building, grouped by category. Call this FIRST before designing.
+- discover_mcp_tools(server_config_path?) — connect to MCP servers \
+and list all available tools with full schemas. Use for parameter details.
+- validate_agent_tools(agent_path) — validate that all tools declared \
+in an agent's nodes actually exist. Call after building.
+- list_agents() — list all agent packages in exports/ with session counts
+- list_agent_sessions(agent_name, status?, limit?) — list sessions
+- get_agent_session_state(agent_name, session_id) — full session state
+- get_agent_session_memory(agent_name, session_id, key?) — memory data
+- list_agent_checkpoints(agent_name, session_id) — list checkpoints
+- get_agent_checkpoint(agent_name, session_id, checkpoint_id?) — load checkpoint
+- run_agent_tests(agent_name, test_types?, fail_fast?) — run pytest with parsing
+
+# Meta-Agent Capabilities
+
+You are not just a file writer. You have deep integration with the \
+Hive framework:
+
+## Tool Discovery (MANDATORY before designing)
+Before designing any agent, run list_agent_tools() to get all \
+available tool names. ONLY use tools from this list in your node \
+definitions. NEVER guess or fabricate tool names from memory.
+
+For full parameter schemas when you need details:
+  discover_mcp_tools()
+
+To check a specific agent's configured tools:
+  list_agent_tools("exports/{agent_name}/mcp_servers.json")
+
+## Agent Awareness
+Run list_agents() to see what agents already exist. Read their code \
+for patterns:
+  read_file("exports/{name}/agent.py")
+  read_file("exports/{name}/nodes/__init__.py")
+
+## Post-Build Testing
+After writing agent code, validate structurally AND run tests:
+  run_command("python -c 'from {name} import default_agent; \\
+    print(default_agent.validate())'")
+  run_agent_tests("{name}")
+
+## Debugging Built Agents
+When a user says "my agent is failing" or "debug this agent":
+1. list_agent_sessions("{agent_name}") — find the session
+2. get_agent_session_state("{agent_name}", "{session_id}") — see status
+3. get_agent_session_memory("{agent_name}", "{session_id}") — inspect data
+4. list_agent_checkpoints / get_agent_checkpoint — trace execution
+
+# Workflow
+
+You operate in a continuous loop. The user describes what they want, \
+you build it. No rigid phases — use judgment. But the general flow is:
+
+## 1. Understand
+
+When the user describes what they want to build, hear the structure:
+- The actors, the trigger, the core loop, the output, the pain.
+
+Play back a model: "Here's what I'm picturing: [concrete picture]. \
+Before I start — [1-2 questions you can't infer]."
+
+Ask only what you CANNOT infer. Fill blanks with domain knowledge.
+
+## 2. Qualify
+
+Assess framework fit honestly. Run list_agent_tools() to check \
+what tools exist. Read the framework guide:
+  read_file("core/framework/agents/hive_coder/reference/framework_guide.md")
+
+Consider:
+- What works well (multi-turn, HITL, tool orchestration)
+- Limitations (LLM latency, context limits, cost)
+- Deal-breakers (missing tools, wrong paradigm)
+
+Give a clear recommendation: proceed, adjust scope, or reconsider.
+
+## 3. Design
+
+Design the agent architecture:
+- Goal: id, name, description, 3-5 success criteria, 2-4 constraints
+- Nodes: **2-4 nodes MAXIMUM** (see rules below)
+- Edges: on_success for linear, conditional for routing
+- Lifecycle: ALWAYS forever-alive (`terminal_nodes=[]`) unless the user \
+explicitly requests a one-shot/batch agent. Forever-alive agents loop \
+continuously — the user exits by closing the TUI. This is the standard \
+pattern for all interactive agents.
+
+### Node Count Rules (HARD LIMITS)
+
+**2-4 nodes** for all agents. Never exceed 4 unless the user explicitly \
+requests more. Each node boundary serializes outputs to shared memory \
+and DESTROYS all in-context information (tool results, reasoning, history).
+
+**MERGE nodes when:**
+- Node has NO tools (pure LLM reasoning) → merge into predecessor/successor
+- Node sets only 1 trivial output → collapse into predecessor
+- Multiple consecutive autonomous nodes → combine into one rich node
+- A "report" or "summary" node → merge into the client-facing node
+- A "confirm" or "schedule" node that calls no external service → remove
+
+**SEPARATE nodes only when:**
+- Client-facing vs autonomous (different interaction models)
+- Fundamentally different tool sets
+- Fan-out parallelism (parallel branches MUST be separate)
+
+**Typical patterns:**
+- 2 nodes: `interact (client-facing) → process (autonomous) → interact`
+- 3 nodes: `intake (CF) → process (auto) → review (CF) → intake`
+- WRONG: 7 nodes where half have no tools and just do LLM reasoning
+
+Read reference agents before designing:
+  list_agents()
+  read_file("exports/deep_research_agent/agent.py")
+  read_file("exports/deep_research_agent/nodes/__init__.py")
+
+Present the design with ASCII art graph. Get user approval.
+
+## 4. Implement
+
+Read templates before writing code:
+  read_file("core/framework/agents/hive_coder/reference/file_templates.md")
+  read_file("core/framework/agents/hive_coder/reference/anti_patterns.md")
+
+Write files in order:
+1. mkdir -p exports/{name}/nodes exports/{name}/tests
+2. config.py — RuntimeConfig + AgentMetadata
+3. nodes/__init__.py — NodeSpec definitions with system prompts
+4. agent.py — Goal, edges, graph, agent class
+5. __init__.py — package exports
+6. __main__.py — CLI with click
+7. mcp_servers.json — tool server config
+8. tests/ — fixtures
+
+### Critical Rules
+
+**Imports** (must match exactly — only import what you use):
+```python
+from framework.graph import (
+    NodeSpec, 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
+```
+For agents with async entry points (timers, webhooks, events), also add:
+```python
+from framework.graph.edge import GraphSpec, AsyncEntryPointSpec
+from framework.runtime.agent_runtime import (
+    AgentRuntime, AgentRuntimeConfig, create_agent_runtime,
+)
+```
+NEVER `from core.framework...` — PYTHONPATH includes core/.
+
+**__init__.py MUST re-export ALL module-level variables** \
+(THIS IS THE #1 SOURCE OF AGENT LOAD FAILURES):
+The runner imports the package (__init__.py), NOT agent.py. It reads \
+goal, nodes, edges, entry_node, entry_points, pause_nodes, \
+terminal_nodes, conversation_mode, identity_prompt, loop_config via \
+getattr(). If ANY are missing from __init__.py, they silently default \
+to None or {} — causing "must define goal, nodes, edges" or "node X \
+is unreachable" errors. The __init__.py MUST import and re-export \
+ALL of these from .agent:
+```python
+from .agent import (
+    MyAgent, default_agent, goal, nodes, edges,
+    entry_node, entry_points, pause_nodes, terminal_nodes,
+    conversation_mode, identity_prompt, loop_config,
+)
+```
+
+**entry_points**: `{"start": "first-node-id"}`
+For agents with multiple entry points (e.g. a reminder trigger), \
+add them: `{"start": "intake", "reminder": "reminder"}`
+
+**conversation_mode** — ONLY two valid values:
+- `"continuous"` — recommended for interactive agents (context carries \
+across node transitions)
+- Omit entirely — for isolated per-node conversations
+NEVER use: "client_facing", "interactive", "adaptive", or any other \
+value. These DO NOT EXIST.
+
+**loop_config** — ONLY three valid keys:
+```python
+loop_config = {
+    "max_iterations": 100,
+    "max_tool_calls_per_turn": 20,
+    "max_history_tokens": 32000,
+}
+```
+NEVER add: "strategy", "mode", "timeout", or other keys.
+
+**mcp_servers.json**:
+```json
+{
+  "hive-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "mcp_server.py", "--stdio"],
+    "cwd": "../../tools"
+  }
+}
+```
+NO "mcpServers" wrapper. cwd "../../tools". command "uv".
+
+**Storage**: `Path.home() / ".hive" / "agents" / "{name}"`
+
+**Client-facing system prompts** — STEP 1/STEP 2 pattern:
+```
+STEP 1 — Present to user (text only, NO tool calls):
+[instructions]
+
+STEP 2 — After user responds, call set_output:
+[set_output calls]
+```
+
+**Autonomous system prompts** — set_output in SEPARATE turn.
+
+**Tools** — NEVER fabricate tool names. Common hallucinations: \
+csv_read, csv_write, csv_append, file_upload, database_query. \
+If list_agent_tools() shows these don't exist, use alternatives \
+(e.g. save_data/load_data for data persistence).
+
+**Node rules**:
+- **2-4 nodes MAX.** Never exceed 4. Merge thin nodes aggressively.
+- A node with 0 tools is NOT a real node — merge it.
+- node_type always "event_loop"
+- max_node_visits default is 0 (unbounded) — correct for forever-alive. \
+Only set >0 in one-shot agents with bounded feedback loops.
+- Feedback inputs: nullable_output_keys
+- terminal_nodes=[] for forever-alive (the default)
+- Every node MUST have at least one outgoing edge (no dead ends)
+- Agents are forever-alive unless user explicitly asks for one-shot
+
+**Agent class**: CamelCase name, default_agent at module level. \
+Constructor takes `config=None`. Follow the exact pattern in \
+file_templates.md — do NOT invent constructor params like \
+`llm_provider` or `tool_registry`.
+
+**Module-level variables** (read by AgentRunner.load()):
+goal, nodes, edges, entry_node, entry_points, pause_nodes,
+terminal_nodes, conversation_mode, identity_prompt, loop_config
+
+For agents with async triggers, also export:
+async_entry_points, runtime_config
+
+**Async entry points** (timers, webhooks, events):
+When an agent needs scheduled tasks, webhook reactions, or event-driven \
+triggers, use `AsyncEntryPointSpec` (from framework.graph.edge) and \
+`AgentRuntimeConfig` (from framework.runtime.agent_runtime):
+- Timer (cron): `trigger_type="timer"`, \
+`trigger_config={"cron": "0 9 * * *"}` — standard 5-field cron expression \
+(e.g. `"0 9 * * MON-FRI"` weekdays 9am, `"*/30 * * * *"` every 30 min)
+- Timer (interval): `trigger_type="timer"`, \
+`trigger_config={"interval_minutes": 20, "run_immediately": False}`
+- Event (for webhooks): `trigger_type="event"`, \
+`trigger_config={"event_types": ["webhook_received"]}`
+- `isolation_level="shared"` so async runs can read primary session memory
+- `runtime_config = AgentRuntimeConfig(webhook_routes=[...])` for HTTP webhooks
+- Reference: `exports/gmail_inbox_guardian/agent.py`
+- Full docs: `core/framework/agents/hive_coder/reference/framework_guide.md` \
+(Async Entry Points section)
+
+## 5. Verify
+
+Run FOUR validation steps after writing. All must pass:
+
+**Step A — Class validation** (checks graph structure):
+```
+run_command("python -c 'from {name} import default_agent; \\
+  print(default_agent.validate())'")
+```
+
+**Step B — Runner load test** (checks package export contract — \
+THIS IS THE SAME PATH THE TUI USES):
+```
+run_command("python -c 'from framework.runner.runner import \\
+  AgentRunner; r = AgentRunner.load(\"exports/{name}\"); \\
+  print(\"AgentRunner.load: OK\")'")
+```
+This catches missing __init__.py exports, bad conversation_mode, \
+invalid loop_config, and unreachable nodes. If Step A passes but \
+Step B fails, the problem is in __init__.py exports.
+
+**Step C — Tool validation** (checks that declared tools actually exist \
+in the agent's MCP servers — catches hallucinated tool names):
+```
+validate_agent_tools("exports/{name}")
+```
+If any tools are missing: fix the node definitions to use only tools \
+that exist. Run list_agent_tools() to see what's available.
+
+**Step D — Run tests:**
+```
+run_agent_tests("{name}")
+```
+
+If anything fails: read error, fix with edit_file, re-validate. Up to 3x.
+
+**CRITICAL: Testing forever-alive agents**
+Most agents use `terminal_nodes=[]` (forever-alive). This means \
+`runner.run()` NEVER returns — it hangs forever waiting for a \
+terminal node that doesn't exist. Agent tests MUST be structural:
+- Validate graph, node specs, edges, tools, prompts
+- Check goal/constraints/success criteria definitions
+- Test `AgentRunner.load()` + `_setup()` (skip if no API key)
+- NEVER call `runner.run()` or `trigger_and_wait()` in tests for \
+forever-alive agents — they will hang and time out.
+When you restructure an agent (change nodes/edges), always update \
+the tests to match. Stale tests referencing old node names will fail.
+
+## 6. Present
+
+Show the user what you built: agent name, goal summary, graph ASCII \
+art, files created, validation status. Offer to revise or build another.
+
+After user confirms satisfaction:
+  set_output("agent_name", "the_agent_name")
+  set_output("validation_result", "valid")
+
+If building another agent, just start the loop again — no need to \
+set_output until the user is done.
+
+## 7. Live Test (optional)
+
+After the user approves, offer to load and run the agent in-session.
+
+If running with a queen (server/frontend):
+```
+load_built_agent("exports/{name}")  # loads as the session worker
+```
+The frontend updates automatically — the user sees the agent's graph, \
+the tab renames, and you can delegate via start_worker(task).
+
+If running standalone (TUI):
+```
+load_agent("exports/{name}")   # registers as secondary graph
+start_agent("{name}")           # triggers default entry point
+```
+""",
+    tools=[
+        "read_file",
+        "write_file",
+        "edit_file",
+        "list_directory",
+        "search_files",
+        "run_command",
+        "undo_changes",
+        # Meta-agent tools
+        "list_agent_tools",
+        "discover_mcp_tools",
+        "validate_agent_tools",
+        "list_agents",
+        "list_agent_sessions",
+        "get_agent_session_state",
+        "get_agent_session_memory",
+        "list_agent_checkpoints",
+        "get_agent_checkpoint",
+        "run_agent_tests",
+        # Graph lifecycle tools (multi-graph sessions)
+        "load_agent",
+        "unload_agent",
+        "start_agent",
+        "restart_agent",
+        "get_user_presence",
+    ],
+)
+
+
+ticket_triage_node = NodeSpec(
+    id="ticket_triage",
+    name="Ticket Triage",
+    description=(
+        "Queen's triage node. Receives an EscalationTicket from the Health Judge "
+        "via event-driven entry point and decides: dismiss or notify the operator."
+    ),
+    node_type="event_loop",
+    client_facing=True,  # Operator can chat with queen once connected (Ctrl+Q)
+    max_node_visits=0,
+    input_keys=["ticket"],
+    output_keys=["intervention_decision"],
+    nullable_output_keys=["intervention_decision"],
+    success_criteria=(
+        "A clear intervention decision: either dismissed with documented reasoning, "
+        "or operator notified via notify_operator with specific analysis."
+    ),
+    tools=["notify_operator"],
+    system_prompt="""\
+You are the Queen (Hive Coder). The Worker Health Judge has escalated a worker \
+issue to you. The ticket is in your memory under key "ticket". Read it carefully.
+
+## Dismiss criteria — do NOT call notify_operator:
+- severity is "low" AND steps_since_last_accept < 8
+- Cause is clearly a transient issue (single API timeout, brief stall that \
+  self-resolved based on the evidence)
+- Evidence shows the agent is making real progress despite bad verdicts
+
+## Intervene criteria — call notify_operator:
+- severity is "high" or "critical"
+- steps_since_last_accept >= 10 with no sign of recovery
+- stall_minutes > 4 (worker definitively stuck)
+- Evidence shows a doom loop (same error, same tool, no progress)
+- Cause suggests a logic bug, missing configuration, or unrecoverable state
+
+## When intervening:
+Call notify_operator with:
+  ticket_id: <ticket["ticket_id"]>
+  analysis: "<2-3 sentences: what is wrong, why it matters, suggested action>"
+  urgency: "<low|medium|high|critical>"
+
+## After deciding:
+set_output("intervention_decision", "dismissed: <reason>" or "escalated: <summary>")
+
+Be conservative but not passive. You are the last quality gate before the human \
+is disturbed. One unnecessary alert is less costly than alert fatigue — but \
+genuine stuck agents must be caught.
+""",
+)
+
+ALL_QUEEN_TRIAGE_TOOLS = ["notify_operator"]
+
+
+queen_node = NodeSpec(
+    id="queen",
+    name="Queen",
+    description=(
+        "User's primary interactive interface with full coding capability. "
+        "Can build agents directly or delegate to the worker. Manages the "
+        "worker agent lifecycle and triages health escalations from the judge."
+    ),
+    node_type="event_loop",
+    client_facing=True,
+    max_node_visits=0,
+    input_keys=["greeting"],
+    output_keys=[],
+    nullable_output_keys=[],
+    success_criteria=(
+        "User's intent is understood, coding tasks are completed correctly, "
+        "and the worker is managed effectively when delegated to."
+    ),
+    tools=[
+        # File I/O (from coder-tools MCP)
+        "read_file",
+        "write_file",
+        "edit_file",
+        "list_directory",
+        "search_files",
+        "run_command",
+        "undo_changes",
+        # Meta-agent (from coder-tools MCP)
+        "discover_mcp_tools",
+        "validate_agent_tools",
+        "list_agents",
+        "list_agent_sessions",
+        "get_agent_session_state",
+        "get_agent_session_memory",
+        "list_agent_checkpoints",
+        "get_agent_checkpoint",
+        "run_agent_tests",
+        # Worker lifecycle
+        "start_worker",
+        "stop_worker",
+        "get_worker_status",
+        "inject_worker_message",
+        # Monitoring
+        "get_worker_health_summary",
+        "notify_operator",
+        # Agent loading
+        "load_built_agent",
+    ],
+    system_prompt="""\
+You are the Queen — the user's primary interface. You are a coding agent \
+with the same capabilities as the Hive Coder worker, PLUS the ability to \
+manage the worker's lifecycle.
+
+# Core Mandates
+
+- **Read before writing.** NEVER write code from assumptions. Read \
+reference agents and templates first. Read every file before editing.
+- **Conventions first.** Follow existing project patterns exactly. \
+Analyze imports, structure, and style in reference agents.
+- **Verify assumptions.** Never assume a class, import, or pattern \
+exists. Read actual source to confirm. Search if unsure.
+- **Discover tools dynamically.** NEVER reference tools from static \
+docs. Always run list_agent_tools() to see what actually exists.
+- **Self-verify.** After writing code, run validation and tests. Fix \
+errors yourself. Don't declare success until validation passes.
+- **Concise.** No emojis. No preambles. No postambles. Substance only.
+
+# Tools
+
+## File I/O
+- read_file(path, offset?, limit?) — read with line numbers
+- write_file(path, content) — create/overwrite, auto-mkdir
+- edit_file(path, old_text, new_text, replace_all?) — fuzzy-match edit
+- list_directory(path, recursive?) — list contents
+- search_files(pattern, path?, include?) — regex search
+- run_command(command, cwd?, timeout?) — shell execution
+- undo_changes(path?) — restore from git snapshot
+
+## Meta-Agent
+- list_agent_tools(server_config_path?) — list all tool names available \
+for agent building, grouped by category. Call this FIRST before designing.
+- discover_mcp_tools(server_config_path?) — connect to MCP servers \
+and list all available tools with full schemas. Use for parameter details.
+- validate_agent_tools(agent_path) — validate that all tools declared \
+in an agent's nodes actually exist. Call after building.
+- list_agents() — list all agent packages in exports/ with session counts
+- list_agent_sessions(agent_name, status?, limit?) — list sessions
+- get_agent_session_state(agent_name, session_id) — full session state
+- get_agent_session_memory(agent_name, session_id, key?) — memory data
+- list_agent_checkpoints(agent_name, session_id) — list checkpoints
+- get_agent_checkpoint(agent_name, session_id, checkpoint_id?) — checkpoint
+- run_agent_tests(agent_name, test_types?, fail_fast?) — run pytest
+
+## Worker Lifecycle
+- start_worker(task) — Start the worker with a task description. The \
+worker runs autonomously until it finishes or asks the user a question.
+- stop_worker() — Cancel the worker's current execution.
+- get_worker_status() — Check if the worker is idle, running, or waiting \
+for user input. Returns execution details.
+- inject_worker_message(content) — Send a message to the running worker. \
+Use this to relay user instructions or concerns.
+
+## Monitoring
+- get_worker_health_summary() — Read the latest health data from the judge.
+- notify_operator(ticket_id, analysis, urgency) — Alert the user about a \
+critical issue. Use sparingly.
+
+## Agent Loading
+- load_built_agent(agent_path) — Load a newly built agent as the worker in \
+this session. Call after building and validating an agent to make it \
+available immediately. The user sees the graph update and can interact \
+with it without leaving the session.
+
+# Behavior
+
+## Direct coding
+You can do any coding task directly — reading files, writing code, running \
+commands, building agents, debugging. For quick tasks, do them yourself.
+
+## Worker delegation
+The worker is a specialized agent (see Worker Profile at the end of this \
+prompt). It can ONLY do what its goal and tools allow.
+
+**Decision rule — read the Worker Profile first:**
+- The user's request directly matches the worker's goal → start_worker(task)
+- Anything else → do it yourself. Do NOT reframe user requests into \
+subtasks to justify delegation.
+- Building, modifying, or configuring agents is ALWAYS your job. Never \
+delegate agent construction to the worker, even as a "research" subtask.
+
+## When idle (worker not running):
+- Greet the user. Mention what the worker can do.
+- For tasks matching the worker's goal, call start_worker(task).
+- For everything else, do it directly.
+
+## When worker is running:
+- If the user asks about progress, call get_worker_status().
+- If the user has a concern or instruction for the worker, call \
+inject_worker_message(content) to relay it.
+- You can still do coding tasks directly while the worker runs.
+- If an escalation ticket arrives from the judge, assess severity:
+  - Low/transient: acknowledge silently, do not disturb the user.
+  - High/critical: notify the user with a brief analysis and suggested action.
+
+## When worker asks user a question:
+- The system will route the user's response directly to the worker. \
+You do not need to relay it. The user will come back to you after responding.
+
+# Agent Building Workflow
+
+When building Hive agent packages, follow this workflow:
+
+## 1. Understand & Qualify
+Hear what the user wants. Run list_agent_tools() to check tool availability. \
+Read the framework guide:
+  read_file("core/framework/agents/hive_coder/reference/framework_guide.md")
+
+## 2. Design
+Design the agent: Goal, 2-4 nodes MAX, edges. Read reference agents:
+  list_agents()
+  read_file("exports/deep_research_agent/nodes/__init__.py")
+
+Present design with ASCII art. Get user approval.
+
+## 3. Implement
+Read templates before writing:
+  read_file("core/framework/agents/hive_coder/reference/file_templates.md")
+
+Write files: config.py, nodes/__init__.py, agent.py, __init__.py, \
+__main__.py, mcp_servers.json, tests/.
+
+## 4. Verify
+Run FOUR validation steps:
+  run_command("python -c 'from {name} import default_agent; print(default_agent.validate())'")
+  run_command("python -c 'from framework.runner.runner import AgentRunner; \\
+    r = AgentRunner.load(\"exports/{name}\"); print(\"OK\")'")
+  validate_agent_tools("exports/{name}")
+  run_agent_tests("{name}")
+
+## 5. Load into Session
+After building and verifying, load the agent into the current session:
+  load_built_agent("exports/{name}")
+This makes the agent available immediately — the user sees its graph, \
+the tab name updates, and you can delegate to it via start_worker(). \
+Do NOT tell the user to run `python -m {name} run` — load it here.
+
+# Style
+
+- Concise. No fluff. Direct.
+- No emojis.
+- When starting the worker, describe what you told it in one sentence.
+- When relaying status, be specific.
+- When an escalation arrives, lead with severity and recommended action.
+""",
+)
+
+ALL_QUEEN_TOOLS = [
+    # File I/O (from coder-tools MCP)
+    "read_file",
+    "write_file",
+    "edit_file",
+    "list_directory",
+    "search_files",
+    "run_command",
+    "undo_changes",
+    # Meta-agent (from coder-tools MCP)
+    "list_agent_tools",
+    "discover_mcp_tools",
+    "validate_agent_tools",
+    "list_agents",
+    "list_agent_sessions",
+    "get_agent_session_state",
+    "get_agent_session_memory",
+    "list_agent_checkpoints",
+    "get_agent_checkpoint",
+    "run_agent_tests",
+    # Worker lifecycle
+    "start_worker",
+    "stop_worker",
+    "get_worker_status",
+    "inject_worker_message",
+    # Monitoring
+    "get_worker_health_summary",
+    "notify_operator",
+    # Agent loading
+    "load_built_agent",
+]
+
+__all__ = [
+    "coder_node",
+    "ticket_triage_node",
+    "queen_node",
+    "ALL_QUEEN_TRIAGE_TOOLS",
+    "ALL_QUEEN_TOOLS",
+]

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

@@ -0,0 +1,107 @@
+# Common Mistakes When Building Hive Agents
+
+## Critical Errors
+
+1. **Using tools that don't exist** — Always verify tools are available in the hive-tools MCP server before assigning them to nodes. Never guess tool names.
+
+2. **Wrong entry_points format** — MUST be `{"start": "first-node-id"}`. NOT a set, NOT `{node_id: [keys]}`.
+
+3. **Wrong mcp_servers.json format** — Flat dict (no `"mcpServers"` wrapper). `cwd` must be `"../../tools"`. `command` must be `"uv"` with args `["run", "python", ...]`.
+
+4. **Missing STEP 1/STEP 2 in client-facing prompts** — Without explicit phases, the LLM calls set_output before the user responds. Always use the pattern.
+
+5. **Forgetting nullable_output_keys** — When a node receives inputs from multiple edges and some inputs only arrive on certain edges (e.g., feedback), mark those as nullable. Without this, the executor blocks waiting for a value that will never arrive.
+
+6. **Creating dead-end nodes in forever-alive graphs** — Every node must have at least one outgoing edge. A node with no outgoing edges ends the execution, breaking the loop.
+
+7. **Setting max_node_visits to a non-zero value in forever-alive agents** — The framework default is `max_node_visits=0` (unbounded). Setting it to any positive value (e.g., 1) means the node stops executing after that many visits, silently breaking the forever-alive loop. Only set `max_node_visits > 0` in one-shot agents with feedback loops that need bounded retries.
+
+7. **Missing module-level exports in `__init__.py`** — The runner loads agents via `importlib.import_module(package_name)`, which imports `__init__.py`. It then reads `goal`, `nodes`, `edges`, `entry_node`, `entry_points`, `pause_nodes`, `terminal_nodes`, `conversation_mode`, `identity_prompt`, `loop_config` via `getattr()`. If ANY of these are missing from `__init__.py`, they default to `None` or `{}` — causing "must define goal, nodes, edges" errors or "node X is unreachable" validation failures. **ALL module-level variables from agent.py must be re-exported in `__init__.py`.**
+
+## Value Errors
+
+8. **Invalid `conversation_mode` value** — Only two valid values: `"continuous"` (recommended for interactive agents) or omit entirely (for isolated per-node conversations). Values like `"client_facing"`, `"interactive"`, `"adaptive"` do NOT exist and will cause runtime errors.
+
+9. **Invalid `loop_config` keys** — Only three valid keys: `max_iterations` (int), `max_tool_calls_per_turn` (int), `max_history_tokens` (int). Keys like `"strategy"`, `"mode"`, `"timeout"` are NOT valid and are silently ignored or cause errors.
+
+10. **Fabricating tools that don't exist** — Never guess tool names. Always verify via `list_agent_tools()` before designing and `validate_agent_tools()` after building. Common hallucinations: `csv_read`, `csv_write`, `csv_append`, `file_upload`, `database_query`, `bulk_fetch_emails`. If a required tool doesn't exist, redesign the agent to use tools that DO exist (e.g., `save_data`/`load_data` for data persistence).
+
+## Design Errors
+
+11. **Too many thin nodes** — Hard limit: **2-4 nodes** for most agents. Each node boundary serializes outputs to shared memory and loses all in-context information (tool results, intermediate reasoning, conversation history). A node with 0 tools that just does LLM reasoning is NOT a real node — merge it into its predecessor or successor.
+
+**Merge when:**
+- Node has NO tools — pure LLM reasoning belongs in the node that produces or consumes its data
+- Node sets only 1 trivial output (e.g., `set_output("done", "true")`) — collapse into predecessor
+- Multiple consecutive autonomous nodes with same/similar tools — combine into one
+- A "report" or "summary" node that just presents analysis — merge into the client-facing node
+- A "schedule" or "confirm" node that doesn't actually schedule anything — remove entirely
+
+**Keep separate when:**
+- Client-facing vs autonomous — different interaction models require separate nodes
+- Fundamentally different tool sets (e.g., web search vs file I/O)
+- Fan-out parallelism — parallel branches MUST be separate nodes
+
+**Bad example** (7 nodes — WAY too many):
+```
+profile_setup → daily_intake → update_tracker → analyze_progress → generate_plan → schedule_reminders → report
+```
+`analyze_progress` has no tools. `schedule_reminders` just sets one boolean. `report` just presents analysis. `update_tracker` and `generate_plan` are sequential autonomous work.
+
+**Good example** (3 nodes):
+```
+intake (client-facing) → process (autonomous: track + analyze + plan) → intake (loop back)
+```
+One client-facing node handles ALL user interaction (setup, logging, reports). One autonomous node handles ALL backend work (CSV update, analysis, plan generation) with tools and context preserved.
+
+12. **Adding framework gating for LLM behavior** — Don't add output rollback, premature rejection, or interaction protocol injection. Fix with better prompts or custom judges.
+
+13. **Not using continuous conversation mode** — Interactive agents should use `conversation_mode="continuous"`. Without it, each node starts with blank context.
+
+14. **Adding terminal nodes by default** — ALL agents should use `terminal_nodes=[]` (forever-alive) unless the user explicitly requests a one-shot/batch agent. Forever-alive is the standard pattern. Every node must have at least one outgoing edge. Dead-end nodes break the loop.
+
+15. **Calling set_output in same turn as tool calls** — Instruct the LLM to call set_output in a SEPARATE turn from real tool calls.
+
+## File Template Errors
+
+16. **Wrong import paths** — Use `from framework.graph import ...`, NOT `from core.framework.graph import ...`. The PYTHONPATH includes `core/`.
+
+17. **Missing storage path** — Agent class must set `self._storage_path = Path.home() / ".hive" / "agents" / "agent_name"`.
+
+18. **Missing mcp_servers.json** — Without this, the agent has no tools at runtime.
+
+19. **Bare `python` command in mcp_servers.json** — Use `"command": "uv"` with args `["run", "python", ...]`.
+
+## Testing Errors
+
+20. **Using `runner.run()` on forever-alive agents** — `runner.run()` calls `trigger_and_wait()` which blocks until the graph reaches a terminal node. Forever-alive agents have `terminal_nodes=[]`, so **`runner.run()` hangs forever**. This is the #1 cause of stuck test suites.
+
+**For forever-alive agents, write structural tests instead:**
+- Validate graph structure (nodes, edges, entry points)
+- Verify node specs (tools, prompts, client-facing flag)
+- Check goal/constraints/success criteria definitions
+- Test that `AgentRunner.load()` + `_setup()` succeeds (skip if no API key)
+
+**What NOT to do:**
+```python
+# WRONG — hangs forever on forever-alive agents
+result = await runner.run({"topic": "quantum computing"})
+```
+
+**Correct pattern for structure tests:**
+```python
+def test_research_has_web_tools(self):
+    assert "web_search" in research_node.tools
+
+def test_research_routes_back_to_interact(self):
+    edges_to_interact = [e for e in edges if e.source == "research" and e.target == "interact"]
+    assert edges_to_interact
+```
+
+21. **Stale tests after agent restructuring** — When you change an agent's node count or names (e.g., 4 nodes → 2 nodes), the tests MUST be updated too. Tests referencing old node names (e.g., `"review"`, `"report"`) will fail or hang. Always check that test assertions match the current `nodes/__init__.py`.
+
+22. **Running full integration tests without API keys** — Structural tests (validate, import) work without keys. Full integration tests need `ANTHROPIC_API_KEY`. Use `pytest.skip()` in the runner fixture when `_setup()` fails due to missing credentials.
+
+23. **Forgetting sys.path setup in conftest.py** — Tests need `exports/` and `core/` on sys.path.
+
+24. **Not using auto_responder for client-facing nodes** — Tests with client-facing nodes hang without an auto-responder that injects input. But note: even WITH auto_responder, forever-alive agents still hang because the graph never terminates. Auto-responder only helps for agents with terminal nodes.

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

@@ -0,0 +1,597 @@
+# 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: Intake (client-facing)
+intake_node = NodeSpec(
+    id="intake",
+    name="Intake",
+    description="Gather requirements from the user",
+    node_type="event_loop",
+    client_facing=True,
+    max_node_visits=0,  # Unlimited for forever-alive
+    input_keys=["topic"],
+    output_keys=["brief"],
+    success_criteria="The brief is specific and actionable.",
+    system_prompt="""\
+You are an intake specialist.
+
+**STEP 1 — Read and respond (text only, NO tool calls):**
+1. Read the topic provided
+2. If vague, ask 1-2 clarifying questions
+3. If clear, confirm your understanding
+
+**STEP 2 — After the user confirms, call set_output:**
+- set_output("brief", "Clear description of what to do")
+""",
+    tools=[],
+)
+
+# Node 2: Worker (autonomous)
+worker_node = NodeSpec(
+    id="worker",
+    name="Worker",
+    description="Do the main work",
+    node_type="event_loop",
+    max_node_visits=0,
+    input_keys=["brief", "feedback"],
+    output_keys=["results"],
+    nullable_output_keys=["feedback"],  # Only on feedback edge
+    success_criteria="Results are complete and accurate.",
+    system_prompt="""\
+You are a worker agent. Given a brief, do the work.
+
+If feedback is provided, this is a follow-up — address the feedback.
+
+Work in phases:
+1. Use tools to gather/process data
+2. Analyze results
+3. Call set_output for each key in a SEPARATE turn:
+   - set_output("results", "structured results")
+""",
+    tools=["web_search", "web_scrape", "save_data", "load_data", "list_data_files"],
+)
+
+# Node 3: Review (client-facing)
+review_node = NodeSpec(
+    id="review",
+    name="Review",
+    description="Present results for user approval",
+    node_type="event_loop",
+    client_facing=True,
+    max_node_visits=0,
+    input_keys=["results", "brief"],
+    output_keys=["next_action", "feedback"],
+    nullable_output_keys=["feedback"],
+    success_criteria="User has reviewed and decided next steps.",
+    system_prompt="""\
+Present the results to the user.
+
+**STEP 1 — Present (text only, NO tool calls):**
+1. Summary of work done
+2. Key results
+3. Ask: satisfied, or want changes?
+
+**STEP 2 — After user responds, call set_output:**
+- set_output("next_action", "new_topic")   — if starting fresh
+- set_output("next_action", "revise")      — if changes needed
+- set_output("feedback", "what to change") — only if revising
+""",
+    tools=[],
+)
+
+__all__ = ["intake_node", "worker_node", "review_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 intake_node, worker_node, review_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 = [intake_node, worker_node, review_node]
+
+# Edge definitions
+edges = [
+    EdgeSpec(id="intake-to-worker", source="intake", target="worker",
+             condition=EdgeCondition.ON_SUCCESS, priority=1),
+    EdgeSpec(id="worker-to-review", source="worker", target="review",
+             condition=EdgeCondition.ON_SUCCESS, priority=1),
+    # Feedback loop
+    EdgeSpec(id="review-to-worker", source="review", target="worker",
+             condition=EdgeCondition.CONDITIONAL,
+             condition_expr="str(next_action).lower() == 'revise'", priority=2),
+    # Loop back for new topic
+    EdgeSpec(id="review-to-intake", source="review", target="intake",
+             condition=EdgeCondition.CONDITIONAL,
+             condition_expr="str(next_action).lower() == 'new_topic'", priority=1),
+]
+
+# Graph configuration
+entry_node = "intake"
+entry_points = {"start": "intake"}
+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
+        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, mock_mode=False):
+        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 = None
+        if not mock_mode:
+            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, mock_mode=False):
+        if self._agent_runtime is None:
+            self._setup(mock_mode=mock_mode)
+        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, mock_mode=False, session_state=None):
+        await self.start(mock_mode=mock_mode)
+        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):
+        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")
+        for ep_id, nid in self.entry_points.items():
+            if nid not in node_ids: errors.append(f"Entry point '{ep_id}' references unknown node '{nid}'")
+        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("--mock", is_flag=True)
+@click.option("--verbose", "-v", is_flag=True)
+def run(topic, mock, verbose):
+    """Execute the agent."""
+    setup_logging(verbose=verbose)
+    result = asyncio.run(default_agent.run({"topic": topic}, mock_mode=mock))
+    click.echo(json.dumps({"success": result.success, "output": result.output}, indent=2, default=str))
+    sys.exit(0 if result.success else 1)
+
+
+@cli.command()
+@click.option("--mock", is_flag=True)
+def tui(mock):
+    """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 = None if mock else 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="intake", 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
+
+```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
+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()
+```
+
+## 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/hive_coder/reference/framework_guide.md

@@ -0,0 +1,435 @@
+# 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` | no | `[]` | OK for forever-alive |
+| `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 | Always `"event_loop"` |
+| 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: 2-4 nodes for most agents.** Never exceed 5 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 (3 nodes):**
+```
+intake (client-facing) ←→ process (autonomous) ←→ review (client-facing)
+```
+Or for simpler agents, just 2 nodes:
+```
+interact (client-facing) → process (autonomous) → interact (loop)
+```
+
+### 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
+)
+```
+
+### Forever-Alive Pattern
+`terminal_nodes=[]` — every node has outgoing edges, graph loops until user exits.
+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 |
+|---------|---------------|------|
+| **Forever-alive** | `[]` | **DEFAULT for all agents** |
+| Linear | `["last-node"]` | Only if user explicitly requests one-shot/batch |
+
+**Forever-alive is the default.** Always use `terminal_nodes=[]`.
+The framework default for `max_node_visits` is 0 (unbounded), so
+nodes work correctly in forever-alive 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. The
+user exits by closing the TUI. Only use terminal nodes if the user
+explicitly asks for a batch/one-shot agent that runs once and exits.
+
+## 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 need to react to external events (incoming emails, scheduled
+tasks, API calls), use `AsyncEntryPointSpec` and optionally `AgentRuntimeConfig`.
+
+### Imports
+```python
+from framework.graph.edge import GraphSpec, AsyncEntryPointSpec
+from framework.runtime.agent_runtime import AgentRuntime, AgentRuntimeConfig, create_agent_runtime
+```
+Note: `AsyncEntryPointSpec` is in `framework.graph.edge` (the graph/declarative layer).
+`AgentRuntimeConfig` is in `framework.runtime.agent_runtime` (the runtime layer).
+
+### AsyncEntryPointSpec Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| id | str | required | Unique identifier |
+| name | str | required | Human-readable name |
+| entry_node | str | required | Node ID to start execution from |
+| trigger_type | str | `"manual"` | `webhook`, `api`, `timer`, `event`, `manual` |
+| trigger_config | dict | `{}` | Trigger-specific config (see below) |
+| isolation_level | str | `"shared"` | `isolated`, `shared`, `synchronized` |
+| priority | int | `0` | Execution priority (higher = more priority) |
+| max_concurrent | int | `10` | Max concurrent executions |
+
+### Trigger Types
+
+**timer** — Fires on a schedule. Two modes: cron expressions or fixed interval.
+
+Cron (preferred for precise scheduling):
+```python
+AsyncEntryPointSpec(
+    id="daily-digest",
+    name="Daily Digest",
+    entry_node="check-node",
+    trigger_type="timer",
+    trigger_config={"cron": "0 9 * * *"},  # daily at 9am
+    isolation_level="shared",
+    max_concurrent=1,
+)
+```
+- `cron` (str) — standard cron expression (5 fields: min hour dom month dow)
+- Examples: `"0 9 * * *"` (daily 9am), `"0 9 * * MON-FRI"` (weekdays 9am), `"*/30 * * * *"` (every 30 min)
+
+Fixed interval (simpler, for polling-style tasks):
+```python
+AsyncEntryPointSpec(
+    id="scheduled-check",
+    name="Scheduled Check",
+    entry_node="check-node",
+    trigger_type="timer",
+    trigger_config={"interval_minutes": 20, "run_immediately": False},
+    isolation_level="shared",
+    max_concurrent=1,
+)
+```
+- `interval_minutes` (float) — how often to fire
+- `run_immediately` (bool, default False) — fire once on startup
+
+**event** — Subscribes to EventBus (e.g., webhook events):
+```python
+AsyncEntryPointSpec(
+    id="email-event",
+    name="Email Event Handler",
+    entry_node="process-emails",
+    trigger_type="event",
+    trigger_config={"event_types": ["webhook_received"]},
+    isolation_level="shared",
+    max_concurrent=10,
+)
+```
+- `event_types` (list[str]) — EventType values to subscribe to
+- `filter_stream` (str, optional) — only receive from this stream
+- `filter_node` (str, optional) — only receive from this node
+
+**webhook** — HTTP endpoint (requires AgentRuntimeConfig):
+The webhook server publishes `WEBHOOK_RECEIVED` events on the EventBus.
+An `event` trigger type with `event_types: ["webhook_received"]` subscribes
+to those events. The flow is:
+```
+HTTP POST /webhooks/gmail → WebhookServer → EventBus (WEBHOOK_RECEIVED)
+  → event entry point → triggers graph execution from entry_node
+```
+
+**manual** — Triggered programmatically via `runtime.trigger()`.
+
+### Isolation Levels
+
+| Level | Meaning |
+|-------|---------|
+| `isolated` | Private state per execution |
+| `shared` | Eventual consistency — async executions can read primary session memory |
+| `synchronized` | Shared with write locks (use when ordering matters) |
+
+For most async patterns, use `shared` — the async execution reads the primary
+session's memory (e.g., user-configured rules) and runs its own workflow.
+
+### AgentRuntimeConfig (for webhook servers)
+
+```python
+from framework.runtime.agent_runtime import AgentRuntimeConfig
+
+runtime_config = AgentRuntimeConfig(
+    webhook_host="127.0.0.1",
+    webhook_port=8080,
+    webhook_routes=[
+        {
+            "source_id": "gmail",
+            "path": "/webhooks/gmail",
+            "methods": ["POST"],
+            "secret": None,  # Optional HMAC-SHA256 secret
+        },
+    ],
+)
+```
+`runtime_config` is a module-level variable read by `AgentRunner.load()`.
+The runner passes it to `create_agent_runtime()`. On `runtime.start()`,
+if webhook_routes is non-empty, an embedded HTTP server starts.
+
+### Session Sharing
+
+Timer and event triggers automatically call `_get_primary_session_state()`
+before execution. This finds the active user-facing session and provides
+its memory to the async execution, filtered to only the async entry node's
+`input_keys`. This means the async flow can read user-configured values
+(like rules, preferences) without needing separate configuration.
+
+### Module-Level Variables
+
+Agents with async entry points must export two additional variables:
+```python
+# In agent.py:
+async_entry_points = [AsyncEntryPointSpec(...), ...]
+runtime_config = AgentRuntimeConfig(...)  # Only if using webhooks
+```
+
+Both must be re-exported from `__init__.py`:
+```python
+from .agent import (
+    ..., async_entry_points, runtime_config,
+)
+```
+
+### Reference Agent
+
+See `exports/gmail_inbox_guardian/agent.py` for a complete example with:
+- Primary client-facing intake node (user configures rules)
+- Timer-based scheduled inbox checks (every 20 min)
+- Webhook-triggered email event handling
+- Shared isolation for memory access across streams
+
+## Framework Capabilities
+
+**Works well:** Multi-turn conversations, HITL review, tool orchestration, structured outputs, parallel execution, context management, error recovery, session persistence.
+
+**Limitations:** LLM latency (2-10s/turn), context window limits (~128K), cost per run, rate limits, node boundaries lose context.
+
+**Not designed for:** Sub-second responses, millions of items, real-time streaming, guaranteed determinism, offline/air-gapped.
+
+## Tool Discovery
+
+Do NOT rely on a static tool list — it will be outdated. Always use
+`list_agent_tools()` to get available tool names grouped by category.
+For full schemas with parameter details, use `discover_mcp_tools()`.
+
+```
+list_agent_tools()                            # all available tools
+list_agent_tools("exports/my_agent/mcp_servers.json")  # specific agent
+discover_mcp_tools()                          # full schemas with params
+```
+
+After building, validate tools exist: `validate_agent_tools("exports/{name}")`
+
+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/hive_coder/tests/conftest.py

@@ -0,0 +1,31 @@
+"""Test fixtures for Hive Coder 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/hive_coder/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/workflow.py

@@ -245,20 +245,14 @@ class GraphBuilder:
             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 == "event_loop":
+            if node.tools and not node.system_prompt:
+                warnings.append(f"Event loop 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}'")
@@ -447,14 +441,15 @@ class GraphBuilder:
         self.session.test_cases.append(test)
         self._save_session()
 
-    def run_test(
+    async def run_test_async(
         self,
         test: TestCase,
         executor_factory: Callable,
     ) -> TestResult:
         """
-        Run a single test case.
+        Run a single test case asynchronously.
 
+        This method is safe to call from async contexts (Jupyter, FastAPI, etc.).
         executor_factory should return a configured GraphExecutor.
         """
         self._require_phase([BuildPhase.ADDING_NODES, BuildPhase.ADDING_EDGES, BuildPhase.TESTING])
@@ -466,14 +461,10 @@ class GraphBuilder:
             executor = executor_factory()
 
             # Run the test
-            import asyncio
-
-            result = asyncio.run(
-                executor.execute(
-                    graph=graph,
-                    goal=self.session.goal,
-                    input_data=test.input,
-                )
+            result = await executor.execute(
+                graph=graph,
+                goal=self.session.goal,
+                input_data=test.input,
             )
 
             # Check result
@@ -503,6 +494,36 @@ class GraphBuilder:
 
         return test_result
 
+    def run_test(
+        self,
+        test: TestCase,
+        executor_factory: Callable,
+    ) -> TestResult:
+        """
+        Run a single test case.
+
+        This is a synchronous wrapper around run_test_async().
+        If called from an async context (Jupyter, FastAPI, etc.), use run_test_async() instead.
+
+        executor_factory should return a configured GraphExecutor.
+        """
+        import asyncio
+
+        # Check if an event loop is already running
+        # get_running_loop() returns a loop if one exists, or raises RuntimeError if none exists
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            # No event loop running - safe to use asyncio.run()
+            return asyncio.run(self.run_test_async(test, executor_factory))
+
+        # Event loop is running - cannot use asyncio.run()
+        raise RuntimeError(
+            "Cannot call run_test() from an async context. "
+            "An event loop is already running. "
+            "Please use 'await builder.run_test_async(test, executor_factory)' instead."
+        )
+
     def run_all_tests(self, executor_factory: Callable) -> list[TestResult]:
         """Run all test cases."""
         results = []

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
@@ -56,6 +56,13 @@ def _configure_paths():
     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

@@ -50,14 +50,55 @@ def get_max_tokens() -> int:
 
 
 def get_api_key() -> str | None:
-    """Return the API key from the environment variable specified in configuration."""
+    """Return the API key, supporting env var, Claude Code subscription, and ZAI Code.
+
+    Priority:
+    1. Claude Code subscription (``use_claude_code_subscription: true``)
+       reads the OAuth token from ``~/.claude/.credentials.json``.
+    2. 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
+
+    # 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_api_base() -> str | None:
+    """Return the api_base URL for OpenAI-compatible endpoints, if configured."""
+    return get_hive_config().get("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.
+    """
+    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}"},
+            }
+    return {}
+
+
 # ---------------------------------------------------------------------------
 # RuntimeConfig – shared across agent templates
 # ---------------------------------------------------------------------------
@@ -71,4 +112,5 @@ class RuntimeConfig:
     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 = None
+    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

@@ -59,6 +59,13 @@ from .provider import (
     CredentialProvider,
     StaticProvider,
 )
+from .setup import (
+    CredentialSetupSession,
+    MissingCredential,
+    SetupResult,
+    detect_missing_credentials_from_nodes,
+    run_credential_setup_cli,
+)
 from .storage import (
     CompositeStorage,
     CredentialStorage,
@@ -85,6 +92,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",
@@ -115,12 +130,22 @@ __all__ = [
     # Validation
     "ensure_credential_key_env",
     "validate_agent_credentials",
+    # Interactive setup
+    "CredentialSetupSession",
+    "MissingCredential",
+    "SetupResult",
+    "detect_missing_credentials_from_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,29 +1,31 @@
 """
 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
@@ -88,8 +90,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 +105,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,86 +115,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 or normalized credential dict."""
-
+    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"))
 
-        resolved_integration_id = (
-            integration_id
-            or data.get("integration_id")
-            or data.get("alias")
-            or data.get("provider", "")
-        )
-
-        resolved_integration_type = data.get("integration_type") or data.get("provider", "")
-        metadata = data.get("metadata")
-        if metadata is None and data.get("email"):
-            metadata = {"email": data.get("email")}
-        if metadata is None:
-            metadata = {}
-
         return cls(
-            integration_id=resolved_integration_id,
-            integration_type=resolved_integration_type,
-            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=metadata,
         )
 
 
 @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,
         )
 
 
@@ -202,56 +240,33 @@ 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
 
     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
 
@@ -260,7 +275,6 @@ class AdenCredentialClient:
                 timeout=self.config.timeout,
                 headers=headers,
             )
-
         return self._client
 
     def _request_with_retry(
@@ -277,10 +291,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 = response.json()
+                    raise AdenClientError(data.get("message", "Forbidden"))
+
                 if response.status_code == 404:
                     raise AdenNotFoundError(f"Integration not found: {path}")
 
@@ -293,14 +310,15 @@ class AdenCredentialClient:
 
                 if response.status_code == 400:
                     data = response.json()
-                    if data.get("error") == "refresh_failed":
+                    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
 
@@ -321,30 +339,40 @@ 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 = response.json()
+        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}")
@@ -355,100 +383,34 @@ class AdenCredentialClient:
 
     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()
         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}")
-
     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")
@@ -456,26 +418,17 @@ class AdenCredentialClient:
                 data = response.json()
                 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

@@ -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/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/setup.py

@@ -0,0 +1,764 @@
+"""
+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."""
+        missing = detect_missing_credentials_from_nodes(nodes)
+        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.
+        """
+        agent_path = Path(agent_path)
+
+        # Load agent to get nodes
+        agent_json = agent_path / "agent.json"
+        agent_py = agent_path / "agent.py"
+
+        nodes = []
+        if agent_py.exists():
+            # Python-based agent
+            nodes = _load_nodes_from_python_agent(agent_path)
+        elif agent_json.exists():
+            # JSON-based agent
+            nodes = _load_nodes_from_json_agent(agent_json)
+
+        creds = detect_missing_credentials_from_nodes(nodes, missing_only=missing_only)
+        return cls(creds)
+
+    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."""
+        if os.environ.get("HIVE_CREDENTIAL_KEY"):
+            return True
+
+        # Try to load from shell config
+        try:
+            from aden_tools.credentials.shell_config import check_env_var_in_shell_config
+
+            found, value = check_env_var_in_shell_config("HIVE_CREDENTIAL_KEY")
+            if found and value:
+                os.environ["HIVE_CREDENTIAL_KEY"] = value
+                return True
+        except ImportError:
+            pass
+
+        # Generate a new key
+        self._print(f"{Colors.YELLOW}Initializing credential store...{Colors.NC}")
+        try:
+            from cryptography.fernet import Fernet
+
+            generated_key = Fernet.generate_key().decode()
+            os.environ["HIVE_CREDENTIAL_KEY"] = generated_key
+
+            # Save to shell config
+            self._save_key_to_shell_config(generated_key)
+            return True
+        except Exception as e:
+            self._print(f"{Colors.RED}Failed to initialize credential store: {e}{Colors.NC}")
+            return False
+
+    def _save_key_to_shell_config(self, key: str) -> None:
+        """Save HIVE_CREDENTIAL_KEY to shell config."""
+        try:
+            from aden_tools.credentials.shell_config import (
+                add_env_var_to_shell_config,
+            )
+
+            success, config_path = add_env_var_to_shell_config(
+                "HIVE_CREDENTIAL_KEY",
+                key,
+                comment="Encryption key for Hive credential store",
+            )
+            if success:
+                self._print(f"{Colors.GREEN}✓ Encryption key saved to {config_path}{Colors.NC}")
+        except Exception:
+            # Fallback: just tell the user
+            self._print("\n")
+            self._print(
+                f"{Colors.YELLOW}Add this to your shell config (~/.zshrc or ~/.bashrc):{Colors.NC}"
+            )
+            self._print(f'  export HIVE_CREDENTIAL_KEY="{key}"')
+
+    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
+
+            os.environ["ADEN_API_KEY"] = aden_key
+
+            # Save to shell config
+            try:
+                from aden_tools.credentials.shell_config import add_env_var_to_shell_config
+
+                add_env_var_to_shell_config(
+                    "ADEN_API_KEY",
+                    aden_key,
+                    comment="Aden Platform API key",
+                )
+            except Exception:
+                pass
+
+        # 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 detect_missing_credentials_from_nodes(
+    nodes: list,
+    *,
+    missing_only: bool = True,
+) -> list[MissingCredential]:
+    """
+    Detect credentials required by a list of nodes.
+
+    Args:
+        nodes: List of NodeSpec objects
+        missing_only: If True (default), only return credentials that are
+            NOT yet available. If False, return ALL required credentials
+            regardless of availability.
+
+    Returns:
+        List of MissingCredential objects for credentials that need setup
+        (or all required credentials when missing_only=False).
+    """
+    try:
+        from aden_tools.credentials import CREDENTIAL_SPECS
+
+        from framework.credentials import CredentialStore
+        from framework.credentials.storage import (
+            CompositeStorage,
+            EncryptedFileStorage,
+            EnvVarStorage,
+        )
+    except ImportError:
+        return []
+
+    # 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)
+
+    # Build credential store to check availability.
+    # Env vars take priority over encrypted store (fresh key wins over stale).
+    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
+    tool_to_cred: dict[str, str] = {}
+    node_type_to_cred: dict[str, str] = {}
+    for cred_name, spec in CREDENTIAL_SPECS.items():
+        for tool_name in spec.tools:
+            tool_to_cred[tool_name] = cred_name
+        for nt in spec.node_types:
+            node_type_to_cred[nt] = cred_name
+
+    missing: list[MissingCredential] = []
+    checked: set[str] = set()
+
+    # Check tool credentials
+    for tool_name in sorted(required_tools):
+        cred_name = tool_to_cred.get(tool_name)
+        if cred_name is None or cred_name in checked:
+            continue
+        checked.add(cred_name)
+
+        spec = CREDENTIAL_SPECS[cred_name]
+        cred_id = spec.credential_id or cred_name
+        if spec.required and (not missing_only or not store.is_available(cred_id)):
+            affected_tools = sorted(t for t in required_tools if t in spec.tools)
+            missing.append(
+                MissingCredential(
+                    credential_name=cred_name,
+                    env_var=spec.env_var,
+                    description=spec.description,
+                    help_url=spec.help_url,
+                    api_key_instructions=spec.api_key_instructions,
+                    tools=affected_tools,
+                    aden_supported=spec.aden_supported,
+                    direct_api_key_supported=spec.direct_api_key_supported,
+                    credential_id=spec.credential_id,
+                    credential_key=spec.credential_key,
+                )
+            )
+
+    # Check node type credentials
+    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]
+        cred_id = spec.credential_id or cred_name
+        if spec.required and (not missing_only or not store.is_available(cred_id)):
+            affected_types = sorted(t for t in node_types if t in spec.node_types)
+            missing.append(
+                MissingCredential(
+                    credential_name=cred_name,
+                    env_var=spec.env_var,
+                    description=spec.description,
+                    help_url=spec.help_url,
+                    api_key_instructions=spec.api_key_instructions,
+                    node_types=affected_types,
+                    aden_supported=spec.aden_supported,
+                    direct_api_key_supported=spec.direct_api_key_supported,
+                    credential_id=spec.credential_id,
+                    credential_key=spec.credential_key,
+                )
+            )
+
+    return missing
+
+
+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) 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/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

@@ -8,75 +8,153 @@ from __future__ import annotations
 
 import logging
 import os
+from dataclasses import dataclass
 
 logger = logging.getLogger(__name__)
 
 
 def ensure_credential_key_env() -> None:
-    """Load HIVE_CREDENTIAL_KEY from shell config if not already in environment.
+    """Load credentials from shell config if not in environment.
 
-    The setup-credentials skill writes the encryption key to ~/.zshrc or ~/.bashrc.
-    If the user hasn't sourced their config in the current shell, this reads it
-    directly so the runner (and any MCP subprocesses it spawns) can unlock the
-    encrypted credential store.
+    The quickstart.sh and setup-credentials skill write API keys to ~/.zshrc
+    or ~/.bashrc. If the user hasn't sourced their config in the current shell,
+    this reads them directly so the runner (and any MCP subprocesses) can use them.
 
-    Only HIVE_CREDENTIAL_KEY is loaded this way — all other secrets (API keys, etc.)
-    come from the credential store itself.
+    Loads:
+    - HIVE_CREDENTIAL_KEY (encrypted credential store)
+    - ADEN_API_KEY (Aden OAuth sync)
+    - All LLM API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, ZAI_API_KEY, etc.)
     """
-    if os.environ.get("HIVE_CREDENTIAL_KEY"):
-        return
-
     try:
         from aden_tools.credentials.shell_config import check_env_var_in_shell_config
-
-        found, value = check_env_var_in_shell_config("HIVE_CREDENTIAL_KEY")
-        if found and value:
-            os.environ["HIVE_CREDENTIAL_KEY"] = value
-            logger.debug("Loaded HIVE_CREDENTIAL_KEY from shell config")
     except ImportError:
-        pass
+        return
 
+    # Core credentials that are always checked
+    env_vars_to_load = ["HIVE_CREDENTIAL_KEY", "ADEN_API_KEY"]
 
-def validate_agent_credentials(nodes: list) -> None:
-    """Check that required credentials are available before running an agent.
-
-    Scans node specs for required tools and node types, then checks whether
-    the corresponding credentials exist in the credential store.
-
-    Raises CredentialError with actionable guidance if any are missing.
-
-    Args:
-        nodes: List of NodeSpec objects from the agent graph.
-    """
-    required_tools: set[str] = set()
-    for node in nodes:
-        if node.tools:
-            required_tools.update(node.tools)
-    node_types: set[str] = {node.node_type for node in nodes}
-
+    # Add all LLM/tool API keys from CREDENTIAL_SPECS
     try:
         from aden_tools.credentials import CREDENTIAL_SPECS
 
-        from framework.credentials import CredentialStore
-        from framework.credentials.storage import (
-            CompositeStorage,
-            EncryptedFileStorage,
-            EnvVarStorage,
-        )
+        for spec in CREDENTIAL_SPECS.values():
+            if spec.env_var and spec.env_var not in env_vars_to_load:
+                env_vars_to_load.append(spec.env_var)
+    except ImportError:
+        pass
+
+    for var_name in env_vars_to_load:
+        if os.environ.get(var_name):
+            continue
+        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)
+
+
+@dataclass
+class _CredentialCheck:
+    """Result of checking a single credential."""
+
+    env_var: str
+    source: str
+    used_by: str
+    available: bool
+    help_url: str = ""
+
+
+def _presync_aden_tokens(credential_specs: dict) -> 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).
+    """
+    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 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) -> None:
+    """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.
+    """
+    # Collect required tools and node types
+    required_tools = {tool for node in nodes if node.tools for tool in node.tools}
+    node_types = {node.node_type for node in nodes}
+
+    try:
+        from aden_tools.credentials import CREDENTIAL_SPECS
     except ImportError:
         return  # aden_tools not installed, skip check
 
-    # Build credential store
+    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)
+
     env_mapping = {
         (spec.credential_id or name): spec.env_var for name, spec in CREDENTIAL_SPECS.items()
     }
-    storages: list = [EnvVarStorage(env_mapping=env_mapping)]
+    env_storage = EnvVarStorage(env_mapping=env_mapping)
     if os.environ.get("HIVE_CREDENTIAL_KEY"):
-        storages.insert(0, EncryptedFileStorage())
-    if len(storages) == 1:
-        storage = storages[0]
+        storage = CompositeStorage(primary=env_storage, fallbacks=[EncryptedFileStorage()])
     else:
-        storage = CompositeStorage(primary=storages[0], fallbacks=storages[1:])
+        storage = env_storage
     store = CredentialStore(storage=storage)
 
     # Build reverse mappings
@@ -89,7 +167,34 @@ def validate_agent_credentials(nodes: list) -> None:
             node_type_to_cred[nt] = cred_name
 
     missing: list[str] = []
+    invalid: list[str] = []
+    # Aden-backed creds where ADEN_API_KEY is set but integration not connected
+    aden_not_connected: list[str] = []
+    failed_cred_names: list[str] = []  # all cred names that need (re-)collection
+    has_aden_key = bool(os.environ.get("ADEN_API_KEY"))
     checked: set[str] = set()
+    # Credentials that are present and should be health-checked
+    to_verify: list[tuple[str, str]] = []  # (cred_name, used_by_label)
+
+    def _check_credential(spec, cred_name: str, label: str) -> None:
+        cred_id = spec.credential_id or cred_name
+        if not store.is_available(cred_id):
+            # If ADEN_API_KEY is set and this is an Aden-only credential,
+            # the issue is that the integration isn't connected on hive.adenhq.com,
+            # NOT that the user needs to re-enter ADEN_API_KEY.
+            if has_aden_key and spec.aden_supported and not spec.direct_api_key_supported:
+                aden_not_connected.append(
+                    f"  {spec.env_var} for {label}"
+                    f"\n    Connect this integration at hive.adenhq.com first."
+                )
+            else:
+                entry = f"  {spec.env_var} for {label}"
+                if spec.help_url:
+                    entry += f"\n    Get it at: {spec.help_url}"
+                missing.append(entry)
+                failed_cred_names.append(cred_name)
+        elif verify and spec.health_check_endpoint:
+            to_verify.append((cred_name, label))
 
     # Check tool credentials
     for tool_name in sorted(required_tools):
@@ -98,13 +203,11 @@ def validate_agent_credentials(nodes: list) -> None:
             continue
         checked.add(cred_name)
         spec = CREDENTIAL_SPECS[cred_name]
-        cred_id = spec.credential_id or cred_name
-        if spec.required and not store.is_available(cred_id):
-            affected = sorted(t for t in required_tools if t in spec.tools)
-            entry = f"  {spec.env_var} for {', '.join(affected)}"
-            if spec.help_url:
-                entry += f"\n    Get it at: {spec.help_url}"
-            missing.append(entry)
+        if not spec.required:
+            continue
+        affected = sorted(t for t in required_tools if t in spec.tools)
+        label = ", ".join(affected)
+        _check_credential(spec, cred_name, label)
 
     # Check node type credentials (e.g., ANTHROPIC_API_KEY for LLM nodes)
     for nt in sorted(node_types):
@@ -113,21 +216,141 @@ def validate_agent_credentials(nodes: list) -> None:
             continue
         checked.add(cred_name)
         spec = CREDENTIAL_SPECS[cred_name]
-        cred_id = spec.credential_id or cred_name
-        if spec.required and not store.is_available(cred_id):
-            affected_types = sorted(t for t in node_types if t in spec.node_types)
-            entry = f"  {spec.env_var} for {', '.join(affected_types)} nodes"
-            if spec.help_url:
-                entry += f"\n    Get it at: {spec.help_url}"
-            missing.append(entry)
+        if not spec.required:
+            continue
+        affected_types = sorted(t for t in node_types if t in spec.node_types)
+        label = ", ".join(affected_types) + " nodes"
+        _check_credential(spec, cred_name, label)
 
-    if missing:
+    # 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 cred_name, label in to_verify:
+                spec = CREDENTIAL_SPECS[cred_name]
+                cred_id = spec.credential_id or cred_name
+                value = store.get(cred_id)
+                if not value:
+                    continue
+                try:
+                    result = check_credential_health(
+                        cred_name,
+                        value,
+                        health_check_endpoint=spec.health_check_endpoint,
+                        health_check_method=spec.health_check_method,
+                    )
+                    if not result.valid:
+                        entry = f"  {spec.env_var} for {label} — {result.message}"
+                        if spec.help_url:
+                            entry += f"\n    Get a new key at: {spec.help_url}"
+                        invalid.append(entry)
+                        failed_cred_names.append(cred_name)
+                    elif 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(cred_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", cred_name, exc)
+
+    errors = missing + invalid + aden_not_connected
+    if errors:
         from framework.credentials.models import CredentialError
 
-        lines = ["Missing required credentials:\n"]
-        lines.extend(missing)
+        lines: list[str] = []
+        if missing:
+            lines.append("Missing credentials:\n")
+            lines.extend(missing)
+        if invalid:
+            if missing:
+                lines.append("")
+            lines.append("Invalid or expired credentials:\n")
+            lines.extend(invalid)
+        if aden_not_connected:
+            if missing or invalid:
+                lines.append("")
+            lines.append(
+                "Aden integrations not connected "
+                "(ADEN_API_KEY is set but OAuth tokens unavailable):\n"
+            )
+            lines.extend(aden_not_connected)
         lines.append(
             "\nTo fix: run /hive-credentials in Claude Code."
-            "\nIf you've already set up credentials, restart your terminal to load them."
+            "\nIf you've already set up credentials, "
+            "restart your terminal to load them."
         )
-        raise CredentialError("\n".join(lines))
+        exc = CredentialError("\n".join(lines))
+        exc.failed_cred_names = failed_cred_names  # type: ignore[attr-defined]
+        raise exc
+
+
+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.
+
+    ``validate_agent_credentials`` attaches ``failed_cred_names`` (both missing
+    and invalid) to the ``CredentialError``.  This helper converts those names
+    into ``MissingCredential`` entries so the setup screen can re-collect them.
+
+    Falls back to the normal ``from_nodes`` / ``from_agent_path`` detection
+    when the attribute is absent.
+
+    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, MissingCredential
+
+    # Start with normal detection (picks up truly missing creds)
+    if nodes is not None:
+        session = CredentialSetupSession.from_nodes(nodes)
+    elif agent_path is not None:
+        session = CredentialSetupSession.from_agent_path(agent_path)
+    else:
+        session = CredentialSetupSession(missing=[])
+
+    # Add credentials that are present but failed health checks
+    already = {m.credential_name for m in session.missing}
+    failed_names: list[str] = getattr(credential_error, "failed_cred_names", [])
+    if failed_names:
+        try:
+            from aden_tools.credentials import CREDENTIAL_SPECS
+
+            for name in failed_names:
+                if name in already:
+                    continue
+                spec = CREDENTIAL_SPECS.get(name)
+                if spec is None:
+                    continue
+                session.missing.append(
+                    MissingCredential(
+                        credential_name=name,
+                        env_var=spec.env_var,
+                        description=spec.description,
+                        help_url=spec.help_url,
+                        api_key_instructions=spec.api_key_instructions,
+                        tools=list(spec.tools),
+                        aden_supported=spec.aden_supported,
+                        direct_api_key_supported=spec.direct_api_key_supported,
+                        credential_id=spec.credential_id,
+                        credential_key=spec.credential_key,
+                    )
+                )
+        except ImportError:
+            pass
+
+    return session

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,7 +6,6 @@ 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 DEFAULT_MAX_TOKENS, EdgeCondition, EdgeSpec, GraphSpec
@@ -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",
@@ -59,35 +36,8 @@ __all__ = [
     "EdgeCondition",
     "GraphSpec",
     "DEFAULT_MAX_TOKENS",
-    # Executor (fixed graph)
+    # 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/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)

core/framework/graph/conversation.py

@@ -30,6 +30,8 @@ class Message:
     # Phase-aware compaction metadata (continuous mode)
     phase_id: str | None = None
     is_transition_marker: bool = False
+    # True when this message is real human input (from /chat), not a system prompt
+    is_client_input: bool = False
 
     def to_llm_dict(self) -> dict[str, Any]:
         """Convert to OpenAI-format message dict."""
@@ -67,6 +69,8 @@ class Message:
             d["phase_id"] = self.phase_id
         if self.is_transition_marker:
             d["is_transition_marker"] = self.is_transition_marker
+        if self.is_client_input:
+            d["is_client_input"] = self.is_client_input
         return d
 
     @classmethod
@@ -81,6 +85,7 @@ class Message:
             is_error=data.get("is_error", False),
             phase_id=data.get("phase_id"),
             is_transition_marker=data.get("is_transition_marker", False),
+            is_client_input=data.get("is_client_input", False),
         )
 
 
@@ -212,22 +217,12 @@ class NodeConversation:
         Layer 3 (focus) while preserving the conversation history.
         """
         self._system_prompt = new_prompt
+        self._meta_persisted = False  # re-persist with new prompt
 
     def set_current_phase(self, phase_id: str) -> None:
         """Set the current phase ID. Subsequent messages will be stamped with it."""
         self._current_phase = phase_id
 
-    async def switch_store(self, new_store: ConversationStore) -> None:
-        """Switch to a new persistence store at a phase transition.
-
-        Subsequent messages are written to *new_store*.  Meta (system
-        prompt, config) is re-persisted on the next write so the new
-        store's ``meta.json`` reflects the updated prompt.
-        """
-        self._store = new_store
-        self._meta_persisted = False
-        await new_store.write_cursor({"next_seq": self._next_seq})
-
     @property
     def current_phase(self) -> str | None:
         return self._current_phase
@@ -258,6 +253,7 @@ class NodeConversation:
         content: str,
         *,
         is_transition_marker: bool = False,
+        is_client_input: bool = False,
     ) -> Message:
         msg = Message(
             seq=self._next_seq,
@@ -265,6 +261,7 @@ class NodeConversation:
             content=content,
             phase_id=self._current_phase,
             is_transition_marker=is_transition_marker,
+            is_client_input=is_client_input,
         )
         self._messages.append(msg)
         self._next_seq += 1
@@ -682,9 +679,20 @@ class NodeConversation:
     # --- Restore -----------------------------------------------------------
 
     @classmethod
-    async def restore(cls, store: ConversationStore) -> NodeConversation | None:
+    async def restore(
+        cls,
+        store: ConversationStore,
+        phase_id: str | None = None,
+    ) -> NodeConversation | None:
         """Reconstruct a NodeConversation from a store.
 
+        Args:
+            store: The conversation store to read from.
+            phase_id: If set, only load parts matching this phase_id.
+                Used in isolated mode so a node only sees its own
+                messages in the shared flat store.  In continuous mode
+                pass ``None`` to load all parts.
+
         Returns ``None`` if the store contains no metadata (i.e. the
         conversation was never persisted).
         """
@@ -702,6 +710,8 @@ class NodeConversation:
         conv._meta_persisted = True
 
         parts = await store.read_parts()
+        if phase_id:
+            parts = [p for p in parts if p.get("phase_id") == phase_id]
         conv._messages = [Message.from_storage_dict(p) for p in parts]
 
         cursor = await store.read_cursor()

core/framework/graph/edge.py

@@ -341,6 +341,12 @@ class AsyncEntryPointSpec(BaseModel):
 
     model_config = {"extra": "allow"}
 
+    def get_isolation_level(self):
+        """Convert string isolation level to enum (duck-type with EntryPointSpec)."""
+        from framework.runtime.execution_stream import IsolationLevel
+
+        return IsolationLevel(self.isolation_level)
+
 
 class GraphSpec(BaseModel):
     """
@@ -422,7 +428,7 @@ class GraphSpec(BaseModel):
 
     # Cleanup LLM for JSON extraction fallback (fast/cheap model preferred)
     # If not set, uses CEREBRAS_API_KEY -> cerebras/llama-3.3-70b or
-    # ANTHROPIC_API_KEY -> claude-3-5-haiku as fallback
+    # ANTHROPIC_API_KEY -> claude-haiku-4-5 as fallback
     cleanup_llm_model: str | None = None
 
     # Execution limits

core/framework/graph/event_loop_node.py

@@ -202,10 +202,13 @@ class EventLoopNode(NodeProtocol):
         self._config = config or LoopConfig()
         self._tool_executor = tool_executor
         self._conversation_store = conversation_store
-        self._injection_queue: asyncio.Queue[str] = asyncio.Queue()
+        self._injection_queue: asyncio.Queue[tuple[str, bool]] = asyncio.Queue()
         # Client-facing input blocking state
         self._input_ready = asyncio.Event()
+        self._awaiting_input = False
         self._shutdown = False
+        # Track which nodes already have an action plan emitted (skip on revisit)
+        self._action_plan_emitted: set[str] = set()
 
     def validate_input(self, ctx: NodeContext) -> list[str]:
         """Validate hard requirements only.
@@ -228,8 +231,9 @@ class EventLoopNode(NodeProtocol):
         start_time = time.time()
         total_input_tokens = 0
         total_output_tokens = 0
-        stream_id = ctx.node_id
+        stream_id = ctx.stream_id or ctx.node_id
         node_id = ctx.node_id
+        execution_id = ctx.execution_id or ""
 
         # Verdict counters for runtime logging
         _accept_count = _retry_count = _escalate_count = _continue_count = 0
@@ -274,12 +278,63 @@ class EventLoopNode(NodeProtocol):
             )
             accumulator = OutputAccumulator(store=self._conversation_store)
             start_iteration = 0
+            _restored_recent_responses: list[str] = []
+            _restored_tool_fingerprints: list[list[tuple[str, str]]] = []
         else:
             # Try crash-recovery restore from store, then fall back to fresh.
-            conversation, accumulator, start_iteration = await self._restore(ctx)
-            if conversation is None:
+            restored = await self._restore(ctx)
+            if restored is not None:
+                conversation = restored.conversation
+                accumulator = restored.accumulator
+                start_iteration = restored.start_iteration
+                _restored_recent_responses = restored.recent_responses
+                _restored_tool_fingerprints = restored.recent_tool_fingerprints
+
+                # Refresh the system prompt to the current node spec's version.
+                # The stored prompt may be stale after code changes or when
+                # runtime-injected context (e.g. worker identity) has changed.
+                from framework.graph.prompt_composer import _with_datetime
+
+                _current_prompt = _with_datetime(ctx.node_spec.system_prompt or "")
+                if ctx.accounts_prompt:
+                    _current_prompt = f"{_current_prompt}\n\n{ctx.accounts_prompt}"
+                if conversation.system_prompt != _current_prompt:
+                    conversation.update_system_prompt(_current_prompt)
+                    logger.info("Refreshed system prompt for restored conversation")
+            else:
+                _restored_recent_responses = []
+                _restored_tool_fingerprints = []
+
                 # Fresh conversation: either isolated mode or first node in continuous mode.
-                system_prompt = ctx.node_spec.system_prompt or ""
+                from framework.graph.prompt_composer import _with_datetime
+
+                system_prompt = _with_datetime(ctx.node_spec.system_prompt or "")
+                # Append connected accounts info if available
+                if ctx.accounts_prompt:
+                    system_prompt = f"{system_prompt}\n\n{ctx.accounts_prompt}"
+
+                # Inject agent working memory (adapt.md).
+                # If it doesn't exist yet, seed it with available context.
+                if self._config.spillover_dir:
+                    _adapt_path = Path(self._config.spillover_dir) / "adapt.md"
+                    if not _adapt_path.exists() and ctx.accounts_prompt:
+                        _adapt_path.parent.mkdir(parents=True, exist_ok=True)
+                        _adapt_path.write_text(
+                            f"## Identity\n{ctx.accounts_prompt}\n",
+                            encoding="utf-8",
+                        )
+                    if _adapt_path.exists():
+                        _adapt_text = _adapt_path.read_text(encoding="utf-8").strip()
+                        if _adapt_text:
+                            system_prompt = (
+                                f"{system_prompt}\n\n"
+                                f"--- Your Memory ---\n{_adapt_text}\n--- End Memory ---\n\n"
+                                'Maintain your memory by calling save_data("adapt.md", ...) '
+                                'or edit_data("adapt.md", ...) as you work.\n'
+                                "IMMEDIATELY save: user rules about which account/identity to use, "
+                                "behavioral constraints, and preferences. "
+                                "Also record session history, decisions, and working notes."
+                            )
 
                 conversation = NodeConversation(
                     system_prompt=system_prompt,
@@ -303,8 +358,9 @@ class EventLoopNode(NodeProtocol):
         set_output_tool = self._build_set_output_tool(ctx.node_spec.output_keys)
         if set_output_tool:
             tools.append(set_output_tool)
-        if ctx.node_spec.client_facing:
+        if ctx.node_spec.client_facing and not ctx.event_triggered:
             tools.append(self._build_ask_user_tool())
+            tools.append(self._build_escalate_tool())
 
         logger.info(
             "[%s] Tools available (%d): %s | client_facing=%s | judge=%s",
@@ -316,12 +372,21 @@ class EventLoopNode(NodeProtocol):
         )
 
         # 4. Publish loop started
-        await self._publish_loop_started(stream_id, node_id)
+        await self._publish_loop_started(stream_id, node_id, execution_id)
 
-        # 5. Stall / doom loop detection state
-        recent_responses: list[str] = []
-        recent_tool_fingerprints: list[list[tuple[str, str]]] = []
-        user_interaction_count = 0  # tracks how many times this node blocked for user input
+        # 4b. Fire-and-forget action plan generation (once per node per lifetime)
+        if (
+            start_iteration == 0
+            and ctx.llm
+            and self._event_bus
+            and node_id not in self._action_plan_emitted
+        ):
+            self._action_plan_emitted.add(node_id)
+            asyncio.create_task(self._generate_action_plan(ctx, stream_id, node_id, execution_id))
+
+        # 5. Stall / doom loop detection state (restored from cursor if resuming)
+        recent_responses: list[str] = _restored_recent_responses
+        recent_tool_fingerprints: list[list[tuple[str, str]]] = _restored_tool_fingerprints
 
         # 6. Main loop
         for iteration in range(start_iteration, self._config.max_iterations):
@@ -359,7 +424,7 @@ class EventLoopNode(NodeProtocol):
             await self._drain_injection_queue(conversation)
 
             # 6c. Publish iteration event
-            await self._publish_iteration(stream_id, node_id, iteration)
+            await self._publish_iteration(stream_id, node_id, iteration, execution_id)
 
             # 6d. Pre-turn compaction check (tiered)
             if conversation.needs_compaction():
@@ -432,6 +497,7 @@ class EventLoopNode(NodeProtocol):
                                 retry_count=_stream_retry_count,
                                 max_retries=self._config.max_stream_retries,
                                 error=str(e)[:500],
+                                execution_id=execution_id,
                             )
                         await asyncio.sleep(delay)
                         continue  # retry same iteration
@@ -508,7 +574,9 @@ class EventLoopNode(NodeProtocol):
                         node_id,
                         iteration,
                     )
-                    await self._publish_loop_completed(stream_id, node_id, iteration + 1)
+                    await self._publish_loop_completed(
+                        stream_id, node_id, iteration + 1, execution_id
+                    )
                     latency_ms = int((time.time() - start_time) * 1000)
                     return NodeResult(
                         success=True,
@@ -523,7 +591,7 @@ class EventLoopNode(NodeProtocol):
             if len(recent_responses) > self._config.stall_detection_threshold:
                 recent_responses.pop(0)
             if self._is_stalled(recent_responses):
-                await self._publish_stalled(stream_id, node_id)
+                await self._publish_stalled(stream_id, node_id, execution_id)
                 latency_ms = int((time.time() - start_time) * 1000)
                 _continue_count += 1
                 if ctx.runtime_logger:
@@ -575,7 +643,8 @@ class EventLoopNode(NodeProtocol):
             mcp_tool_calls = [
                 tc
                 for tc in logged_tool_calls
-                if tc.get("tool_name") not in ("set_output", "ask_user") and not tc.get("is_error")
+                if tc.get("tool_name") not in ("set_output", "ask_user", "escalate_to_coder")
+                and not tc.get("is_error")
             ]
             if mcp_tool_calls:
                 fps = self._fingerprint_tool_calls(mcp_tool_calls)
@@ -593,13 +662,14 @@ class EventLoopNode(NodeProtocol):
                             stream_id=stream_id,
                             node_id=node_id,
                             description=doom_desc,
+                            execution_id=execution_id,
                         )
                     warning_msg = (
                         f"[SYSTEM] {doom_desc}. You are repeating the "
                         "same tool calls with identical arguments. "
                         "Try a different approach or different arguments."
                     )
-                    if ctx.node_spec.client_facing:
+                    if ctx.node_spec.client_facing and not ctx.event_triggered:
                         await conversation.add_user_message(warning_msg)
                         self._input_ready.clear()
                         if self._event_bus:
@@ -607,8 +677,13 @@ class EventLoopNode(NodeProtocol):
                                 stream_id=stream_id,
                                 node_id=node_id,
                                 prompt=doom_desc,
+                                execution_id=execution_id,
                             )
-                        await self._input_ready.wait()
+                        self._awaiting_input = True
+                        try:
+                            await self._input_ready.wait()
+                        finally:
+                            self._awaiting_input = False
                         recent_tool_fingerprints.clear()
                         recent_responses.clear()
                     else:
@@ -618,8 +693,15 @@ class EventLoopNode(NodeProtocol):
                 # Text-only turn breaks the doom loop chain
                 recent_tool_fingerprints.clear()
 
-            # 6g. Write cursor checkpoint
-            await self._write_cursor(ctx, conversation, accumulator, iteration)
+            # 6g. Write cursor checkpoint (includes stall/doom state for resume)
+            await self._write_cursor(
+                ctx,
+                conversation,
+                accumulator,
+                iteration,
+                recent_responses=recent_responses,
+                recent_tool_fingerprints=recent_tool_fingerprints,
+            )
 
             # 6h. Client-facing input blocking
             #
@@ -636,7 +718,7 @@ class EventLoopNode(NodeProtocol):
             # conversation — they flow through without blocking.
             _cf_block = False
             _cf_auto = False
-            if ctx.node_spec.client_facing:
+            if ctx.node_spec.client_facing and not ctx.event_triggered:
                 if user_input_requested:
                     _cf_block = True
                 elif assistant_text and not real_tool_results and not outputs_set:
@@ -645,7 +727,9 @@ class EventLoopNode(NodeProtocol):
 
             if _cf_block:
                 if self._shutdown:
-                    await self._publish_loop_completed(stream_id, node_id, iteration + 1)
+                    await self._publish_loop_completed(
+                        stream_id, node_id, iteration + 1, execution_id
+                    )
                     latency_ms = int((time.time() - start_time) * 1000)
                     _continue_count += 1
                     if ctx.runtime_logger:
@@ -695,7 +779,9 @@ class EventLoopNode(NodeProtocol):
                 got_input = await self._await_user_input(ctx)
                 logger.info("[%s] iter=%d: unblocked, got_input=%s", node_id, iteration, got_input)
                 if not got_input:
-                    await self._publish_loop_completed(stream_id, node_id, iteration + 1)
+                    await self._publish_loop_completed(
+                        stream_id, node_id, iteration + 1, execution_id
+                    )
                     latency_ms = int((time.time() - start_time) * 1000)
                     _continue_count += 1
                     if ctx.runtime_logger:
@@ -736,7 +822,6 @@ class EventLoopNode(NodeProtocol):
                         conversation=conversation if _is_continuous else None,
                     )
 
-                user_interaction_count += 1
                 recent_responses.clear()
 
                 if _cf_auto:
@@ -815,6 +900,7 @@ class EventLoopNode(NodeProtocol):
                 feedback=fb_preview,
                 judge_type=judge_type,
                 iteration=iteration,
+                execution_id=execution_id,
             )
 
             if verdict.action == "ACCEPT":
@@ -856,7 +942,7 @@ class EventLoopNode(NodeProtocol):
                 for key, value in accumulator.to_dict().items():
                     ctx.memory.write(key, value, validate=False)
 
-                await self._publish_loop_completed(stream_id, node_id, iteration + 1)
+                await self._publish_loop_completed(stream_id, node_id, iteration + 1, execution_id)
                 latency_ms = int((time.time() - start_time) * 1000)
                 _accept_count += 1
                 if ctx.runtime_logger:
@@ -899,7 +985,7 @@ class EventLoopNode(NodeProtocol):
 
             elif verdict.action == "ESCALATE":
                 # Exit point 6: Judge ESCALATE — log step + log_node_complete
-                await self._publish_loop_completed(stream_id, node_id, iteration + 1)
+                await self._publish_loop_completed(stream_id, node_id, iteration + 1, execution_id)
                 latency_ms = int((time.time() - start_time) * 1000)
                 _escalate_count += 1
                 if ctx.runtime_logger:
@@ -963,7 +1049,9 @@ class EventLoopNode(NodeProtocol):
                 continue
 
         # 7. Max iterations exhausted
-        await self._publish_loop_completed(stream_id, node_id, self._config.max_iterations)
+        await self._publish_loop_completed(
+            stream_id, node_id, self._config.max_iterations, execution_id
+        )
         latency_ms = int((time.time() - start_time) * 1000)
         if ctx.runtime_logger:
             ctx.runtime_logger.log_node_complete(
@@ -992,14 +1080,19 @@ class EventLoopNode(NodeProtocol):
             conversation=conversation if _is_continuous else None,
         )
 
-    async def inject_event(self, content: str) -> None:
-        """Inject an external event into the running loop.
+    async def inject_event(self, content: str, *, is_client_input: bool = False) -> None:
+        """Inject an external event or user input into the running loop.
 
         The content becomes a user message prepended to the next iteration.
         Thread-safe via asyncio.Queue.
         Also unblocks _await_user_input() if the node is waiting.
+
+        Args:
+            content: The message text.
+            is_client_input: True when the message originates from a real
+                human user (e.g. /chat endpoint), False for external events.
         """
-        await self._injection_queue.put(content)
+        await self._injection_queue.put((content, is_client_input))
         self._input_ready.set()
 
     def signal_shutdown(self) -> None:
@@ -1030,12 +1123,17 @@ class EventLoopNode(NodeProtocol):
 
         if self._event_bus:
             await self._event_bus.emit_client_input_requested(
-                stream_id=ctx.node_id,
+                stream_id=ctx.stream_id or ctx.node_id,
                 node_id=ctx.node_id,
                 prompt="",
+                execution_id=ctx.execution_id or "",
             )
 
-        await self._input_ready.wait()
+        self._awaiting_input = True
+        try:
+            await self._input_ready.wait()
+        finally:
+            self._awaiting_input = False
         return not self._shutdown
 
     # -------------------------------------------------------------------
@@ -1067,8 +1165,9 @@ class EventLoopNode(NodeProtocol):
         ``real_tool_results`` which resets each inner iteration, this list grows
         across the entire turn.
         """
-        stream_id = ctx.node_id
+        stream_id = ctx.stream_id or ctx.node_id
         node_id = ctx.node_id
+        execution_id = ctx.execution_id or ""
         token_counts: dict[str, int] = {"input": 0, "output": 0}
         tool_call_count = 0
         final_text = ""
@@ -1120,7 +1219,12 @@ class EventLoopNode(NodeProtocol):
                 if isinstance(event, TextDeltaEvent):
                     accumulated_text = event.snapshot
                     await self._publish_text_delta(
-                        stream_id, node_id, event.content, event.snapshot, ctx
+                        stream_id,
+                        node_id,
+                        event.content,
+                        event.snapshot,
+                        ctx,
+                        execution_id,
                     )
 
                 elif isinstance(event, ToolCallEvent):
@@ -1204,7 +1308,12 @@ class EventLoopNode(NodeProtocol):
                 executed_in_batch += 1
 
                 await self._publish_tool_started(
-                    stream_id, node_id, tc.tool_use_id, tc.tool_name, tc.tool_input
+                    stream_id,
+                    node_id,
+                    tc.tool_use_id,
+                    tc.tool_name,
+                    tc.tool_input,
+                    execution_id,
                 )
                 logger.info(
                     "[%s] tool_call: %s(%s)",
@@ -1236,7 +1345,7 @@ class EventLoopNode(NodeProtocol):
                         key = tc.tool_input.get("key", "")
                         await accumulator.set(key, value)
                         outputs_set_this_turn.append(key)
-                        await self._publish_output_key_set(stream_id, node_id, key)
+                        await self._publish_output_key_set(stream_id, node_id, key, execution_id)
                     logged_tool_calls.append(
                         {
                             "tool_use_id": tc.tool_use_id,
@@ -1258,6 +1367,26 @@ class EventLoopNode(NodeProtocol):
                     )
                     results_by_id[tc.tool_use_id] = result
 
+                elif tc.tool_name == "escalate_to_coder":
+                    # --- Framework-level escalation handling ---
+                    if self._event_bus:
+                        await self._event_bus.emit_escalation_requested(
+                            stream_id=stream_id,
+                            node_id=node_id,
+                            reason=tc.tool_input.get("reason", ""),
+                            context=tc.tool_input.get("context", ""),
+                            execution_id=ctx.execution_id,
+                        )
+                    # Block like ask_user — the TUI loads the coder,
+                    # and /back injects a message to unblock us.
+                    user_input_requested = True
+                    result = ToolResult(
+                        tool_use_id=tc.tool_use_id,
+                        content="Escalating to Hive Coder. You will resume when done.",
+                        is_error=False,
+                    )
+                    results_by_id[tc.tool_use_id] = result
+
                 else:
                     # --- Real tool: check for truncated args, else queue ---
                     if "_raw" in tc.tool_input:
@@ -1304,7 +1433,7 @@ class EventLoopNode(NodeProtocol):
                     continue  # shouldn't happen
 
                 # Build log entries for real tools
-                if tc.tool_name not in ("set_output", "ask_user"):
+                if tc.tool_name not in ("set_output", "ask_user", "escalate_to_coder"):
                     tool_entry = {
                         "tool_use_id": tc.tool_use_id,
                         "tool_name": tc.tool_name,
@@ -1327,6 +1456,7 @@ class EventLoopNode(NodeProtocol):
                     tc.tool_name,
                     result.content,
                     result.is_error,
+                    execution_id,
                 )
 
             # If the limit was hit, add error results for every remaining
@@ -1449,6 +1579,46 @@ class EventLoopNode(NodeProtocol):
             },
         )
 
+    def _build_escalate_tool(self) -> Tool:
+        """Build the synthetic escalate_to_coder tool.
+
+        Client-facing nodes call this when the user's request requires
+        capabilities beyond the current agent (code changes, feature
+        expansion, debugging).  The TUI intercepts the event and loads
+        hive_coder in the foreground.
+        """
+        return Tool(
+            name="escalate_to_coder",
+            description=(
+                "Call this tool when the user requests something you "
+                "cannot handle — a code change, feature expansion, bug "
+                "fix, or framework-level modification. This will bring "
+                "in Hive Coder, a coding agent that can read and write "
+                "files. Provide a clear reason and relevant context so "
+                "the coder can pick up where you left off."
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "reason": {
+                        "type": "string",
+                        "description": (
+                            "Why you are escalating (what the user needs that you cannot do)."
+                        ),
+                    },
+                    "context": {
+                        "type": "string",
+                        "description": (
+                            "Relevant context: what you discussed, "
+                            "what files are involved, what the user "
+                            "wants changed."
+                        ),
+                    },
+                },
+                "required": ["reason"],
+            },
+        )
+
     def _build_set_output_tool(self, output_keys: list[str] | None) -> Tool | None:
         """Build the synthetic set_output tool for explicit output declaration."""
         if not output_keys:
@@ -1580,6 +1750,12 @@ class EventLoopNode(NodeProtocol):
                         ),
                     )
 
+                # Client-facing nodes with no output keys are meant for
+                # continuous interaction — they should not auto-accept.
+                # Only exit via shutdown, max_iterations, or max_node_visits.
+                if not output_keys and ctx.node_spec.client_facing:
+                    return JudgeVerdict(action="RETRY", feedback="")
+
                 # Level 2: conversation-aware quality check (if success_criteria set)
                 if ctx.node_spec.success_criteria and ctx.llm:
                     from framework.graph.conversation_judge import evaluate_phase_completion
@@ -2000,7 +2176,7 @@ class EventLoopNode(NodeProtocol):
                     await self._event_bus.publish(
                         AgentEvent(
                             type=EventType.CONTEXT_COMPACTED,
-                            stream_id=ctx.node_id,
+                            stream_id=ctx.stream_id or ctx.node_id,
                             node_id=ctx.node_id,
                             data={
                                 "level": "prune_only",
@@ -2056,7 +2232,7 @@ class EventLoopNode(NodeProtocol):
             await self._event_bus.publish(
                 AgentEvent(
                     type=EventType.CONTEXT_COMPACTED,
-                    stream_id=ctx.node_id,
+                    stream_id=ctx.stream_id or ctx.node_id,
                     node_id=ctx.node_id,
                     data={
                         "level": level,
@@ -2079,7 +2255,11 @@ class EventLoopNode(NodeProtocol):
         )
         prompt = (
             "Summarize this conversation so far in 2-3 sentences, "
-            "preserving key decisions and results:\n\n"
+            "preserving key decisions and results.\n\n"
+            "IMPORTANT: Always preserve any user-stated rules, constraints, "
+            "or preferences — especially which account/identity to use, "
+            "formatting preferences, and behavioral instructions. "
+            "These MUST appear verbatim or near-verbatim in your summary.\n\n"
             f"{messages_text}"
         )
         if tool_history:
@@ -2096,7 +2276,9 @@ class EventLoopNode(NodeProtocol):
             response = await ctx.llm.acomplete(
                 messages=[{"role": "user", "content": prompt}],
                 system=(
-                    "Summarize conversations concisely. Always preserve the tool history section."
+                    "Summarize conversations concisely. Always preserve the tool "
+                    "history section. Always preserve user-stated rules, constraints, "
+                    "and account/identity preferences verbatim."
                 ),
                 max_tokens=summary_budget,
             )
@@ -2168,13 +2350,24 @@ class EventLoopNode(NodeProtocol):
 
         # 5. Spillover files — list actual files so the LLM can load
         # them immediately instead of having to call list_data_files first.
+        # Inline adapt.md (agent memory) directly — it contains user rules
+        # and identity preferences that must survive emergency compaction.
         if self._config.spillover_dir:
             try:
                 from pathlib import Path
 
                 data_dir = Path(self._config.spillover_dir)
                 if data_dir.is_dir():
-                    files = sorted(f.name for f in data_dir.iterdir() if f.is_file())
+                    # Inline adapt.md content directly
+                    adapt_path = data_dir / "adapt.md"
+                    if adapt_path.is_file():
+                        adapt_text = adapt_path.read_text(encoding="utf-8").strip()
+                        if adapt_text:
+                            parts.append(f"AGENT MEMORY (adapt.md):\n{adapt_text}")
+
+                    files = sorted(
+                        f.name for f in data_dir.iterdir() if f.is_file() and f.name != "adapt.md"
+                    )
                     if files:
                         file_list = "\n".join(f"  - {f}" for f in files[:30])
                         parts.append("DATA FILES (use load_data to read):\n" + file_list)
@@ -2205,29 +2398,69 @@ class EventLoopNode(NodeProtocol):
     # Persistence: restore, cursor, injection, pause
     # -------------------------------------------------------------------
 
+    @dataclass
+    class _RestoredState:
+        """State recovered from a previous checkpoint."""
+
+        conversation: NodeConversation
+        accumulator: OutputAccumulator
+        start_iteration: int
+        recent_responses: list[str]
+        recent_tool_fingerprints: list[list[tuple[str, str]]]
+
     async def _restore(
         self,
         ctx: NodeContext,
-    ) -> tuple[NodeConversation | None, OutputAccumulator | None, int]:
-        """Attempt to restore from a previous checkpoint."""
-        if self._conversation_store is None:
-            return None, None, 0
+    ) -> _RestoredState | None:
+        """Attempt to restore from a previous checkpoint.
 
-        conversation = await NodeConversation.restore(self._conversation_store)
+        Returns a ``_RestoredState`` with conversation, accumulator, iteration
+        counter, and stall/doom-loop detection state — everything needed to
+        resume exactly where execution stopped.
+        """
+        if self._conversation_store is None:
+            return None
+
+        # In isolated mode, filter parts by phase_id so the node only sees
+        # its own messages in the shared flat conversation store.  In
+        # continuous mode (or when _restore is called for timer-resume)
+        # load all parts — the full conversation threads across nodes.
+        _is_continuous = getattr(ctx, "continuous_mode", False)
+        phase_filter = None if _is_continuous else ctx.node_id
+        conversation = await NodeConversation.restore(
+            self._conversation_store,
+            phase_id=phase_filter,
+        )
         if conversation is None:
-            return None, None, 0
+            return None
 
         accumulator = await OutputAccumulator.restore(self._conversation_store)
 
         cursor = await self._conversation_store.read_cursor()
         start_iteration = cursor.get("iteration", 0) + 1 if cursor else 0
 
+        # Restore stall/doom-loop detection state
+        recent_responses: list[str] = cursor.get("recent_responses", []) if cursor else []
+        raw_fps = cursor.get("recent_tool_fingerprints", []) if cursor else []
+        recent_tool_fingerprints: list[list[tuple[str, str]]] = [
+            [tuple(pair) for pair in fps]  # type: ignore[misc]
+            for fps in raw_fps
+        ]
+
         logger.info(
             f"Restored event loop: iteration={start_iteration}, "
             f"messages={conversation.message_count}, "
-            f"outputs={list(accumulator.values.keys())}"
+            f"outputs={list(accumulator.values.keys())}, "
+            f"stall_window={len(recent_responses)}, "
+            f"doom_window={len(recent_tool_fingerprints)}"
+        )
+        return EventLoopNode._RestoredState(
+            conversation=conversation,
+            accumulator=accumulator,
+            start_iteration=start_iteration,
+            recent_responses=recent_responses,
+            recent_tool_fingerprints=recent_tool_fingerprints,
         )
-        return conversation, accumulator, start_iteration
 
     async def _write_cursor(
         self,
@@ -2235,8 +2468,15 @@ class EventLoopNode(NodeProtocol):
         conversation: NodeConversation,
         accumulator: OutputAccumulator,
         iteration: int,
+        *,
+        recent_responses: list[str] | None = None,
+        recent_tool_fingerprints: list[list[tuple[str, str]]] | None = None,
     ) -> None:
-        """Write checkpoint cursor for crash recovery."""
+        """Write checkpoint cursor for crash recovery.
+
+        Persists iteration counter, accumulator outputs, and stall/doom-loop
+        detection state so that resume picks up exactly where execution stopped.
+        """
         if self._conversation_store:
             cursor = await self._conversation_store.read_cursor() or {}
             cursor.update(
@@ -2247,6 +2487,14 @@ class EventLoopNode(NodeProtocol):
                     "outputs": accumulator.to_dict(),
                 }
             )
+            # Persist stall/doom-loop detection state for reliable resume
+            if recent_responses is not None:
+                cursor["recent_responses"] = recent_responses
+            if recent_tool_fingerprints is not None:
+                # Convert list[list[tuple]] → list[list[list]] for JSON
+                cursor["recent_tool_fingerprints"] = [
+                    [list(pair) for pair in fps] for fps in recent_tool_fingerprints
+                ]
             await self._conversation_store.write_cursor(cursor)
 
     async def _drain_injection_queue(self, conversation: NodeConversation) -> int:
@@ -2254,12 +2502,17 @@ class EventLoopNode(NodeProtocol):
         count = 0
         while not self._injection_queue.empty():
             try:
-                content = self._injection_queue.get_nowait()
+                content, is_client_input = self._injection_queue.get_nowait()
                 logger.info(
-                    "[drain] injected message: %s",
+                    "[drain] injected message (client_input=%s): %s",
+                    is_client_input,
                     content[:200] if content else "(empty)",
                 )
-                await conversation.add_user_message(f"[External event]: {content}")
+                # Real user input is stored as-is; external events get a prefix
+                if is_client_input:
+                    await conversation.add_user_message(content, is_client_input=True)
+                else:
+                    await conversation.add_user_message(f"[External event]: {content}")
                 count += 1
             except asyncio.QueueEmpty:
                 break
@@ -2301,36 +2554,93 @@ class EventLoopNode(NodeProtocol):
     # EventBus publishing helpers
     # -------------------------------------------------------------------
 
-    async def _publish_loop_started(self, stream_id: str, node_id: str) -> None:
+    async def _publish_loop_started(
+        self, stream_id: str, node_id: str, execution_id: str = ""
+    ) -> None:
         if self._event_bus:
             await self._event_bus.emit_node_loop_started(
                 stream_id=stream_id,
                 node_id=node_id,
                 max_iterations=self._config.max_iterations,
+                execution_id=execution_id,
             )
 
-    async def _publish_iteration(self, stream_id: str, node_id: str, iteration: int) -> None:
+    async def _generate_action_plan(
+        self,
+        ctx: NodeContext,
+        stream_id: str,
+        node_id: str,
+        execution_id: str,
+    ) -> None:
+        """Generate a brief action plan via LLM and emit it as an SSE event.
+
+        Runs as a fire-and-forget task so it never blocks the main loop.
+        """
+        try:
+            system_prompt = ctx.node_spec.system_prompt or ""
+            # Trim to keep the prompt small
+            prompt_summary = system_prompt[:500]
+            if len(system_prompt) > 500:
+                prompt_summary += "..."
+
+            tool_names = [t.name for t in ctx.available_tools]
+            output_keys = ctx.node_spec.output_keys or []
+
+            prompt = (
+                f'You are about to work on a task as node "{node_id}".\n\n'
+                f"System prompt:\n{prompt_summary}\n\n"
+                f"Tools available: {tool_names}\n"
+                f"Required outputs: {output_keys}\n\n"
+                f"Write a brief action plan (2-5 bullet points) describing "
+                f"what you will do to complete this task. Be specific and concise.\n"
+                f"Return ONLY the plan text, no preamble."
+            )
+
+            response = await ctx.llm.acomplete(
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=300,
+            )
+
+            plan = response.content.strip()
+            if plan and self._event_bus:
+                await self._event_bus.emit_node_action_plan(
+                    stream_id=stream_id,
+                    node_id=node_id,
+                    plan=plan,
+                    execution_id=execution_id,
+                )
+        except Exception as e:
+            logger.warning("Action plan generation failed for node '%s': %s", node_id, e)
+
+    async def _publish_iteration(
+        self, stream_id: str, node_id: str, iteration: int, execution_id: str = ""
+    ) -> None:
         if self._event_bus:
             await self._event_bus.emit_node_loop_iteration(
                 stream_id=stream_id,
                 node_id=node_id,
                 iteration=iteration,
+                execution_id=execution_id,
             )
 
-    async def _publish_loop_completed(self, stream_id: str, node_id: str, iterations: int) -> None:
+    async def _publish_loop_completed(
+        self, stream_id: str, node_id: str, iterations: int, execution_id: str = ""
+    ) -> None:
         if self._event_bus:
             await self._event_bus.emit_node_loop_completed(
                 stream_id=stream_id,
                 node_id=node_id,
                 iterations=iterations,
+                execution_id=execution_id,
             )
 
-    async def _publish_stalled(self, stream_id: str, node_id: str) -> None:
+    async def _publish_stalled(self, stream_id: str, node_id: str, execution_id: str = "") -> None:
         if self._event_bus:
             await self._event_bus.emit_node_stalled(
                 stream_id=stream_id,
                 node_id=node_id,
                 reason="Consecutive identical responses detected",
+                execution_id=execution_id,
             )
 
     async def _publish_text_delta(
@@ -2340,6 +2650,7 @@ class EventLoopNode(NodeProtocol):
         content: str,
         snapshot: str,
         ctx: NodeContext,
+        execution_id: str = "",
     ) -> None:
         if self._event_bus:
             if ctx.node_spec.client_facing:
@@ -2348,6 +2659,7 @@ class EventLoopNode(NodeProtocol):
                     node_id=node_id,
                     content=content,
                     snapshot=snapshot,
+                    execution_id=execution_id,
                 )
             else:
                 await self._event_bus.emit_llm_text_delta(
@@ -2355,6 +2667,7 @@ class EventLoopNode(NodeProtocol):
                     node_id=node_id,
                     content=content,
                     snapshot=snapshot,
+                    execution_id=execution_id,
                 )
 
     async def _publish_tool_started(
@@ -2364,6 +2677,7 @@ class EventLoopNode(NodeProtocol):
         tool_use_id: str,
         tool_name: str,
         tool_input: dict,
+        execution_id: str = "",
     ) -> None:
         if self._event_bus:
             await self._event_bus.emit_tool_call_started(
@@ -2372,6 +2686,7 @@ class EventLoopNode(NodeProtocol):
                 tool_use_id=tool_use_id,
                 tool_name=tool_name,
                 tool_input=tool_input,
+                execution_id=execution_id,
             )
 
     async def _publish_tool_completed(
@@ -2382,6 +2697,7 @@ class EventLoopNode(NodeProtocol):
         tool_name: str,
         result: str,
         is_error: bool,
+        execution_id: str = "",
     ) -> None:
         if self._event_bus:
             await self._event_bus.emit_tool_call_completed(
@@ -2391,6 +2707,7 @@ class EventLoopNode(NodeProtocol):
                 tool_name=tool_name,
                 result=result,
                 is_error=is_error,
+                execution_id=execution_id,
             )
 
     async def _publish_judge_verdict(
@@ -2401,6 +2718,7 @@ class EventLoopNode(NodeProtocol):
         feedback: str = "",
         judge_type: str = "implicit",
         iteration: int = 0,
+        execution_id: str = "",
     ) -> None:
         if self._event_bus:
             await self._event_bus.emit_judge_verdict(
@@ -2410,6 +2728,7 @@ class EventLoopNode(NodeProtocol):
                 feedback=feedback,
                 judge_type=judge_type,
                 iteration=iteration,
+                execution_id=execution_id,
             )
 
     async def _publish_output_key_set(
@@ -2417,10 +2736,12 @@ class EventLoopNode(NodeProtocol):
         stream_id: str,
         node_id: str,
         key: str,
+        execution_id: str = "",
     ) -> None:
         if self._event_bus:
             await self._event_bus.emit_output_key_set(
                 stream_id=stream_id,
                 node_id=node_id,
                 key=key,
+                execution_id=execution_id,
             )

core/framework/graph/executor.py

@@ -11,7 +11,6 @@ The executor:
 
 import asyncio
 import logging
-import warnings
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -21,13 +20,10 @@ from framework.graph.checkpoint_config import CheckpointConfig
 from framework.graph.edge import EdgeCondition, EdgeSpec, GraphSpec
 from framework.graph.goal import Goal
 from framework.graph.node import (
-    FunctionNode,
-    LLMNode,
     NodeContext,
     NodeProtocol,
     NodeResult,
     NodeSpec,
-    RouterNode,
     SharedMemory,
 )
 from framework.graph.output_cleaner import CleansingConfig, OutputCleaner
@@ -135,9 +131,13 @@ class GraphExecutor:
         parallel_config: ParallelExecutionConfig | None = None,
         event_bus: Any | None = None,
         stream_id: str = "",
+        execution_id: str = "",
         runtime_logger: Any = None,
         storage_path: str | Path | None = None,
         loop_config: dict[str, Any] | None = None,
+        accounts_prompt: str = "",
+        accounts_data: list[dict] | None = None,
+        tool_provider_map: dict[str, str] | None = None,
     ):
         """
         Initialize the executor.
@@ -157,6 +157,9 @@ class GraphExecutor:
             runtime_logger: Optional RuntimeLogger for per-graph-run logging
             storage_path: Optional base path for conversation persistence
             loop_config: Optional EventLoopNode configuration (max_iterations, etc.)
+            accounts_prompt: Connected accounts block for system prompt injection
+            accounts_data: Raw account data for per-node prompt generation
+            tool_provider_map: Tool name to provider name mapping for account routing
         """
         self.runtime = runtime
         self.llm = llm
@@ -168,9 +171,13 @@ class GraphExecutor:
         self.logger = logging.getLogger(__name__)
         self._event_bus = event_bus
         self._stream_id = stream_id
+        self._execution_id = execution_id or getattr(runtime, "execution_id", "")
         self.runtime_logger = runtime_logger
         self._storage_path = Path(storage_path) if storage_path else None
         self._loop_config = loop_config or {}
+        self.accounts_prompt = accounts_prompt
+        self.accounts_data = accounts_data
+        self.tool_provider_map = tool_provider_map
 
         # Initialize output cleaner
         self.cleansing_config = cleansing_config or CleansingConfig()
@@ -237,7 +244,12 @@ class GraphExecutor:
 
     def _validate_tools(self, graph: GraphSpec) -> list[str]:
         """
-        Validate that all tools declared by nodes are available.
+        Validate that all tools declared by reachable nodes are available.
+
+        Only checks nodes reachable from graph.entry_node via edges.
+        Nodes belonging to other entry points (e.g. the coder node when
+        entering via ticket_triage) are skipped — they will be validated
+        when their own entry point triggers execution.
 
         Returns:
             List of error messages (empty if all tools are available)
@@ -245,7 +257,20 @@ class GraphExecutor:
         errors = []
         available_tool_names = {t.name for t in self.tools}
 
+        # Compute reachable nodes from the execution's entry node
+        reachable: set[str] = set()
+        to_visit = [graph.entry_node]
+        while to_visit:
+            nid = to_visit.pop()
+            if nid in reachable:
+                continue
+            reachable.add(nid)
+            for edge in graph.get_outgoing_edges(nid):
+                to_visit.append(edge.target)
+
         for node in graph.nodes:
+            if node.id not in reachable:
+                continue
             if node.tools:
                 missing = set(node.tools) - available_tool_names
                 if missing:
@@ -346,6 +371,9 @@ class GraphExecutor:
             for key, value in input_data.items():
                 memory.write(key, value)
 
+        # Detect event-triggered execution (timer/webhook) — no interactive user.
+        _event_triggered = bool(input_data and isinstance(input_data.get("event"), dict))
+
         path: list[str] = []
         total_tokens = 0
         total_latency = 0
@@ -473,7 +501,7 @@ class GraphExecutor:
             try:
                 from framework.storage.conversation_store import FileConversationStore
 
-                entry_conv_path = self._storage_path / "conversations" / current_node_id
+                entry_conv_path = self._storage_path / "conversations"
                 if entry_conv_path.exists():
                     _store = FileConversationStore(base_path=entry_conv_path)
 
@@ -527,6 +555,7 @@ class GraphExecutor:
                 await self._event_bus.emit_execution_resumed(
                     stream_id=self._stream_id,
                     node_id=current_node_id,
+                    execution_id=self._execution_id,
                 )
 
         # Start run
@@ -571,6 +600,7 @@ class GraphExecutor:
                             stream_id=self._stream_id,
                             node_id=current_node_id,
                             reason="User requested pause (Ctrl+Z)",
+                            execution_id=self._execution_id,
                         )
 
                     # Create session state for pause
@@ -619,7 +649,7 @@ class GraphExecutor:
                     cnt = node_visit_counts.get(current_node_id, 0) + 1
                     node_visit_counts[current_node_id] = cnt
                 _is_retry = False
-                max_visits = getattr(node_spec, "max_node_visits", 1)
+                max_visits = getattr(node_spec, "max_node_visits", 0)
                 if max_visits > 0 and node_visit_counts[current_node_id] > max_visits:
                     self.logger.warning(
                         f"   ⊘ Node '{node_spec.name}' visit limit reached "
@@ -690,6 +720,7 @@ class GraphExecutor:
                     inherited_conversation=continuous_conversation if is_continuous else None,
                     override_tools=cumulative_tools if is_continuous else None,
                     cumulative_output_keys=cumulative_output_keys if is_continuous else None,
+                    event_triggered=_event_triggered,
                 )
 
                 # Log actual input data being read
@@ -740,7 +771,9 @@ class GraphExecutor:
                 # Emit node-started event (skip event_loop nodes — they emit their own)
                 if self._event_bus and node_spec.node_type != "event_loop":
                     await self._event_bus.emit_node_loop_started(
-                        stream_id=self._stream_id, node_id=current_node_id
+                        stream_id=self._stream_id,
+                        node_id=current_node_id,
+                        execution_id=self._execution_id,
                     )
 
                 # Execute node
@@ -750,7 +783,10 @@ class GraphExecutor:
                 # Emit node-completed event (skip event_loop nodes)
                 if self._event_bus and node_spec.node_type != "event_loop":
                     await self._event_bus.emit_node_loop_completed(
-                        stream_id=self._stream_id, node_id=current_node_id, iterations=1
+                        stream_id=self._stream_id,
+                        node_id=current_node_id,
+                        iterations=1,
+                        execution_id=self._execution_id,
                     )
 
                 # Ensure runtime logging has an L2 entry for this node
@@ -833,9 +869,13 @@ class GraphExecutor:
                     # [CORRECTED] Use node_spec.max_retries instead of hardcoded 3
                     max_retries = getattr(node_spec, "max_retries", 3)
 
-                    # Event loop nodes handle retry internally via judge —
-                    # executor retry is catastrophic (retry multiplication)
-                    if node_spec.node_type == "event_loop" and max_retries > 0:
+                    # EventLoopNode instances handle retry internally via judge —
+                    # executor retry would cause catastrophic retry multiplication.
+                    # Only override for actual EventLoopNode instances, not custom
+                    # NodeProtocol implementations that happen to use node_type="event_loop"
+                    from framework.graph.event_loop_node import EventLoopNode
+
+                    if isinstance(node_impl, EventLoopNode) and max_retries > 0:
                         self.logger.warning(
                             f"EventLoopNode '{node_spec.id}' has max_retries={max_retries}. "
                             "Overriding to 0 — event loop nodes handle retry internally via judge."
@@ -866,6 +906,7 @@ class GraphExecutor:
                                 retry_count=retry_count,
                                 max_retries=max_retries,
                                 error=result.error or "",
+                                execution_id=self._execution_id,
                             )
 
                         _is_retry = True
@@ -961,6 +1002,7 @@ class GraphExecutor:
                             stream_id=self._stream_id,
                             node_id=node_spec.id,
                             reason="HITL pause node",
+                            execution_id=self._execution_id,
                         )
 
                     saved_memory = memory.read_all()
@@ -1026,6 +1068,7 @@ class GraphExecutor:
                             source_node=current_node_id,
                             target_node=result.next_node,
                             edge_condition="router",
+                            execution_id=self._execution_id,
                         )
 
                     current_node_id = result.next_node
@@ -1061,6 +1104,7 @@ class GraphExecutor:
                                     edge_condition=edge.condition.value
                                     if hasattr(edge.condition, "value")
                                     else str(edge.condition),
+                                    execution_id=self._execution_id,
                                 )
 
                         # Execute branches in parallel
@@ -1112,6 +1156,7 @@ class GraphExecutor:
                                 stream_id=self._stream_id,
                                 source_node=current_node_id,
                                 target_node=next_node,
+                                execution_id=self._execution_id,
                             )
 
                         # CHECKPOINT: node_complete (after determining next node)
@@ -1159,6 +1204,7 @@ class GraphExecutor:
                     next_spec = graph.get_node(current_node_id)
                     if next_spec and next_spec.node_type == "event_loop":
                         from framework.graph.prompt_composer import (
+                            build_accounts_prompt,
                             build_narrative,
                             build_transition_marker,
                             compose_system_prompt,
@@ -1167,26 +1213,44 @@ class GraphExecutor:
                         # Build Layer 2 (narrative) from current state
                         narrative = build_narrative(memory, path, graph)
 
-                        # Compose new system prompt (Layer 1 + 2 + 3)
+                        # Read agent working memory (adapt.md) once for both
+                        # system prompt and transition marker.
+                        _adapt_text: str | None = None
+                        if self._storage_path:
+                            _adapt_path = self._storage_path / "data" / "adapt.md"
+                            if _adapt_path.exists():
+                                _raw = _adapt_path.read_text(encoding="utf-8").strip()
+                                _adapt_text = _raw or None
+
+                        # Merge adapt.md into narrative for system prompt
+                        if _adapt_text:
+                            narrative = (
+                                f"{narrative}\n\n--- Agent Memory ---\n{_adapt_text}"
+                                if narrative
+                                else _adapt_text
+                            )
+
+                        # Build per-node accounts prompt for the next node
+                        _node_accounts = self.accounts_prompt or None
+                        if self.accounts_data and self.tool_provider_map:
+                            _node_accounts = (
+                                build_accounts_prompt(
+                                    self.accounts_data,
+                                    self.tool_provider_map,
+                                    node_tool_names=next_spec.tools,
+                                )
+                                or None
+                            )
+
+                        # Compose new system prompt (Layer 1 + 2 + 3 + accounts)
                         new_system = compose_system_prompt(
                             identity_prompt=getattr(graph, "identity_prompt", None),
                             focus_prompt=next_spec.system_prompt,
                             narrative=narrative,
+                            accounts_prompt=_node_accounts,
                         )
                         continuous_conversation.update_system_prompt(new_system)
 
-                        # Switch conversation store to the next node's directory
-                        # so the transition marker and all subsequent messages are
-                        # persisted there instead of the first node's directory.
-                        if self._storage_path:
-                            from framework.storage.conversation_store import (
-                                FileConversationStore,
-                            )
-
-                            next_store_path = self._storage_path / "conversations" / next_spec.id
-                            next_store = FileConversationStore(base_path=next_store_path)
-                            await continuous_conversation.switch_store(next_store)
-
                         # Insert transition marker into conversation
                         data_dir = str(self._storage_path / "data") if self._storage_path else None
                         marker = build_transition_marker(
@@ -1195,6 +1259,7 @@ class GraphExecutor:
                             memory=memory,
                             cumulative_tool_names=sorted(cumulative_tool_names),
                             data_dir=data_dir,
+                            adapt_content=_adapt_text,
                         )
                         await continuous_conversation.add_user_message(
                             marker,
@@ -1290,6 +1355,34 @@ class GraphExecutor:
             # Handle cancellation (e.g., TUI quit) - save as paused instead of failed
             self.logger.info("⏸ Execution cancelled - saving state for resume")
 
+            # Flush WIP accumulator outputs from the interrupted node's
+            # cursor.json into SharedMemory so they survive resume.  The
+            # accumulator writes to cursor.json on every set() call, but
+            # only writes to SharedMemory when the judge ACCEPTs.  Without
+            # this, edge conditions checking these keys see None on resume.
+            if current_node_id and self._storage_path:
+                try:
+                    import json as _json
+
+                    cursor_path = self._storage_path / "conversations" / "cursor.json"
+                    if cursor_path.exists():
+                        cursor_data = _json.loads(cursor_path.read_text(encoding="utf-8"))
+                        wip_outputs = cursor_data.get("outputs", {})
+                        for key, value in wip_outputs.items():
+                            if value is not None:
+                                memory.write(key, value, validate=False)
+                        if wip_outputs:
+                            self.logger.info(
+                                "Flushed %d WIP accumulator outputs to memory: %s",
+                                len(wip_outputs),
+                                list(wip_outputs.keys()),
+                            )
+                except Exception:
+                    self.logger.debug(
+                        "Could not flush accumulator outputs from cursor",
+                        exc_info=True,
+                    )
+
             # Save memory and state for resume
             saved_memory = memory.read_all()
             session_state_out: dict[str, Any] = {
@@ -1367,6 +1460,23 @@ class GraphExecutor:
                     execution_quality="failed",
                 )
 
+            # Flush WIP accumulator outputs (same as CancelledError path)
+            if current_node_id and self._storage_path:
+                try:
+                    import json as _json
+
+                    cursor_path = self._storage_path / "conversations" / "cursor.json"
+                    if cursor_path.exists():
+                        cursor_data = _json.loads(cursor_path.read_text(encoding="utf-8"))
+                        for key, value in cursor_data.get("outputs", {}).items():
+                            if value is not None:
+                                memory.write(key, value, validate=False)
+                except Exception:
+                    self.logger.debug(
+                        "Could not flush accumulator outputs from cursor",
+                        exc_info=True,
+                    )
+
             # Save memory and state for potential resume
             saved_memory = memory.read_all()
             session_state_out: dict[str, Any] = {
@@ -1430,6 +1540,7 @@ class GraphExecutor:
         inherited_conversation: Any = None,
         override_tools: list | None = None,
         cumulative_output_keys: list[str] | None = None,
+        event_triggered: bool = False,
     ) -> NodeContext:
         """Build execution context for a node."""
         # Filter tools to those available to this node
@@ -1447,6 +1558,17 @@ class GraphExecutor:
             write_keys=node_spec.output_keys,
         )
 
+        # Build per-node accounts prompt (filtered to this node's tools)
+        node_accounts_prompt = self.accounts_prompt
+        if self.accounts_data and self.tool_provider_map:
+            from framework.graph.prompt_composer import build_accounts_prompt
+
+            node_accounts_prompt = build_accounts_prompt(
+                self.accounts_data,
+                self.tool_provider_map,
+                node_tool_names=node_spec.tools,
+            )
+
         return NodeContext(
             runtime=self.runtime,
             node_id=node_spec.id,
@@ -1463,18 +1585,23 @@ class GraphExecutor:
             continuous_mode=continuous_mode,
             inherited_conversation=inherited_conversation,
             cumulative_output_keys=cumulative_output_keys or [],
+            event_triggered=event_triggered,
+            accounts_prompt=node_accounts_prompt,
+            execution_id=self._execution_id,
+            stream_id=self._stream_id,
         )
 
-    # Valid node types - no ambiguous "llm" type allowed
     VALID_NODE_TYPES = {
-        "llm_tool_use",
-        "llm_generate",
-        "router",
-        "function",
-        "human_input",
         "event_loop",
     }
-    DEPRECATED_NODE_TYPES = {"llm_tool_use": "event_loop", "llm_generate": "event_loop"}
+    # Node types removed in v0.5 — provide migration guidance
+    REMOVED_NODE_TYPES = {
+        "function": "event_loop",
+        "llm_tool_use": "event_loop",
+        "llm_generate": "event_loop",
+        "router": "event_loop",  # Unused theoretical infrastructure
+        "human_input": "event_loop",  # Use client_facing=True instead
+    }
 
     def _get_node_implementation(
         self, node_spec: NodeSpec, cleanup_llm_model: str | None = None
@@ -1484,62 +1611,23 @@ class GraphExecutor:
         if node_spec.id in self.node_registry:
             return self.node_registry[node_spec.id]
 
+        # Reject removed node types with migration guidance
+        if node_spec.node_type in self.REMOVED_NODE_TYPES:
+            replacement = self.REMOVED_NODE_TYPES[node_spec.node_type]
+            raise RuntimeError(
+                f"Node type '{node_spec.node_type}' was removed in v0.5. "
+                f"Migrate node '{node_spec.id}' to '{replacement}'. "
+                f"See https://github.com/adenhq/hive/issues/4753 for migration guide."
+            )
+
         # Validate node type
         if node_spec.node_type not in self.VALID_NODE_TYPES:
             raise RuntimeError(
                 f"Invalid node type '{node_spec.node_type}' for node '{node_spec.id}'. "
-                f"Must be one of: {sorted(self.VALID_NODE_TYPES)}. "
-                f"Use 'llm_tool_use' for nodes that call tools, 'llm_generate' for text generation."
-            )
-
-        # Warn on deprecated node types
-        if node_spec.node_type in self.DEPRECATED_NODE_TYPES:
-            replacement = self.DEPRECATED_NODE_TYPES[node_spec.node_type]
-            warnings.warn(
-                f"Node type '{node_spec.node_type}' is deprecated. "
-                f"Use '{replacement}' instead. "
-                f"Node: '{node_spec.id}'",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-
-        # Create based on type
-        if node_spec.node_type == "llm_tool_use":
-            if not node_spec.tools:
-                raise RuntimeError(
-                    f"Node '{node_spec.id}' is type 'llm_tool_use' but declares no tools. "
-                    "Either add tools to the node or change type to 'llm_generate'."
-                )
-            return LLMNode(
-                tool_executor=self.tool_executor,
-                require_tools=True,
-                cleanup_llm_model=cleanup_llm_model,
-            )
-
-        if node_spec.node_type == "llm_generate":
-            return LLMNode(
-                tool_executor=None,
-                require_tools=False,
-                cleanup_llm_model=cleanup_llm_model,
-            )
-
-        if node_spec.node_type == "router":
-            return RouterNode()
-
-        if node_spec.node_type == "function":
-            # Function nodes need explicit registration
-            raise RuntimeError(
-                f"Function node '{node_spec.id}' not registered. Register with node_registry."
-            )
-
-        if node_spec.node_type == "human_input":
-            # Human input nodes are handled specially by HITL mechanism
-            return LLMNode(
-                tool_executor=None,
-                require_tools=False,
-                cleanup_llm_model=cleanup_llm_model,
+                f"Must be one of: {sorted(self.VALID_NODE_TYPES)}."
             )
 
+        # Create based on type (only event_loop is valid)
         if node_spec.node_type == "event_loop":
             # Auto-create EventLoopNode with sensible defaults.
             # Custom configs can still be pre-registered via node_registry.
@@ -1550,7 +1638,7 @@ class GraphExecutor:
             if self._storage_path:
                 from framework.storage.conversation_store import FileConversationStore
 
-                store_path = self._storage_path / "conversations" / node_spec.id
+                store_path = self._storage_path / "conversations"
                 conv_store = FileConversationStore(base_path=store_path)
 
             # Auto-configure spillover directory for large tool results.
@@ -1799,14 +1887,19 @@ class GraphExecutor:
                 branch.error = f"Node {branch.node_id} not found in graph"
                 return branch, RuntimeError(branch.error)
 
+            # Get node implementation to check its type
+            branch_impl = self._get_node_implementation(node_spec, graph.cleanup_llm_model)
+
             effective_max_retries = node_spec.max_retries
-            if node_spec.node_type == "event_loop":
-                if effective_max_retries > 1:
-                    self.logger.warning(
-                        f"EventLoopNode '{node_spec.id}' has "
-                        f"max_retries={effective_max_retries}. Overriding "
-                        "to 1 — event loop nodes handle retry internally."
-                    )
+            # Only override for actual EventLoopNode instances, not custom NodeProtocol impls
+            from framework.graph.event_loop_node import EventLoopNode
+
+            if isinstance(branch_impl, EventLoopNode) and effective_max_retries > 1:
+                self.logger.warning(
+                    f"EventLoopNode '{node_spec.id}' has "
+                    f"max_retries={effective_max_retries}. Overriding "
+                    "to 1 — event loop nodes handle retry internally."
+                )
                 effective_max_retries = 1
 
             branch.status = "running"
@@ -1855,7 +1948,9 @@ class GraphExecutor:
                     # Emit node-started event (skip event_loop nodes)
                     if self._event_bus and node_spec.node_type != "event_loop":
                         await self._event_bus.emit_node_loop_started(
-                            stream_id=self._stream_id, node_id=branch.node_id
+                            stream_id=self._stream_id,
+                            node_id=branch.node_id,
+                            execution_id=self._execution_id,
                         )
 
                     self.logger.info(
@@ -1879,7 +1974,10 @@ class GraphExecutor:
                     # Emit node-completed event (skip event_loop nodes)
                     if self._event_bus and node_spec.node_type != "event_loop":
                         await self._event_bus.emit_node_loop_completed(
-                            stream_id=self._stream_id, node_id=branch.node_id, iterations=1
+                            stream_id=self._stream_id,
+                            node_id=branch.node_id,
+                            iterations=1,
+                            execution_id=self._execution_id,
                         )
 
                     if result.success:
@@ -1972,10 +2070,6 @@ class GraphExecutor:
         """Register a custom node implementation."""
         self.node_registry[node_id] = implementation
 
-    def register_function(self, node_id: str, func: Callable) -> None:
-        """Register a function as a node."""
-        self.node_registry[node_id] = FunctionNode(func)
-
     def request_pause(self) -> None:
         """
         Request graceful pause of the current execution.

core/framework/graph/flexible_executor.py

@@ -1,552 +0,0 @@
-"""
-Flexible Graph Executor with Worker-Judge Loop.
-
-Executes plans created by external planner (Claude Code, etc.)
-using a Worker-Judge loop:
-
-1. External planner creates Plan
-2. FlexibleGraphExecutor receives Plan
-3. Worker executes each step
-4. Judge evaluates each result
-5. If Judge says "replan" → return to external planner with feedback
-6. If Judge says "escalate" → request human intervention
-7. If all steps complete → return success
-
-This keeps planning external while execution/evaluation is internal.
-"""
-
-from collections.abc import Callable
-from dataclasses import dataclass
-from datetime import datetime
-from typing import Any
-
-from framework.graph.code_sandbox import CodeSandbox
-from framework.graph.goal import Goal
-from framework.graph.judge import HybridJudge, create_default_judge
-from framework.graph.plan import (
-    ApprovalDecision,
-    ApprovalRequest,
-    ApprovalResult,
-    ExecutionStatus,
-    Judgment,
-    JudgmentAction,
-    Plan,
-    PlanExecutionResult,
-    PlanStep,
-    StepStatus,
-)
-from framework.graph.worker_node import StepExecutionResult, WorkerNode
-from framework.llm.provider import LLMProvider, Tool
-from framework.runtime.core import Runtime
-
-# Type alias for approval callback
-ApprovalCallback = Callable[[ApprovalRequest], ApprovalResult]
-
-
-@dataclass
-class ExecutorConfig:
-    """Configuration for FlexibleGraphExecutor."""
-
-    max_retries_per_step: int = 3
-    max_total_steps: int = 100
-    timeout_seconds: int = 300
-    enable_parallel_execution: bool = False  # Future: parallel step execution
-
-
-class FlexibleGraphExecutor:
-    """
-    Executes plans with Worker-Judge loop.
-
-    Plans come from external source (Claude Code, etc.).
-    Returns feedback for replanning if needed.
-
-    Usage:
-        executor = FlexibleGraphExecutor(
-            runtime=runtime,
-            llm=llm_provider,
-            tools=tools,
-        )
-
-        result = await executor.execute_plan(plan, goal, context)
-
-        if result.status == ExecutionStatus.NEEDS_REPLAN:
-            # External planner should create new plan using result.feedback
-            new_plan = external_planner.replan(result.feedback_context)
-            result = await executor.execute_plan(new_plan, goal, result.feedback_context)
-    """
-
-    def __init__(
-        self,
-        runtime: Runtime,
-        llm: LLMProvider | None = None,
-        tools: dict[str, Tool] | None = None,
-        tool_executor: Callable | None = None,
-        functions: dict[str, Callable] | None = None,
-        judge: HybridJudge | None = None,
-        config: ExecutorConfig | None = None,
-        approval_callback: ApprovalCallback | None = None,
-    ):
-        """
-        Initialize the FlexibleGraphExecutor.
-
-        Args:
-            runtime: Runtime for decision logging
-            llm: LLM provider for Worker and Judge
-            tools: Available tools
-            tool_executor: Function to execute tools
-            functions: Registered functions
-            judge: Custom judge (defaults to HybridJudge with default rules)
-            config: Executor configuration
-            approval_callback: Callback for human-in-the-loop approval.
-                If None, steps requiring approval will pause execution.
-        """
-        self.runtime = runtime
-        self.llm = llm
-        self.tools = tools or {}
-        self.tool_executor = tool_executor
-        self.functions = functions or {}
-        self.config = config or ExecutorConfig()
-        self.approval_callback = approval_callback
-
-        # Create judge
-        self.judge = judge or create_default_judge(llm)
-
-        # Create worker
-        self.worker = WorkerNode(
-            runtime=runtime,
-            llm=llm,
-            tools=tools,
-            tool_executor=tool_executor,
-            functions=functions,
-            sandbox=CodeSandbox(),
-        )
-
-    async def execute_plan(
-        self,
-        plan: Plan,
-        goal: Goal,
-        context: dict[str, Any] | None = None,
-    ) -> PlanExecutionResult:
-        """
-        Execute a plan created by external planner.
-
-        Args:
-            plan: The plan to execute
-            goal: The goal context
-            context: Initial context (e.g., from previous execution)
-
-        Returns:
-            PlanExecutionResult with status and feedback
-        """
-        context = context or {}
-        context.update(plan.context)  # Merge plan's accumulated context
-
-        # Start run
-        _run_id = self.runtime.start_run(
-            goal_id=goal.id,
-            goal_description=goal.description,
-            input_data={"plan_id": plan.id, "revision": plan.revision},
-        )
-
-        steps_executed = 0
-        total_tokens = 0
-        total_latency = 0
-
-        try:
-            while steps_executed < self.config.max_total_steps:
-                # Get next ready steps
-                ready_steps = plan.get_ready_steps()
-
-                if not ready_steps:
-                    # Check if we're done or stuck
-                    if plan.is_complete():
-                        break
-                    else:
-                        # No ready steps but not complete - something's wrong
-                        return self._create_result(
-                            status=ExecutionStatus.NEEDS_REPLAN,
-                            plan=plan,
-                            context=context,
-                            feedback=(
-                                "No executable steps available but plan not complete. "
-                                "Check dependencies."
-                            ),
-                            steps_executed=steps_executed,
-                            total_tokens=total_tokens,
-                            total_latency=total_latency,
-                        )
-
-                # Execute next step (for now, sequential; could be parallel)
-                step = ready_steps[0]
-                # Debug: show ready steps
-                # ready_ids = [s.id for s in ready_steps]
-                # print(f"  [DEBUG] Ready steps: {ready_ids}, executing: {step.id}")
-
-                # APPROVAL CHECK - before execution
-                if step.requires_approval:
-                    approval_result = await self._request_approval(step, context)
-
-                    if approval_result is None:
-                        # No callback, pause execution
-                        step.status = StepStatus.AWAITING_APPROVAL
-                        return self._create_result(
-                            status=ExecutionStatus.AWAITING_APPROVAL,
-                            plan=plan,
-                            context=context,
-                            feedback=f"Step '{step.id}' requires approval: {step.description}",
-                            steps_executed=steps_executed,
-                            total_tokens=total_tokens,
-                            total_latency=total_latency,
-                        )
-
-                    if approval_result.decision == ApprovalDecision.REJECT:
-                        step.status = StepStatus.REJECTED
-                        step.error = approval_result.reason or "Rejected by human"
-                        # Skip this step and continue with dependents marked as skipped
-                        self._skip_dependent_steps(plan, step.id)
-                        continue
-
-                    if approval_result.decision == ApprovalDecision.ABORT:
-                        return self._create_result(
-                            status=ExecutionStatus.ABORTED,
-                            plan=plan,
-                            context=context,
-                            feedback=approval_result.reason or "Aborted by human",
-                            steps_executed=steps_executed,
-                            total_tokens=total_tokens,
-                            total_latency=total_latency,
-                        )
-
-                    if approval_result.decision == ApprovalDecision.MODIFY:
-                        # Apply modifications to step
-                        if approval_result.modifications:
-                            self._apply_modifications(step, approval_result.modifications)
-
-                    # APPROVE - continue to execution
-
-                step.status = StepStatus.IN_PROGRESS
-                step.started_at = datetime.now()
-                step.attempts += 1
-
-                # WORK
-                work_result = await self.worker.execute(step, context)
-                steps_executed += 1
-                total_tokens += work_result.tokens_used
-                total_latency += work_result.latency_ms
-
-                # JUDGE
-                judgment = await self.judge.evaluate(
-                    step=step,
-                    result=work_result.__dict__,
-                    goal=goal,
-                    context=context,
-                )
-
-                # Handle judgment
-                result = await self._handle_judgment(
-                    step=step,
-                    work_result=work_result,
-                    judgment=judgment,
-                    plan=plan,
-                    goal=goal,
-                    context=context,
-                    steps_executed=steps_executed,
-                    total_tokens=total_tokens,
-                    total_latency=total_latency,
-                )
-
-                if result is not None:
-                    # Judgment resulted in early return (replan/escalate)
-                    self.runtime.end_run(
-                        success=False,
-                        narrative=f"Execution stopped: {result.status.value}",
-                    )
-                    return result
-
-            # All steps completed successfully
-            self.runtime.end_run(
-                success=True,
-                output_data=context,
-                narrative=f"Plan completed: {steps_executed} steps executed",
-            )
-
-            return self._create_result(
-                status=ExecutionStatus.COMPLETED,
-                plan=plan,
-                context=context,
-                steps_executed=steps_executed,
-                total_tokens=total_tokens,
-                total_latency=total_latency,
-            )
-
-        except Exception as e:
-            self.runtime.report_problem(
-                severity="critical",
-                description=str(e),
-            )
-            self.runtime.end_run(
-                success=False,
-                narrative=f"Execution failed: {e}",
-            )
-
-            return PlanExecutionResult(
-                status=ExecutionStatus.FAILED,
-                error=str(e),
-                feedback=f"Execution error: {e}",
-                feedback_context=plan.to_feedback_context(),
-                completed_steps=[s.id for s in plan.get_completed_steps()],
-                steps_executed=steps_executed,
-                total_tokens=total_tokens,
-                total_latency_ms=total_latency,
-            )
-
-    async def _handle_judgment(
-        self,
-        step: PlanStep,
-        work_result: StepExecutionResult,
-        judgment: Judgment,
-        plan: Plan,
-        goal: Goal,
-        context: dict[str, Any],
-        steps_executed: int,
-        total_tokens: int,
-        total_latency: int,
-    ) -> PlanExecutionResult | None:
-        """
-        Handle judgment and return result if execution should stop.
-
-        Returns None to continue execution, or PlanExecutionResult to stop.
-        """
-        if judgment.action == JudgmentAction.ACCEPT:
-            # Step succeeded - update state and continue
-            step.status = StepStatus.COMPLETED
-            step.completed_at = datetime.now()
-            step.result = work_result.outputs
-
-            # Map outputs to expected output keys
-            # If output has generic "result" key but step expects specific keys, map it
-            outputs_to_store = work_result.outputs.copy()
-            if step.expected_outputs and "result" in outputs_to_store:
-                result_value = outputs_to_store["result"]
-                # For each expected output key that's not in outputs, map from "result"
-                for expected_key in step.expected_outputs:
-                    if expected_key not in outputs_to_store:
-                        outputs_to_store[expected_key] = result_value
-
-            # Update context with mapped outputs
-            context.update(outputs_to_store)
-
-            # Store in plan context for replanning feedback
-            plan.context[step.id] = outputs_to_store
-
-            return None  # Continue execution
-
-        elif judgment.action == JudgmentAction.RETRY:
-            # Retry step if under limit
-            if step.attempts < step.max_retries:
-                step.status = StepStatus.PENDING
-                step.error = judgment.feedback
-
-                # Record retry decision
-                self.runtime.decide(
-                    intent=f"Retry step {step.id}",
-                    options=[{"id": "retry", "description": "Retry with feedback"}],
-                    chosen="retry",
-                    reasoning=judgment.reasoning,
-                    context={"attempt": step.attempts, "feedback": judgment.feedback},
-                )
-
-                return None  # Continue (step will be retried)
-            else:
-                # Max retries exceeded - escalate to replan
-                step.status = StepStatus.FAILED
-                step.error = f"Max retries ({step.max_retries}) exceeded: {judgment.feedback}"
-
-                return self._create_result(
-                    status=ExecutionStatus.NEEDS_REPLAN,
-                    plan=plan,
-                    context=context,
-                    feedback=(
-                        f"Step '{step.id}' failed after {step.attempts} attempts: "
-                        f"{judgment.feedback}"
-                    ),
-                    steps_executed=steps_executed,
-                    total_tokens=total_tokens,
-                    total_latency=total_latency,
-                )
-
-        elif judgment.action == JudgmentAction.REPLAN:
-            # Return to external planner
-            step.status = StepStatus.FAILED
-            step.error = judgment.feedback
-
-            return self._create_result(
-                status=ExecutionStatus.NEEDS_REPLAN,
-                plan=plan,
-                context=context,
-                feedback=judgment.feedback or f"Step '{step.id}' requires replanning",
-                steps_executed=steps_executed,
-                total_tokens=total_tokens,
-                total_latency=total_latency,
-            )
-
-        elif judgment.action == JudgmentAction.ESCALATE:
-            # Request human intervention
-            return self._create_result(
-                status=ExecutionStatus.NEEDS_ESCALATION,
-                plan=plan,
-                context=context,
-                feedback=judgment.feedback or f"Step '{step.id}' requires human intervention",
-                steps_executed=steps_executed,
-                total_tokens=total_tokens,
-                total_latency=total_latency,
-            )
-
-        return None  # Unknown action - continue
-
-    def _create_result(
-        self,
-        status: ExecutionStatus,
-        plan: Plan,
-        context: dict[str, Any],
-        feedback: str | None = None,
-        steps_executed: int = 0,
-        total_tokens: int = 0,
-        total_latency: int = 0,
-    ) -> PlanExecutionResult:
-        """Create a PlanExecutionResult."""
-        return PlanExecutionResult(
-            status=status,
-            results=context,
-            feedback=feedback,
-            feedback_context=plan.to_feedback_context(),
-            completed_steps=[s.id for s in plan.get_completed_steps()],
-            steps_executed=steps_executed,
-            total_tokens=total_tokens,
-            total_latency_ms=total_latency,
-        )
-
-    def register_function(self, name: str, func: Callable) -> None:
-        """Register a function for FUNCTION actions."""
-        self.functions[name] = func
-        self.worker.register_function(name, func)
-
-    def register_tool(self, tool: Tool) -> None:
-        """Register a tool for TOOL_USE actions."""
-        self.tools[tool.name] = tool
-        self.worker.register_tool(tool)
-
-    def add_evaluation_rule(self, rule) -> None:
-        """Add an evaluation rule to the judge."""
-        self.judge.add_rule(rule)
-
-    async def _request_approval(
-        self,
-        step: PlanStep,
-        context: dict[str, Any],
-    ) -> ApprovalResult | None:
-        """
-        Request human approval for a step.
-
-        Returns None if no callback is set (execution should pause).
-        """
-        if self.approval_callback is None:
-            return None
-
-        # Build preview of what will happen
-        preview_parts = []
-        if step.action.tool_name:
-            preview_parts.append(f"Tool: {step.action.tool_name}")
-            if step.action.tool_args:
-                import json
-
-                args_preview = json.dumps(step.action.tool_args, indent=2, default=str)
-                if len(args_preview) > 500:
-                    args_preview = args_preview[:500] + "..."
-                preview_parts.append(f"Args: {args_preview}")
-        elif step.action.prompt:
-            prompt_preview = (
-                step.action.prompt[:300] + "..."
-                if len(step.action.prompt) > 300
-                else step.action.prompt
-            )
-            preview_parts.append(f"Prompt: {prompt_preview}")
-
-        # Include step inputs resolved from context (what will be sent/used)
-        relevant_context = {}
-        for input_key, input_value in step.inputs.items():
-            # Resolve variable references like "$email_sequence"
-            if isinstance(input_value, str) and input_value.startswith("$"):
-                context_key = input_value[1:]  # Remove $ prefix
-                if context_key in context:
-                    relevant_context[input_key] = context[context_key]
-            else:
-                relevant_context[input_key] = input_value
-
-        request = ApprovalRequest(
-            step_id=step.id,
-            step_description=step.description,
-            action_type=step.action.action_type.value,
-            action_details={
-                "tool_name": step.action.tool_name,
-                "tool_args": step.action.tool_args,
-                "prompt": step.action.prompt,
-            },
-            context=relevant_context,
-            approval_message=step.approval_message,
-            preview="\n".join(preview_parts) if preview_parts else None,
-        )
-
-        return self.approval_callback(request)
-
-    def _skip_dependent_steps(self, plan: Plan, rejected_step_id: str) -> None:
-        """Mark steps that depend on a rejected step as skipped."""
-        for step in plan.steps:
-            if rejected_step_id in step.dependencies:
-                if step.status == StepStatus.PENDING:
-                    step.status = StepStatus.SKIPPED
-                    step.error = f"Skipped because dependency '{rejected_step_id}' was rejected"
-                    # Recursively skip dependents
-                    self._skip_dependent_steps(plan, step.id)
-
-    def _apply_modifications(self, step: PlanStep, modifications: dict[str, Any]) -> None:
-        """Apply human modifications to a step before execution."""
-        # Allow modifying tool args
-        if "tool_args" in modifications and step.action.tool_args:
-            step.action.tool_args.update(modifications["tool_args"])
-
-        # Allow modifying prompt
-        if "prompt" in modifications:
-            step.action.prompt = modifications["prompt"]
-
-        # Allow modifying inputs
-        if "inputs" in modifications:
-            step.inputs.update(modifications["inputs"])
-
-    def set_approval_callback(self, callback: ApprovalCallback) -> None:
-        """Set the approval callback for HITL steps."""
-        self.approval_callback = callback
-
-
-# Convenience function for simple execution
-async def execute_plan(
-    plan: Plan,
-    goal: Goal,
-    runtime: Runtime,
-    llm: LLMProvider | None = None,
-    tools: dict[str, Tool] | None = None,
-    tool_executor: Callable | None = None,
-    context: dict[str, Any] | None = None,
-) -> PlanExecutionResult:
-    """
-    Execute a plan with default configuration.
-
-    Convenience function for simple use cases.
-    """
-    executor = FlexibleGraphExecutor(
-        runtime=runtime,
-        llm=llm,
-        tools=tools,
-        tool_executor=tool_executor,
-    )
-    return await executor.execute_plan(plan, goal, context)

core/framework/graph/goal.py

@@ -44,6 +44,11 @@ class SuccessCriterion(BaseModel):
     metric: str = Field(
         description="How to measure: 'output_contains', 'output_equals', 'llm_judge', 'custom'"
     )
+    # NEW: runtime evaluation type (separate from metric)
+    type: str = Field(
+        default="success_rate", description="Runtime evaluation type, e.g. 'success_rate'"
+    )
+
     target: Any = Field(description="The target value or condition")
     weight: float = Field(default=1.0, ge=0.0, le=1.0, description="Relative importance (0-1)")
     met: bool = False

core/framework/graph/hitl.py

@@ -197,7 +197,7 @@ Example format:
 
             client = anthropic.Anthropic(api_key=api_key)
             message = client.messages.create(
-                model="claude-3-5-haiku-20241022",
+                model="claude-haiku-4-5-20251001",
                 max_tokens=500,
                 messages=[{"role": "user", "content": prompt}],
             )

core/framework/graph/judge.py

@@ -1,406 +0,0 @@
-"""
-Hybrid Judge for Evaluating Plan Step Results.
-
-The HybridJudge evaluates step execution results using:
-1. Rule-based evaluation (fast, deterministic)
-2. LLM-based evaluation (fallback for ambiguous cases)
-
-Escalation path: rules → LLM → human
-"""
-
-from dataclasses import dataclass, field
-from typing import Any
-
-from framework.graph.code_sandbox import safe_eval
-from framework.graph.goal import Goal
-from framework.graph.plan import (
-    EvaluationRule,
-    Judgment,
-    JudgmentAction,
-    PlanStep,
-)
-from framework.llm.provider import LLMProvider
-
-
-@dataclass
-class RuleEvaluationResult:
-    """Result of rule-based evaluation."""
-
-    is_definitive: bool  # True if a rule matched definitively
-    judgment: Judgment | None = None
-    context: dict[str, Any] = field(default_factory=dict)
-    rules_checked: int = 0
-    rule_matched: str | None = None
-
-
-class HybridJudge:
-    """
-    Evaluates plan step results using rules first, then LLM fallback.
-
-    Usage:
-        judge = HybridJudge(llm=llm_provider)
-        judge.add_rule(EvaluationRule(
-            id="success_check",
-            condition="result.get('success') == True",
-            action=JudgmentAction.ACCEPT,
-        ))
-
-        judgment = await judge.evaluate(step, result, goal)
-    """
-
-    def __init__(
-        self,
-        llm: LLMProvider | None = None,
-        rules: list[EvaluationRule] | None = None,
-        llm_confidence_threshold: float = 0.7,
-    ):
-        """
-        Initialize the HybridJudge.
-
-        Args:
-            llm: LLM provider for ambiguous cases
-            rules: Initial evaluation rules
-            llm_confidence_threshold: Confidence below this triggers escalation
-        """
-        self.llm = llm
-        self.rules: list[EvaluationRule] = rules or []
-        self.llm_confidence_threshold = llm_confidence_threshold
-
-        # Sort rules by priority (higher first)
-        self._sort_rules()
-
-    def _sort_rules(self):
-        """Sort rules by priority."""
-        self.rules.sort(key=lambda r: -r.priority)
-
-    def add_rule(self, rule: EvaluationRule) -> None:
-        """Add an evaluation rule."""
-        self.rules.append(rule)
-        self._sort_rules()
-
-    def remove_rule(self, rule_id: str) -> bool:
-        """Remove a rule by ID. Returns True if found and removed."""
-        for i, rule in enumerate(self.rules):
-            if rule.id == rule_id:
-                self.rules.pop(i)
-                return True
-        return False
-
-    async def evaluate(
-        self,
-        step: PlanStep,
-        result: Any,
-        goal: Goal,
-        context: dict[str, Any] | None = None,
-    ) -> Judgment:
-        """
-        Evaluate a step result.
-
-        Args:
-            step: The executed plan step
-            result: The result of executing the step
-            goal: The goal context for evaluation
-            context: Additional context from previous steps
-
-        Returns:
-            Judgment with action and feedback
-        """
-        context = context or {}
-
-        # Try rule-based evaluation first
-        rule_result = self._evaluate_rules(step, result, goal, context)
-
-        if rule_result.is_definitive:
-            return rule_result.judgment
-
-        # Fall back to LLM evaluation
-        if self.llm:
-            return await self._evaluate_llm(step, result, goal, context, rule_result)
-
-        # No LLM available - default to accept with low confidence
-        return Judgment(
-            action=JudgmentAction.ACCEPT,
-            reasoning="No definitive rule matched and no LLM available for evaluation",
-            confidence=0.5,
-            llm_used=False,
-        )
-
-    def _evaluate_rules(
-        self,
-        step: PlanStep,
-        result: Any,
-        goal: Goal,
-        context: dict[str, Any],
-    ) -> RuleEvaluationResult:
-        """Evaluate step using rules."""
-        rules_checked = 0
-
-        # Build evaluation context
-        eval_context = {
-            "step": step.model_dump() if hasattr(step, "model_dump") else step,
-            "result": result,
-            "goal": goal.model_dump() if hasattr(goal, "model_dump") else goal,
-            "context": context,
-            "success": isinstance(result, dict) and result.get("success", False),
-            "error": isinstance(result, dict) and result.get("error"),
-        }
-
-        for rule in self.rules:
-            rules_checked += 1
-
-            # Evaluate rule condition
-            eval_result = safe_eval(rule.condition, eval_context)
-
-            if eval_result.success and eval_result.result:
-                # Rule matched!
-                feedback = self._format_feedback(rule.feedback_template, eval_context)
-
-                return RuleEvaluationResult(
-                    is_definitive=True,
-                    judgment=Judgment(
-                        action=rule.action,
-                        reasoning=rule.description,
-                        feedback=feedback if feedback else None,
-                        rule_matched=rule.id,
-                        confidence=1.0,
-                        llm_used=False,
-                    ),
-                    rules_checked=rules_checked,
-                    rule_matched=rule.id,
-                )
-
-        # No rule matched definitively
-        return RuleEvaluationResult(
-            is_definitive=False,
-            context=eval_context,
-            rules_checked=rules_checked,
-        )
-
-    def _format_feedback(
-        self,
-        template: str,
-        context: dict[str, Any],
-    ) -> str:
-        """Format feedback template with context values."""
-        if not template:
-            return ""
-
-        try:
-            return template.format(**context)
-        except (KeyError, ValueError):
-            return template
-
-    async def _evaluate_llm(
-        self,
-        step: PlanStep,
-        result: Any,
-        goal: Goal,
-        context: dict[str, Any],
-        rule_result: RuleEvaluationResult,
-    ) -> Judgment:
-        """Evaluate step using LLM."""
-        system_prompt = self._build_llm_system_prompt(goal)
-        user_prompt = self._build_llm_user_prompt(step, result, context, rule_result)
-
-        try:
-            response = await self.llm.acomplete(
-                messages=[{"role": "user", "content": user_prompt}],
-                system=system_prompt,
-            )
-
-            # Parse LLM response
-            judgment = self._parse_llm_response(response.content)
-            judgment.llm_used = True
-
-            # Check confidence threshold
-            if judgment.confidence < self.llm_confidence_threshold:
-                # Low confidence - escalate
-                return Judgment(
-                    action=JudgmentAction.ESCALATE,
-                    reasoning=(
-                        f"LLM confidence ({judgment.confidence:.2f}) "
-                        f"below threshold ({self.llm_confidence_threshold})"
-                    ),
-                    feedback=judgment.feedback,
-                    confidence=judgment.confidence,
-                    llm_used=True,
-                    context={"original_judgment": judgment.model_dump()},
-                )
-
-            return judgment
-
-        except Exception as e:
-            # LLM failed - escalate
-            return Judgment(
-                action=JudgmentAction.ESCALATE,
-                reasoning=f"LLM evaluation failed: {e}",
-                feedback="Human review needed due to LLM error",
-                llm_used=True,
-            )
-
-    def _build_llm_system_prompt(self, goal: Goal) -> str:
-        """Build system prompt for LLM judge."""
-        return f"""You are a judge evaluating the execution of a plan step.
-
-GOAL: {goal.description}
-
-SUCCESS CRITERIA:
-{chr(10).join(f"- {sc.description}" for sc in goal.success_criteria)}
-
-CONSTRAINTS:
-{chr(10).join(f"- {c.description}" for c in goal.constraints)}
-
-Your task is to evaluate whether the step was executed successfully and decide the next action.
-
-Respond in this exact format:
-ACTION: [ACCEPT|RETRY|REPLAN|ESCALATE]
-CONFIDENCE: [0.0-1.0]
-REASONING: [Your reasoning]
-FEEDBACK: [Feedback for retry/replan, or empty if accepting]
-
-Actions:
-- ACCEPT: Step completed successfully, continue to next step
-- RETRY: Step failed but can be retried with feedback
-- REPLAN: Step failed in a way that requires replanning
-- ESCALATE: Requires human intervention
-"""
-
-    def _build_llm_user_prompt(
-        self,
-        step: PlanStep,
-        result: Any,
-        context: dict[str, Any],
-        rule_result: RuleEvaluationResult,
-    ) -> str:
-        """Build user prompt for LLM judge."""
-        return f"""Evaluate this step execution:
-
-STEP: {step.description}
-STEP ID: {step.id}
-ACTION TYPE: {step.action.action_type}
-EXPECTED OUTPUTS: {step.expected_outputs}
-
-RESULT:
-{result}
-
-CONTEXT FROM PREVIOUS STEPS:
-{context}
-
-RULES CHECKED: {rule_result.rules_checked} (none matched definitively)
-
-Please evaluate and provide your judgment."""
-
-    def _parse_llm_response(self, response: str) -> Judgment:
-        """Parse LLM response into Judgment."""
-        lines = response.strip().split("\n")
-
-        action = JudgmentAction.ACCEPT
-        confidence = 0.8
-        reasoning = ""
-        feedback = ""
-
-        for line in lines:
-            line = line.strip()
-            if line.startswith("ACTION:"):
-                action_str = line.split(":", 1)[1].strip().upper()
-                try:
-                    action = JudgmentAction(action_str.lower())
-                except ValueError:
-                    action = JudgmentAction.ESCALATE
-
-            elif line.startswith("CONFIDENCE:"):
-                try:
-                    confidence = float(line.split(":", 1)[1].strip())
-                except ValueError:
-                    confidence = 0.5
-
-            elif line.startswith("REASONING:"):
-                reasoning = line.split(":", 1)[1].strip()
-
-            elif line.startswith("FEEDBACK:"):
-                feedback = line.split(":", 1)[1].strip()
-
-        return Judgment(
-            action=action,
-            reasoning=reasoning or "LLM evaluation",
-            feedback=feedback if feedback else None,
-            confidence=confidence,
-        )
-
-
-# Factory function for creating judge with common rules
-def create_default_judge(llm: LLMProvider | None = None) -> HybridJudge:
-    """
-    Create a HybridJudge with commonly useful default rules.
-
-    Args:
-        llm: LLM provider for fallback evaluation
-
-    Returns:
-        Configured HybridJudge instance
-    """
-    judge = HybridJudge(llm=llm)
-
-    # Rule: Accept on explicit success flag
-    judge.add_rule(
-        EvaluationRule(
-            id="explicit_success",
-            description="Step explicitly marked as successful",
-            condition="isinstance(result, dict) and result.get('success') == True",
-            action=JudgmentAction.ACCEPT,
-            priority=100,
-        )
-    )
-
-    # Rule: Retry on transient errors
-    judge.add_rule(
-        EvaluationRule(
-            id="transient_error_retry",
-            description="Transient error that can be retried",
-            condition=(
-                "isinstance(result, dict) and "
-                "result.get('error_type') in ['timeout', 'rate_limit', 'connection_error']"
-            ),
-            action=JudgmentAction.RETRY,
-            feedback_template="Transient error: {result[error]}. Please retry.",
-            priority=90,
-        )
-    )
-
-    # Rule: Replan on missing data
-    judge.add_rule(
-        EvaluationRule(
-            id="missing_data_replan",
-            description="Required data not available",
-            condition="isinstance(result, dict) and result.get('error_type') == 'missing_data'",
-            action=JudgmentAction.REPLAN,
-            feedback_template="Missing required data: {result[error]}. Plan needs adjustment.",
-            priority=80,
-        )
-    )
-
-    # Rule: Escalate on security issues
-    judge.add_rule(
-        EvaluationRule(
-            id="security_escalate",
-            description="Security issue detected",
-            condition="isinstance(result, dict) and result.get('error_type') == 'security'",
-            action=JudgmentAction.ESCALATE,
-            feedback_template="Security issue detected: {result[error]}",
-            priority=200,
-        )
-    )
-
-    # Rule: Fail on max retries exceeded
-    judge.add_rule(
-        EvaluationRule(
-            id="max_retries_fail",
-            description="Maximum retries exceeded",
-            condition="step.get('attempts', 0) >= step.get('max_retries', 3)",
-            action=JudgmentAction.REPLAN,
-            feedback_template="Step '{step[id]}' failed after {step[attempts]} attempts",
-            priority=150,
-        )
-    )
-
-    return judge

core/framework/graph/plan.py

@@ -1,513 +0,0 @@
-"""
-Plan Data Structures for Flexible Execution.
-
-Plans are created externally (by Claude Code or another LLM agent) and
-executed internally by the FlexibleGraphExecutor with Worker-Judge loop.
-
-The Plan is the contract between the external planner and the executor:
-- Planner creates a Plan with PlanSteps
-- Executor runs steps and judges results
-- If replanning needed, returns feedback to external planner
-"""
-
-from datetime import datetime
-from enum import StrEnum
-from typing import Any
-
-from pydantic import BaseModel, Field
-
-
-class ActionType(StrEnum):
-    """Types of actions a PlanStep can perform."""
-
-    LLM_CALL = "llm_call"  # Call LLM for generation
-    TOOL_USE = "tool_use"  # Use a registered tool
-    SUB_GRAPH = "sub_graph"  # Execute a sub-graph
-    FUNCTION = "function"  # Call a Python function
-    CODE_EXECUTION = "code_execution"  # Execute dynamic code (sandboxed)
-
-
-class StepStatus(StrEnum):
-    """Status of a plan step."""
-
-    PENDING = "pending"
-    AWAITING_APPROVAL = "awaiting_approval"  # Waiting for human approval
-    IN_PROGRESS = "in_progress"
-    COMPLETED = "completed"
-    FAILED = "failed"
-    SKIPPED = "skipped"
-    REJECTED = "rejected"  # Human rejected execution
-
-    def is_terminal(self) -> bool:
-        """Check if this status represents a terminal (finished) state.
-
-        Terminal states are states where the step will not execute further,
-        either because it completed successfully or failed/was skipped.
-        """
-        return self in (
-            StepStatus.COMPLETED,
-            StepStatus.FAILED,
-            StepStatus.SKIPPED,
-            StepStatus.REJECTED,
-        )
-
-    def is_successful(self) -> bool:
-        """Check if this status represents successful completion."""
-        return self == StepStatus.COMPLETED
-
-
-class ApprovalDecision(StrEnum):
-    """Human decision on a step requiring approval."""
-
-    APPROVE = "approve"  # Execute as planned
-    REJECT = "reject"  # Skip this step
-    MODIFY = "modify"  # Execute with modifications
-    ABORT = "abort"  # Stop entire execution
-
-
-class ApprovalRequest(BaseModel):
-    """Request for human approval before executing a step."""
-
-    step_id: str
-    step_description: str
-    action_type: str
-    action_details: dict[str, Any] = Field(default_factory=dict)
-    context: dict[str, Any] = Field(default_factory=dict)
-    approval_message: str | None = None
-
-    # Preview of what will happen
-    preview: str | None = None
-
-    model_config = {"extra": "allow"}
-
-
-class ApprovalResult(BaseModel):
-    """Result of human approval decision."""
-
-    decision: ApprovalDecision
-    reason: str | None = None
-    modifications: dict[str, Any] = Field(default_factory=dict)
-
-    model_config = {"extra": "allow"}
-
-
-class JudgmentAction(StrEnum):
-    """Actions the judge can take after evaluating a step."""
-
-    ACCEPT = "accept"  # Step completed successfully, continue
-    RETRY = "retry"  # Retry the step with feedback
-    REPLAN = "replan"  # Return to external planner for new plan
-    ESCALATE = "escalate"  # Request human intervention
-
-
-class ActionSpec(BaseModel):
-    """
-    Specification for an action to be executed.
-
-    This is the "what to do" part of a PlanStep.
-    """
-
-    action_type: ActionType
-
-    # For LLM_CALL
-    prompt: str | None = None
-    system_prompt: str | None = None
-    model: str | None = None
-
-    # For TOOL_USE
-    tool_name: str | None = None
-    tool_args: dict[str, Any] = Field(default_factory=dict)
-
-    # For SUB_GRAPH
-    graph_id: str | None = None
-
-    # For FUNCTION
-    function_name: str | None = None
-    function_args: dict[str, Any] = Field(default_factory=dict)
-
-    # For CODE_EXECUTION
-    code: str | None = None
-    language: str = "python"
-
-    model_config = {"extra": "allow"}
-
-
-class PlanStep(BaseModel):
-    """
-    A single step in a plan.
-
-    Created by external planner, executed by Worker, evaluated by Judge.
-    """
-
-    id: str
-    description: str
-    action: ActionSpec
-
-    # Data flow
-    inputs: dict[str, Any] = Field(
-        default_factory=dict,
-        description="Input data for this step (can reference previous step outputs)",
-    )
-    expected_outputs: list[str] = Field(
-        default_factory=list, description="Keys this step should produce"
-    )
-
-    # Dependencies
-    dependencies: list[str] = Field(
-        default_factory=list, description="IDs of steps that must complete before this one"
-    )
-
-    # Human-in-the-loop (HITL)
-    requires_approval: bool = Field(
-        default=False, description="If True, requires human approval before execution"
-    )
-    approval_message: str | None = Field(
-        default=None, description="Message to show human when requesting approval"
-    )
-
-    # Execution state
-    status: StepStatus = StepStatus.PENDING
-    result: Any | None = None
-    error: str | None = None
-    attempts: int = 0
-    max_retries: int = 3
-
-    # Metadata
-    started_at: datetime | None = None
-    completed_at: datetime | None = None
-
-    model_config = {"extra": "allow"}
-
-    def is_ready(self, terminal_step_ids: set[str]) -> bool:
-        """Check if this step is ready to execute (all dependencies finished).
-
-        A step is ready when:
-        1. Its status is PENDING (not yet started)
-        2. All its dependencies are in a terminal state (completed, failed, skipped, or rejected)
-
-        Note: This allows dependent steps to become "ready" even if their dependencies
-        failed. The executor should check if any dependencies failed and handle
-        accordingly (e.g., skip the step or mark it as blocked).
-
-        Args:
-            terminal_step_ids: Set of step IDs that are in a terminal state
-        """
-        if self.status != StepStatus.PENDING:
-            return False
-        return all(dep in terminal_step_ids for dep in self.dependencies)
-
-
-class Judgment(BaseModel):
-    """
-    Result of judging a step execution.
-
-    The Judge evaluates step results and decides what to do next.
-    """
-
-    action: JudgmentAction
-    reasoning: str
-    feedback: str | None = None  # For retry/replan - what went wrong
-
-    # For rule-based judgments
-    rule_matched: str | None = None
-
-    # For LLM-based judgments
-    confidence: float = 1.0
-    llm_used: bool = False
-
-    # Context for replanning
-    context: dict[str, Any] = Field(default_factory=dict)
-
-    model_config = {"extra": "allow"}
-
-
-class EvaluationRule(BaseModel):
-    """
-    A rule for the HybridJudge to evaluate step results.
-
-    Rules are checked before falling back to LLM evaluation.
-    """
-
-    id: str
-    description: str
-
-    # Condition (Python expression evaluated with result, step, goal context)
-    condition: str
-
-    # What to do if condition matches
-    action: JudgmentAction
-    feedback_template: str = ""  # Can use {result}, {step}, etc.
-
-    # Priority (higher = checked first)
-    priority: int = 0
-
-    model_config = {"extra": "allow"}
-
-
-class Plan(BaseModel):
-    """
-    A complete execution plan.
-
-    Created by external planner (Claude Code, etc).
-    Executed by FlexibleGraphExecutor.
-    """
-
-    id: str
-    goal_id: str
-    description: str
-
-    # Steps to execute
-    steps: list[PlanStep] = Field(default_factory=list)
-
-    # Execution state
-    revision: int = 1  # Incremented on replan
-    current_step_idx: int = 0
-
-    # Accumulated context from execution
-    context: dict[str, Any] = Field(default_factory=dict)
-
-    # Metadata
-    created_at: datetime = Field(default_factory=datetime.now)
-    created_by: str = "external"  # Who created this plan
-
-    # Previous attempt info (for replanning)
-    previous_feedback: str | None = None
-
-    model_config = {"extra": "allow"}
-
-    @classmethod
-    def from_json(cls, data: str | dict) -> "Plan":
-        """
-        Load a Plan from exported JSON.
-
-        This handles the output from export_graph() and properly converts
-        action_type strings to ActionType enums.
-
-        Args:
-            data: JSON string or dict from export_graph()
-
-        Returns:
-            Plan object ready for FlexibleGraphExecutor
-
-        Example:
-            # Load from export_graph() output
-            exported = export_graph()
-            plan = Plan.from_json(exported)
-
-            # Load from file
-            with open("plan.json") as f:
-                plan = Plan.from_json(json.load(f))
-        """
-        import json as json_module
-
-        if isinstance(data, str):
-            data = json_module.loads(data)
-
-        # Handle nested "plan" key from export_graph output
-        if "plan" in data:
-            data = data["plan"]
-
-        # Convert steps
-        steps = []
-        for step_data in data.get("steps", []):
-            action_data = step_data.get("action", {})
-
-            # Convert action_type string to enum
-            action_type_str = action_data.get("action_type", "function")
-            action_type = ActionType(action_type_str)
-
-            action = ActionSpec(
-                action_type=action_type,
-                prompt=action_data.get("prompt"),
-                system_prompt=action_data.get("system_prompt"),
-                tool_name=action_data.get("tool_name"),
-                tool_args=action_data.get("tool_args", {}),
-                function_name=action_data.get("function_name"),
-                function_args=action_data.get("function_args", {}),
-                code=action_data.get("code"),
-            )
-
-            step = PlanStep(
-                id=step_data["id"],
-                description=step_data.get("description", ""),
-                action=action,
-                inputs=step_data.get("inputs", {}),
-                expected_outputs=step_data.get("expected_outputs", []),
-                dependencies=step_data.get("dependencies", []),
-                requires_approval=step_data.get("requires_approval", False),
-                approval_message=step_data.get("approval_message"),
-            )
-            steps.append(step)
-
-        return cls(
-            id=data.get("id", "plan"),
-            goal_id=data.get("goal_id", ""),
-            description=data.get("description", ""),
-            steps=steps,
-            context=data.get("context", {}),
-            revision=data.get("revision", 1),
-        )
-
-    def get_step(self, step_id: str) -> PlanStep | None:
-        """Get a step by ID."""
-        for step in self.steps:
-            if step.id == step_id:
-                return step
-        return None
-
-    def get_ready_steps(self) -> list[PlanStep]:
-        """Get all steps that are ready to execute.
-
-        A step is ready when all its dependencies are in terminal states
-        (completed, failed, skipped, or rejected).
-        """
-        terminal_ids = {s.id for s in self.steps if s.status.is_terminal()}
-        return [s for s in self.steps if s.is_ready(terminal_ids)]
-
-    def get_completed_steps(self) -> list[PlanStep]:
-        """Get all completed steps."""
-        return [s for s in self.steps if s.status == StepStatus.COMPLETED]
-
-    def is_complete(self) -> bool:
-        """Check if all steps are in terminal states (finished executing).
-
-        Returns True when all steps have reached a terminal state, regardless
-        of whether they succeeded or failed. Use has_failed_steps() to check
-        if any steps failed.
-        """
-        return all(s.status.is_terminal() for s in self.steps)
-
-    def is_successful(self) -> bool:
-        """Check if all steps completed successfully."""
-        return all(s.status == StepStatus.COMPLETED for s in self.steps)
-
-    def has_failed_steps(self) -> bool:
-        """Check if any steps failed, were skipped, or were rejected."""
-        return any(
-            s.status in (StepStatus.FAILED, StepStatus.SKIPPED, StepStatus.REJECTED)
-            for s in self.steps
-        )
-
-    def get_failed_steps(self) -> list[PlanStep]:
-        """Get all steps that failed, were skipped, or were rejected."""
-        return [
-            s
-            for s in self.steps
-            if s.status in (StepStatus.FAILED, StepStatus.SKIPPED, StepStatus.REJECTED)
-        ]
-
-    def to_feedback_context(self) -> dict[str, Any]:
-        """Create context for replanning."""
-        return {
-            "plan_id": self.id,
-            "revision": self.revision,
-            "completed_steps": [
-                {
-                    "id": s.id,
-                    "description": s.description,
-                    "result": s.result,
-                }
-                for s in self.get_completed_steps()
-            ],
-            "failed_steps": [
-                {
-                    "id": s.id,
-                    "description": s.description,
-                    "error": s.error,
-                    "attempts": s.attempts,
-                }
-                for s in self.steps
-                if s.status == StepStatus.FAILED
-            ],
-            "context": self.context,
-        }
-
-
-class ExecutionStatus(StrEnum):
-    """Status of plan execution."""
-
-    COMPLETED = "completed"
-    AWAITING_APPROVAL = "awaiting_approval"  # Paused for human approval
-    NEEDS_REPLAN = "needs_replan"
-    NEEDS_ESCALATION = "needs_escalation"
-    REJECTED = "rejected"  # Human rejected a step
-    ABORTED = "aborted"  # Human aborted execution
-    FAILED = "failed"
-
-
-class PlanExecutionResult(BaseModel):
-    """
-    Result of executing a plan.
-
-    Returned to external planner with status and feedback.
-    """
-
-    status: ExecutionStatus
-
-    # Results from completed steps
-    results: dict[str, Any] = Field(default_factory=dict)
-
-    # For needs_replan - what to tell the planner
-    feedback: str | None = None
-    feedback_context: dict[str, Any] = Field(default_factory=dict)
-
-    # Steps that completed before stopping
-    completed_steps: list[str] = Field(default_factory=list)
-
-    # Metrics
-    steps_executed: int = 0
-    total_tokens: int = 0
-    total_latency_ms: int = 0
-
-    # Error info (for failed status)
-    error: str | None = None
-
-    model_config = {"extra": "allow"}
-
-
-def load_export(data: str | dict) -> tuple["Plan", Any]:
-    """
-    Load both Plan and Goal from export_graph() output.
-
-    The export_graph() MCP tool returns both the plan and the goal that was
-    defined and approved during the agent building process. This function
-    loads both so you can use them with FlexibleGraphExecutor.
-
-    Args:
-        data: JSON string or dict from export_graph()
-
-    Returns:
-        Tuple of (Plan, Goal) ready for FlexibleGraphExecutor
-
-    Example:
-        # Load from export_graph() output
-        exported = export_graph()
-        plan, goal = load_export(exported)
-
-        result = await executor.execute_plan(plan, goal, context)
-    """
-    import json as json_module
-
-    from framework.graph.goal import Goal
-
-    if isinstance(data, str):
-        data = json_module.loads(data)
-
-    # Load plan
-    plan = Plan.from_json(data)
-
-    # Load goal
-    goal_data = data.get("goal", {})
-    if goal_data:
-        goal = Goal.model_validate(goal_data)
-    else:
-        # Fallback: create minimal goal from plan metadata
-        goal = Goal(
-            id=plan.goal_id,
-            name=plan.goal_id,
-            description=plan.description,
-            success_criteria=[],
-            constraints=[],
-        )
-
-    return plan, goal

core/framework/graph/prompt_composer.py

@@ -16,8 +16,9 @@ Layer 3 — Focus (per-node system_prompt, reframed as focus directive):
 from __future__ import annotations
 
 import logging
+from datetime import datetime
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from framework.graph.edge import GraphSpec
@@ -26,10 +27,119 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _with_datetime(prompt: str) -> str:
+    """Append current datetime with local timezone to a system prompt."""
+    local = datetime.now().astimezone()
+    stamp = f"Current date and time: {local.strftime('%Y-%m-%d %H:%M %Z (UTC%z)')}"
+    return f"{prompt}\n\n{stamp}" if prompt else stamp
+
+
+def build_accounts_prompt(
+    accounts: list[dict[str, Any]],
+    tool_provider_map: dict[str, str] | None = None,
+    node_tool_names: list[str] | None = None,
+) -> str:
+    """Build a prompt section describing connected accounts.
+
+    When tool_provider_map is provided, produces structured output grouped
+    by provider with tool mapping, so the LLM knows which ``account`` value
+    to pass to which tool.
+
+    When node_tool_names is also provided, filters to only show providers
+    whose tools overlap with the node's tool list.
+
+    Args:
+        accounts: List of account info dicts from
+            CredentialStoreAdapter.get_all_account_info().
+        tool_provider_map: Mapping of tool_name -> provider_name
+            (e.g. {"gmail_list_messages": "google"}).
+        node_tool_names: Tool names available to the current node.
+            When provided, only providers with matching tools are shown.
+
+    Returns:
+        Formatted accounts block, or empty string if no accounts.
+    """
+    if not accounts:
+        return ""
+
+    # Flat format (backward compat) when no tool mapping provided
+    if tool_provider_map is None:
+        lines = [
+            "Connected accounts (use the alias as the `account` parameter "
+            "when calling tools to target a specific account):"
+        ]
+        for acct in accounts:
+            provider = acct.get("provider", "unknown")
+            alias = acct.get("alias", "unknown")
+            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 ""
+            lines.append(f"- {provider}/{alias}{detail}")
+        return "\n".join(lines)
+
+    # --- Structured format: group by provider with tool mapping ---
+
+    # Invert tool_provider_map to provider -> [tools]
+    provider_tools: dict[str, list[str]] = {}
+    for tool_name, provider in tool_provider_map.items():
+        provider_tools.setdefault(provider, []).append(tool_name)
+
+    # Filter to relevant providers based on node tools
+    node_tool_set = set(node_tool_names) if node_tool_names else None
+
+    # Group accounts by provider
+    provider_accounts: dict[str, list[dict[str, Any]]] = {}
+    for acct in accounts:
+        provider = acct.get("provider", "unknown")
+        provider_accounts.setdefault(provider, []).append(acct)
+
+    sections: list[str] = ["Connected accounts:"]
+
+    for provider, acct_list in provider_accounts.items():
+        tools_for_provider = sorted(provider_tools.get(provider, []))
+
+        # If node tools specified, only show providers with overlapping tools
+        if node_tool_set is not None:
+            relevant_tools = [t for t in tools_for_provider if t in node_tool_set]
+            if not relevant_tools:
+                continue
+            tools_for_provider = relevant_tools
+
+        # Local-only providers: tools read from env vars, no account= routing
+        all_local = all(a.get("source") == "local" for a in acct_list)
+
+        # Provider header with tools
+        display_name = provider.replace("_", " ").title()
+        if tools_for_provider and not all_local:
+            tools_str = ", ".join(tools_for_provider)
+            sections.append(f'\n{display_name} (use account="<alias>" with: {tools_str}):')
+        elif tools_for_provider and all_local:
+            tools_str = ", ".join(tools_for_provider)
+            sections.append(f"\n{display_name} (tools: {tools_str}):")
+        else:
+            sections.append(f"\n{display_name}:")
+
+        # Account entries
+        for acct in acct_list:
+            alias = acct.get("alias", "unknown")
+            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 ""
+            source_tag = " [local]" if acct.get("source") == "local" else ""
+            sections.append(f"  - {provider}/{alias}{detail}{source_tag}")
+
+    # If filtering removed all providers, return empty
+    if len(sections) <= 1:
+        return ""
+
+    return "\n".join(sections)
+
+
 def compose_system_prompt(
     identity_prompt: str | None,
     focus_prompt: str | None,
     narrative: str | None = None,
+    accounts_prompt: str | None = None,
 ) -> str:
     """Compose the three-layer system prompt.
 
@@ -37,9 +147,10 @@ def compose_system_prompt(
         identity_prompt: Layer 1 — static agent identity (from GraphSpec).
         focus_prompt: Layer 3 — per-node focus directive (from NodeSpec.system_prompt).
         narrative: Layer 2 — auto-generated from conversation state.
+        accounts_prompt: Connected accounts block (sits between identity and narrative).
 
     Returns:
-        Composed system prompt with all layers present.
+        Composed system prompt with all layers present, plus current datetime.
     """
     parts: list[str] = []
 
@@ -47,6 +158,10 @@ def compose_system_prompt(
     if identity_prompt:
         parts.append(identity_prompt)
 
+    # Accounts (semi-static, deployment-specific)
+    if accounts_prompt:
+        parts.append(f"\n{accounts_prompt}")
+
     # Layer 2: Narrative (what's happened so far)
     if narrative:
         parts.append(f"\n--- Context (what has happened so far) ---\n{narrative}")
@@ -55,7 +170,7 @@ def compose_system_prompt(
     if focus_prompt:
         parts.append(f"\n--- Current Focus ---\n{focus_prompt}")
 
-    return "\n".join(parts) if parts else ""
+    return _with_datetime("\n".join(parts) if parts else "")
 
 
 def build_narrative(
@@ -112,6 +227,7 @@ def build_transition_marker(
     memory: SharedMemory,
     cumulative_tool_names: list[str],
     data_dir: Path | str | None = None,
+    adapt_content: str | None = None,
 ) -> str:
     """Build a 'State of the World' transition marker.
 
@@ -125,6 +241,7 @@ def build_transition_marker(
         memory: Current shared memory state.
         cumulative_tool_names: All tools available (cumulative set).
         data_dir: Path to spillover data directory.
+        adapt_content: Agent working memory (adapt.md) content.
 
     Returns:
         Transition marker message text.
@@ -166,6 +283,10 @@ def build_transition_marker(
                         "\nData files (use load_data to access):\n" + "\n".join(file_lines)
                     )
 
+    # Agent working memory
+    if adapt_content:
+        sections.append(f"\n--- Agent Memory ---\n{adapt_content}")
+
     # Available tools
     if cumulative_tool_names:
         sections.append("\nAvailable tools: " + ", ".join(sorted(cumulative_tool_names)))

core/framework/graph/worker_node.py

@@ -1,620 +0,0 @@
-"""
-Worker Node for Executing Plan Steps.
-
-The Worker executes individual plan steps by dispatching to the
-appropriate executor based on action type:
-- LLM calls
-- Tool usage
-- Sub-graph execution
-- Function calls
-- Code execution (sandboxed)
-"""
-
-import json
-import logging
-import re
-import time
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from typing import Any
-
-from framework.graph.code_sandbox import CodeSandbox
-from framework.graph.plan import (
-    ActionSpec,
-    ActionType,
-    PlanStep,
-)
-from framework.llm.provider import LLMProvider, Tool
-from framework.runtime.core import Runtime
-
-logger = logging.getLogger(__name__)
-
-
-def parse_llm_json_response(text: str) -> tuple[Any | None, str]:
-    """
-    Parse JSON from LLM response, handling markdown code blocks.
-
-    LLMs often return JSON wrapped in markdown code blocks like:
-    ```json
-    {"key": "value"}
-    ```
-
-    This function extracts and parses the JSON.
-
-    Args:
-        text: Raw LLM response text
-
-    Returns:
-        Tuple of (parsed_json_or_None, cleaned_text)
-    """
-    if not isinstance(text, str):
-        return None, str(text)
-
-    cleaned = text.strip()
-
-    # Try to extract JSON from markdown code blocks
-    # Pattern: ```json ... ``` or ``` ... ```
-    code_block_pattern = r"```(?:json)?\s*([\s\S]*?)\s*```"
-    matches = re.findall(code_block_pattern, cleaned)
-
-    if matches:
-        # Try to parse each match
-        for match in matches:
-            try:
-                parsed = json.loads(match.strip())
-                return parsed, match.strip()
-            except json.JSONDecodeError as e:
-                logger.debug(
-                    f"Failed to parse JSON from code block: {e}. "
-                    f"Content preview: {match.strip()[:100]}..."
-                )
-                continue
-
-    # No code blocks or parsing failed - try parsing the whole response
-    try:
-        parsed = json.loads(cleaned)
-        return parsed, cleaned
-    except json.JSONDecodeError as e:
-        logger.debug(
-            f"Failed to parse entire response as JSON: {e}. Content preview: {cleaned[:100]}..."
-        )
-
-    # Try to find JSON-like content (starts with { or [)
-    json_start_pattern = r"(\{[\s\S]*\}|\[[\s\S]*\])"
-    json_matches = re.findall(json_start_pattern, cleaned)
-
-    for match in json_matches:
-        try:
-            parsed = json.loads(match)
-            return parsed, match
-        except json.JSONDecodeError as e:
-            logger.debug(f"Failed to parse JSON pattern: {e}. Content preview: {match[:100]}...")
-            continue
-
-    # Could not parse as JSON - log warning
-    logger.warning(
-        f"Could not parse LLM response as JSON after trying all strategies. "
-        f"Response preview: {cleaned[:200]}..."
-    )
-    return None, cleaned
-
-
-@dataclass
-class StepExecutionResult:
-    """Result of executing a plan step."""
-
-    success: bool
-    outputs: dict[str, Any] = field(default_factory=dict)
-    error: str | None = None
-    error_type: str | None = None  # For judge rules: timeout, rate_limit, etc.
-
-    # Metadata
-    tokens_used: int = 0
-    latency_ms: int = 0
-    executor_type: str = ""
-
-
-class WorkerNode:
-    """
-    Executes plan steps by dispatching to appropriate executors.
-
-    Usage:
-        worker = WorkerNode(
-            runtime=runtime,
-            llm=llm_provider,
-            tools=tool_registry,
-        )
-
-        result = await worker.execute(step, context)
-    """
-
-    def __init__(
-        self,
-        runtime: Runtime,
-        llm: LLMProvider | None = None,
-        tools: dict[str, Tool] | None = None,
-        tool_executor: Callable | None = None,
-        functions: dict[str, Callable] | None = None,
-        sub_graph_executor: Callable | None = None,
-        sandbox: CodeSandbox | None = None,
-    ):
-        """
-        Initialize the Worker.
-
-        Args:
-            runtime: Runtime for decision logging
-            llm: LLM provider for LLM_CALL actions
-            tools: Available tools for TOOL_USE actions
-            tool_executor: Function to execute tools
-            functions: Registered functions for FUNCTION actions
-            sub_graph_executor: Function to execute sub-graphs
-            sandbox: Code sandbox for CODE_EXECUTION actions
-        """
-        self.runtime = runtime
-        self.llm = llm
-        self.tools = tools or {}
-        self.tool_executor = tool_executor
-        self.functions = functions or {}
-        self.sub_graph_executor = sub_graph_executor
-        self.sandbox = sandbox or CodeSandbox()
-
-    async def execute(
-        self,
-        step: PlanStep,
-        context: dict[str, Any],
-    ) -> StepExecutionResult:
-        """
-        Execute a plan step.
-
-        Args:
-            step: The step to execute
-            context: Current execution context
-
-        Returns:
-            StepExecutionResult with outputs and status
-        """
-        # Record decision
-        decision_id = self.runtime.decide(
-            intent=f"Execute plan step: {step.description}",
-            options=[
-                {
-                    "id": step.action.action_type.value,
-                    "description": f"Execute {step.action.action_type.value} action",
-                    "action_type": step.action.action_type.value,
-                }
-            ],
-            chosen=step.action.action_type.value,
-            reasoning=f"Step requires {step.action.action_type.value}",
-            context={"step_id": step.id, "inputs": step.inputs},
-        )
-
-        start_time = time.time()
-
-        try:
-            # Resolve inputs from context
-            resolved_inputs = self._resolve_inputs(step.inputs, context)
-
-            # Dispatch to appropriate executor
-            result = await self._dispatch(step.action, resolved_inputs, context)
-
-            latency_ms = int((time.time() - start_time) * 1000)
-            result.latency_ms = latency_ms
-
-            # Record outcome
-            self.runtime.record_outcome(
-                decision_id=decision_id,
-                success=result.success,
-                result=result.outputs if result.success else result.error,
-                tokens_used=result.tokens_used,
-                latency_ms=latency_ms,
-            )
-
-            return result
-
-        except Exception as e:
-            latency_ms = int((time.time() - start_time) * 1000)
-
-            self.runtime.record_outcome(
-                decision_id=decision_id,
-                success=False,
-                error=str(e),
-                latency_ms=latency_ms,
-            )
-
-            return StepExecutionResult(
-                success=False,
-                error=str(e),
-                error_type="exception",
-                latency_ms=latency_ms,
-            )
-
-    def _resolve_inputs(
-        self,
-        inputs: dict[str, Any],
-        context: dict[str, Any],
-    ) -> dict[str, Any]:
-        """Resolve input references from context."""
-        resolved = {}
-
-        for key, value in inputs.items():
-            if isinstance(value, str) and value.startswith("$"):
-                # Reference to context variable
-                ref_key = value[1:]  # Remove $
-                resolved[key] = context.get(ref_key, value)
-            else:
-                resolved[key] = value
-
-        return resolved
-
-    async def _dispatch(
-        self,
-        action: ActionSpec,
-        inputs: dict[str, Any],
-        context: dict[str, Any],
-    ) -> StepExecutionResult:
-        """Dispatch to appropriate executor based on action type."""
-        if action.action_type == ActionType.LLM_CALL:
-            return await self._execute_llm_call(action, inputs, context)
-
-        elif action.action_type == ActionType.TOOL_USE:
-            return await self._execute_tool_use(action, inputs)
-
-        elif action.action_type == ActionType.SUB_GRAPH:
-            return await self._execute_sub_graph(action, inputs, context)
-
-        elif action.action_type == ActionType.FUNCTION:
-            return await self._execute_function(action, inputs)
-
-        elif action.action_type == ActionType.CODE_EXECUTION:
-            return self._execute_code(action, inputs, context)
-
-        else:
-            return StepExecutionResult(
-                success=False,
-                error=f"Unknown action type: {action.action_type}",
-                error_type="invalid_action",
-            )
-
-    async def _execute_llm_call(
-        self,
-        action: ActionSpec,
-        inputs: dict[str, Any],
-        context: dict[str, Any],
-    ) -> StepExecutionResult:
-        """Execute an LLM call action."""
-        if self.llm is None:
-            return StepExecutionResult(
-                success=False,
-                error="No LLM provider configured",
-                error_type="configuration",
-                executor_type="llm_call",
-            )
-
-        try:
-            # Build prompt with context data
-            prompt = action.prompt or ""
-
-            # First try format placeholders (for prompts like "Hello {name}")
-            if inputs:
-                try:
-                    prompt = prompt.format(**inputs)
-                except (KeyError, ValueError):
-                    pass  # Keep original prompt if formatting fails
-
-            # Always append context data so LLM can personalize
-            # This ensures the LLM has access to lead info, company context, etc.
-            if inputs:
-                context_section = "\n\n--- Context Data ---\n"
-                for key, value in inputs.items():
-                    if isinstance(value, dict | list):
-                        context_section += f"{key}: {json.dumps(value, indent=2)}\n"
-                    else:
-                        context_section += f"{key}: {value}\n"
-                prompt = prompt + context_section
-
-            messages = [{"role": "user", "content": prompt}]
-
-            response = await self.llm.acomplete(
-                messages=messages,
-                system=action.system_prompt,
-            )
-
-            # Try to parse JSON from LLM response
-            # LLMs often return JSON wrapped in markdown code blocks
-            parsed_json, _ = parse_llm_json_response(response.content)
-
-            # If JSON was parsed successfully, use it as the result
-            # Otherwise, use the raw text
-            result_value = parsed_json if parsed_json is not None else response.content
-
-            return StepExecutionResult(
-                success=True,
-                outputs={
-                    "result": result_value,
-                    "response": response.content,  # Always keep raw response
-                    "parsed_json": parsed_json,  # Explicit parsed JSON (or None)
-                },
-                tokens_used=response.input_tokens + response.output_tokens,
-                executor_type="llm_call",
-            )
-
-        except Exception as e:
-            error_type = "rate_limit" if "rate" in str(e).lower() else "llm_error"
-            return StepExecutionResult(
-                success=False,
-                error=str(e),
-                error_type=error_type,
-                executor_type="llm_call",
-            )
-
-    async def _execute_tool_use(
-        self,
-        action: ActionSpec,
-        inputs: dict[str, Any],
-    ) -> StepExecutionResult:
-        """Execute a tool use action."""
-        tool_name = action.tool_name
-        if not tool_name:
-            return StepExecutionResult(
-                success=False,
-                error="No tool name specified",
-                error_type="invalid_action",
-                executor_type="tool_use",
-            )
-
-        # Merge action args with inputs
-        args = {**action.tool_args, **inputs}
-
-        # Resolve any $variable references in the merged args
-        # (tool_args may contain $refs that should be resolved from inputs)
-        resolved_args = {}
-        for key, value in args.items():
-            if isinstance(value, str) and value.startswith("$"):
-                ref_key = value[1:]  # Remove $
-                resolved_args[key] = args.get(ref_key, value)
-            else:
-                resolved_args[key] = value
-        args = resolved_args
-
-        # First, check if we have a registered function with this name
-        # This allows simpler tool registration without full Tool/ToolExecutor setup
-        if tool_name in self.functions:
-            try:
-                func = self.functions[tool_name]
-                result = func(**args)
-
-                # Handle async functions
-                if hasattr(result, "__await__"):
-                    result = await result
-
-                # If result is already a dict with success/outputs, use it directly
-                if isinstance(result, dict) and "success" in result:
-                    return StepExecutionResult(
-                        success=result.get("success", False),
-                        outputs=result.get("outputs", {}),
-                        error=result.get("error"),
-                        error_type=result.get("error_type"),
-                        executor_type="tool_use",
-                    )
-
-                # Otherwise wrap the result
-                return StepExecutionResult(
-                    success=True,
-                    outputs={"result": result},
-                    executor_type="tool_use",
-                )
-
-            except Exception as e:
-                return StepExecutionResult(
-                    success=False,
-                    error=str(e),
-                    error_type="tool_exception",
-                    executor_type="tool_use",
-                )
-
-        # Fall back to formal Tool registry
-        if tool_name not in self.tools:
-            return StepExecutionResult(
-                success=False,
-                error=f"Tool '{tool_name}' not found",
-                error_type="missing_tool",
-                executor_type="tool_use",
-            )
-
-        if self.tool_executor is None:
-            return StepExecutionResult(
-                success=False,
-                error="No tool executor configured",
-                error_type="configuration",
-                executor_type="tool_use",
-            )
-
-        try:
-            # Execute tool via formal executor
-            from framework.llm.provider import ToolUse
-
-            tool_use = ToolUse(
-                id=f"step_{tool_name}",
-                name=tool_name,
-                input=args,
-            )
-
-            result = self.tool_executor(tool_use)
-
-            if result.is_error:
-                return StepExecutionResult(
-                    success=False,
-                    outputs={},
-                    error=result.content,
-                    error_type="tool_error",
-                    executor_type="tool_use",
-                )
-
-            # Parse JSON result and unpack fields into outputs
-            # Tools return JSON like {"lead_email": "...", "company_name": "..."}
-            # We want each field as a separate output key
-            outputs = {"result": result.content}
-            try:
-                parsed = json.loads(result.content)
-                if isinstance(parsed, dict):
-                    # Unpack all fields from the JSON response
-                    outputs.update(parsed)
-            except (json.JSONDecodeError, TypeError):
-                pass  # Keep result as-is if not valid JSON
-
-            return StepExecutionResult(
-                success=True,
-                outputs=outputs,
-                executor_type="tool_use",
-            )
-
-        except Exception as e:
-            return StepExecutionResult(
-                success=False,
-                error=str(e),
-                error_type="tool_exception",
-                executor_type="tool_use",
-            )
-
-    async def _execute_sub_graph(
-        self,
-        action: ActionSpec,
-        inputs: dict[str, Any],
-        context: dict[str, Any],
-    ) -> StepExecutionResult:
-        """Execute a sub-graph action."""
-        if self.sub_graph_executor is None:
-            return StepExecutionResult(
-                success=False,
-                error="No sub-graph executor configured",
-                error_type="configuration",
-                executor_type="sub_graph",
-            )
-
-        graph_id = action.graph_id
-        if not graph_id:
-            return StepExecutionResult(
-                success=False,
-                error="No graph ID specified",
-                error_type="invalid_action",
-                executor_type="sub_graph",
-            )
-
-        try:
-            result = await self.sub_graph_executor(graph_id, inputs, context)
-
-            return StepExecutionResult(
-                success=result.success,
-                outputs=result.output if result.success else {},
-                error=result.error if not result.success else None,
-                tokens_used=result.total_tokens,
-                executor_type="sub_graph",
-            )
-
-        except Exception as e:
-            return StepExecutionResult(
-                success=False,
-                error=str(e),
-                error_type="sub_graph_exception",
-                executor_type="sub_graph",
-            )
-
-    async def _execute_function(
-        self,
-        action: ActionSpec,
-        inputs: dict[str, Any],
-    ) -> StepExecutionResult:
-        """Execute a function action."""
-        func_name = action.function_name
-        if not func_name:
-            return StepExecutionResult(
-                success=False,
-                error="No function name specified",
-                error_type="invalid_action",
-                executor_type="function",
-            )
-
-        if func_name not in self.functions:
-            return StepExecutionResult(
-                success=False,
-                error=f"Function '{func_name}' not registered",
-                error_type="missing_function",
-                executor_type="function",
-            )
-
-        try:
-            func = self.functions[func_name]
-
-            # Merge action args with inputs
-            args = {**action.function_args, **inputs}
-
-            # Execute function
-            result = func(**args)
-
-            # Handle async functions
-            if hasattr(result, "__await__"):
-                result = await result
-
-            return StepExecutionResult(
-                success=True,
-                outputs={"result": result},
-                executor_type="function",
-            )
-
-        except Exception as e:
-            return StepExecutionResult(
-                success=False,
-                error=str(e),
-                error_type="function_exception",
-                executor_type="function",
-            )
-
-    def _execute_code(
-        self,
-        action: ActionSpec,
-        inputs: dict[str, Any],
-        context: dict[str, Any],
-    ) -> StepExecutionResult:
-        """Execute a code action in sandbox."""
-        code = action.code
-        if not code:
-            return StepExecutionResult(
-                success=False,
-                error="No code specified",
-                error_type="invalid_action",
-                executor_type="code_execution",
-            )
-
-        # Merge inputs with context for code
-        code_inputs = {**context, **inputs}
-
-        # Execute in sandbox
-        sandbox_result = self.sandbox.execute(code, code_inputs)
-
-        if sandbox_result.success:
-            return StepExecutionResult(
-                success=True,
-                outputs={
-                    "result": sandbox_result.result,
-                    **sandbox_result.variables,
-                },
-                executor_type="code_execution",
-                latency_ms=sandbox_result.execution_time_ms,
-            )
-        else:
-            error_type = "security" if "Security" in (sandbox_result.error or "") else "code_error"
-            return StepExecutionResult(
-                success=False,
-                error=sandbox_result.error,
-                error_type=error_type,
-                executor_type="code_execution",
-                latency_ms=sandbox_result.execution_time_ms,
-            )
-
-    def register_function(self, name: str, func: Callable) -> None:
-        """Register a function for FUNCTION actions."""
-        self.functions[name] = func
-
-    def register_tool(self, tool: Tool) -> None:
-        """Register a tool for TOOL_USE actions."""
-        self.tools[tool.name] = tool

core/framework/llm/litellm.py

@@ -28,6 +28,51 @@ from framework.llm.stream_events import StreamEvent
 
 logger = logging.getLogger(__name__)
 
+
+def _patch_litellm_anthropic_oauth() -> None:
+    """Patch litellm's Anthropic header construction to fix OAuth token handling.
+
+    litellm bug: validate_environment() puts the OAuth token into x-api-key,
+    but Anthropic's API rejects OAuth tokens in x-api-key. They must be sent
+    via Authorization: Bearer only, with x-api-key omitted entirely.
+
+    This patch wraps validate_environment to remove x-api-key when the
+    Authorization header carries an OAuth token (sk-ant-oat prefix).
+
+    See: https://github.com/BerriAI/litellm/issues/19618
+    """
+    try:
+        from litellm.llms.anthropic.common_utils import AnthropicModelInfo
+        from litellm.types.llms.anthropic import ANTHROPIC_OAUTH_TOKEN_PREFIX
+    except ImportError:
+        return
+
+    original = AnthropicModelInfo.validate_environment
+
+    def _patched_validate_environment(
+        self, headers, model, messages, optional_params, litellm_params, api_key=None, api_base=None
+    ):
+        result = original(
+            self,
+            headers,
+            model,
+            messages,
+            optional_params,
+            litellm_params,
+            api_key=api_key,
+            api_base=api_base,
+        )
+        auth = result.get("authorization", "")
+        if auth.startswith(f"Bearer {ANTHROPIC_OAUTH_TOKEN_PREFIX}"):
+            result.pop("x-api-key", None)
+        return result
+
+    AnthropicModelInfo.validate_environment = _patched_validate_environment
+
+
+if litellm is not None:
+    _patch_litellm_anthropic_oauth()
+
 RATE_LIMIT_MAX_RETRIES = 10
 RATE_LIMIT_BACKOFF_BASE = 2  # seconds
 RATE_LIMIT_MAX_DELAY = 120  # seconds - cap to prevent absurd waits
@@ -283,6 +328,20 @@ class LiteLLMProvider(LLMProvider):
                         f"Full request dumped to: {dump_path}"
                     )
 
+                    # finish_reason=length means the model exhausted max_tokens
+                    # before producing content. Retrying with the same max_tokens
+                    # will never help — return immediately instead of looping.
+                    if finish_reason == "length":
+                        max_tok = kwargs.get("max_tokens", "unset")
+                        logger.error(
+                            f"[retry] {model} returned empty content with "
+                            f"finish_reason=length (max_tokens={max_tok}). "
+                            f"The model exhausted its token budget before "
+                            f"producing visible output. Increase max_tokens "
+                            f"or use a different model. Not retrying."
+                        )
+                        return response
+
                     if attempt == retries:
                         logger.error(
                             f"[retry] GAVE UP on {model} after {retries + 1} "
@@ -576,6 +635,20 @@ class LiteLLMProvider(LLMProvider):
                         f"Full request dumped to: {dump_path}"
                     )
 
+                    # finish_reason=length means the model exhausted max_tokens
+                    # before producing content. Retrying with the same max_tokens
+                    # will never help — return immediately instead of looping.
+                    if finish_reason == "length":
+                        max_tok = kwargs.get("max_tokens", "unset")
+                        logger.error(
+                            f"[async-retry] {model} returned empty content with "
+                            f"finish_reason=length (max_tokens={max_tok}). "
+                            f"The model exhausted its token budget before "
+                            f"producing visible output. Increase max_tokens "
+                            f"or use a different model. Not retrying."
+                        )
+                        return response
+
                     if attempt == retries:
                         logger.error(
                             f"[async-retry] GAVE UP on {model} after {retries + 1} "
@@ -858,6 +931,7 @@ class LiteLLMProvider(LLMProvider):
             tool_calls_acc: dict[int, dict[str, str]] = {}
             input_tokens = 0
             output_tokens = 0
+            stream_finish_reason: str | None = None
 
             try:
                 response = await litellm.acompletion(**kwargs)  # type: ignore[union-attr]
@@ -893,6 +967,7 @@ class LiteLLMProvider(LLMProvider):
 
                     # --- Finish ---
                     if choice.finish_reason:
+                        stream_finish_reason = choice.finish_reason
                         for _idx, tc_data in sorted(tool_calls_acc.items()):
                             try:
                                 parsed_args = json.loads(tc_data["arguments"])
@@ -947,6 +1022,24 @@ class LiteLLMProvider(LLMProvider):
                         for event in tail_events:
                             yield event
                         return
+
+                    # finish_reason=length means the model exhausted
+                    # max_tokens before producing content. Retrying with
+                    # the same max_tokens will never help.
+                    if stream_finish_reason == "length":
+                        max_tok = kwargs.get("max_tokens", "unset")
+                        logger.error(
+                            f"[stream] {self.model} returned empty content "
+                            f"with finish_reason=length "
+                            f"(max_tokens={max_tok}). The model exhausted "
+                            f"its token budget before producing visible "
+                            f"output. Increase max_tokens or use a "
+                            f"different model. Not retrying."
+                        )
+                        for event in tail_events:
+                            yield event
+                        return
+
                     wait = _compute_retry_delay(attempt)
                     token_count, token_method = _estimate_tokens(
                         self.model,

core/framework/mcp/agent_builder_server.py

@@ -36,7 +36,6 @@ from framework.graph import (  # noqa: E402
     NodeSpec,
     SuccessCriterion,
 )
-from framework.graph.plan import Plan  # noqa: E402
 
 # Testing framework imports
 from framework.testing.prompts import (  # noqa: E402
@@ -587,13 +586,12 @@ def add_node(
     description: Annotated[str, "What this node does"],
     node_type: Annotated[
         str,
-        "Type: event_loop (recommended), function, router. "
-        "Deprecated: llm_generate, llm_tool_use (use event_loop instead)",
+        "Type: event_loop (recommended), router.",
     ],
     input_keys: Annotated[str, "JSON array of keys this node reads from shared memory"],
     output_keys: Annotated[str, "JSON array of keys this node writes to shared memory"],
     system_prompt: Annotated[str, "Instructions for LLM nodes"] = "",
-    tools: Annotated[str, "JSON array of tool names for event_loop or llm_tool_use nodes"] = "[]",
+    tools: Annotated[str, "JSON array of tool names for event_loop nodes"] = "[]",
     routes: Annotated[
         str, "JSON object mapping conditions to target node IDs for router nodes"
     ] = "{}",
@@ -665,24 +663,18 @@ def add_node(
         errors.append("Node must have an id")
     if not name:
         errors.append("Node must have a name")
-    if node_type == "llm_tool_use" and not tools_list:
-        errors.append(f"Node '{node_id}' of type llm_tool_use must specify tools")
+
+    # Reject removed node types
+    if node_type in ("function", "llm_tool_use", "llm_generate"):
+        errors.append(f"Node type '{node_type}' is no longer supported. Use 'event_loop' instead.")
+
     if node_type == "router" and not routes_dict:
         errors.append(f"Router node '{node_id}' must specify routes")
-    if node_type in ("llm_generate", "llm_tool_use") and not system_prompt:
-        warnings.append(f"LLM node '{node_id}' should have a system_prompt")
 
     # EventLoopNode validation
     if node_type == "event_loop" and not system_prompt:
         warnings.append(f"Event loop node '{node_id}' should have a system_prompt")
 
-    # Deprecated type warnings
-    if node_type in ("llm_generate", "llm_tool_use"):
-        warnings.append(
-            f"Node type '{node_type}' is deprecated. Use 'event_loop' instead. "
-            "EventLoopNode supports tool use, streaming, and judge-based evaluation."
-        )
-
     # Warn about client_facing on nodes with tools (likely autonomous work)
     if node_type == "event_loop" and client_facing and tools_list:
         warnings.append(
@@ -838,8 +830,7 @@ def update_node(
     description: Annotated[str, "Updated description"] = "",
     node_type: Annotated[
         str,
-        "Updated type: event_loop (recommended), function, router. "
-        "Deprecated: llm_generate, llm_tool_use",
+        "Updated type: event_loop (recommended), router.",
     ] = "",
     input_keys: Annotated[str, "Updated JSON array of input keys"] = "",
     output_keys: Annotated[str, "Updated JSON array of output keys"] = "",
@@ -919,24 +910,19 @@ def update_node(
     errors = []
     warnings = []
 
-    if node.node_type == "llm_tool_use" and not node.tools:
-        errors.append(f"Node '{node_id}' of type llm_tool_use must specify tools")
+    # Reject removed node types
+    if node.node_type in ("function", "llm_tool_use", "llm_generate"):
+        errors.append(
+            f"Node type '{node.node_type}' is no longer supported. Use 'event_loop' instead."
+        )
+
     if node.node_type == "router" and not node.routes:
         errors.append(f"Router node '{node_id}' must specify routes")
-    if node.node_type in ("llm_generate", "llm_tool_use") and not node.system_prompt:
-        warnings.append(f"LLM node '{node_id}' should have a system_prompt")
 
     # EventLoopNode validation
     if node.node_type == "event_loop" and not node.system_prompt:
         warnings.append(f"Event loop node '{node_id}' should have a system_prompt")
 
-    # Deprecated type warnings
-    if node.node_type in ("llm_generate", "llm_tool_use"):
-        warnings.append(
-            f"Node type '{node.node_type}' is deprecated. Use 'event_loop' instead. "
-            "EventLoopNode supports tool use, streaming, and judge-based evaluation."
-        )
-
     # nullable_output_keys must be a subset of output_keys
     if node.nullable_output_keys:
         invalid_nullable = [k for k in node.nullable_output_keys if k not in node.output_keys]
@@ -1390,17 +1376,6 @@ def validate_graph() -> str:
                     f"must be a subset of output_keys {node.output_keys}"
                 )
 
-    # Deprecated node type warnings
-    deprecated_nodes = [
-        {"node_id": n.id, "type": n.node_type, "replacement": "event_loop"}
-        for n in session.nodes
-        if n.node_type in ("llm_generate", "llm_tool_use")
-    ]
-    for dn in deprecated_nodes:
-        warnings.append(
-            f"Node '{dn['node_id']}' uses deprecated type '{dn['type']}'. Use 'event_loop' instead."
-        )
-
     # Warn if all event_loop nodes are client_facing (common misconfiguration)
     el_nodes = [n for n in session.nodes if n.node_type == "event_loop"]
     cf_el_nodes = [n for n in el_nodes if n.client_facing]
@@ -1436,7 +1411,6 @@ def validate_graph() -> str:
             "event_loop_nodes": event_loop_nodes,
             "client_facing_nodes": client_facing_nodes,
             "feedback_edges": feedback_edges,
-            "deprecated_node_types": deprecated_nodes,
         }
     )
 
@@ -1646,9 +1620,8 @@ def export_graph() -> str:
     """
     Export the validated graph as a GraphSpec for GraphExecutor.
 
-    Exports the complete agent definition including nodes, edges, goal,
-    and evaluation rules. The GraphExecutor runs the graph with dynamic
-    edge traversal and routing logic.
+    Exports the complete agent definition including nodes, edges, and goal.
+    The GraphExecutor runs the graph with dynamic edge traversal and routing logic.
 
     AUTOMATICALLY WRITES FILES TO DISK:
     - exports/{agent-name}/agent.json - Full agent specification
@@ -1856,7 +1829,6 @@ def export_graph() -> str:
             "files_written": files_written,
             "graph": graph_spec,
             "goal": session.goal.model_dump(),
-            "evaluation_rules": _evaluation_rules,
             "required_tools": list(all_tools),
             "node_count": len(session.nodes),
             "edge_count": len(edges_list),
@@ -1966,9 +1938,6 @@ def get_session_status() -> str:
             "mcp_servers": [s["name"] for s in session.mcp_servers],
             "event_loop_nodes": [n.id for n in session.nodes if n.node_type == "event_loop"],
             "client_facing_nodes": [n.id for n in session.nodes if n.client_facing],
-            "deprecated_nodes": [
-                n.id for n in session.nodes if n.node_type in ("llm_generate", "llm_tool_use")
-            ],
             "feedback_edges": [e.id for e in session.edges if e.priority < 0],
         }
     )
@@ -2139,7 +2108,7 @@ def add_mcp_server(
                     "total_mcp_servers": len(session.mcp_servers),
                     "note": (
                         f"MCP server '{name}' registered with {len(tool_names)} tools. "
-                        "These tools can now be used in llm_tool_use nodes."
+                        "These tools can now be used in event_loop nodes."
                     ),
                 },
                 indent=2,
@@ -2240,7 +2209,7 @@ def list_mcp_tools(
             "success": True,
             "tools_by_server": all_tools,
             "total_tools": total_tools,
-            "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",
         },
         indent=2,
     )
@@ -2339,23 +2308,6 @@ def test_node(
                 + f"Max visits per graph run: {node_spec.max_node_visits}."
             )
 
-    elif node_spec.node_type in ("llm_generate", "llm_tool_use"):
-        # Legacy LLM node types
-        result["system_prompt"] = node_spec.system_prompt
-        result["available_tools"] = node_spec.tools
-        result["deprecation_warning"] = (
-            f"Node type '{node_spec.node_type}' is deprecated. Use 'event_loop' instead."
-        )
-
-        if mock_llm_response:
-            result["mock_response"] = mock_llm_response
-            result["simulation"] = "LLM would receive prompt and produce response"
-        else:
-            result["simulation"] = "LLM would be called with the system prompt and input data"
-
-    elif node_spec.node_type == "function":
-        result["simulation"] = "Function node would execute deterministic logic"
-
     # Show memory state after (simulated)
     result["expected_memory_state"] = {
         "inputs_available": {k: input_data.get(k, "<not provided>") for k in node_spec.input_keys},
@@ -2449,7 +2401,7 @@ def test_graph(
             "writes": current_node.output_keys,
         }
 
-        if current_node.node_type in ("llm_generate", "llm_tool_use", "event_loop"):
+        if current_node.node_type == "event_loop":
             step_info["prompt_preview"] = (
                 current_node.system_prompt[:200] + "..."
                 if current_node.system_prompt and len(current_node.system_prompt) > 200
@@ -2520,466 +2472,6 @@ def test_graph(
     )
 
 
-# =============================================================================
-# FLEXIBLE EXECUTION TOOLS (Worker-Judge Pattern)
-# =============================================================================
-
-# Storage for evaluation rules
-_evaluation_rules: list[dict] = []
-
-
-@mcp.tool()
-def add_evaluation_rule(
-    rule_id: Annotated[str, "Unique identifier for the rule"],
-    description: Annotated[str, "Human-readable description of what this rule checks"],
-    condition: Annotated[
-        str,
-        "Python expression with result, step, goal context. E.g., 'result.get(\"success\")'",
-    ],
-    action: Annotated[str, "Action when rule matches: accept, retry, replan, escalate"],
-    feedback_template: Annotated[
-        str, "Template for feedback message, can use {result}, {step}"
-    ] = "",
-    priority: Annotated[int, "Rule priority (higher = checked first)"] = 0,
-) -> str:
-    """
-    Add an evaluation rule for the HybridJudge.
-
-    Rules are checked in priority order before falling back to LLM evaluation.
-    Use this to define deterministic success/failure conditions.
-
-    Example conditions:
-    - 'result.get("success") == True' - Check for explicit success flag
-    - 'result.get("error_type") == "timeout"' - Check for specific error type
-    - 'len(result.get("data", [])) > 0' - Check for non-empty data
-    """
-    global _evaluation_rules
-
-    # Validate action
-    valid_actions = ["accept", "retry", "replan", "escalate"]
-    if action.lower() not in valid_actions:
-        return json.dumps(
-            {
-                "success": False,
-                "error": f"Invalid action '{action}'. Must be one of: {valid_actions}",
-            }
-        )
-
-    # Check for duplicate
-    if any(r["id"] == rule_id for r in _evaluation_rules):
-        return json.dumps(
-            {
-                "success": False,
-                "error": f"Rule '{rule_id}' already exists",
-            }
-        )
-
-    rule = {
-        "id": rule_id,
-        "description": description,
-        "condition": condition,
-        "action": action.lower(),
-        "feedback_template": feedback_template,
-        "priority": priority,
-    }
-
-    _evaluation_rules.append(rule)
-    _evaluation_rules.sort(key=lambda r: -r["priority"])
-
-    return json.dumps(
-        {
-            "success": True,
-            "rule": rule,
-            "total_rules": len(_evaluation_rules),
-        }
-    )
-
-
-@mcp.tool()
-def list_evaluation_rules() -> str:
-    """List all configured evaluation rules for the HybridJudge."""
-    return json.dumps(
-        {
-            "rules": _evaluation_rules,
-            "total": len(_evaluation_rules),
-        }
-    )
-
-
-@mcp.tool()
-def remove_evaluation_rule(
-    rule_id: Annotated[str, "ID of the rule to remove"],
-) -> str:
-    """Remove an evaluation rule."""
-    global _evaluation_rules
-
-    for i, rule in enumerate(_evaluation_rules):
-        if rule["id"] == rule_id:
-            _evaluation_rules.pop(i)
-            return json.dumps({"success": True, "removed": rule_id})
-
-    return json.dumps({"success": False, "error": f"Rule '{rule_id}' not found"})
-
-
-@mcp.tool()
-def create_plan(
-    plan_id: Annotated[str, "Unique identifier for the plan"],
-    goal_id: Annotated[str, "ID of the goal this plan achieves"],
-    description: Annotated[str, "Description of what this plan does"],
-    steps: Annotated[
-        str,
-        "JSON array of plan steps with id, description, action, inputs, outputs, deps",
-    ],
-    context: Annotated[str, "JSON object with initial context for execution"] = "{}",
-) -> str:
-    """
-    Create a plan for flexible execution.
-
-    Plans are executed by the Worker-Judge loop. Each step specifies:
-    - id: Unique step identifier
-    - description: What this step does
-    - action: Object with action_type and parameters
-      - action_type: "llm_call", "tool_use", "function", "code_execution", "sub_graph"
-      - For llm_call: prompt, system_prompt
-      - For tool_use: tool_name, tool_args
-      - For function: function_name, function_args
-      - For code_execution: code
-    - inputs: Dict mapping input names to values or "$variable" references
-    - expected_outputs: List of output keys this step should produce
-    - dependencies: List of step IDs that must complete first (deps)
-
-    Example step:
-    {
-        "id": "step_1",
-        "description": "Fetch user data",
-        "action": {"action_type": "tool_use", "tool_name": "get_user", ...},
-        "inputs": {"user_id": "$input_user_id"},
-        "expected_outputs": ["user_data"],
-        "dependencies": []
-    }
-    """
-    try:
-        steps_list = json.loads(steps)
-        context_dict = json.loads(context)
-    except json.JSONDecodeError as e:
-        return json.dumps({"success": False, "error": f"Invalid JSON: {e}"})
-
-    # Validate steps
-    errors = []
-    step_ids = set()
-
-    for i, step in enumerate(steps_list):
-        if "id" not in step:
-            errors.append(f"Step {i} missing 'id'")
-        else:
-            if step["id"] in step_ids:
-                errors.append(f"Duplicate step id: {step['id']}")
-            step_ids.add(step["id"])
-
-        if "description" not in step:
-            errors.append(f"Step {i} missing 'description'")
-
-        if "action" not in step:
-            errors.append(f"Step {i} missing 'action'")
-        elif "action_type" not in step.get("action", {}):
-            errors.append(f"Step {i} action missing 'action_type'")
-
-        # Check dependencies exist
-        for dep in step.get("dependencies", []):
-            if dep not in step_ids:
-                errors.append(f"Step {step.get('id', i)} has unknown dependency: {dep}")
-
-    if errors:
-        return json.dumps({"success": False, "errors": errors})
-
-    # Build plan object
-    plan = {
-        "id": plan_id,
-        "goal_id": goal_id,
-        "description": description,
-        "steps": steps_list,
-        "context": context_dict,
-        "revision": 1,
-        "created_at": datetime.now().isoformat(),
-    }
-
-    return json.dumps(
-        {
-            "success": True,
-            "plan": plan,
-            "step_count": len(steps_list),
-            "note": "Plan created. Use execute_plan to run it with the Worker-Judge loop.",
-        },
-        indent=2,
-    )
-
-
-@mcp.tool()
-def validate_plan(
-    plan_json: Annotated[str, "JSON string of the plan to validate"],
-) -> str:
-    """
-    Validate a plan structure before execution.
-
-    Checks:
-    - All required fields present
-    - No circular dependencies
-    - All dependencies reference existing steps
-    - Action types are valid
-    - Context flow: all $variable references can be resolved
-    """
-    try:
-        plan = json.loads(plan_json)
-    except json.JSONDecodeError as e:
-        return json.dumps({"valid": False, "errors": [f"Invalid JSON: {e}"]})
-
-    errors = []
-    warnings = []
-
-    # Check required fields
-    required = ["id", "goal_id", "steps"]
-    for field in required:
-        if field not in plan:
-            errors.append(f"Missing required field: {field}")
-
-    if "steps" not in plan:
-        return json.dumps({"valid": False, "errors": errors})
-
-    steps = plan["steps"]
-    step_ids = {s.get("id") for s in steps if "id" in s}
-    steps_by_id = {s.get("id"): s for s in steps}
-
-    # Check each step
-    valid_action_types = ["llm_call", "tool_use", "function", "code_execution", "sub_graph"]
-
-    for i, step in enumerate(steps):
-        step_id = step.get("id", f"step_{i}")
-
-        # Check dependencies
-        for dep in step.get("dependencies", []):
-            if dep not in step_ids:
-                errors.append(f"Step '{step_id}': unknown dependency '{dep}'")
-
-        # Check action type
-        action = step.get("action", {})
-        action_type = action.get("action_type")
-        if action_type and action_type not in valid_action_types:
-            errors.append(f"Step '{step_id}': invalid action_type '{action_type}'")
-
-        # Check action has required params
-        if action_type == "llm_call" and not action.get("prompt"):
-            warnings.append(f"Step '{step_id}': llm_call without prompt")
-        if action_type == "tool_use" and not action.get("tool_name"):
-            errors.append(f"Step '{step_id}': tool_use requires tool_name")
-        if action_type == "code_execution" and not action.get("code"):
-            errors.append(f"Step '{step_id}': code_execution requires code")
-
-    # Check for circular dependencies
-    def has_cycle(step_id: str, visited: set, path: set) -> bool:
-        if step_id in path:
-            return True
-        if step_id in visited:
-            return False
-
-        visited.add(step_id)
-        path.add(step_id)
-
-        step = next((s for s in steps if s.get("id") == step_id), None)
-        if step:
-            for dep in step.get("dependencies", []):
-                if has_cycle(dep, visited, path):
-                    return True
-
-        path.remove(step_id)
-        return False
-
-    for step in steps:
-        if has_cycle(step.get("id", ""), set(), set()):
-            errors.append(f"Circular dependency detected involving step '{step.get('id')}'")
-            break
-
-    # === CONTEXT FLOW VALIDATION ===
-    # Compute what keys each step can access (from dependencies' outputs)
-
-    # Build output map (step_id -> expected_outputs)
-    step_outputs: dict[str, set[str]] = {}
-    for step in steps:
-        step_outputs[step.get("id", "")] = set(step.get("expected_outputs", []))
-
-    # Compute available context for each step in topological order
-    available_context: dict[str, set[str]] = {}
-    computed = set()
-    remaining = set(step_ids)
-
-    # Get initial context keys from plan.context
-    initial_context = set(plan.get("context", {}).keys())
-
-    for _ in range(len(steps) * 2):
-        if not remaining:
-            break
-
-        for step_id in list(remaining):
-            step = steps_by_id.get(step_id)
-            if not step:
-                remaining.discard(step_id)
-                continue
-
-            deps = step.get("dependencies", [])
-
-            # Can compute if all dependencies are computed
-            if all(d in computed for d in deps):
-                # Collect outputs from all dependencies (transitive)
-                available = set(initial_context)
-                for dep_id in deps:
-                    available.update(step_outputs.get(dep_id, set()))
-                    available.update(available_context.get(dep_id, set()))
-
-                available_context[step_id] = available
-                computed.add(step_id)
-                remaining.discard(step_id)
-                break
-
-    # Check each step's inputs can be resolved
-    context_errors = []
-    context_warnings = []
-
-    for step in steps:
-        step_id = step.get("id", "")
-        available = available_context.get(step_id, set())
-        deps = step.get("dependencies", [])
-        inputs = step.get("inputs", {})
-
-        missing_vars = []
-        for _, input_value in inputs.items():
-            # Check $variable references
-            if isinstance(input_value, str) and input_value.startswith("$"):
-                var_name = input_value[1:]  # Remove $ prefix
-                if var_name not in available:
-                    missing_vars.append(var_name)
-
-        if missing_vars:
-            if not deps:
-                # Entry step - inputs must come from initial context
-                context_warnings.append(
-                    f"Step '{step_id}' requires ${missing_vars} from initial context. "
-                    f"Ensure these are provided when running the agent: {missing_vars}"
-                )
-            else:
-                # Find which step could provide each missing var
-                suggestions = []
-                for var in missing_vars:
-                    producers = [s.get("id") for s in steps if var in s.get("expected_outputs", [])]
-                    if producers:
-                        suggestions.append(f"${var} is produced by {producers} - add as dependency")
-                    else:
-                        suggestions.append(
-                            f"${var} is not produced by any step - add a step that outputs '{var}'"
-                        )
-
-                context_errors.append(
-                    f"Step '{step_id}' references ${missing_vars} but deps "
-                    f"{deps} don't provide them. Suggestions: {'; '.join(suggestions)}"
-                )
-
-    errors.extend(context_errors)
-    warnings.extend(context_warnings)
-
-    return json.dumps(
-        {
-            "valid": len(errors) == 0,
-            "errors": errors,
-            "warnings": warnings,
-            "step_count": len(steps),
-            "context_flow": {step_id: list(keys) for step_id, keys in available_context.items()}
-            if available_context
-            else None,
-        }
-    )
-
-
-@mcp.tool()
-def simulate_plan_execution(
-    plan_json: Annotated[str, "JSON string of the plan to simulate"],
-    max_steps: Annotated[int, "Maximum steps to simulate"] = 20,
-) -> str:
-    """
-    Simulate plan execution without actually running it.
-
-    Shows the order steps would execute based on dependencies.
-    Useful for understanding the execution flow before running.
-    """
-    try:
-        plan = json.loads(plan_json)
-    except json.JSONDecodeError as e:
-        return json.dumps({"success": False, "error": f"Invalid JSON: {e}"})
-
-    # Validate first
-    validation = json.loads(validate_plan(plan_json))
-    if not validation["valid"]:
-        return json.dumps(
-            {
-                "success": False,
-                "error": "Plan is not valid",
-                "validation_errors": validation["errors"],
-            }
-        )
-
-    steps = plan.get("steps", [])
-    completed = set()
-    execution_order = []
-    iteration = 0
-
-    while len(completed) < len(steps) and iteration < max_steps:
-        iteration += 1
-
-        # Find ready steps
-        ready = []
-        for step in steps:
-            step_id = step.get("id")
-            if step_id in completed:
-                continue
-            deps = set(step.get("dependencies", []))
-            if deps.issubset(completed):
-                ready.append(step)
-
-        if not ready:
-            break
-
-        # Execute first ready step (in real execution, could be parallel)
-        step = ready[0]
-        step_id = step.get("id")
-
-        execution_order.append(
-            {
-                "iteration": iteration,
-                "step_id": step_id,
-                "description": step.get("description"),
-                "action_type": step.get("action", {}).get("action_type"),
-                "dependencies_met": list(step.get("dependencies", [])),
-                "parallel_candidates": [s.get("id") for s in ready[1:]],
-            }
-        )
-
-        completed.add(step_id)
-
-    remaining = [s.get("id") for s in steps if s.get("id") not in completed]
-
-    return json.dumps(
-        {
-            "success": True,
-            "execution_order": execution_order,
-            "steps_simulated": len(execution_order),
-            "remaining_steps": remaining,
-            "plan_complete": len(remaining) == 0,
-            "note": (
-                "This is a simulation. Actual execution may differ "
-                "based on step results and judge decisions."
-            ),
-        },
-        indent=2,
-    )
-
-
 # =============================================================================
 # TESTING TOOLS (Goal-Based Evaluation)
 # =============================================================================
@@ -3713,90 +3205,37 @@ def list_tests(
     )
 
 
-# =============================================================================
-# PLAN LOADING AND EXECUTION
-# =============================================================================
-
-
-def load_plan_from_json(plan_json: str | dict) -> Plan:
-    """
-    Load a Plan object from exported JSON.
-
-    Args:
-        plan_json: JSON string or dict from export_graph()
-
-    Returns:
-        Plan object ready for FlexibleGraphExecutor
-    """
-    from framework.graph.plan import Plan
-
-    return Plan.from_json(plan_json)
-
-
-@mcp.tool()
-def load_exported_plan(
-    plan_json: Annotated[str, "JSON string from export_graph() output"],
-) -> str:
-    """
-    Validate and load an exported plan, returning its structure.
-
-    Use this to verify a plan can be loaded before execution.
-    """
-    try:
-        plan = load_plan_from_json(plan_json)
-        return json.dumps(
-            {
-                "success": True,
-                "plan_id": plan.id,
-                "goal_id": plan.goal_id,
-                "description": plan.description,
-                "step_count": len(plan.steps),
-                "steps": [
-                    {
-                        "id": s.id,
-                        "description": s.description,
-                        "action_type": s.action.action_type.value,
-                        "dependencies": s.dependencies,
-                    }
-                    for s in plan.steps
-                ],
-            },
-            indent=2,
-        )
-    except Exception as e:
-        return json.dumps({"success": False, "error": str(e)})
-
-
 # =============================================================================
 # CREDENTIAL STORE TOOLS
 # =============================================================================
 
 
 def _get_credential_store():
-    """Get a CredentialStore that checks encrypted files and env vars.
+    """Get a CredentialStore that checks encrypted files, env vars, and Aden sync.
 
-    Uses CompositeStorage: encrypted file storage (primary) with env var fallback.
-    This ensures credentials stored via `store_credential` AND env vars are both found.
+    Uses CredentialStoreAdapter.default() which handles:
+    - Aden sync + provider index (resolving hashed IDs for OAuth)
+    - CompositeStorage (encrypted primary + env fallback)
+    - Auto-refresh of OAuth tokens
+    - Graceful fallback if Aden is unavailable
     """
-    from framework.credentials import CredentialStore
-    from framework.credentials.storage import CompositeStorage, EncryptedFileStorage, EnvVarStorage
-
-    # Build env var mapping from CREDENTIAL_SPECS for the fallback
-    env_mapping: dict[str, str] = {}
     try:
-        from aden_tools.credentials import CREDENTIAL_SPECS
+        from aden_tools.credentials.store_adapter import CredentialStoreAdapter
 
-        for name, spec in CREDENTIAL_SPECS.items():
-            cred_id = spec.credential_id or name
-            env_mapping[cred_id] = spec.env_var
+        return CredentialStoreAdapter.default().store
     except ImportError:
-        pass
+        from framework.credentials import CredentialStore
+        from framework.credentials.storage import (
+            CompositeStorage,
+            EncryptedFileStorage,
+            EnvVarStorage,
+        )
 
-    storage = CompositeStorage(
-        primary=EncryptedFileStorage(),
-        fallbacks=[EnvVarStorage(env_mapping=env_mapping)],
-    )
-    return CredentialStore(storage=storage)
+        storage = CompositeStorage(
+            primary=EncryptedFileStorage(),
+            fallbacks=[EnvVarStorage(env_mapping={})],
+        )
+        return CredentialStore(storage=storage)
 
 
 @mcp.tool()
@@ -3899,6 +3338,11 @@ def store_credential(
         str, "Logical credential name (e.g., 'hubspot', 'brave_search', 'anthropic')"
     ],
     credential_value: Annotated[str, "The secret value to store (API key, token, etc.)"],
+    alias: Annotated[
+        str,
+        "Named alias for this account (e.g., 'work', 'personal'). Defaults to 'default'. "
+        "Use aliases to store multiple accounts for the same service.",
+    ] = "default",
     key_name: Annotated[
         str, "Key name within the credential (e.g., 'api_key', 'access_token')"
     ] = "api_key",
@@ -3908,38 +3352,42 @@ def store_credential(
     Store a credential securely in the local encrypted store at ~/.hive/credentials.
 
     Uses Fernet encryption (AES-128-CBC + HMAC). Requires HIVE_CREDENTIAL_KEY env var.
+
+    Credentials are stored as {credential_name}/{alias}, allowing multiple named accounts
+    per service (e.g., 'brave_search/work', 'brave_search/personal').
+    A health check is run automatically to validate the key and extract identity metadata.
     """
     try:
-        from pydantic import SecretStr
+        from framework.credentials.local.registry import LocalCredentialRegistry
 
-        from framework.credentials import CredentialKey, CredentialObject
-
-        store = _get_credential_store()
-
-        if not display_name:
-            display_name = credential_name.replace("_", " ").title()
-
-        cred = CredentialObject(
-            id=credential_name,
-            name=display_name,
-            keys={
-                key_name: CredentialKey(
-                    name=key_name,
-                    value=SecretStr(credential_value),
-                )
-            },
+        registry = LocalCredentialRegistry.default()
+        info, health_result = registry.save_account(
+            credential_id=credential_name,
+            alias=alias,
+            api_key=credential_value,
+            run_health_check=True,
         )
-        store.save_credential(cred)
 
-        return json.dumps(
-            {
-                "success": True,
-                "credential": credential_name,
-                "key": key_name,
-                "location": "~/.hive/credentials",
-                "encrypted": True,
+        result: dict = {
+            "success": True,
+            "credential": credential_name,
+            "alias": alias,
+            "storage_id": info.storage_id,
+            "status": info.status,
+            "location": "~/.hive/credentials",
+            "encrypted": True,
+        }
+
+        if health_result is not None:
+            result["health_check"] = {
+                "valid": health_result.valid,
+                "message": health_result.message,
             }
-        )
+            identity = info.identity.to_dict()
+            if identity:
+                result["identity"] = identity
+
+        return json.dumps(result)
     except Exception as e:
         return json.dumps({"success": False, "error": str(e)})
 
@@ -3949,26 +3397,28 @@ def list_stored_credentials() -> str:
     """
     List all credentials currently stored in the local encrypted store.
 
-    Returns credential IDs and metadata (never returns secret values).
+    Returns credential IDs, aliases, status, and identity metadata (never returns secret values).
     """
     try:
-        store = _get_credential_store()
-        credential_ids = store.list_credentials()
+        from framework.credentials.local.registry import LocalCredentialRegistry
+
+        registry = LocalCredentialRegistry.default()
+        accounts = registry.list_accounts()
 
         credentials = []
-        for cred_id in credential_ids:
-            try:
-                cred = store.get_credential(cred_id)
-                credentials.append(
-                    {
-                        "id": cred.id,
-                        "name": cred.name,
-                        "keys": list(cred.keys.keys()),
-                        "created_at": cred.created_at.isoformat() if cred.created_at else None,
-                    }
-                )
-            except Exception:
-                credentials.append({"id": cred_id, "error": "Could not load"})
+        for info in accounts:
+            entry: dict = {
+                "credential_id": info.credential_id,
+                "alias": info.alias,
+                "storage_id": info.storage_id,
+                "status": info.status,
+                "created_at": info.created_at.isoformat() if info.created_at else None,
+                "last_validated": info.last_validated.isoformat() if info.last_validated else None,
+            }
+            identity = info.identity.to_dict()
+            if identity:
+                entry["identity"] = identity
+            credentials.append(entry)
 
         return json.dumps(
             {
@@ -3985,26 +3435,75 @@ def list_stored_credentials() -> str:
 @mcp.tool()
 def delete_stored_credential(
     credential_name: Annotated[str, "Logical credential name to delete (e.g., 'hubspot')"],
+    alias: Annotated[
+        str,
+        "Alias of the account to delete (e.g., 'work', 'personal'). Defaults to 'default'.",
+    ] = "default",
 ) -> str:
     """
     Delete a credential from the local encrypted store.
     """
     try:
-        store = _get_credential_store()
-        deleted = store.delete_credential(credential_name)
+        from framework.credentials.local.registry import LocalCredentialRegistry
+
+        registry = LocalCredentialRegistry.default()
+        storage_id = f"{credential_name}/{alias}"
+        deleted = registry.delete_account(credential_name, alias)
         return json.dumps(
             {
                 "success": deleted,
                 "credential": credential_name,
-                "message": f"Credential '{credential_name}' deleted"
+                "alias": alias,
+                "storage_id": storage_id,
+                "message": f"Credential '{storage_id}' deleted"
                 if deleted
-                else f"Credential '{credential_name}' not found",
+                else f"Credential '{storage_id}' not found",
             }
         )
     except Exception as e:
         return json.dumps({"success": False, "error": str(e)})
 
 
+@mcp.tool()
+def validate_credential(
+    credential_name: Annotated[
+        str, "Logical credential name to validate (e.g., 'brave_search', 'github')"
+    ],
+    alias: Annotated[
+        str,
+        "Alias of the account to validate (e.g., 'work', 'personal'). Defaults to 'default'.",
+    ] = "default",
+) -> str:
+    """
+    Re-run health check for a stored credential and update its status.
+
+    Makes a live API call to verify the credential is still valid and updates
+    the stored status and last_validated timestamp.
+    """
+    try:
+        from framework.credentials.local.registry import LocalCredentialRegistry
+
+        registry = LocalCredentialRegistry.default()
+        result = registry.validate_account(credential_name, alias)
+
+        response: dict = {
+            "credential": credential_name,
+            "alias": alias,
+            "storage_id": f"{credential_name}/{alias}",
+            "valid": result.valid,
+            "status": "active" if result.valid else "failed",
+            "message": result.message,
+        }
+
+        identity = result.details.get("identity") if result.details else None
+        if identity:
+            response["identity"] = identity
+
+        return json.dumps(response)
+    except Exception as e:
+        return json.dumps({"success": False, "error": str(e)})
+
+
 @mcp.tool()
 def verify_credentials(
     agent_path: Annotated[str, "Path to the exported agent directory (e.g., 'exports/my-agent')"],

core/framework/monitoring/__init__.py

@@ -0,0 +1,33 @@
+"""Framework-level worker monitoring package.
+
+Provides the Worker Health Judge: a reusable secondary graph that attaches to
+any worker agent runtime and monitors its execution health via periodic log
+inspection. Emits structured EscalationTickets when degradation is detected.
+
+Usage::
+
+    from framework.monitoring import HEALTH_JUDGE_ENTRY_POINT, judge_goal, judge_graph
+    from framework.tools.worker_monitoring_tools import register_worker_monitoring_tools
+
+    # Register tools bound to the worker runtime's EventBus
+    monitoring_registry = ToolRegistry()
+    register_worker_monitoring_tools(monitoring_registry, worker_runtime._event_bus, storage_path)
+
+    # Load judge as secondary graph on the worker runtime
+    await worker_runtime.add_graph(
+        graph_id="judge",
+        graph=judge_graph,
+        goal=judge_goal,
+        entry_points={"health_check": HEALTH_JUDGE_ENTRY_POINT},
+        storage_subpath="graphs/judge",
+    )
+"""
+
+from .judge import HEALTH_JUDGE_ENTRY_POINT, judge_goal, judge_graph, judge_node
+
+__all__ = [
+    "HEALTH_JUDGE_ENTRY_POINT",
+    "judge_goal",
+    "judge_graph",
+    "judge_node",
+]

core/framework/monitoring/judge.py

@@ -0,0 +1,258 @@
+"""Worker Health Judge — framework-level reusable monitoring graph.
+
+Attaches to any worker agent runtime as a secondary graph. Fires on a
+2-minute timer, reads the worker's session logs via ``get_worker_health_summary``,
+accumulates observations in a continuous conversation context, and emits a
+structured ``EscalationTicket`` when it detects a degradation pattern.
+
+Usage::
+
+    from framework.monitoring import judge_graph, judge_goal, HEALTH_JUDGE_ENTRY_POINT
+    from framework.tools.worker_monitoring_tools import register_worker_monitoring_tools
+
+    # Register tools bound to the worker runtime's event bus
+    monitoring_registry = ToolRegistry()
+    register_worker_monitoring_tools(
+        monitoring_registry, worker_runtime._event_bus, storage_path
+    )
+    monitoring_tools = list(monitoring_registry.get_tools().values())
+    monitoring_executor = monitoring_registry.get_executor()
+
+    # Load judge as secondary graph on the worker runtime
+    await worker_runtime.add_graph(
+        graph_id="judge",
+        graph=judge_graph,
+        goal=judge_goal,
+        entry_points={"health_check": HEALTH_JUDGE_ENTRY_POINT},
+        storage_subpath="graphs/judge",
+    )
+
+Design:
+- ``isolation_level="isolated"`` — the judge has its own memory, not
+  polluting the worker's shared memory namespace.
+- ``conversation_mode="continuous"`` — the judge's conversation carries
+  across timer ticks. The conversation IS the judge's memory. It tracks
+  trends by referring to its own prior messages ("Last check I saw 47
+  steps; now 52; 5 new steps, 3 RETRY").
+- No shared memory keys. No external state files.
+"""
+
+from __future__ import annotations
+
+from framework.graph import Constraint, Goal, NodeSpec, SuccessCriterion
+from framework.graph.edge import AsyncEntryPointSpec, GraphSpec
+
+# ---------------------------------------------------------------------------
+# Goal
+# ---------------------------------------------------------------------------
+
+judge_goal = Goal(
+    id="worker-health-monitor",
+    name="Worker Health Monitor",
+    description=(
+        "Periodically assess the health of the worker agent by reading its "
+        "execution logs. Detect degradation patterns (excessive retries, "
+        "stalls, doom loops) and emit structured EscalationTickets when the "
+        "worker needs attention."
+    ),
+    success_criteria=[
+        SuccessCriterion(
+            id="accurate-detection",
+            description="Only escalates genuine degradation, not normal retry cycles",
+            metric="false_positive_rate",
+            target="low",
+            weight=0.5,
+        ),
+        SuccessCriterion(
+            id="timely-detection",
+            description="Detects genuine stalls within 2 timer ticks (≤4 minutes)",
+            metric="detection_latency_minutes",
+            target="<=4",
+            weight=0.5,
+        ),
+    ],
+    constraints=[
+        Constraint(
+            id="conservative-escalation",
+            description=(
+                "Do not escalate on a single bad verdict or a brief stall. "
+                "Require clear patterns (10+ consecutive bad verdicts or 4+ minute stall) "
+                "before creating a ticket."
+            ),
+            constraint_type="hard",
+            category="quality",
+        ),
+        Constraint(
+            id="complete-ticket",
+            description=(
+                "Every EscalationTicket must have all required fields filled. "
+                "Do not emit partial or placeholder tickets."
+            ),
+            constraint_type="hard",
+            category="correctness",
+        ),
+    ],
+)
+
+# ---------------------------------------------------------------------------
+# Node
+# ---------------------------------------------------------------------------
+
+judge_node = NodeSpec(
+    id="judge",
+    name="Worker Health Judge",
+    description=(
+        "Autonomous health monitor for worker agents. Reads execution logs "
+        "on each timer tick, compares to prior observations (via conversation "
+        "history), and emits a structured EscalationTicket when a genuine "
+        "degradation pattern is detected."
+    ),
+    node_type="event_loop",
+    client_facing=False,  # Autonomous monitor, not interactive
+    max_node_visits=0,  # Unbounded — runs on every timer tick
+    input_keys=[],
+    output_keys=["health_verdict"],
+    nullable_output_keys=["health_verdict"],
+    success_criteria=(
+        "A clear health verdict is produced each check: either 'healthy' with "
+        "a brief observation, or a complete EscalationTicket is emitted via "
+        "emit_escalation_ticket and health_verdict describes the issue."
+    ),
+    tools=[
+        "get_worker_health_summary",
+        "emit_escalation_ticket",
+    ],
+    system_prompt="""\
+You are the Worker Health Judge. You run every 2 minutes alongside a worker \
+agent to monitor its execution health.
+
+# Your Role
+
+You observe the worker's iteration patterns over time and escalate only when \
+you see genuine degradation — not normal retry cycles. Your conversation history \
+IS your memory. On each check, refer to your previous observations to track trends.
+
+# Check Procedure
+
+On each timer tick (every 2 minutes):
+
+## Step 1: Read health snapshot
+Call get_worker_health_summary() with no arguments to auto-discover the active \
+session. This returns:
+- worker_agent_id: the worker's agent name — use this for ticket identity fields
+- worker_graph_id: the worker's primary graph ID — use this for ticket identity fields
+- session_id: the session being monitored — use this for worker_session_id in tickets
+- total_steps: how many log steps have been recorded
+- recent_verdicts: list of recent ACCEPT/RETRY/CONTINUE verdicts
+- steps_since_last_accept: consecutive non-ACCEPT steps
+- stall_minutes: wall-clock since last step (null if active)
+- evidence_snippet: recent LLM output
+
+## Step 2: Compare to prior check
+Look at your conversation history. What was total_steps last time?
+- If total_steps is UNCHANGED from prior check AND prior check was also unchanged:
+  → STALL confirmed (worker has produced no new iterations in 4+ minutes).
+  → Escalate with severity="high" or "critical" depending on stall duration.
+- If total_steps increased: worker is making progress. Examine verdicts.
+
+## Step 3: Analyze verdict pattern
+- Healthy: Mix of ACCEPT and RETRY, steps_since_last_accept < 5. No action.
+- Warning: steps_since_last_accept is 5-9. Note it, no escalation yet.
+- Degraded: steps_since_last_accept >= 10. Examine evidence_snippet.
+  - If evidence shows the agent is making real progress (complex reasoning,
+    exploring solutions, productive tool use): may be a hard problem. Note it.
+  - If evidence shows a loop (same error, same tool call, no new information):
+    → Escalate with severity="medium" or "high".
+- Critical: steps_since_last_accept >= 20, OR stall_minutes >= 4.
+  → Escalate with severity="critical".
+
+## Step 4: Decide
+
+### If healthy:
+set_output("health_verdict", "healthy: <brief observation>")
+Done.
+
+### If escalating:
+Build an EscalationTicket JSON string with ALL required fields:
+{
+  "worker_agent_id": "<worker_agent_id from get_worker_health_summary>",
+  "worker_session_id": "<session_id from get_worker_health_summary>",
+  "worker_node_id": "<worker_graph_id from get_worker_health_summary>",
+  "worker_graph_id": "<worker_graph_id from get_worker_health_summary>",
+  "severity": "<low|medium|high|critical>",
+  "cause": "<what you observed — concrete, specific>",
+  "judge_reasoning": "<why you decided to escalate, not just dismiss>",
+  "suggested_action": "<what you recommend: restart, human review, etc.>",
+  "recent_verdicts": [<list from get_worker_health_summary>],
+  "total_steps_checked": <int>,
+  "steps_since_last_accept": <int>,
+  "stall_minutes": <float or null>,
+  "evidence_snippet": "<from get_worker_health_summary>"
+}
+
+Call: emit_escalation_ticket(ticket_json=<the JSON string above>)
+Then: set_output("health_verdict", "escalated: <one-line summary>")
+
+# Severity Guide
+
+- low: Mild concern, worth noting. 5-9 consecutive bad verdicts.
+- medium: Clear degradation pattern. 10-15 bad verdicts or brief stall (1-2 min).
+- high: Serious issue. 15+ bad verdicts or stall 2-4 minutes or clear doom loop.
+- critical: Worker is definitively stuck. 20+ bad verdicts or stall > 4 minutes.
+
+# Conservative Bias
+
+You MUST resist the urge to escalate prematurely. Worker agents naturally retry.
+A node may legitimately need 5-8 retries before succeeding. Do not escalate unless:
+1. The pattern is clear and sustained across your observation window, AND
+2. The evidence shows no genuine progress
+
+One missed escalation is less costly than two false alarms. The Queen will filter \
+further. But do not be passive — genuine stalls and doom loops must be caught.
+
+# Rules
+- Never escalate on the FIRST check unless stall_minutes > 4
+- Always call get_worker_health_summary FIRST before deciding anything
+- All ticket fields are REQUIRED — do not submit partial tickets
+- After any emit_escalation_ticket call, always set_output to complete the check
+""",
+)
+
+# ---------------------------------------------------------------------------
+# Entry Point
+# ---------------------------------------------------------------------------
+
+HEALTH_JUDGE_ENTRY_POINT = AsyncEntryPointSpec(
+    id="health_check",
+    name="Worker Health Check",
+    entry_node="judge",
+    trigger_type="timer",
+    trigger_config={
+        "interval_minutes": 2,
+        "run_immediately": True,  # Fire immediately to establish a baseline
+    },
+    isolation_level="isolated",  # Own memory namespace, not polluting worker's
+)
+
+# ---------------------------------------------------------------------------
+# Graph
+# ---------------------------------------------------------------------------
+
+judge_graph = GraphSpec(
+    id="judge-graph",
+    goal_id=judge_goal.id,
+    version="1.0.0",
+    entry_node="judge",
+    entry_points={"health_check": "judge"},
+    terminal_nodes=[],  # Forever-alive: fires on every timer tick
+    pause_nodes=[],
+    nodes=[judge_node],
+    edges=[],
+    conversation_mode="continuous",  # Conversation persists across timer ticks
+    async_entry_points=[HEALTH_JUDGE_ENTRY_POINT],
+    loop_config={
+        "max_iterations": 10,  # One check shouldn't take many turns
+        "max_tool_calls_per_turn": 3,  # get_summary + optionally emit_ticket
+        "max_history_tokens": 16000,  # Compact — judge only needs recent context
+    },
+)

core/framework/runner/cli.py

@@ -208,6 +208,21 @@ def register_commands(subparsers: argparse._SubParsersAction) -> None:
     )
     tui_parser.set_defaults(func=cmd_tui)
 
+    # code command (Hive Coder — framework agent builder)
+    code_parser = subparsers.add_parser(
+        "code",
+        help="Launch Hive Coder to build agents",
+        description="Interactive agent builder. Describe what you want and Hive Coder builds it.",
+    )
+    code_parser.add_argument(
+        "--model",
+        "-m",
+        type=str,
+        default=None,
+        help="LLM model to use (any LiteLLM-compatible name)",
+    )
+    code_parser.set_defaults(func=cmd_code)
+
     # sessions command group (checkpoint/resume management)
     sessions_parser = subparsers.add_parser(
         "sessions",
@@ -331,6 +346,56 @@ def register_commands(subparsers: argparse._SubParsersAction) -> None:
     )
     resume_parser.set_defaults(func=cmd_resume)
 
+    # setup-credentials command
+    setup_creds_parser = subparsers.add_parser(
+        "setup-credentials",
+        help="Interactive credential setup",
+        description="Guide through setting up required credentials for an agent.",
+    )
+    setup_creds_parser.add_argument(
+        "agent_path",
+        type=str,
+        nargs="?",
+        help="Path to agent folder (optional - runs general setup if not specified)",
+    )
+    setup_creds_parser.set_defaults(func=cmd_setup_credentials)
+
+    # serve command (HTTP API server)
+    serve_parser = subparsers.add_parser(
+        "serve",
+        help="Start HTTP API server",
+        description="Start an HTTP server exposing REST + SSE APIs for agent control.",
+    )
+    serve_parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Host to bind (default: 127.0.0.1)",
+    )
+    serve_parser.add_argument(
+        "--port",
+        "-p",
+        type=int,
+        default=8787,
+        help="Port to listen on (default: 8787)",
+    )
+    serve_parser.add_argument(
+        "--agent",
+        "-a",
+        type=str,
+        action="append",
+        default=[],
+        help="Agent path to preload (repeatable)",
+    )
+    serve_parser.add_argument(
+        "--model",
+        "-m",
+        type=str,
+        default=None,
+        help="LLM model for preloaded agents",
+    )
+    serve_parser.set_defaults(func=cmd_serve)
+
 
 def _load_resume_state(
     agent_path: str, session_id: str, checkpoint_id: str | None = None
@@ -388,6 +453,40 @@ def _load_resume_state(
         }
 
 
+def _prompt_before_start(agent_path: str, runner, model: str | None = None):
+    """Prompt user to start agent or update credentials.
+
+    Returns:
+        Updated runner if user proceeds, None if user aborts.
+    """
+    from framework.credentials.setup import CredentialSetupSession
+    from framework.runner import AgentRunner
+
+    while True:
+        print()
+        try:
+            choice = input("Press Enter to start agent, or 'u' to update credentials: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return None
+
+        if choice == "":
+            return runner
+        elif choice.lower() == "u":
+            session = CredentialSetupSession.from_agent_path(agent_path)
+            result = session.run_interactive()
+            if result.success:
+                # Reload runner with updated credentials
+                try:
+                    runner = AgentRunner.load(agent_path, model=model)
+                except Exception as e:
+                    print(f"Error reloading agent: {e}")
+                    return None
+            # Loop back to prompt again
+        elif choice.lower() == "q":
+            return None
+
+
 def cmd_run(args: argparse.Namespace) -> int:
     """Run an exported agent."""
     import logging
@@ -427,6 +526,7 @@ def cmd_run(args: argparse.Namespace) -> int:
             try:
                 # Load runner inside the async loop to ensure strict loop affinity
                 # (only one load — avoids spawning duplicate MCP subprocesses)
+                # AgentRunner handles credential setup interactively when stdin is a TTY.
                 try:
                     runner = AgentRunner.load(
                         args.agent_path,
@@ -439,9 +539,19 @@ def cmd_run(args: argparse.Namespace) -> int:
                     print(f"Error loading agent: {e}")
                     return
 
+                # Prompt before starting (allows credential updates)
+                if sys.stdin.isatty():
+                    runner = _prompt_before_start(args.agent_path, runner, args.model)
+                    if runner is None:
+                        return
+
                 # Force setup inside the loop
                 if runner._agent_runtime is None:
-                    runner._setup()
+                    try:
+                        runner._setup()
+                    except CredentialError as e:
+                        print(f"\n{e}", file=sys.stderr)
+                        return
 
                 # Start runtime before TUI so it's ready for user input
                 if runner._agent_runtime and not runner._agent_runtime.is_running:
@@ -470,6 +580,7 @@ def cmd_run(args: argparse.Namespace) -> int:
         return 0
     else:
         # Standard execution — load runner here (not shared with TUI path)
+        # AgentRunner handles credential setup interactively when stdin is a TTY.
         try:
             runner = AgentRunner.load(
                 args.agent_path,
@@ -482,6 +593,12 @@ def cmd_run(args: argparse.Namespace) -> int:
             print(f"Error: {e}", file=sys.stderr)
             return 1
 
+        # Prompt before starting (allows credential updates)
+        if sys.stdin.isatty() and not args.quiet:
+            runner = _prompt_before_start(args.agent_path, runner, args.model)
+            if runner is None:
+                return 1
+
         # Load session/checkpoint state for resume (headless mode)
         session_state = None
         resume_session = getattr(args, "resume_session", None)
@@ -966,7 +1083,7 @@ Output ONLY valid JSON, no explanation:"""
 
     try:
         message = client.messages.create(
-            model="claude-3-5-haiku-20241022",  # Fast and cheap
+            model="claude-haiku-4-5-20251001",  # Fast and cheap
             max_tokens=500,
             messages=[{"role": "user", "content": prompt}],
         )
@@ -1226,60 +1343,26 @@ def cmd_shell(args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_tui(args: argparse.Namespace) -> int:
-    """Browse agents and launch the interactive TUI dashboard."""
-    import logging
+def _get_framework_agents_dir() -> Path:
+    """Resolve the framework agents directory relative to this file."""
+    return Path(__file__).resolve().parent.parent / "agents"
 
+
+def _launch_agent_tui(
+    agent_path: str | Path,
+    model: str | None = None,
+) -> int:
+    """Load an agent and launch the TUI. Shared by cmd_tui and cmd_code."""
     from framework.credentials.models import CredentialError
     from framework.runner import AgentRunner
     from framework.tui.app import AdenTUI
 
-    logging.basicConfig(level=logging.WARNING, format="%(message)s")
-
-    exports_dir = Path("exports")
-    examples_dir = Path("examples/templates")
-
-    has_exports = _has_agents(exports_dir)
-    has_examples = _has_agents(examples_dir)
-
-    if not has_exports and not has_examples:
-        print("No agents found in exports/ or examples/templates/", file=sys.stderr)
-        return 1
-
-    # Determine which directory to browse
-    if has_exports and has_examples:
-        print("\nAgent sources:\n")
-        print("  1. Your Agents (exports/)")
-        print("  2. Sample Agents (examples/templates/)")
-        print()
-        try:
-            choice = input("Select source (number): ").strip()
-            if choice == "1":
-                agents_dir = exports_dir
-            elif choice == "2":
-                agents_dir = examples_dir
-            else:
-                print("Invalid selection")
-                return 1
-        except (EOFError, KeyboardInterrupt):
-            print()
-            return 1
-    elif has_exports:
-        agents_dir = exports_dir
-    else:
-        agents_dir = examples_dir
-
-    # Let user pick an agent
-    agent_path = _select_agent(agents_dir)
-    if not agent_path:
-        return 1
-
-    # Launch TUI (same pattern as cmd_run --tui)
     async def run_with_tui():
+        # AgentRunner handles credential setup interactively when stdin is a TTY.
         try:
             runner = AgentRunner.load(
                 agent_path,
-                model=args.model,
+                model=model,
             )
         except CredentialError as e:
             print(f"\n{e}", file=sys.stderr)
@@ -1289,7 +1372,11 @@ def cmd_tui(args: argparse.Namespace) -> int:
             return
 
         if runner._agent_runtime is None:
-            runner._setup()
+            try:
+                runner._setup()
+            except CredentialError as e:
+                print(f"\n{e}", file=sys.stderr)
+                return
 
         if runner._agent_runtime and not runner._agent_runtime.is_running:
             await runner._agent_runtime.start()
@@ -1310,6 +1397,105 @@ def cmd_tui(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_tui(args: argparse.Namespace) -> int:
+    """Launch the interactive TUI dashboard with in-app agent picker."""
+    import logging
+
+    logging.basicConfig(level=logging.WARNING, format="%(message)s")
+
+    from framework.tui.app import AdenTUI
+
+    async def run_tui():
+        app = AdenTUI(
+            model=args.model,
+        )
+        await app.run_async()
+
+    asyncio.run(run_tui())
+    print("TUI session ended.")
+    return 0
+
+
+def cmd_code(args: argparse.Namespace) -> int:
+    """Launch Hive Coder with multi-graph support.
+
+    Unlike ``_launch_agent_tui``, this sets up graph lifecycle tools and
+    assigns ``graph_id="hive_coder"`` so the coder can load, supervise,
+    and restart secondary agent graphs within the same session.
+    """
+    import logging
+
+    logging.basicConfig(level=logging.WARNING, format="%(message)s")
+
+    framework_agents_dir = _get_framework_agents_dir()
+    hive_coder_path = framework_agents_dir / "hive_coder"
+
+    if not (hive_coder_path / "agent.py").exists():
+        print("Error: Hive Coder agent not found.", file=sys.stderr)
+        return 1
+
+    # Ensure framework agents dir is on sys.path for import
+    fa_str = str(framework_agents_dir)
+    if fa_str not in sys.path:
+        sys.path.insert(0, fa_str)
+
+    from framework.credentials.models import CredentialError
+    from framework.runner import AgentRunner
+    from framework.tools.session_graph_tools import register_graph_tools
+    from framework.tui.app import AdenTUI
+
+    async def run_with_tui():
+        try:
+            runner = AgentRunner.load(hive_coder_path, model=args.model)
+        except CredentialError as e:
+            print(f"\n{e}", file=sys.stderr)
+            return
+        except Exception as e:
+            print(f"Error loading agent: {e}")
+            return
+
+        if runner._agent_runtime is None:
+            try:
+                runner._setup()
+            except CredentialError as e:
+                print(f"\n{e}", file=sys.stderr)
+                return
+
+        runtime = runner._agent_runtime
+
+        # -- Multi-graph setup --
+        # Tag the primary graph so events carry graph_id="hive_coder"
+        runtime._graph_id = "hive_coder"
+        runtime._active_graph_id = "hive_coder"
+
+        # Register graph lifecycle tools (load_agent, unload_agent, etc.)
+        register_graph_tools(runner._tool_registry, runtime)
+
+        # Refresh tool schemas AND executor so streams see the new tools.
+        # The executor closure references the registry dict by ref, but
+        # refreshing both is robust against any copy-on-read behavior.
+        runtime._tools = list(runner._tool_registry.get_tools().values())
+        runtime._tool_executor = runner._tool_registry.get_executor()
+
+        if not runtime.is_running:
+            await runtime.start()
+
+        app = AdenTUI(runtime)
+        try:
+            await app.run_async()
+        except Exception as e:
+            import traceback
+
+            traceback.print_exc()
+            print(f"TUI error: {e}")
+
+        await runner.cleanup_async()
+
+    asyncio.run(run_with_tui())
+    print("TUI session ended.")
+    return 0
+
+
 def _extract_python_agent_metadata(agent_path: Path) -> tuple[str, str]:
     """Extract name and description from a Python-based agent's config.py.
 
@@ -1719,3 +1905,84 @@ def cmd_resume(args: argparse.Namespace) -> int:
     if args.tui:
         print("Mode: TUI")
     return 1
+
+
+def cmd_setup_credentials(args: argparse.Namespace) -> int:
+    """Interactive credential setup for an agent."""
+    from framework.credentials.setup import CredentialSetupSession
+
+    agent_path = getattr(args, "agent_path", None)
+
+    if agent_path:
+        # Setup credentials for a specific agent
+        session = CredentialSetupSession.from_agent_path(agent_path)
+    else:
+        # No agent specified - show usage
+        print("Usage: hive setup-credentials <agent_path>")
+        print()
+        print("Examples:")
+        print("  hive setup-credentials exports/my-agent")
+        print("  hive setup-credentials examples/templates/deep_research_agent")
+        return 1
+
+    result = session.run_interactive()
+    return 0 if result.success else 1
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    """Start the HTTP API server."""
+    import logging
+
+    from aiohttp import web
+
+    from framework.server.app import create_app
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    model = getattr(args, "model", None)
+    app = create_app(model=model)
+
+    async def run_server():
+        manager = app["manager"]
+
+        # Preload agents specified via --agent
+        for agent_path in args.agent:
+            try:
+                session = await manager.create_session_with_worker(agent_path, model=model)
+                info = session.worker_info
+                name = info.name if info else session.worker_id
+                print(f"Loaded agent: {session.worker_id} ({name})")
+            except Exception as e:
+                print(f"Error loading {agent_path}: {e}")
+
+        # Start server using AppRunner/TCPSite (same pattern as webhook_server.py)
+        runner = web.AppRunner(app)
+        await runner.setup()
+        site = web.TCPSite(runner, args.host, args.port)
+        await site.start()
+
+        print()
+        print(f"Hive API server running on http://{args.host}:{args.port}")
+        print(f"Health: http://{args.host}:{args.port}/api/health")
+        print(f"Agents loaded: {sum(1 for s in manager.list_sessions() if s.worker_runtime)}")
+        print()
+        print("Press Ctrl+C to stop")
+
+        # Run forever until interrupted
+        try:
+            await asyncio.Event().wait()
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await manager.shutdown_all()
+            await runner.cleanup()
+
+    try:
+        asyncio.run(run_server())
+    except KeyboardInterrupt:
+        print("\nServer stopped.")
+
+    return 0

core/framework/runner/orchestrator.py

@@ -71,9 +71,15 @@ class AgentOrchestrator:
 
         # Auto-create LLM - LiteLLM auto-detects provider and API key from model name
         if self._llm is None:
+            from framework.config import get_api_base, get_api_key, get_llm_extra_kwargs
             from framework.llm.litellm import LiteLLMProvider
 
-            self._llm = LiteLLMProvider(model=self._model)
+            self._llm = LiteLLMProvider(
+                model=self._model,
+                api_key=get_api_key(),
+                api_base=get_api_base(),
+                **get_llm_extra_kwargs(),
+            )
 
     def register(
         self,

core/framework/runner/runner.py

@@ -36,27 +36,130 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 CLAUDE_CREDENTIALS_FILE = Path.home() / ".claude" / ".credentials.json"
+CLAUDE_OAUTH_TOKEN_URL = "https://console.anthropic.com/v1/oauth/token"
+CLAUDE_OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+
+# Buffer in seconds before token expiry to trigger a proactive refresh
+_TOKEN_REFRESH_BUFFER_SECS = 300  # 5 minutes
+
+
+def _refresh_claude_code_token(refresh_token: str) -> dict | None:
+    """Refresh the Claude Code OAuth token using the refresh token.
+
+    POSTs to the Anthropic OAuth token endpoint with form-urlencoded data
+    (per OAuth 2.0 RFC 6749 Section 4.1.3).
+
+    Returns:
+        Dict with new token data (access_token, refresh_token, expires_in)
+        on success, None on failure.
+    """
+    import urllib.error
+    import urllib.parse
+    import urllib.request
+
+    data = urllib.parse.urlencode(
+        {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": CLAUDE_OAUTH_CLIENT_ID,
+        }
+    ).encode("utf-8")
+
+    req = urllib.request.Request(
+        CLAUDE_OAUTH_TOKEN_URL,
+        data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            return json.loads(resp.read())
+    except (urllib.error.URLError, json.JSONDecodeError, TimeoutError, OSError) as exc:
+        logger.debug("Claude Code token refresh failed: %s", exc)
+        return None
+
+
+def _save_refreshed_credentials(token_data: dict) -> None:
+    """Write refreshed token data back to ~/.claude/.credentials.json."""
+    import time
+
+    if not CLAUDE_CREDENTIALS_FILE.exists():
+        return
+
+    try:
+        with open(CLAUDE_CREDENTIALS_FILE) as f:
+            creds = json.load(f)
+
+        oauth = creds.get("claudeAiOauth", {})
+        oauth["accessToken"] = token_data["access_token"]
+        if "refresh_token" in token_data:
+            oauth["refreshToken"] = token_data["refresh_token"]
+        if "expires_in" in token_data:
+            oauth["expiresAt"] = int((time.time() + token_data["expires_in"]) * 1000)
+        creds["claudeAiOauth"] = oauth
+
+        with open(CLAUDE_CREDENTIALS_FILE, "w") as f:
+            json.dump(creds, f, indent=2)
+        logger.debug("Claude Code credentials refreshed successfully")
+    except (json.JSONDecodeError, OSError, KeyError) as exc:
+        logger.debug("Failed to save refreshed credentials: %s", exc)
 
 
 def get_claude_code_token() -> str | None:
-    """
-    Get the OAuth token from Claude Code subscription.
+    """Get the OAuth token from Claude Code subscription with auto-refresh.
 
     Reads from ~/.claude/.credentials.json which is created by the
     Claude Code CLI when users authenticate with their subscription.
 
+    If the token is expired or close to expiry, attempts an automatic
+    refresh using the stored refresh token.
+
     Returns:
         The access token if available, None otherwise.
     """
+    import time
+
     if not CLAUDE_CREDENTIALS_FILE.exists():
         return None
+
     try:
         with open(CLAUDE_CREDENTIALS_FILE) as f:
             creds = json.load(f)
-        return creds.get("claudeAiOauth", {}).get("accessToken")
     except (json.JSONDecodeError, OSError):
         return None
 
+    oauth = creds.get("claudeAiOauth", {})
+    access_token = oauth.get("accessToken")
+    if not access_token:
+        return None
+
+    # Check token expiry (expiresAt is in milliseconds)
+    expires_at_ms = oauth.get("expiresAt", 0)
+    now_ms = int(time.time() * 1000)
+    buffer_ms = _TOKEN_REFRESH_BUFFER_SECS * 1000
+
+    if expires_at_ms > now_ms + buffer_ms:
+        # Token is still valid
+        return access_token
+
+    # Token is expired or near expiry — attempt refresh
+    refresh_token = oauth.get("refreshToken")
+    if not refresh_token:
+        logger.warning("Claude Code token expired and no refresh token available")
+        return access_token  # Return expired token; it may still work briefly
+
+    logger.info("Claude Code token expired or near expiry, refreshing...")
+    token_data = _refresh_claude_code_token(refresh_token)
+
+    if token_data and "access_token" in token_data:
+        _save_refreshed_credentials(token_data)
+        return token_data["access_token"]
+
+    # Refresh failed — return the existing token and warn
+    logger.warning("Claude Code token refresh failed. Run 'claude' to re-authenticate.")
+    return access_token
+
 
 @dataclass
 class AgentInfo:
@@ -247,6 +350,11 @@ class AgentRunner:
         model: str | None = None,
         intro_message: str = "",
         runtime_config: "AgentRuntimeConfig | None" = None,
+        interactive: bool = True,
+        skip_credential_validation: bool = False,
+        requires_account_selection: bool = False,
+        configure_for_account: Callable | None = None,
+        list_accounts: Callable | None = None,
     ):
         """
         Initialize the runner (use AgentRunner.load() instead).
@@ -260,6 +368,12 @@ class AgentRunner:
             model: Model to use (reads from agent config or ~/.hive/configuration.json if None)
             intro_message: Optional greeting shown to user on TUI load
             runtime_config: Optional AgentRuntimeConfig (webhook settings, etc.)
+            interactive: If True (default), offer interactive credential setup on failure.
+                Set to False when called from the TUI (which handles setup via its own screen).
+            skip_credential_validation: If True, skip credential checks at load time.
+            requires_account_selection: If True, TUI shows account picker before starting.
+            configure_for_account: Callback(runner, account_dict) to scope tools after selection.
+            list_accounts: Callback() -> list[dict] to fetch available accounts.
         """
         self.agent_path = agent_path
         self.graph = graph
@@ -268,6 +382,11 @@ class AgentRunner:
         self.model = model or self._resolve_default_model()
         self.intro_message = intro_message
         self.runtime_config = runtime_config
+        self._interactive = interactive
+        self.skip_credential_validation = skip_credential_validation
+        self.requires_account_selection = requires_account_selection
+        self._configure_for_account = configure_for_account
+        self._list_accounts = list_accounts
 
         # Set up storage
         if storage_path:
@@ -311,45 +430,70 @@ class AgentRunner:
     def _validate_credentials(self) -> None:
         """Check that required credentials are available before spawning MCP servers.
 
-        Raises CredentialError with actionable guidance if any are missing.
+        If ``interactive`` is True and stdin is a TTY, automatically launches
+        the interactive credential setup flow so the user can fix the issue
+        in-place.  Re-validates after setup succeeds.
+
+        When ``interactive`` is False (e.g. TUI callers), the CredentialError
+        propagates immediately so the caller can handle it with its own UI.
         """
-        validate_agent_credentials(self.graph.nodes)
+        if self.skip_credential_validation:
+            return
+
+        if not self._interactive:
+            # Let the CredentialError propagate — caller handles UI.
+            validate_agent_credentials(self.graph.nodes)
+            return
+
+        import sys
+
+        from framework.credentials.models import CredentialError
+
+        try:
+            validate_agent_credentials(self.graph.nodes)
+            return  # All good
+        except CredentialError as e:
+            if not sys.stdin.isatty():
+                raise
+
+            # Interactive: show the error then enter credential setup
+            print(f"\n{e}", file=sys.stderr)
+
+            from framework.credentials.validation import build_setup_session_from_error
+
+            session = build_setup_session_from_error(e, nodes=self.graph.nodes)
+            if not session.missing:
+                raise
+
+            result = session.run_interactive()
+            if not result.success:
+                raise CredentialError(
+                    "Credential setup incomplete. "
+                    "Run again after configuring the required credentials."
+                ) from None
+
+            # Re-validate after setup
+            validate_agent_credentials(self.graph.nodes)
 
     @staticmethod
     def _import_agent_module(agent_path: Path):
         """Import an agent package from its directory path.
 
-        Tries package import first (works when exports/ is on sys.path,
-        which cli.py:_configure_paths() ensures). Falls back to direct
-        file import of agent.py via importlib.util.
+        Ensures the agent's parent directory is on sys.path so the package
+        can be imported normally (supports relative imports within the agent).
         """
         import importlib
+        import sys
 
         package_name = agent_path.name
+        parent_dir = str(agent_path.resolve().parent)
 
-        # Try importing as a package (works when exports/ is on sys.path)
-        try:
-            return importlib.import_module(package_name)
-        except ImportError:
-            pass
+        # Ensure the parent directory is on sys.path so the agent package
+        # is importable (e.g., exports/ or examples/templates/)
+        if parent_dir not in sys.path:
+            sys.path.insert(0, parent_dir)
 
-        # Fallback: import agent.py directly via file path
-        import importlib.util
-
-        agent_py = agent_path / "agent.py"
-        if not agent_py.exists():
-            raise FileNotFoundError(
-                f"No importable agent found at {agent_path}. "
-                f"Expected a Python package with agent.py."
-            )
-        spec = importlib.util.spec_from_file_location(
-            f"{package_name}.agent",
-            agent_py,
-            submodule_search_locations=[str(agent_path)],
-        )
-        module = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(module)
-        return module
+        return importlib.import_module(package_name)
 
     @classmethod
     def load(
@@ -358,6 +502,7 @@ class AgentRunner:
         mock_mode: bool = False,
         storage_path: Path | None = None,
         model: str | None = None,
+        interactive: bool = True,
     ) -> "AgentRunner":
         """
         Load an agent from an export folder.
@@ -371,6 +516,8 @@ class AgentRunner:
             mock_mode: If True, use mock LLM responses
             storage_path: Path for runtime storage (defaults to ~/.hive/agents/{name})
             model: LLM model to use (reads from agent's default_config if None)
+            interactive: If True (default), offer interactive credential setup.
+                Set to False from TUI callers that handle setup via their own UI.
 
         Returns:
             AgentRunner instance ready to run
@@ -438,6 +585,12 @@ class AgentRunner:
             # Read runtime config (webhook settings, etc.) if defined
             agent_runtime_config = getattr(agent_module, "runtime_config", None)
 
+            # Read pre-run hooks (e.g., credential_tester needs account selection)
+            skip_cred = getattr(agent_module, "skip_credential_validation", False)
+            needs_acct = getattr(agent_module, "requires_account_selection", False)
+            configure_fn = getattr(agent_module, "configure_for_account", None)
+            list_accts_fn = getattr(agent_module, "list_connected_accounts", None)
+
             return cls(
                 agent_path=agent_path,
                 graph=graph,
@@ -447,6 +600,11 @@ class AgentRunner:
                 model=model,
                 intro_message=intro_message,
                 runtime_config=agent_runtime_config,
+                interactive=interactive,
+                skip_credential_validation=skip_cred,
+                requires_account_selection=needs_acct,
+                configure_for_account=configure_fn,
+                list_accounts=list_accts_fn,
             )
 
         # Fallback: load from agent.json (legacy JSON-based agents)
@@ -464,6 +622,7 @@ class AgentRunner:
             mock_mode=mock_mode,
             storage_path=storage_path,
             model=model,
+            interactive=interactive,
         )
 
     def register_tool(
@@ -554,7 +713,7 @@ class AgentRunner:
         """
         self._approval_callback = callback
 
-    def _setup(self) -> None:
+    def _setup(self, event_bus=None) -> None:
         """Set up runtime, LLM, and executor."""
         # Configure structured logging (auto-detects JSON vs human-readable)
         from framework.observability import configure_logging
@@ -587,6 +746,7 @@ class AgentRunner:
             config = get_hive_config()
             llm_config = config.get("llm", {})
             use_claude_code = llm_config.get("use_claude_code_subscription", False)
+            api_base = llm_config.get("api_base")
 
             api_key = None
             if use_claude_code:
@@ -596,35 +756,99 @@ class AgentRunner:
                     print("Warning: Claude Code subscription configured but no token found.")
                     print("Run 'claude' to authenticate, then try again.")
 
-            if api_key:
-                # Use Claude Code subscription token
-                self._llm = LiteLLMProvider(model=self.model, api_key=api_key)
-            else:
-                # Fall back to environment variable
-                # First check api_key_env_var from config (set by quickstart)
-                api_key_env = llm_config.get("api_key_env_var") or self._get_api_key_env_var(
-                    self.model
+            if api_key and use_claude_code:
+                # Use litellm's built-in Anthropic OAuth support.
+                # The lowercase "authorization" key triggers OAuth detection which
+                # adds the required anthropic-beta and browser-access headers.
+                self._llm = LiteLLMProvider(
+                    model=self.model,
+                    api_key=api_key,
+                    api_base=api_base,
+                    extra_headers={"authorization": f"Bearer {api_key}"},
                 )
-                if api_key_env and os.environ.get(api_key_env):
-                    self._llm = LiteLLMProvider(model=self.model)
+            else:
+                # Local models (e.g. Ollama) don't need an API key
+                if self._is_local_model(self.model):
+                    self._llm = LiteLLMProvider(
+                        model=self.model,
+                        api_base=api_base,
+                    )
                 else:
-                    # Fall back to credential store
-                    api_key = self._get_api_key_from_credential_store()
-                    if api_key:
-                        self._llm = LiteLLMProvider(model=self.model, api_key=api_key)
-                        # Set env var so downstream code (e.g. cleanup LLM in
-                        # node._extract_json) can also find it
-                        if api_key_env:
-                            os.environ[api_key_env] = api_key
-                    elif api_key_env:
-                        print(f"Warning: {api_key_env} not set. LLM calls will fail.")
-                        print(f"Set it with: export {api_key_env}=your-api-key")
+                    # Fall back to environment variable
+                    # First check api_key_env_var from config (set by quickstart)
+                    api_key_env = llm_config.get("api_key_env_var") or self._get_api_key_env_var(
+                        self.model
+                    )
+                    if api_key_env and os.environ.get(api_key_env):
+                        self._llm = LiteLLMProvider(
+                            model=self.model,
+                            api_key=os.environ[api_key_env],
+                            api_base=api_base,
+                        )
+                    else:
+                        # Fall back to credential store
+                        api_key = self._get_api_key_from_credential_store()
+                        if api_key:
+                            self._llm = LiteLLMProvider(
+                                model=self.model, api_key=api_key, api_base=api_base
+                            )
+                            # Set env var so downstream code (e.g. cleanup LLM in
+                            # node._extract_json) can also find it
+                            if api_key_env:
+                                os.environ[api_key_env] = api_key
+                        elif api_key_env:
+                            print(f"Warning: {api_key_env} not set. LLM calls will fail.")
+                            print(f"Set it with: export {api_key_env}=your-api-key")
+
+            # Fail fast if the agent needs an LLM but none was configured
+            if self._llm is None:
+                has_llm_nodes = any(node.node_type == "event_loop" for node in self.graph.nodes)
+                if has_llm_nodes:
+                    from framework.credentials.models import CredentialError
+
+                    if self._is_local_model(self.model):
+                        raise CredentialError(
+                            f"Failed to initialize LLM for local model '{self.model}'. "
+                            f"Ensure your local LLM server is running "
+                            f"(e.g. 'ollama serve' for Ollama)."
+                        )
+                    api_key_env = self._get_api_key_env_var(self.model)
+                    hint = (
+                        f"Set it with: export {api_key_env}=your-api-key"
+                        if api_key_env
+                        else "Configure an API key for your LLM provider."
+                    )
+                    raise CredentialError(f"LLM API key not found for model '{self.model}'. {hint}")
 
         # Get tools for runtime
         tools = list(self._tool_registry.get_tools().values())
         tool_executor = self._tool_registry.get_executor()
 
-        self._setup_agent_runtime(tools, tool_executor)
+        # Collect connected account info for system prompt injection
+        accounts_prompt = ""
+        accounts_data: list[dict] | None = None
+        tool_provider_map: dict[str, str] | None = None
+        try:
+            from aden_tools.credentials.store_adapter import CredentialStoreAdapter
+
+            adapter = CredentialStoreAdapter.default()
+            accounts_data = adapter.get_all_account_info()
+            tool_provider_map = adapter.get_tool_provider_map()
+            if accounts_data:
+                from framework.graph.prompt_composer import build_accounts_prompt
+
+                accounts_prompt = build_accounts_prompt(accounts_data, tool_provider_map)
+        except Exception:
+            pass  # Best-effort — agent works without account info
+
+        self._setup_agent_runtime(
+            tools,
+            tool_executor,
+            accounts_prompt=accounts_prompt,
+            accounts_data=accounts_data,
+            tool_provider_map=tool_provider_map,
+            event_bus=event_bus,
+        )
 
     def _get_api_key_env_var(self, model: str) -> str | None:
         """Get the environment variable name for the API key based on model name."""
@@ -644,8 +868,8 @@ class AgentRunner:
             return "MISTRAL_API_KEY"
         elif model_lower.startswith("groq/"):
             return "GROQ_API_KEY"
-        elif model_lower.startswith("ollama/"):
-            return None  # Ollama doesn't need an API key (local)
+        elif self._is_local_model(model_lower):
+            return None  # Local models don't need an API key
         elif model_lower.startswith("azure/"):
             return "AZURE_API_KEY"
         elif model_lower.startswith("cohere/"):
@@ -685,7 +909,31 @@ class AgentRunner:
         except Exception:
             return None
 
-    def _setup_agent_runtime(self, tools: list, tool_executor: Callable | None) -> None:
+    @staticmethod
+    def _is_local_model(model: str) -> bool:
+        """Check if a model is a local model that doesn't require an API key.
+
+        Local providers like Ollama run on the user's machine and do not
+        need any authentication credentials.
+        """
+        LOCAL_PREFIXES = (
+            "ollama/",
+            "ollama_chat/",
+            "vllm/",
+            "lm_studio/",
+            "llamacpp/",
+        )
+        return model.lower().startswith(LOCAL_PREFIXES)
+
+    def _setup_agent_runtime(
+        self,
+        tools: list,
+        tool_executor: Callable | None,
+        accounts_prompt: str = "",
+        accounts_data: list[dict] | None = None,
+        tool_provider_map: dict[str, str] | None = None,
+        event_bus=None,
+    ) -> None:
         """Set up multi-entry-point execution using AgentRuntime."""
         # Convert AsyncEntryPointSpec to EntryPointSpec for AgentRuntime
         entry_points = []
@@ -731,6 +979,19 @@ class AgentRunner:
             async_checkpoint=True,  # Non-blocking
         )
 
+        # Handle runtime_config - ensure it's AgentRuntimeConfig, not RuntimeConfig
+        # RuntimeConfig is for LLM settings; AgentRuntimeConfig is for AgentRuntime settings
+        runtime_config = None
+        if self.runtime_config is not None:
+            from framework.config import RuntimeConfig
+
+            # If it's a RuntimeConfig (LLM config), don't pass it
+            if isinstance(self.runtime_config, RuntimeConfig):
+                runtime_config = None
+            else:
+                # It's already an AgentRuntimeConfig or compatible type
+                runtime_config = self.runtime_config
+
         self._agent_runtime = create_agent_runtime(
             graph=self.graph,
             goal=self.goal,
@@ -741,7 +1002,12 @@ class AgentRunner:
             tool_executor=tool_executor,
             runtime_log_store=log_store,
             checkpoint_config=checkpoint_config,
-            config=self.runtime_config,
+            config=runtime_config,
+            graph_id=self.graph.id or self.agent_path.name,
+            accounts_prompt=accounts_prompt,
+            accounts_data=accounts_data,
+            tool_provider_map=tool_provider_map,
+            event_bus=event_bus,
         )
 
         # Pass intro_message through for TUI display
@@ -1064,88 +1330,36 @@ class AgentRunner:
             warnings.append(f"Missing tool implementations: {', '.join(missing_tools)}")
 
         # Check credentials for required tools and node types
-        # Uses CredentialStore (encrypted files + env var fallback)
+        # Uses CredentialStoreAdapter.default() which includes Aden sync support
         missing_credentials = []
         try:
-            from aden_tools.credentials import CREDENTIAL_SPECS
+            from aden_tools.credentials.store_adapter import CredentialStoreAdapter
 
-            from framework.credentials import CredentialStore
-            from framework.credentials.storage import (
-                CompositeStorage,
-                EncryptedFileStorage,
-                EnvVarStorage,
-            )
-
-            # Build env mapping for credential lookup
-            env_mapping = {
-                (spec.credential_id or name): spec.env_var
-                for name, spec in CREDENTIAL_SPECS.items()
-            }
-
-            # Only use EncryptedFileStorage if the encryption key is configured;
-            # otherwise just check env vars (avoids generating a throwaway key)
-            storages: list = [EnvVarStorage(env_mapping=env_mapping)]
-            if os.environ.get("HIVE_CREDENTIAL_KEY"):
-                storages.insert(0, EncryptedFileStorage())
-
-            if len(storages) == 1:
-                storage = storages[0]
-            else:
-                storage = CompositeStorage(
-                    primary=storages[0],
-                    fallbacks=storages[1:],
-                )
-            store = CredentialStore(storage=storage)
-
-            # Build reverse mappings
-            tool_to_cred: dict[str, str] = {}
-            node_type_to_cred: dict[str, str] = {}
-            for cred_name, spec in CREDENTIAL_SPECS.items():
-                for tool_name in spec.tools:
-                    tool_to_cred[tool_name] = cred_name
-                for nt in spec.node_types:
-                    node_type_to_cred[nt] = cred_name
+            adapter = CredentialStoreAdapter.default()
 
             # Check tool credentials
-            checked: set[str] = set()
-            for tool_name in info.required_tools:
-                cred_name = tool_to_cred.get(tool_name)
-                if cred_name is None or cred_name in checked:
-                    continue
-                checked.add(cred_name)
-                spec = CREDENTIAL_SPECS[cred_name]
-                cred_id = spec.credential_id or cred_name
-                if spec.required and not store.is_available(cred_id):
-                    missing_credentials.append(spec.env_var)
-                    affected_tools = [t for t in info.required_tools if t in spec.tools]
-                    tools_str = ", ".join(affected_tools)
-                    warning_msg = f"Missing {spec.env_var} for {tools_str}"
-                    if spec.help_url:
-                        warning_msg += f"\n  Get it at: {spec.help_url}"
-                    warnings.append(warning_msg)
+            for _cred_name, spec in adapter.get_missing_for_tools(list(info.required_tools)):
+                missing_credentials.append(spec.env_var)
+                affected_tools = [t for t in info.required_tools if t in spec.tools]
+                tools_str = ", ".join(affected_tools)
+                warning_msg = f"Missing {spec.env_var} for {tools_str}"
+                if spec.help_url:
+                    warning_msg += f"\n  Get it at: {spec.help_url}"
+                warnings.append(warning_msg)
 
             # Check node type credentials (e.g., ANTHROPIC_API_KEY for LLM nodes)
             node_types = list({node.node_type for node in self.graph.nodes})
-            for nt in 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]
-                cred_id = spec.credential_id or cred_name
-                if spec.required and not store.is_available(cred_id):
-                    missing_credentials.append(spec.env_var)
-                    affected_types = [t for t in node_types if t in spec.node_types]
-                    types_str = ", ".join(affected_types)
-                    warning_msg = f"Missing {spec.env_var} for {types_str} nodes"
-                    if spec.help_url:
-                        warning_msg += f"\n  Get it at: {spec.help_url}"
-                    warnings.append(warning_msg)
+            for _cred_name, spec in adapter.get_missing_for_node_types(node_types):
+                missing_credentials.append(spec.env_var)
+                affected_types = [t for t in node_types if t in spec.node_types]
+                types_str = ", ".join(affected_types)
+                warning_msg = f"Missing {spec.env_var} for {types_str} nodes"
+                if spec.help_url:
+                    warning_msg += f"\n  Get it at: {spec.help_url}"
+                warnings.append(warning_msg)
         except ImportError:
             # aden_tools not installed - fall back to direct check
-            has_llm_nodes = any(
-                node.node_type in ("llm_generate", "llm_tool_use") for node in self.graph.nodes
-            )
+            has_llm_nodes = any(node.node_type == "event_loop" for node in self.graph.nodes)
             if has_llm_nodes:
                 api_key_env = self._get_api_key_env_var(self.model)
                 if api_key_env and not os.environ.get(api_key_env):
@@ -1361,6 +1575,61 @@ Respond with JSON only:
             type=MessageType.RESPONSE,
         )
 
+    @classmethod
+    async def setup_as_secondary(
+        cls,
+        agent_path: str | Path,
+        runtime: AgentRuntime,
+        graph_id: str | None = None,
+    ) -> str:
+        """Load an agent and register it as a secondary graph on *runtime*.
+
+        Uses :meth:`AgentRunner.load` to parse the agent, then calls
+        :meth:`AgentRuntime.add_graph` with the extracted graph, goal,
+        and entry points.
+
+        Args:
+            agent_path: Path to the agent directory
+            runtime: The running AgentRuntime to attach to
+            graph_id: Optional graph identifier (defaults to directory name)
+
+        Returns:
+            The graph_id used for registration
+        """
+        agent_path = Path(agent_path)
+        runner = cls.load(agent_path)
+        gid = graph_id or agent_path.name
+
+        # Build entry points
+        entry_points: dict[str, EntryPointSpec] = {}
+        if runner.graph.entry_node:
+            entry_points["default"] = EntryPointSpec(
+                id="default",
+                name="Default",
+                entry_node=runner.graph.entry_node,
+                trigger_type="manual",
+                isolation_level="shared",
+            )
+        for aep in runner.graph.async_entry_points:
+            entry_points[aep.id] = EntryPointSpec(
+                id=aep.id,
+                name=aep.name,
+                entry_node=aep.entry_node,
+                trigger_type=aep.trigger_type,
+                trigger_config=aep.trigger_config,
+                isolation_level=aep.isolation_level,
+                priority=aep.priority,
+                max_concurrent=aep.max_concurrent,
+            )
+
+        await runtime.add_graph(
+            graph_id=gid,
+            graph=runner.graph,
+            goal=runner.goal,
+            entry_points=entry_points,
+        )
+        return gid
+
     def cleanup(self) -> None:
         """Clean up resources (synchronous)."""
         # Clean up MCP client connections

core/framework/runner/tool_registry.py

@@ -1,5 +1,6 @@
 """Tool discovery and registration for agent runner."""
 
+import asyncio
 import contextvars
 import importlib.util
 import inspect
@@ -50,6 +51,7 @@ class ToolRegistry:
         self._tools: dict[str, RegisteredTool] = {}
         self._mcp_clients: list[Any] = []  # List of MCPClient instances
         self._session_context: dict[str, Any] = {}  # Auto-injected context for tools
+        self._provider_index: dict[str, set[str]] = {}  # provider -> tool names
 
     def register(
         self,
@@ -224,8 +226,19 @@ class ToolRegistry:
         Get unified tool executor function.
 
         Returns a function that dispatches to the appropriate tool executor.
+        Handles both sync and async tool implementations — async results are
+        wrapped so that ``EventLoopNode._execute_tool`` can await them.
         """
 
+        def _wrap_result(tool_use_id: str, result: Any) -> ToolResult:
+            if isinstance(result, ToolResult):
+                return result
+            return ToolResult(
+                tool_use_id=tool_use_id,
+                content=json.dumps(result) if not isinstance(result, str) else result,
+                is_error=False,
+            )
+
         def executor(tool_use: ToolUse) -> ToolResult:
             if tool_use.name not in self._tools:
                 return ToolResult(
@@ -237,13 +250,24 @@ class ToolRegistry:
             registered = self._tools[tool_use.name]
             try:
                 result = registered.executor(tool_use.input)
-                if isinstance(result, ToolResult):
-                    return result
-                return ToolResult(
-                    tool_use_id=tool_use.id,
-                    content=json.dumps(result) if not isinstance(result, str) else result,
-                    is_error=False,
-                )
+
+                # Async tool: wrap the awaitable so the caller can await it
+                if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+
+                    async def _await_and_wrap():
+                        try:
+                            r = await result
+                            return _wrap_result(tool_use.id, r)
+                        except Exception as exc:
+                            return ToolResult(
+                                tool_use_id=tool_use.id,
+                                content=json.dumps({"error": str(exc)}),
+                                is_error=True,
+                            )
+
+                    return _await_and_wrap()
+
+                return _wrap_result(tool_use.id, result)
             except Exception as e:
                 return ToolResult(
                     tool_use_id=tool_use.id,
@@ -457,6 +481,56 @@ class ToolRegistry:
 
         return tool
 
+    # ------------------------------------------------------------------
+    # Provider-based tool filtering
+    # ------------------------------------------------------------------
+
+    def build_provider_index(self) -> None:
+        """Build provider -> tool-name mapping from CREDENTIAL_SPECS.
+
+        Populates ``_provider_index`` so :meth:`get_by_provider` works.
+        Safe to call even if ``aden_tools`` is not installed (silently no-ops).
+        """
+        try:
+            from aden_tools.credentials import CREDENTIAL_SPECS
+        except ImportError:
+            logger.debug("aden_tools not available, skipping provider index")
+            return
+
+        self._provider_index.clear()
+        for spec in CREDENTIAL_SPECS.values():
+            provider = spec.aden_provider_name
+            if provider:
+                if provider not in self._provider_index:
+                    self._provider_index[provider] = set()
+                self._provider_index[provider].update(spec.tools)
+
+    def get_by_provider(self, provider: str) -> dict[str, Tool]:
+        """Return registered tools that belong to *provider*.
+
+        Lazily builds the provider index on first call.
+        """
+        if not self._provider_index:
+            self.build_provider_index()
+        tool_names = self._provider_index.get(provider, set())
+        return {name: rt.tool for name, rt in self._tools.items() if name in tool_names}
+
+    def get_tool_names_by_provider(self, provider: str) -> list[str]:
+        """Return sorted registered tool names for *provider*."""
+        if not self._provider_index:
+            self.build_provider_index()
+        tool_names = self._provider_index.get(provider, set())
+        return sorted(name for name in self._tools if name in tool_names)
+
+    def get_all_provider_tool_names(self) -> list[str]:
+        """Return sorted names of all registered tools that belong to any provider."""
+        if not self._provider_index:
+            self.build_provider_index()
+        all_names: set[str] = set()
+        for names in self._provider_index.values():
+            all_names.update(names)
+        return sorted(name for name in self._tools if name in all_names)
+
     def cleanup(self) -> None:
         """Clean up all MCP client connections."""
         for client in self._mcp_clients:

core/framework/runtime/EVENT_TYPES.md

@@ -0,0 +1,539 @@
+# Event Types and Schema Reference
+
+The Hive runtime uses a pub/sub `EventBus` for inter-component communication and observability. Every event is an `AgentEvent` dataclass published through `EventBus.publish()`.
+
+## Event Envelope (`AgentEvent`)
+
+Every event shares a common envelope:
+
+| Field            | Type              | Description                                                  |
+| ---------------- | ----------------- | ------------------------------------------------------------ |
+| `type`           | `EventType` (str) | Event type identifier (see below)                            |
+| `stream_id`      | `str`             | Entry point / pipeline that emitted the event                |
+| `node_id`        | `str \| None`     | Graph node that emitted the event                            |
+| `execution_id`   | `str \| None`     | Unique execution run ID (UUID, set by `ExecutionStream`)     |
+| `graph_id`       | `str \| None`     | Graph that emitted the event (set by `GraphScopedEventBus`)  |
+| `data`           | `dict`            | Event-type-specific payload (see individual schemas below)   |
+| `timestamp`      | `datetime`        | When the event was created                                   |
+| `correlation_id` | `str \| None`     | Optional ID for tracking related events across streams       |
+
+### Identity Fields
+
+The identity tuple `(graph_id, stream_id, node_id, execution_id)` uniquely locates any event:
+
+- **`graph_id`** — Which graph produced the event. Set automatically by `GraphScopedEventBus` (a subclass that stamps `graph_id` on every `publish()` call). Values: `"worker"`, `"judge"`, `"queen"`, or the graph spec ID.
+- **`stream_id`** — Which entry point / pipeline. Corresponds to `EntryPointSpec.id` in the graph definition. For single-entry-point graphs, this equals the entry point name (e.g. `"default"`, `"health_check"`, `"ticket_receiver"`).
+- **`node_id`** — Which specific node emitted the event. For `EventLoopNode` events, this is the node spec ID.
+- **`execution_id`** — UUID identifying a specific execution run. Multiple concurrent executions of the same entry point each get a unique `execution_id`.
+
+---
+
+## Execution Lifecycle
+
+### `execution_started`
+
+A new graph execution has begun.
+
+| Data Field | Type   | Description                     |
+| ---------- | ------ | ------------------------------- |
+| `input`    | `dict` | Input data passed to the graph  |
+
+**Emitted by:** `ExecutionStream._run_execution()`
+
+---
+
+### `execution_completed`
+
+A graph execution finished successfully.
+
+| Data Field | Type   | Description       |
+| ---------- | ------ | ----------------- |
+| `output`   | `dict` | Final output data |
+
+**Emitted by:** `ExecutionStream._run_execution()`
+
+---
+
+### `execution_failed`
+
+A graph execution failed with an error.
+
+| Data Field | Type  | Description   |
+| ---------- | ----- | ------------- |
+| `error`    | `str` | Error message |
+
+**Emitted by:** `ExecutionStream._run_execution()`
+
+---
+
+### `execution_paused`
+
+Execution has been paused (Ctrl+Z or HITL approval).
+
+| Data Field | Type  | Description       |
+| ---------- | ----- | ----------------- |
+| `reason`   | `str` | Why it was paused |
+
+**Emitted by:** `GraphExecutor.execute()`
+
+---
+
+### `execution_resumed`
+
+Execution has resumed from a paused state.
+
+| Data Field | Type | Description |
+| ---------- | ---- | ----------- |
+| *(none)*   |      |             |
+
+**Emitted by:** `GraphExecutor.execute()`
+
+---
+
+## Node Event-Loop Lifecycle
+
+These events track the inner loop of `EventLoopNode` — the multi-turn LLM streaming loop that powers most agent nodes.
+
+### `node_loop_started`
+
+An EventLoopNode has begun its execution loop.
+
+| Data Field       | Type       | Description                     |
+| ---------------- | ---------- | ------------------------------- |
+| `max_iterations` | `int\|null`| Maximum iterations configured   |
+
+**Emitted by:** `EventLoopNode._publish_loop_started()`, `GraphExecutor` (for function nodes in parallel branches)
+
+---
+
+### `node_loop_iteration`
+
+An EventLoopNode has started a new iteration (one LLM turn).
+
+| Data Field  | Type  | Description               |
+| ----------- | ----- | ------------------------- |
+| `iteration` | `int` | Zero-based iteration index |
+
+**Emitted by:** `EventLoopNode._publish_iteration()`
+
+---
+
+### `node_loop_completed`
+
+An EventLoopNode has finished its execution loop.
+
+| Data Field   | Type  | Description                            |
+| ------------ | ----- | -------------------------------------- |
+| `iterations` | `int` | Total number of iterations completed   |
+
+**Emitted by:** `EventLoopNode._publish_loop_completed()`, `GraphExecutor` (for function nodes in parallel branches)
+
+---
+
+## LLM Streaming
+
+### `llm_text_delta`
+
+Incremental text output from the LLM (non-client-facing nodes only).
+
+| Data Field | Type  | Description                              |
+| ---------- | ----- | ---------------------------------------- |
+| `content`  | `str` | New text chunk (delta)                   |
+| `snapshot` | `str` | Full accumulated text so far             |
+
+**Emitted by:** `EventLoopNode._publish_text_delta()` when `client_facing=False`
+
+---
+
+### `llm_reasoning_delta`
+
+Incremental reasoning/thinking output from the LLM.
+
+| Data Field | Type  | Description         |
+| ---------- | ----- | ------------------- |
+| `content`  | `str` | New reasoning chunk |
+
+**Emitted by:** Not currently wired in `EventLoopNode` (reserved for extended thinking models).
+
+---
+
+## Tool Lifecycle
+
+### `tool_call_started`
+
+The LLM has requested a tool call and execution is about to begin.
+
+| Data Field   | Type   | Description                          |
+| ------------ | ------ | ------------------------------------ |
+| `tool_use_id`| `str`  | Unique ID for this tool invocation   |
+| `tool_name`  | `str`  | Name of the tool being called        |
+| `tool_input` | `dict` | Arguments passed to the tool         |
+
+**Emitted by:** `EventLoopNode._publish_tool_started()`
+
+---
+
+### `tool_call_completed`
+
+A tool call has finished executing.
+
+| Data Field   | Type   | Description                            |
+| ------------ | ------ | -------------------------------------- |
+| `tool_use_id`| `str`  | Same ID from `tool_call_started`       |
+| `tool_name`  | `str`  | Name of the tool                       |
+| `result`     | `str`  | Tool execution result (may be truncated)|
+| `is_error`   | `bool` | Whether the tool returned an error     |
+
+**Emitted by:** `EventLoopNode._publish_tool_completed()`
+
+---
+
+## Client I/O
+
+These events are emitted only by nodes with `client_facing=True`. They drive the TUI's chat interface.
+
+### `client_output_delta`
+
+Incremental text output meant for the human operator.
+
+| Data Field | Type  | Description                  |
+| ---------- | ----- | ---------------------------- |
+| `content`  | `str` | New text chunk (delta)       |
+| `snapshot` | `str` | Full accumulated text so far |
+
+**Emitted by:** `EventLoopNode._publish_text_delta()` when `client_facing=True`
+
+---
+
+### `client_input_requested`
+
+The node is waiting for human input (via `ask_user` tool or auto-block on text-only turns).
+
+| Data Field | Type  | Description                                       |
+| ---------- | ----- | ------------------------------------------------- |
+| `prompt`   | `str` | Optional prompt/question shown to the user        |
+
+**Emitted by:** `EventLoopNode._await_user_input()`, doom loop handler
+
+The TUI subscribes to this event to show the input prompt and focus the chat input. After the user types, `inject_event()` is called on the node to unblock it.
+
+---
+
+## Internal Node Observability
+
+### `node_internal_output`
+
+Output from a non-client-facing node (for debugging/monitoring).
+
+| Data Field | Type  | Description      |
+| ---------- | ----- | ---------------- |
+| `content`  | `str` | Output text      |
+
+**Emitted by:** Available via `emit_node_internal_output()` — not currently wired in the default `EventLoopNode`.
+
+---
+
+### `node_input_blocked`
+
+A non-client-facing node is blocked waiting for input.
+
+| Data Field | Type  | Description     |
+| ---------- | ----- | --------------- |
+| `prompt`   | `str` | Block reason    |
+
+**Emitted by:** Available via `emit_node_input_blocked()` — reserved for future use.
+
+---
+
+### `node_stalled`
+
+The node's LLM has produced identical responses for several consecutive turns (stall detection).
+
+| Data Field | Type  | Description                                       |
+| ---------- | ----- | ------------------------------------------------- |
+| `reason`   | `str` | Always `"Consecutive identical responses detected"`|
+
+**Emitted by:** `EventLoopNode._publish_stalled()`
+
+---
+
+### `node_tool_doom_loop`
+
+The LLM is calling the same tool(s) with identical arguments repeatedly (doom loop detection).
+
+| Data Field    | Type  | Description                          |
+| ------------- | ----- | ------------------------------------ |
+| `description` | `str` | Human-readable doom loop description |
+
+**Emitted by:** `EventLoopNode` doom loop handler
+
+---
+
+## Judge Decisions
+
+### `judge_verdict`
+
+The judge (custom or implicit) has evaluated the current iteration.
+
+| Data Field   | Type  | Description                                          |
+| ------------ | ----- | ---------------------------------------------------- |
+| `action`     | `str` | `"ACCEPT"`, `"RETRY"`, `"ESCALATE"`, or `"CONTINUE"` |
+| `feedback`   | `str` | Judge feedback (empty for ACCEPT/CONTINUE)           |
+| `judge_type` | `str` | `"custom"` (explicit JudgeProtocol) or `"implicit"` (stop-reason heuristic) |
+| `iteration`  | `int` | Which iteration this verdict applies to              |
+
+**Emitted by:** `EventLoopNode._publish_judge_verdict()`
+
+**Verdict meanings:**
+- **ACCEPT** — Output meets requirements; node exits successfully.
+- **RETRY** — Output needs improvement; loop continues with feedback injected.
+- **ESCALATE** — Problem cannot be solved at this level; triggers escalation.
+- **CONTINUE** — Implicit verdict: LLM called tools, so it's making progress — let it keep going.
+
+---
+
+## Output Tracking
+
+### `output_key_set`
+
+A node has set an output key via the `set_output` synthetic tool.
+
+| Data Field | Type  | Description       |
+| ---------- | ----- | ----------------- |
+| `key`      | `str` | Output key name   |
+
+**Emitted by:** `EventLoopNode._publish_output_key_set()`
+
+---
+
+## Retry & Edge Tracking
+
+### `node_retry`
+
+A transient error occurred during an LLM call and the node is retrying.
+
+| Data Field    | Type  | Description                        |
+| ------------- | ----- | ---------------------------------- |
+| `retry_count` | `int` | Current retry attempt number       |
+| `max_retries` | `int` | Maximum retries configured         |
+| `error`       | `str` | Error message (truncated to 500ch) |
+
+**Emitted by:** `EventLoopNode` (stream retry handler), `GraphExecutor` (node-level retry)
+
+---
+
+### `edge_traversed`
+
+The executor has traversed an edge from one node to another.
+
+| Data Field       | Type  | Description                                    |
+| ---------------- | ----- | ---------------------------------------------- |
+| `source_node`    | `str` | Node ID the edge starts from                   |
+| `target_node`    | `str` | Node ID the edge goes to                       |
+| `edge_condition` | `str` | Edge condition: `"router"`, `"on_success"`, etc. |
+
+**Emitted by:** `GraphExecutor.execute()` — after router decisions, condition-based edges, and fallback edges.
+
+---
+
+## Context Management
+
+### `context_compacted`
+
+Not currently emitted — reserved for future use when `NodeConversation` compacts history.
+
+---
+
+## State Changes
+
+### `state_changed`
+
+A shared memory key has been modified.
+
+| Data Field  | Type  | Description                        |
+| ----------- | ----- | ---------------------------------- |
+| `key`       | `str` | Memory key that changed            |
+| `old_value` | `Any` | Previous value                     |
+| `new_value` | `Any` | New value                          |
+| `scope`     | `str` | Scope of the change                |
+
+**Emitted by:** Available via `emit_state_changed()` — not currently wired in default execution.
+
+---
+
+### `state_conflict`
+
+Not currently emitted — reserved for concurrent write conflict detection.
+
+---
+
+## Goal Tracking
+
+### `goal_progress`
+
+Goal completion progress update.
+
+| Data Field        | Type    | Description                          |
+| ----------------- | ------- | ------------------------------------ |
+| `progress`        | `float` | 0.0–1.0 completion fraction         |
+| `criteria_status` | `dict`  | Per-criterion status                 |
+
+**Emitted by:** Available via `emit_goal_progress()` — not currently wired in default execution.
+
+---
+
+### `goal_achieved`
+
+Not currently emitted — reserved for explicit goal completion signals.
+
+---
+
+### `constraint_violation`
+
+A goal constraint has been violated.
+
+| Data Field      | Type  | Description              |
+| --------------- | ----- | ------------------------ |
+| `constraint_id` | `str` | Which constraint failed  |
+| `description`   | `str` | What went wrong          |
+
+**Emitted by:** Available via `emit_constraint_violation()`.
+
+---
+
+## Stream Lifecycle
+
+### `stream_started` / `stream_stopped`
+
+Not currently emitted — reserved for `ExecutionStream` lifecycle tracking.
+
+---
+
+## External Triggers
+
+### `webhook_received`
+
+An external webhook has been received.
+
+| Data Field     | Type   | Description                  |
+| -------------- | ------ | ---------------------------- |
+| `path`         | `str`  | Webhook URL path             |
+| `method`       | `str`  | HTTP method                  |
+| `headers`      | `dict` | HTTP headers                 |
+| `payload`      | `dict` | Request body                 |
+| `query_params` | `dict` | URL query parameters         |
+
+**Emitted by:** Webhook server integration.
+
+Note: `node_id` is not set on this event; `stream_id` is the webhook source ID.
+
+---
+
+## Escalation
+
+### `escalation_requested`
+
+An agent has requested handoff to the Hive Coder (via the `escalate_to_coder` synthetic tool).
+
+| Data Field | Type  | Description                     |
+| ---------- | ----- | ------------------------------- |
+| `reason`   | `str` | Why escalation is needed        |
+| `context`  | `str` | Additional context for the coder|
+
+**Emitted by:** `EventLoopNode` when the LLM calls `escalate_to_coder`.
+
+---
+
+## Worker Health Monitoring
+
+These events form the **judge → queen → operator** escalation pipeline.
+
+### `worker_escalation_ticket`
+
+The Worker Health Judge has detected a degradation pattern and is escalating to the Queen.
+
+| Data Field | Type   | Description                          |
+| ---------- | ------ | ------------------------------------ |
+| `ticket`   | `dict` | Full `EscalationTicket` (see below)  |
+
+**Emitted by:** `emit_escalation_ticket` tool (in `worker_monitoring_tools.py`)
+
+#### EscalationTicket Schema
+
+| Field                     | Type               | Description                                              |
+| ------------------------- | ------------------ | -------------------------------------------------------- |
+| `ticket_id`               | `str`              | Auto-generated UUID                                      |
+| `created_at`              | `str`              | ISO timestamp                                            |
+| `worker_agent_id`         | `str`              | Which worker agent                                       |
+| `worker_session_id`       | `str`              | Which session                                            |
+| `worker_node_id`          | `str`              | Which node is struggling                                 |
+| `worker_graph_id`         | `str`              | Which graph                                              |
+| `severity`                | `str`              | `"low"`, `"medium"`, `"high"`, or `"critical"`           |
+| `cause`                   | `str`              | Human-readable problem description                       |
+| `judge_reasoning`         | `str`              | Judge's deliberation chain                               |
+| `suggested_action`        | `str`              | e.g. `"Restart node"`, `"Human review"`, `"Kill session"`|
+| `recent_verdicts`         | `list[str]`        | e.g. `["RETRY", "RETRY", "CONTINUE", "RETRY"]`          |
+| `total_steps_checked`     | `int`              | Steps the judge inspected                                |
+| `steps_since_last_accept` | `int`              | Consecutive non-ACCEPT steps                             |
+| `stall_minutes`           | `float \| null`    | Minutes since last activity (null if active)             |
+| `evidence_snippet`        | `str`              | Excerpt from recent LLM output                           |
+
+---
+
+### `queen_intervention_requested`
+
+The Queen has triaged an escalation ticket and decided the human operator should be involved.
+
+| Data Field        | Type  | Description                                          |
+| ----------------- | ----- | ---------------------------------------------------- |
+| `ticket_id`       | `str` | From the original `EscalationTicket`                 |
+| `analysis`        | `str` | Queen's 2–3 sentence analysis                        |
+| `severity`        | `str` | `"low"`, `"medium"`, `"high"`, or `"critical"`       |
+| `queen_graph_id`  | `str` | Queen's graph ID (for TUI navigation)                |
+| `queen_stream_id` | `str` | Queen's stream ID                                    |
+
+**Emitted by:** `notify_operator` tool (in `worker_monitoring_tools.py`)
+
+The TUI subscribes to this event and shows a non-disruptive notification. The worker continues running.
+
+---
+
+## Custom Events
+
+### `custom`
+
+User-defined events with arbitrary payloads. No schema enforced.
+
+---
+
+## Subscription & Filtering
+
+Events can be filtered when subscribing:
+
+```python
+bus.subscribe(
+    event_types=[EventType.TOOL_CALL_STARTED, EventType.TOOL_CALL_COMPLETED],
+    handler=my_handler,
+    filter_stream="default",       # Only events from this stream
+    filter_node="planner",         # Only events from this node
+    filter_execution="exec-uuid",  # Only events from this execution
+    filter_graph="worker",         # Only events from this graph
+)
+```
+
+## Debug Event Logging
+
+Set `HIVE_DEBUG_EVENTS=1` to write every published event to a JSONL file at `~/.hive/event_logs/<timestamp>.jsonl`. Each line is the full JSON serialization of an `AgentEvent`:
+
+```json
+{
+  "type": "tool_call_started",
+  "stream_id": "default",
+  "node_id": "planner",
+  "execution_id": "a1b2c3d4-...",
+  "graph_id": "worker",
+  "data": {"tool_use_id": "tu_1", "tool_name": "web_search", "tool_input": {"query": "..."}},
+  "timestamp": "2026-02-24T12:00:00.000000",
+  "correlation_id": null
+}
+```

core/framework/runtime/RESUMABLE_SESSIONS_DESIGN.md

@@ -84,12 +84,10 @@ class Checkpoint:
         │   ├── checkpoint_1.json         # Individual checkpoints
         │   ├── checkpoint_2.json
         │   └── checkpoint_N.json
-        ├── conversations/                # Per-node conversation state (existing)
-        │   ├── node_id_1/
-        │   │   ├── parts/
-        │   │   ├── meta.json
-        │   │   └── cursor.json
-        │   └── node_id_2/...
+        ├── conversations/                # Flat conversation state (parts carry phase_id)
+        │   ├── meta.json                # Current node config
+        │   ├── cursor.json              # Iteration, outputs, stall state
+        │   └── parts/                   # Sequential message files
         ├── data/                         # Spillover artifacts (existing)
         └── logs/                         # L1/L2/L3 logs (existing)
 ```

core/framework/runtime/RUNTIME_LOGGING.md

@@ -27,7 +27,7 @@ This layered approach enables efficient debugging: start with L1 to identify pro
         │   ├── summary.json     # L1: Run outcome
         │   ├── details.jsonl    # L2: Per-node results
         │   └── tool_logs.jsonl  # L3: Step-by-step execution
-        ├── conversations/       # Per-node EventLoop state
+        ├── conversations/       # Flat EventLoop state (parts carry phase_id)
         └── data/                # Spillover artifacts
 ```
 

core/framework/runtime/core.py

@@ -66,6 +66,10 @@ class Runtime:
         self._current_run: Run | None = None
         self._current_node: str = "unknown"
 
+    @property
+    def execution_id(self) -> str:
+        return ""
+
     # === RUN LIFECYCLE ===
 
     def start_run(

core/framework/runtime/escalation_ticket.py

@@ -0,0 +1,39 @@
+"""EscalationTicket — structured schema for worker health judge escalations."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class EscalationTicket(BaseModel):
+    """Structured escalation report emitted by the Worker Health Judge.
+
+    The judge must fill every field before calling emit_escalation_ticket.
+    Pydantic validation rejects partial tickets, preventing impulsive escalation.
+    """
+
+    ticket_id: str = Field(default_factory=lambda: str(uuid4()))
+    created_at: str = Field(default_factory=lambda: datetime.now(UTC).isoformat())
+
+    # Worker identification
+    worker_agent_id: str
+    worker_session_id: str
+    worker_node_id: str
+    worker_graph_id: str
+
+    # Problem characterization (filled by judge via LLM deliberation)
+    severity: Literal["low", "medium", "high", "critical"]
+    cause: str  # Human-readable: "Node has produced 18 RETRY verdicts..."
+    judge_reasoning: str  # Judge's own deliberation chain
+    suggested_action: str  # "Restart node", "Human review", "Kill session", etc.
+
+    # Evidence
+    recent_verdicts: list[str]  # e.g. ["RETRY", "RETRY", "CONTINUE", "RETRY"]
+    total_steps_checked: int  # How many steps the judge saw
+    steps_since_last_accept: int  # Steps with no ACCEPT verdict
+    stall_minutes: float | None  # Wall-clock minutes since last new log step (None if active)
+    evidence_snippet: str  # Brief excerpt from recent LLM output or error

core/framework/runtime/event_bus.py

@@ -8,15 +8,53 @@ Allows streams to:
 """
 
 import asyncio
+import json
 import logging
+import os
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import StrEnum
-from typing import Any
+from pathlib import Path
+from typing import IO, Any
 
 logger = logging.getLogger(__name__)
 
+# ---------------------------------------------------------------------------
+# HIVE_DEBUG_EVENTS — write every published event to a JSONL file.
+#
+# Set the env var to any truthy value to enable:
+#   HIVE_DEBUG_EVENTS=1          → writes to ~/.hive/event_logs/<ts>.jsonl
+#   HIVE_DEBUG_EVENTS=/tmp/ev    → writes to that exact directory
+#
+# Each line is a full JSON serialisation of the AgentEvent.
+# The file is opened lazily on first publish and flushed after every write.
+# ---------------------------------------------------------------------------
+_DEBUG_EVENTS_RAW = os.environ.get("HIVE_DEBUG_EVENTS", "").strip()
+_DEBUG_EVENTS_ENABLED = _DEBUG_EVENTS_RAW.lower() in ("1", "true", "full") or (
+    bool(_DEBUG_EVENTS_RAW) and _DEBUG_EVENTS_RAW.lower() not in ("0", "false", "")
+)
+
+
+def _open_event_log() -> IO[str] | None:
+    """Open a JSONL event log file.  Returns None if disabled."""
+    if not _DEBUG_EVENTS_ENABLED:
+        return None
+    raw = _DEBUG_EVENTS_RAW
+    if raw.lower() in ("1", "true", "full"):
+        log_dir = Path.home() / ".hive" / "event_logs"
+    else:
+        log_dir = Path(raw)
+    log_dir.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    path = log_dir / f"{ts}.jsonl"
+    logger.info("Event debug log → %s", path)
+    return open(path, "a", encoding="utf-8")  # noqa: SIM115
+
+
+_event_log_file: IO[str] | None = None
+_event_log_ready = False  # lazy init guard
+
 
 class EventType(StrEnum):
     """Types of events that can be published."""
@@ -45,6 +83,7 @@ class EventType(StrEnum):
     NODE_LOOP_STARTED = "node_loop_started"
     NODE_LOOP_ITERATION = "node_loop_iteration"
     NODE_LOOP_COMPLETED = "node_loop_completed"
+    NODE_ACTION_PLAN = "node_action_plan"
 
     # LLM streaming observability
     LLM_TEXT_DELTA = "llm_text_delta"
@@ -83,6 +122,16 @@ class EventType(StrEnum):
     # Custom events
     CUSTOM = "custom"
 
+    # Escalation (agent requests handoff to hive_coder)
+    ESCALATION_REQUESTED = "escalation_requested"
+
+    # Worker health monitoring (judge → queen → operator)
+    WORKER_ESCALATION_TICKET = "worker_escalation_ticket"
+    QUEEN_INTERVENTION_REQUESTED = "queen_intervention_requested"
+
+    # Worker lifecycle (session manager → frontend)
+    WORKER_LOADED = "worker_loaded"
+
 
 @dataclass
 class AgentEvent:
@@ -95,6 +144,7 @@ class AgentEvent:
     data: dict[str, Any] = field(default_factory=dict)
     timestamp: datetime = field(default_factory=datetime.now)
     correlation_id: str | None = None  # For tracking related events
+    graph_id: str | None = None  # Which graph emitted this event (multi-graph sessions)
 
     def to_dict(self) -> dict:
         """Convert to dictionary for serialization."""
@@ -106,6 +156,7 @@ class AgentEvent:
             "data": self.data,
             "timestamp": self.timestamp.isoformat(),
             "correlation_id": self.correlation_id,
+            "graph_id": self.graph_id,
         }
 
 
@@ -123,6 +174,7 @@ class Subscription:
     filter_stream: str | None = None  # Only receive events from this stream
     filter_node: str | None = None  # Only receive events from this node
     filter_execution: str | None = None  # Only receive events from this execution
+    filter_graph: str | None = None  # Only receive events from this graph
 
 
 class EventBus:
@@ -182,6 +234,7 @@ class EventBus:
         filter_stream: str | None = None,
         filter_node: str | None = None,
         filter_execution: str | None = None,
+        filter_graph: str | None = None,
     ) -> str:
         """
         Subscribe to events.
@@ -192,6 +245,7 @@ class EventBus:
             filter_stream: Only receive events from this stream
             filter_node: Only receive events from this node
             filter_execution: Only receive events from this execution
+            filter_graph: Only receive events from this graph
 
         Returns:
             Subscription ID (use to unsubscribe)
@@ -206,6 +260,7 @@ class EventBus:
             filter_stream=filter_stream,
             filter_node=filter_node,
             filter_execution=filter_execution,
+            filter_graph=filter_graph,
         )
 
         self._subscriptions[sub_id] = subscription
@@ -242,6 +297,20 @@ class EventBus:
             if len(self._event_history) > self._max_history:
                 self._event_history = self._event_history[-self._max_history :]
 
+        # Write event to JSONL file (gated by HIVE_DEBUG_EVENTS env var)
+        if _DEBUG_EVENTS_ENABLED:
+            global _event_log_file, _event_log_ready  # noqa: PLW0603
+            if not _event_log_ready:
+                _event_log_file = _open_event_log()
+                _event_log_ready = True
+            if _event_log_file is not None:
+                try:
+                    line = json.dumps(event.to_dict(), default=str)
+                    _event_log_file.write(line + "\n")
+                    _event_log_file.flush()
+                except Exception:
+                    pass  # never break event delivery
+
         # Find matching subscriptions
         matching_handlers: list[EventHandler] = []
 
@@ -271,6 +340,10 @@ class EventBus:
         if subscription.filter_execution and subscription.filter_execution != event.execution_id:
             return False
 
+        # Check graph filter
+        if subscription.filter_graph and subscription.filter_graph != event.graph_id:
+            return False
+
         return True
 
     async def _execute_handlers(
@@ -464,6 +537,24 @@ class EventBus:
             )
         )
 
+    async def emit_node_action_plan(
+        self,
+        stream_id: str,
+        node_id: str,
+        plan: str,
+        execution_id: str | None = None,
+    ) -> None:
+        """Emit node action plan event."""
+        await self.publish(
+            AgentEvent(
+                type=EventType.NODE_ACTION_PLAN,
+                stream_id=stream_id,
+                node_id=node_id,
+                execution_id=execution_id,
+                data={"plan": plan},
+            )
+        )
+
     # === LLM STREAMING PUBLISHERS ===
 
     async def emit_llm_text_delta(
@@ -820,6 +911,71 @@ class EventBus:
             )
         )
 
+    async def emit_escalation_requested(
+        self,
+        stream_id: str,
+        node_id: str,
+        reason: str = "",
+        context: str = "",
+        execution_id: str | None = None,
+    ) -> None:
+        """Emit escalation requested event (agent wants hive_coder)."""
+        await self.publish(
+            AgentEvent(
+                type=EventType.ESCALATION_REQUESTED,
+                stream_id=stream_id,
+                node_id=node_id,
+                execution_id=execution_id,
+                data={"reason": reason, "context": context},
+            )
+        )
+
+    async def emit_worker_escalation_ticket(
+        self,
+        stream_id: str,
+        node_id: str,
+        ticket: dict,
+        execution_id: str | None = None,
+    ) -> None:
+        """Emitted by health judge when worker shows a degradation pattern."""
+        await self.publish(
+            AgentEvent(
+                type=EventType.WORKER_ESCALATION_TICKET,
+                stream_id=stream_id,
+                node_id=node_id,
+                execution_id=execution_id,
+                data={"ticket": ticket},
+            )
+        )
+
+    async def emit_queen_intervention_requested(
+        self,
+        stream_id: str,
+        node_id: str,
+        ticket_id: str,
+        analysis: str,
+        severity: str,
+        queen_graph_id: str,
+        queen_stream_id: str,
+        execution_id: str | None = None,
+    ) -> None:
+        """Emitted by queen when she decides the operator should be involved."""
+        await self.publish(
+            AgentEvent(
+                type=EventType.QUEEN_INTERVENTION_REQUESTED,
+                stream_id=stream_id,
+                node_id=node_id,
+                execution_id=execution_id,
+                data={
+                    "ticket_id": ticket_id,
+                    "analysis": analysis,
+                    "severity": severity,
+                    "queen_graph_id": queen_graph_id,
+                    "queen_stream_id": queen_stream_id,
+                },
+            )
+        )
+
     # === QUERY OPERATIONS ===
 
     def get_history(
@@ -873,6 +1029,7 @@ class EventBus:
         stream_id: str | None = None,
         node_id: str | None = None,
         execution_id: str | None = None,
+        graph_id: str | None = None,
         timeout: float | None = None,
     ) -> AgentEvent | None:
         """
@@ -883,6 +1040,7 @@ class EventBus:
             stream_id: Filter by stream
             node_id: Filter by node
             execution_id: Filter by execution
+            graph_id: Filter by graph
             timeout: Maximum time to wait (seconds)
 
         Returns:
@@ -903,6 +1061,7 @@ class EventBus:
             filter_stream=stream_id,
             filter_node=node_id,
             filter_execution=execution_id,
+            filter_graph=graph_id,
         )
 
         try:

core/framework/runtime/execution_stream.py

@@ -19,6 +19,7 @@ from typing import TYPE_CHECKING, Any
 
 from framework.graph.checkpoint_config import CheckpointConfig
 from framework.graph.executor import ExecutionResult, GraphExecutor
+from framework.runtime.event_bus import EventBus
 from framework.runtime.shared_state import IsolationLevel, SharedStateManager
 from framework.runtime.stream_runtime import StreamRuntime, StreamRuntimeAdapter
 
@@ -26,7 +27,7 @@ if TYPE_CHECKING:
     from framework.graph.edge import GraphSpec
     from framework.graph.goal import Goal
     from framework.llm.provider import LLMProvider, Tool
-    from framework.runtime.event_bus import EventBus
+    from framework.runtime.event_bus import AgentEvent
     from framework.runtime.outcome_aggregator import OutcomeAggregator
     from framework.storage.concurrent import ConcurrentStorage
     from framework.storage.session_store import SessionStore
@@ -34,6 +35,52 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+class GraphScopedEventBus(EventBus):
+    """Proxy that stamps ``graph_id`` on every published event.
+
+    The ``GraphExecutor`` and ``EventLoopNode`` emit events via the
+    convenience methods on ``EventBus`` (e.g. ``emit_llm_text_delta``).
+    Rather than threading ``graph_id`` through every one of those 20+
+    methods, this subclass overrides ``publish()`` to stamp the id
+    before forwarding to the real bus.
+
+    Because the ``emit_*`` methods are *inherited* from ``EventBus``,
+    ``self.publish()`` inside them resolves to this class's override —
+    unlike a ``__getattr__``-based proxy where the delegated bound
+    methods would call ``EventBus.publish`` directly, bypassing the
+    stamp entirely.
+    """
+
+    def __init__(self, bus: "EventBus", graph_id: str) -> None:
+        # Intentionally skip super().__init__() — we delegate all state
+        # (subscriptions, history, semaphore, etc.) to the real bus.
+        self._real_bus = bus
+        self._scope_graph_id = graph_id
+
+    async def publish(self, event: "AgentEvent") -> None:  # type: ignore[override]
+        event.graph_id = self._scope_graph_id
+        await self._real_bus.publish(event)
+
+    # --- Delegate state-reading methods to the real bus ---
+    # These access internal state (_subscriptions, _event_history, etc.)
+    # that only exists on the real bus.
+
+    def subscribe(self, *args: Any, **kwargs: Any) -> str:
+        return self._real_bus.subscribe(*args, **kwargs)
+
+    def unsubscribe(self, subscription_id: str) -> bool:
+        return self._real_bus.unsubscribe(subscription_id)
+
+    def get_history(self, *args: Any, **kwargs: Any) -> list:
+        return self._real_bus.get_history(*args, **kwargs)
+
+    def get_stats(self) -> dict:
+        return self._real_bus.get_stats()
+
+    async def wait_for(self, *args: Any, **kwargs: Any) -> Any:
+        return await self._real_bus.wait_for(*args, **kwargs)
+
+
 @dataclass
 class EntryPointSpec:
     """Specification for an entry point."""
@@ -117,6 +164,10 @@ class ExecutionStream:
         runtime_log_store: Any = None,
         session_store: "SessionStore | None" = None,
         checkpoint_config: CheckpointConfig | None = None,
+        graph_id: str | None = None,
+        accounts_prompt: str = "",
+        accounts_data: list[dict] | None = None,
+        tool_provider_map: dict[str, str] | None = None,
     ):
         """
         Initialize execution stream.
@@ -136,11 +187,16 @@ class ExecutionStream:
             runtime_log_store: Optional RuntimeLogStore for per-execution logging
             session_store: Optional SessionStore for unified session storage
             checkpoint_config: Optional checkpoint configuration for resumable sessions
+            graph_id: Optional graph identifier for multi-graph sessions
+            accounts_prompt: Connected accounts block for system prompt injection
+            accounts_data: Raw account data for per-node prompt generation
+            tool_provider_map: Tool name to provider name mapping for account routing
         """
         self.stream_id = stream_id
         self.entry_spec = entry_spec
         self.graph = graph
         self.goal = goal
+        self.graph_id = graph_id
         self._state_manager = state_manager
         self._storage = storage
         self._outcome_aggregator = outcome_aggregator
@@ -153,6 +209,9 @@ class ExecutionStream:
         self._runtime_log_store = runtime_log_store
         self._checkpoint_config = checkpoint_config
         self._session_store = session_store
+        self._accounts_prompt = accounts_prompt
+        self._accounts_data = accounts_data
+        self._tool_provider_map = tool_provider_map
 
         # Create stream-scoped runtime
         self._runtime = StreamRuntime(
@@ -173,6 +232,11 @@ class ExecutionStream:
         self._semaphore = asyncio.Semaphore(entry_spec.max_concurrent)
         self._lock = asyncio.Lock()
 
+        # Graph-scoped event bus (stamps graph_id on published events)
+        self._scoped_event_bus = self._event_bus
+        if self._event_bus and self.graph_id:
+            self._scoped_event_bus = GraphScopedEventBus(self._event_bus, self.graph_id)
+
         # State
         self._running = False
 
@@ -185,10 +249,10 @@ class ExecutionStream:
         logger.info(f"ExecutionStream '{self.stream_id}' started")
 
         # Emit stream started event
-        if self._event_bus:
+        if self._scoped_event_bus:
             from framework.runtime.event_bus import AgentEvent, EventType
 
-            await self._event_bus.publish(
+            await self._scoped_event_bus.publish(
                 AgentEvent(
                     type=EventType.STREAM_STARTED,
                     stream_id=self.stream_id,
@@ -201,6 +265,41 @@ class ExecutionStream:
         """Return IDs of all currently active executions."""
         return list(self._active_executions.keys())
 
+    @property
+    def is_awaiting_input(self) -> bool:
+        """True when an active execution is blocked waiting for client input."""
+        if not self._active_executors:
+            return False
+        for executor in self._active_executors.values():
+            for node in executor.node_registry.values():
+                if getattr(node, "_awaiting_input", False):
+                    return True
+        return False
+
+    def get_waiting_nodes(self) -> list[dict[str, str]]:
+        """Return nodes currently blocked waiting for client input.
+
+        Each entry is ``{"node_id": ..., "execution_id": ...}``.
+        """
+        waiting: list[dict[str, str]] = []
+        for exec_id, executor in self._active_executors.items():
+            for node_id, node in executor.node_registry.items():
+                if getattr(node, "_awaiting_input", False):
+                    waiting.append({"node_id": node_id, "execution_id": exec_id})
+        return waiting
+
+    def get_injectable_nodes(self) -> list[dict[str, str]]:
+        """Return nodes that support message injection (have ``inject_event``).
+
+        Each entry is ``{"node_id": ..., "execution_id": ...}``.
+        """
+        injectable: list[dict[str, str]] = []
+        for exec_id, executor in self._active_executors.items():
+            for node_id, node in executor.node_registry.items():
+                if hasattr(node, "inject_event"):
+                    injectable.append({"node_id": node_id, "execution_id": exec_id})
+        return injectable
+
     def _record_execution_result(self, execution_id: str, result: ExecutionResult) -> None:
         """Record a completed execution result with retention pruning."""
         self._execution_results[execution_id] = result
@@ -251,17 +350,23 @@ class ExecutionStream:
         logger.info(f"ExecutionStream '{self.stream_id}' stopped")
 
         # Emit stream stopped event
-        if self._event_bus:
+        if self._scoped_event_bus:
             from framework.runtime.event_bus import AgentEvent, EventType
 
-            await self._event_bus.publish(
+            await self._scoped_event_bus.publish(
                 AgentEvent(
                     type=EventType.STREAM_STOPPED,
                     stream_id=self.stream_id,
                 )
             )
 
-    async def inject_input(self, node_id: str, content: str) -> bool:
+    async def inject_input(
+        self,
+        node_id: str,
+        content: str,
+        *,
+        is_client_input: bool = False,
+    ) -> bool:
         """Inject user input into a running client-facing EventLoopNode.
 
         Searches active executors for a node matching ``node_id`` and calls
@@ -272,7 +377,7 @@ class ExecutionStream:
         for executor in self._active_executors.values():
             node = executor.node_registry.get(node_id)
             if node is not None and hasattr(node, "inject_event"):
-                await node.inject_event(content)
+                await node.inject_event(content, is_client_input=is_client_input)
                 return True
         return False
 
@@ -358,8 +463,8 @@ class ExecutionStream:
 
             try:
                 # Emit started event
-                if self._event_bus:
-                    await self._event_bus.emit_execution_started(
+                if self._scoped_event_bus:
+                    await self._scoped_event_bus.emit_execution_started(
                         stream_id=self.stream_id,
                         execution_id=execution_id,
                         input_data=ctx.input_data,
@@ -398,17 +503,28 @@ class ExecutionStream:
                 # to this execution.  The executor sets data_dir via execution
                 # context (contextvars) so data tools and spillover share the
                 # same session-scoped directory.
-                exec_storage = self._storage.base_path / "sessions" / execution_id
+                # Derive storage from session_store (graph-specific for secondary
+                # graphs) so that all files — conversations, state, checkpoints,
+                # data — land under the graph's own sessions/ directory, not the
+                # primary worker's.
+                if self._session_store:
+                    exec_storage = self._session_store.sessions_dir / execution_id
+                else:
+                    exec_storage = self._storage.base_path / "sessions" / execution_id
                 executor = GraphExecutor(
                     runtime=runtime_adapter,
                     llm=self._llm,
                     tools=self._tools,
                     tool_executor=self._tool_executor,
-                    event_bus=self._event_bus,
+                    event_bus=self._scoped_event_bus,
                     stream_id=self.stream_id,
+                    execution_id=execution_id,
                     storage_path=exec_storage,
                     runtime_logger=runtime_logger,
                     loop_config=self.graph.loop_config,
+                    accounts_prompt=self._accounts_prompt,
+                    accounts_data=self._accounts_data,
+                    tool_provider_map=self._tool_provider_map,
                 )
                 # Track executor so inject_input() can reach EventLoopNode instances
                 self._active_executors[execution_id] = executor
@@ -454,16 +570,17 @@ class ExecutionStream:
                     await self._write_session_state(execution_id, ctx, result=result)
 
                 # Emit completion/failure event
-                if self._event_bus:
+                # (skip for pauses — executor already emitted execution_paused)
+                if self._scoped_event_bus:
                     if result.success:
-                        await self._event_bus.emit_execution_completed(
+                        await self._scoped_event_bus.emit_execution_completed(
                             stream_id=self.stream_id,
                             execution_id=execution_id,
                             output=result.output,
                             correlation_id=ctx.correlation_id,
                         )
-                    else:
-                        await self._event_bus.emit_execution_failed(
+                    elif not result.paused_at:
+                        await self._scoped_event_bus.emit_execution_failed(
                             stream_id=self.stream_id,
                             execution_id=execution_id,
                             error=result.error or "Unknown error",
@@ -541,8 +658,8 @@ class ExecutionStream:
                     pass  # Don't let end_run errors mask the original error
 
                 # Emit failure event
-                if self._event_bus:
-                    await self._event_bus.emit_execution_failed(
+                if self._scoped_event_bus:
+                    await self._scoped_event_bus.emit_execution_failed(
                         stream_id=self.stream_id,
                         execution_id=execution_id,
                         error=str(e),

core/framework/runtime/outcome_aggregator.py

@@ -313,7 +313,6 @@ class OutcomeAggregator:
     async def _evaluate_criterion(self, criterion: Any) -> CriterionStatus:
         """
         Evaluate a single success criterion.
-
         This is a heuristic evaluation based on decision outcomes.
         More sophisticated evaluation can be added per criterion type.
         """
@@ -325,6 +324,11 @@ class OutcomeAggregator:
             evidence=[],
         )
 
+        # Guard: only apply this heuristic to success-rate criteria
+        criterion_type = getattr(criterion, "type", "success_rate")
+        if criterion_type != "success_rate":
+            return status
+
         # Get relevant decisions (those mentioning this criterion or related intents)
         relevant_decisions = [
             d
@@ -341,13 +345,17 @@ class OutcomeAggregator:
         outcomes = [d.outcome for d in relevant_decisions if d.outcome is not None]
         if outcomes:
             success_count = sum(1 for o in outcomes if o.success)
+
+            # Progress is computed as raw success rate of decision outcomes.
             status.progress = success_count / len(outcomes)
 
             # Add evidence
             for d in relevant_decisions[:5]:  # Limit evidence
                 if d.outcome:
                     evidence = (
-                        f"{d.decision.intent}: {'success' if d.outcome.success else 'failed'}"
+                        f"decision_id={d.decision.id}, "
+                        f"intent={d.decision.intent}, "
+                        f"result={'success' if d.outcome.success else 'failed'}"
                     )
                     status.evidence.append(evidence)
 

core/framework/runtime/runtime_log_schemas.py

@@ -30,14 +30,14 @@ class NodeStepLog(BaseModel):
     """Full tool and LLM details for one step within a node.
 
     For EventLoopNode, each iteration is a step. For single-step nodes
-    (LLMNode, FunctionNode, RouterNode), step_index is 0.
+    (e.g. RouterNode), step_index is 0.
 
     OTel-aligned fields (trace_id, span_id, execution_id) enable correlation
     and future OpenTelemetry export without schema changes.
     """
 
     node_id: str
-    node_type: str = ""  # "event_loop"|"llm_tool_use"|"llm_generate"|"function"|"router"
+    node_type: str = ""  # "event_loop" (the only valid type)
     step_index: int = 0  # iteration number for event_loop, 0 for single-step nodes
     llm_text: str = ""
     tool_calls: list[ToolCallLog] = Field(default_factory=list)

core/framework/runtime/stream_runtime.py

@@ -448,6 +448,10 @@ class StreamRuntimeAdapter:
     def storage(self):
         return self._runtime._storage
 
+    @property
+    def execution_id(self) -> str:
+        return self._execution_id
+
     @property
     def current_run(self) -> Run | None:
         return self._runtime.get_run(self._execution_id)

core/framework/runtime/tests/test_agent_runtime.py

@@ -64,7 +64,7 @@ def sample_graph():
             id="process-webhook",
             name="Process Webhook",
             description="Process incoming webhook",
-            node_type="llm_generate",
+            node_type="event_loop",
             input_keys=["webhook_data"],
             output_keys=["result"],
         ),
@@ -72,7 +72,7 @@ def sample_graph():
             id="process-api",
             name="Process API Request",
             description="Process API request",
-            node_type="llm_generate",
+            node_type="event_loop",
             input_keys=["request_data"],
             output_keys=["result"],
         ),
@@ -538,7 +538,7 @@ class TestGraphSpecValidation:
                 id="valid-node",
                 name="Valid Node",
                 description="A valid node",
-                node_type="llm_generate",
+                node_type="event_loop",
                 input_keys=[],
                 output_keys=[],
             ),
@@ -641,5 +641,185 @@ class TestCreateAgentRuntime:
         assert "api" in runtime._entry_points
 
 
+# === Timer Entry Point Tests ===
+
+
+class TestTimerEntryPoints:
+    """Tests for timer-driven entry points (interval and cron)."""
+
+    @pytest.mark.asyncio
+    async def test_interval_timer_starts_task(self, sample_graph, sample_goal, temp_storage):
+        """Test that interval_minutes timer creates an async task."""
+        runtime = AgentRuntime(
+            graph=sample_graph,
+            goal=sample_goal,
+            storage_path=temp_storage,
+        )
+
+        entry_spec = EntryPointSpec(
+            id="timer-interval",
+            name="Interval Timer",
+            entry_node="process-webhook",
+            trigger_type="timer",
+            trigger_config={"interval_minutes": 60},
+        )
+        runtime.register_entry_point(entry_spec)
+
+        await runtime.start()
+        try:
+            assert len(runtime._timer_tasks) == 1
+            assert not runtime._timer_tasks[0].done()
+            # Give the async task a moment to set next_fire
+            await asyncio.sleep(0.05)
+            assert "timer-interval" in runtime._timer_next_fire
+        finally:
+            await runtime.stop()
+
+        assert len(runtime._timer_tasks) == 0
+
+    @pytest.mark.asyncio
+    async def test_cron_timer_starts_task(self, sample_graph, sample_goal, temp_storage):
+        """Test that cron expression timer creates an async task."""
+        runtime = AgentRuntime(
+            graph=sample_graph,
+            goal=sample_goal,
+            storage_path=temp_storage,
+        )
+
+        entry_spec = EntryPointSpec(
+            id="timer-cron",
+            name="Cron Timer",
+            entry_node="process-webhook",
+            trigger_type="timer",
+            trigger_config={"cron": "*/5 * * * *"},  # Every 5 minutes
+        )
+        runtime.register_entry_point(entry_spec)
+
+        await runtime.start()
+        try:
+            assert len(runtime._timer_tasks) == 1
+            assert not runtime._timer_tasks[0].done()
+            # Give the async task a moment to set next_fire
+            await asyncio.sleep(0.05)
+            assert "timer-cron" in runtime._timer_next_fire
+        finally:
+            await runtime.stop()
+
+    @pytest.mark.asyncio
+    async def test_invalid_cron_expression_skipped(
+        self, sample_graph, sample_goal, temp_storage, caplog
+    ):
+        """Test that an invalid cron expression logs a warning and skips."""
+        runtime = AgentRuntime(
+            graph=sample_graph,
+            goal=sample_goal,
+            storage_path=temp_storage,
+        )
+
+        entry_spec = EntryPointSpec(
+            id="timer-bad-cron",
+            name="Bad Cron Timer",
+            entry_node="process-webhook",
+            trigger_type="timer",
+            trigger_config={"cron": "not a cron expression"},
+        )
+        runtime.register_entry_point(entry_spec)
+
+        await runtime.start()
+        try:
+            assert len(runtime._timer_tasks) == 0
+            assert "invalid cron" in caplog.text.lower() or "Invalid cron" in caplog.text
+        finally:
+            await runtime.stop()
+
+    @pytest.mark.asyncio
+    async def test_cron_takes_priority_over_interval(
+        self, sample_graph, sample_goal, temp_storage, caplog
+    ):
+        """Test that when both cron and interval_minutes are set, cron wins."""
+        import logging
+
+        runtime = AgentRuntime(
+            graph=sample_graph,
+            goal=sample_goal,
+            storage_path=temp_storage,
+        )
+
+        entry_spec = EntryPointSpec(
+            id="timer-both",
+            name="Both Timer",
+            entry_node="process-webhook",
+            trigger_type="timer",
+            trigger_config={"cron": "0 9 * * *", "interval_minutes": 30},
+        )
+        runtime.register_entry_point(entry_spec)
+
+        with caplog.at_level(logging.INFO):
+            await runtime.start()
+        try:
+            assert len(runtime._timer_tasks) == 1
+            # Should log cron, not interval
+            assert any("cron" in r.message.lower() for r in caplog.records)
+        finally:
+            await runtime.stop()
+
+    @pytest.mark.asyncio
+    async def test_no_interval_or_cron_warns(self, sample_graph, sample_goal, temp_storage, caplog):
+        """Test that timer with neither cron nor interval_minutes logs a warning."""
+        runtime = AgentRuntime(
+            graph=sample_graph,
+            goal=sample_goal,
+            storage_path=temp_storage,
+        )
+
+        entry_spec = EntryPointSpec(
+            id="timer-empty",
+            name="Empty Timer",
+            entry_node="process-webhook",
+            trigger_type="timer",
+            trigger_config={},
+        )
+        runtime.register_entry_point(entry_spec)
+
+        await runtime.start()
+        try:
+            assert len(runtime._timer_tasks) == 0
+            assert "no 'cron' or valid 'interval_minutes'" in caplog.text
+        finally:
+            await runtime.stop()
+
+    @pytest.mark.asyncio
+    async def test_cron_immediate_fires_first(self, sample_graph, sample_goal, temp_storage):
+        """Test that run_immediately=True with cron doesn't set next_fire before first run."""
+        runtime = AgentRuntime(
+            graph=sample_graph,
+            goal=sample_goal,
+            storage_path=temp_storage,
+        )
+
+        entry_spec = EntryPointSpec(
+            id="timer-cron-immediate",
+            name="Cron Immediate",
+            entry_node="process-webhook",
+            trigger_type="timer",
+            trigger_config={"cron": "0 0 * * *", "run_immediately": True},
+        )
+        runtime.register_entry_point(entry_spec)
+
+        await runtime.start()
+        try:
+            assert len(runtime._timer_tasks) == 1
+            # With run_immediately, the task enters the while loop directly,
+            # so _timer_next_fire is NOT set before the first trigger attempt
+            # (it pops it at the top of the loop)
+            # Give it a moment to start executing
+            await asyncio.sleep(0.05)
+            # Task should still be running (it will try to trigger and likely fail
+            # since there's no LLM, but the task itself continues)
+            assert not runtime._timer_tasks[0].done()
+        finally:
+            await runtime.stop()
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])

core/framework/runtime/tests/test_webhook_server.py

@@ -472,7 +472,7 @@ class TestEventDrivenEntryPoints:
                 id="process-event",
                 name="Process Event",
                 description="Process incoming event",
-                node_type="llm_generate",
+                node_type="event_loop",
                 input_keys=["event"],
                 output_keys=["result"],
             ),

core/framework/server/README.md

@@ -0,0 +1,346 @@
+# Hive Server
+
+HTTP API backend for the Hive agent framework. Built on **aiohttp**, fully async, serving the frontend workspace and external clients.
+
+## Architecture
+
+Sessions are the primary entity. A session owns an EventBus + LLM and always has a queen executor. Workers are optional — they can be loaded into and unloaded from a session at any time.
+
+```
+Session {
+    event_bus       # owned by session, shared with queen + worker
+    llm             # owned by session
+    queen_executor  # always present
+    worker_runtime? # optional — loaded/unloaded independently
+}
+```
+
+## Structure
+
+```
+server/
+├── app.py                 # Application factory, middleware, static serving
+├── session_manager.py     # Session lifecycle (create/load worker/unload/stop)
+├── sse.py                 # Server-Sent Events helper
+├── routes_sessions.py     # Session lifecycle, info, worker-session browsing, discovery
+├── routes_execution.py    # Trigger, inject, chat, stop, resume, replay
+├── routes_events.py       # SSE event streaming
+├── routes_graphs.py       # Graph topology & node inspection
+├── routes_logs.py         # Execution logs (summary/details/tools)
+├── routes_credentials.py  # Credential management & validation
+├── routes_agents.py       # Legacy backward-compat routes
+└── tests/
+    └── test_api.py        # Full test suite with mocked runtimes
+```
+
+## Core Components
+
+### `app.py` — Application Factory
+
+`create_app(model)` builds the aiohttp `Application` with:
+
+- **CORS middleware** — allows localhost origins
+- **Error middleware** — catches exceptions, returns JSON errors
+- **Static serving** — serves the frontend SPA with index.html fallback
+- **Graceful shutdown** — stops all sessions on exit
+
+### `session_manager.py` — Session Lifecycle Manager
+
+Manages `Session` objects. Key methods:
+
+- **`create_session()`** — creates EventBus + LLM, starts queen (no worker)
+- **`create_session_with_worker()`** — one-step: session + worker + judge
+- **`load_worker()`** — loads agent into existing session, starts judge
+- **`unload_worker()`** — removes worker + judge, queen stays alive
+- **`stop_session()`** — tears down everything (worker + queen)
+
+Three-conversation model:
+1. **Queen** — persistent interactive executor for user chat (always present)
+2. **Worker** — `AgentRuntime` that executes graphs (optional)
+3. **Judge** — timer-driven background executor for health monitoring (active when worker is loaded)
+
+### `sse.py` — SSE Helper
+
+Thin wrapper around `aiohttp.StreamResponse` for Server-Sent Events with keepalive pings.
+
+## API Reference
+
+All session-scoped routes use the `session_id` returned from `POST /api/sessions`.
+
+### Discovery
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `GET` | `/api/discover` | Discover agents from filesystem |
+
+Returns agents grouped by category with metadata (name, description, node count, tags, etc.).
+
+### Session Lifecycle
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `POST` | `/api/sessions` | Create a session |
+| `GET` | `/api/sessions` | List all active sessions |
+| `GET` | `/api/sessions/{session_id}` | Session detail (includes entry points + graphs if worker loaded) |
+| `DELETE` | `/api/sessions/{session_id}` | Stop session entirely |
+
+**Create session** has two modes:
+
+```jsonc
+// Queen-only session (no worker)
+POST /api/sessions
+{}
+// or with custom ID:
+{ "session_id": "my-custom-id" }
+
+// Session with worker (one-step)
+POST /api/sessions
+{
+  "agent_path": "exports/my-agent",
+  "agent_id": "custom-worker-name",  // optional
+  "model": "claude-sonnet-4-20250514"      // optional
+}
+```
+
+- Returns `201` with session object on success
+- Returns `409` with `{"loading": true}` if agent is currently loading
+- Returns `404` if agent_path doesn't exist
+
+**Get session** returns `202` with `{"loading": true}` while loading, `404` if not found.
+
+### Worker Lifecycle
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `POST` | `/api/sessions/{session_id}/worker` | Load a worker into session |
+| `DELETE` | `/api/sessions/{session_id}/worker` | Unload worker (queen stays alive) |
+
+```jsonc
+// Load worker into existing session
+POST /api/sessions/{session_id}/worker
+{
+  "agent_path": "exports/my-agent",
+  "worker_id": "custom-name",  // optional
+  "model": "..."               // optional
+}
+
+// Unload worker
+DELETE /api/sessions/{session_id}/worker
+```
+
+### Execution Control
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `POST` | `/api/sessions/{session_id}/trigger` | Start a new execution |
+| `POST` | `/api/sessions/{session_id}/inject` | Inject input into a waiting node |
+| `POST` | `/api/sessions/{session_id}/chat` | Smart chat routing |
+| `POST` | `/api/sessions/{session_id}/stop` | Cancel a running execution |
+| `POST` | `/api/sessions/{session_id}/pause` | Alias for stop |
+| `POST` | `/api/sessions/{session_id}/resume` | Resume a paused execution |
+| `POST` | `/api/sessions/{session_id}/replay` | Re-run from a checkpoint |
+| `GET` | `/api/sessions/{session_id}/goal-progress` | Evaluate goal progress |
+
+**Trigger:**
+```jsonc
+POST /api/sessions/{session_id}/trigger
+{
+  "entry_point_id": "default",
+  "input_data": { "query": "research topic X" },
+  "session_state": {}  // optional
+}
+// Returns: { "execution_id": "..." }
+```
+
+**Chat** routes messages with priority:
+1. Worker awaiting input -> inject into worker node
+2. Queen active -> inject into queen conversation
+3. Neither available -> 503
+
+```jsonc
+POST /api/sessions/{session_id}/chat
+{ "message": "hello" }
+// Returns: { "status": "injected"|"queen", "delivered": true }
+```
+
+**Inject** into a specific node:
+```jsonc
+POST /api/sessions/{session_id}/inject
+{ "node_id": "gather_info", "content": "user response", "graph_id": "main" }
+```
+
+**Stop:**
+```jsonc
+POST /api/sessions/{session_id}/stop
+{ "execution_id": "..." }
+```
+
+**Resume:**
+```jsonc
+POST /api/sessions/{session_id}/resume
+{
+  "session_id": "session_20260224_...",    // worker session to resume
+  "checkpoint_id": "cp_..."               // optional — resumes from latest if omitted
+}
+```
+
+**Replay** (re-run from checkpoint):
+```jsonc
+POST /api/sessions/{session_id}/replay
+{
+  "session_id": "session_20260224_...",
+  "checkpoint_id": "cp_..."               // required
+}
+```
+
+### SSE Event Streaming
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `GET` | `/api/sessions/{session_id}/events` | SSE event stream |
+
+```
+GET /api/sessions/{session_id}/events
+GET /api/sessions/{session_id}/events?types=CLIENT_OUTPUT_DELTA,EXECUTION_COMPLETED
+```
+
+Keepalive ping every 15s. Streams from the session's EventBus (covers both queen and worker events).
+
+Default event types: `CLIENT_OUTPUT_DELTA`, `CLIENT_INPUT_REQUESTED`, `LLM_TEXT_DELTA`, `TOOL_CALL_STARTED`, `TOOL_CALL_COMPLETED`, `EXECUTION_STARTED`, `EXECUTION_COMPLETED`, `EXECUTION_FAILED`, `EXECUTION_PAUSED`, `NODE_LOOP_STARTED`, `NODE_LOOP_ITERATION`, `NODE_LOOP_COMPLETED`, `NODE_ACTION_PLAN`, `EDGE_TRAVERSED`, `GOAL_PROGRESS`, `QUEEN_INTERVENTION_REQUESTED`, `WORKER_ESCALATION_TICKET`, `NODE_INTERNAL_OUTPUT`, `NODE_STALLED`, `NODE_RETRY`, `NODE_TOOL_DOOM_LOOP`, `CONTEXT_COMPACTED`, `WORKER_LOADED`.
+
+### Session Info
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `GET` | `/api/sessions/{session_id}/stats` | Runtime statistics |
+| `GET` | `/api/sessions/{session_id}/entry-points` | List entry points |
+| `GET` | `/api/sessions/{session_id}/graphs` | List loaded graph IDs |
+
+### Graph & Node Inspection
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `GET` | `/api/sessions/{session_id}/graphs/{graph_id}/nodes` | List nodes + edges |
+| `GET` | `/api/sessions/{session_id}/graphs/{graph_id}/nodes/{node_id}` | Node detail + outgoing edges |
+| `GET` | `/api/sessions/{session_id}/graphs/{graph_id}/nodes/{node_id}/criteria` | Success criteria + last execution info |
+| `GET` | `/api/sessions/{session_id}/graphs/{graph_id}/nodes/{node_id}/tools` | Resolved tool metadata |
+
+**List nodes** supports optional enrichment with session progress:
+```
+GET /api/sessions/{session_id}/graphs/{graph_id}/nodes?session_id=worker_session_id
+```
+Adds `visit_count`, `has_failures`, `is_current`, `in_path` to each node.
+
+### Logs
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `GET` | `/api/sessions/{session_id}/logs` | Session-level logs |
+| `GET` | `/api/sessions/{session_id}/graphs/{graph_id}/nodes/{node_id}/logs` | Node-scoped logs |
+
+```
+# List recent runs
+GET /api/sessions/{session_id}/logs?level=summary&limit=20
+
+# Detailed per-node execution for a specific worker session
+GET /api/sessions/{session_id}/logs?session_id=ws_id&level=details
+
+# Tool call logs
+GET /api/sessions/{session_id}/logs?session_id=ws_id&level=tools
+
+# Node-scoped (requires session_id query param)
+GET .../nodes/{node_id}/logs?session_id=ws_id&level=all
+```
+
+Log levels: `summary` (run stats), `details` (per-node execution), `tools` (tool calls + LLM text).
+
+### Worker Session Browsing
+
+Browse persisted execution runs on disk.
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `GET` | `/api/sessions/{session_id}/worker-sessions` | List worker sessions |
+| `GET` | `/api/sessions/{session_id}/worker-sessions/{ws_id}` | Worker session state |
+| `DELETE` | `/api/sessions/{session_id}/worker-sessions/{ws_id}` | Delete worker session |
+| `GET` | `/api/sessions/{session_id}/worker-sessions/{ws_id}/checkpoints` | List checkpoints |
+| `POST` | `/api/sessions/{session_id}/worker-sessions/{ws_id}/checkpoints/{cp_id}/restore` | Restore from checkpoint |
+| `GET` | `/api/sessions/{session_id}/worker-sessions/{ws_id}/messages` | Get conversation messages |
+
+**Messages** support filtering:
+```
+GET .../messages?node_id=gather_info      # filter by node
+GET .../messages?client_only=true         # only user inputs + client-facing assistant outputs
+```
+
+### Credentials
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `GET` | `/api/credentials` | List credential metadata (no secrets) |
+| `POST` | `/api/credentials` | Save a credential |
+| `GET` | `/api/credentials/{credential_id}` | Get credential metadata |
+| `DELETE` | `/api/credentials/{credential_id}` | Delete a credential |
+| `POST` | `/api/credentials/check-agent` | Validate agent credentials |
+
+**Save credential:**
+```jsonc
+POST /api/credentials
+{ "credential_id": "brave_search", "keys": { "api_key": "BSA..." } }
+```
+
+**Check agent credentials** — two-phase validation (same as runtime startup):
+```jsonc
+POST /api/credentials/check-agent
+{
+  "agent_path": "exports/my-agent",
+  "verify": true    // optional, default true — run health checks
+}
+// Returns:
+{
+  "required": [
+    {
+      "credential_name": "brave_search",
+      "credential_id": "brave_search",
+      "env_var": "BRAVE_SEARCH_API_KEY",
+      "description": "Brave Search API key",
+      "help_url": "https://...",
+      "tools": ["brave_web_search"],
+      "node_types": [],
+      "available": true,
+      "valid": true,              // true/false/null (null = not checked)
+      "validation_message": "OK",  // human-readable health check result
+      "direct_api_key_supported": true,
+      "aden_supported": true,
+      "credential_key": "api_key"
+    }
+  ]
+}
+```
+
+When `verify: true`, runs health checks (lightweight HTTP calls) against each available credential to confirm it actually works — not just that it exists.
+
+## Key Patterns
+
+- **Session-primary** — sessions are the lookup key for all routes, workers are optional children
+- **Per-request manager access** — routes get `SessionManager` via `request.app["manager"]`
+- **Path validation** — user-provided path segments validated with `safe_path_segment()` to prevent directory traversal
+- **Event-driven streaming** — per-client buffer queues (max 1000 events) with 15s keepalive pings
+- **Shared EventBus** — session owns the bus, queen and worker both publish to it, SSE always connects to `session.event_bus`
+- **No secrets in responses** — credential endpoints never return secret values
+
+## Storage Paths
+
+```
+~/.hive/
+├── queen/session/{session_id}/       # Queen conversation state
+├── judge/session/{session_id}/       # Judge state
+├── agents/{agent_name}/sessions/     # Worker execution sessions
+└── credentials/                      # Encrypted credential store
+```
+
+## Running Tests
+
+```bash
+pytest framework/server/tests/ -v
+```

core/framework/server/__init__.py

@@ -0,0 +1 @@
+"""HTTP API server for the Hive agent framework."""

core/framework/server/agent_manager.py

@@ -0,0 +1,36 @@
+"""Backward-compatibility shim.
+
+The primary implementation is now in ``session_manager.py``.
+This module re-exports ``SessionManager`` as ``AgentManager`` and
+keeps ``AgentSlot`` for test compatibility.
+"""
+
+import asyncio
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from framework.server.session_manager import Session, SessionManager  # noqa: F401
+
+
+@dataclass
+class AgentSlot:
+    """Legacy data class — kept for test compatibility only.
+
+    New code should use ``Session`` from ``session_manager``.
+    """
+
+    id: str
+    agent_path: Path
+    runner: Any
+    runtime: Any
+    info: Any
+    loaded_at: float
+    queen_executor: Any = None
+    queen_task: asyncio.Task | None = None
+    judge_task: asyncio.Task | None = None
+    escalation_sub: str | None = None
+
+
+# Backward compat alias
+AgentManager = SessionManager

core/framework/server/app.py

@@ -0,0 +1,209 @@
+"""aiohttp Application factory for the Hive HTTP API server."""
+
+import logging
+from pathlib import Path
+
+from aiohttp import web
+
+from framework.server.session_manager import Session, SessionManager
+
+logger = logging.getLogger(__name__)
+
+
+def safe_path_segment(value: str) -> str:
+    """Validate a URL path parameter is a safe filesystem name.
+
+    Raises HTTPBadRequest if the value contains path separators or
+    traversal sequences.  aiohttp decodes ``%2F`` inside route params,
+    so a raw ``{session_id}`` can contain ``/`` or ``..`` after decoding.
+    """
+    if "/" in value or "\\" in value or ".." in value:
+        raise web.HTTPBadRequest(reason="Invalid path parameter")
+    return value
+
+
+def resolve_session(request: web.Request):
+    """Resolve a Session from {session_id} in the URL.
+
+    Returns (session, None) on success or (None, error_response) on failure.
+    """
+    manager: SessionManager = request.app["manager"]
+    sid = request.match_info["session_id"]
+    session = manager.get_session(sid)
+    if not session:
+        return None, web.json_response({"error": f"Session '{sid}' not found"}, status=404)
+    return session, None
+
+
+def sessions_dir(session: Session) -> Path:
+    """Resolve the worker sessions directory for a session.
+
+    Storage layout: ~/.hive/agents/{agent_name}/sessions/
+    Requires a worker to be loaded (worker_path must be set).
+    """
+    if session.worker_path is None:
+        raise ValueError("No worker loaded — no worker sessions directory")
+    agent_name = session.worker_path.name
+    return Path.home() / ".hive" / "agents" / agent_name / "sessions"
+
+
+# Allowed CORS origins (localhost on any port)
+_CORS_ORIGINS = {"http://localhost", "http://127.0.0.1"}
+
+
+def _is_cors_allowed(origin: str) -> bool:
+    """Check if origin is localhost/127.0.0.1 on any port."""
+    if not origin:
+        return False
+    for base in _CORS_ORIGINS:
+        if origin == base or origin.startswith(base + ":"):
+            return True
+    return False
+
+
+@web.middleware
+async def cors_middleware(request: web.Request, handler):
+    """CORS middleware scoped to localhost origins."""
+    origin = request.headers.get("Origin", "")
+
+    # Handle preflight
+    if request.method == "OPTIONS":
+        response = web.Response(status=204)
+    else:
+        try:
+            response = await handler(request)
+        except web.HTTPException as exc:
+            response = exc
+
+    if _is_cors_allowed(origin):
+        response.headers["Access-Control-Allow-Origin"] = origin
+        response.headers["Access-Control-Allow-Methods"] = "GET, POST, DELETE, OPTIONS"
+        response.headers["Access-Control-Allow-Headers"] = "Content-Type"
+        response.headers["Access-Control-Max-Age"] = "3600"
+
+    return response
+
+
+@web.middleware
+async def error_middleware(request: web.Request, handler):
+    """Catch exceptions and return JSON error responses."""
+    try:
+        return await handler(request)
+    except web.HTTPException:
+        raise  # Let aiohttp handle its own HTTP exceptions
+    except Exception as e:
+        logger.exception(f"Unhandled error: {e}")
+        return web.json_response(
+            {"error": str(e), "type": type(e).__name__},
+            status=500,
+        )
+
+
+async def _on_shutdown(app: web.Application) -> None:
+    """Gracefully unload all agents on server shutdown."""
+    manager: SessionManager = app["manager"]
+    await manager.shutdown_all()
+
+
+async def handle_health(request: web.Request) -> web.Response:
+    """GET /api/health — simple health check."""
+    manager: SessionManager = request.app["manager"]
+    sessions = manager.list_sessions()
+    return web.json_response(
+        {
+            "status": "ok",
+            "sessions": len(sessions),
+            "agents_loaded": sum(1 for s in sessions if s.worker_runtime is not None),
+        }
+    )
+
+
+def create_app(model: str | None = None) -> web.Application:
+    """Create and configure the aiohttp Application.
+
+    Args:
+        model: Default LLM model for agent loading.
+
+    Returns:
+        Configured aiohttp Application ready to run.
+    """
+    app = web.Application(middlewares=[cors_middleware, error_middleware])
+
+    # Store manager on app for handlers
+    app["manager"] = SessionManager(model=model)
+
+    # Initialize credential store
+    from framework.credentials.store import CredentialStore
+
+    try:
+        from framework.credentials.validation import ensure_credential_key_env
+
+        ensure_credential_key_env()
+        app["credential_store"] = CredentialStore.with_aden_sync()
+    except Exception:
+        logger.debug("Encrypted credential store unavailable, using in-memory fallback")
+        app["credential_store"] = CredentialStore.for_testing({})
+
+    # Register shutdown hook
+    app.on_shutdown.append(_on_shutdown)
+
+    # Health check
+    app.router.add_get("/api/health", handle_health)
+
+    # Register route modules
+    from framework.server.routes_credentials import register_routes as register_credential_routes
+    from framework.server.routes_events import register_routes as register_event_routes
+    from framework.server.routes_execution import register_routes as register_execution_routes
+    from framework.server.routes_graphs import register_routes as register_graph_routes
+    from framework.server.routes_logs import register_routes as register_log_routes
+    from framework.server.routes_sessions import register_routes as register_session_routes
+
+    register_credential_routes(app)
+    register_execution_routes(app)
+    register_event_routes(app)
+    register_session_routes(app)
+    register_graph_routes(app)
+    register_log_routes(app)
+
+    # Static file serving — Option C production mode
+    # If frontend/dist/ exists, serve built frontend files on /
+    _setup_static_serving(app)
+
+    return app
+
+
+def _setup_static_serving(app: web.Application) -> None:
+    """Serve frontend static files if the dist directory exists."""
+    # Try: CWD/frontend/dist, core/frontend/dist, repo_root/frontend/dist
+    _here = Path(__file__).resolve().parent  # core/framework/server/
+    candidates = [
+        Path("frontend/dist"),
+        _here.parent.parent / "frontend" / "dist",  # core/frontend/dist
+        _here.parent.parent.parent / "frontend" / "dist",  # repo_root/frontend/dist
+    ]
+
+    dist_dir: Path | None = None
+    for candidate in candidates:
+        if candidate.is_dir() and (candidate / "index.html").exists():
+            dist_dir = candidate.resolve()
+            break
+
+    if dist_dir is None:
+        logger.debug("No frontend/dist found — skipping static file serving")
+        return
+
+    logger.info(f"Serving frontend from {dist_dir}")
+
+    async def handle_spa(request: web.Request) -> web.FileResponse:
+        """Serve static files with SPA fallback to index.html."""
+        rel_path = request.match_info.get("path", "")
+        file_path = (dist_dir / rel_path).resolve()
+
+        if file_path.is_file() and file_path.is_relative_to(dist_dir):
+            return web.FileResponse(file_path)
+
+        # SPA fallback
+        return web.FileResponse(dist_dir / "index.html")
+
+    # Catch-all for SPA — must be registered LAST so /api routes take priority
+    app.router.add_get("/{path:.*}", handle_spa)

core/framework/server/routes_credentials.py

@@ -0,0 +1,213 @@
+"""Credential CRUD routes."""
+
+import logging
+
+from aiohttp import web
+from pydantic import SecretStr
+
+from framework.credentials.models import CredentialKey, CredentialObject
+from framework.credentials.store import CredentialStore
+
+logger = logging.getLogger(__name__)
+
+
+def _get_store(request: web.Request) -> CredentialStore:
+    return request.app["credential_store"]
+
+
+def _credential_to_dict(cred: CredentialObject) -> dict:
+    """Serialize a CredentialObject to JSON — never include secret values."""
+    return {
+        "credential_id": cred.id,
+        "credential_type": str(cred.credential_type),
+        "key_names": list(cred.keys.keys()),
+        "created_at": cred.created_at.isoformat() if cred.created_at else None,
+        "updated_at": cred.updated_at.isoformat() if cred.updated_at else None,
+    }
+
+
+async def handle_list_credentials(request: web.Request) -> web.Response:
+    """GET /api/credentials — list all credential metadata (no secrets)."""
+    store = _get_store(request)
+    cred_ids = store.list_credentials()
+    credentials = []
+    for cid in cred_ids:
+        cred = store.get_credential(cid, refresh_if_needed=False)
+        if cred:
+            credentials.append(_credential_to_dict(cred))
+    return web.json_response({"credentials": credentials})
+
+
+async def handle_get_credential(request: web.Request) -> web.Response:
+    """GET /api/credentials/{credential_id} — get single credential metadata."""
+    credential_id = request.match_info["credential_id"]
+    store = _get_store(request)
+    cred = store.get_credential(credential_id, refresh_if_needed=False)
+    if cred is None:
+        return web.json_response({"error": f"Credential '{credential_id}' not found"}, status=404)
+    return web.json_response(_credential_to_dict(cred))
+
+
+async def handle_save_credential(request: web.Request) -> web.Response:
+    """POST /api/credentials — store a credential.
+
+    Body: {"credential_id": "...", "keys": {"key_name": "value", ...}}
+    """
+    store = _get_store(request)
+    body = await request.json()
+
+    credential_id = body.get("credential_id")
+    keys = body.get("keys")
+
+    if not credential_id or not keys or not isinstance(keys, dict):
+        return web.json_response({"error": "credential_id and keys are required"}, status=400)
+
+    cred = CredentialObject(
+        id=credential_id,
+        keys={k: CredentialKey(name=k, value=SecretStr(v)) for k, v in keys.items()},
+    )
+    store.save_credential(cred)
+    return web.json_response({"saved": credential_id}, status=201)
+
+
+async def handle_delete_credential(request: web.Request) -> web.Response:
+    """DELETE /api/credentials/{credential_id} — delete a credential."""
+    credential_id = request.match_info["credential_id"]
+    store = _get_store(request)
+    deleted = store.delete_credential(credential_id)
+    if not deleted:
+        return web.json_response({"error": f"Credential '{credential_id}' not found"}, status=404)
+    return web.json_response({"deleted": True})
+
+
+async def handle_check_agent(request: web.Request) -> web.Response:
+    """POST /api/credentials/check-agent — check and validate agent credentials.
+
+    Uses the same two-phase validation as agent startup:
+    1. Presence — is the credential available (env, encrypted store, Aden)?
+    2. Health check — does the credential actually work (lightweight HTTP call)?
+
+    Body: {"agent_path": "...", "verify": true}
+    """
+    body = await request.json()
+    agent_path = body.get("agent_path")
+    verify = body.get("verify", True)
+
+    if not agent_path:
+        return web.json_response({"error": "agent_path is required"}, status=400)
+
+    try:
+        import os
+
+        from framework.credentials.setup import CredentialSetupSession
+        from framework.credentials.storage import CompositeStorage, EncryptedFileStorage, EnvVarStorage
+        from framework.credentials.validation import _presync_aden_tokens, ensure_credential_key_env
+
+        # Load env vars from shell config (same as runtime startup)
+        ensure_credential_key_env()
+
+        # Build a proper store with env + encrypted storage (same as validate_agent_credentials)
+        try:
+            from aden_tools.credentials import CREDENTIAL_SPECS
+        except ImportError:
+            CREDENTIAL_SPECS = {}
+
+        if os.environ.get("ADEN_API_KEY") and CREDENTIAL_SPECS:
+            _presync_aden_tokens(CREDENTIAL_SPECS)
+
+        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)
+
+        # Detect required credentials from agent graph
+        session = CredentialSetupSession.from_agent_path(agent_path, missing_only=False)
+
+        # Health check function (may not be available)
+        check_health = None
+        if verify:
+            try:
+                from aden_tools.credentials import check_credential_health
+                check_health = check_credential_health
+            except ImportError:
+                pass
+
+        required = []
+        for mc in session.missing:
+            cred_id = mc.credential_id or mc.credential_name
+            available = store.is_available(cred_id)
+
+            entry = {
+                "credential_name": mc.credential_name,
+                "credential_id": cred_id,
+                "env_var": mc.env_var,
+                "description": mc.description,
+                "help_url": mc.help_url,
+                "tools": mc.tools,
+                "node_types": mc.node_types,
+                "available": available,
+                "direct_api_key_supported": mc.direct_api_key_supported,
+                "aden_supported": mc.aden_supported,
+                "credential_key": mc.credential_key,
+                "valid": None,  # null = not checked
+                "validation_message": None,
+            }
+
+            # Phase 2: health check for available credentials
+            if available and verify and check_health:
+                spec = CREDENTIAL_SPECS.get(mc.credential_name)
+                if spec and spec.health_check_endpoint:
+                    value = store.get(cred_id)
+                    if value:
+                        try:
+                            result = check_health(
+                                mc.credential_name,
+                                value,
+                                health_check_endpoint=spec.health_check_endpoint,
+                                health_check_method=spec.health_check_method,
+                            )
+                            entry["valid"] = result.valid
+                            entry["validation_message"] = result.message
+                        except Exception as exc:
+                            entry["valid"] = False
+                            entry["validation_message"] = f"Health check error: {exc}"
+
+            required.append(entry)
+
+        # Determine overall status
+        any_missing = any(not r["available"] for r in required)
+        any_invalid = any(r["valid"] is False for r in required)
+        all_valid = not any_missing and not any_invalid
+
+        response = {"required": required, "all_valid": all_valid}
+        if any_missing or any_invalid:
+            reasons = []
+            if any_missing:
+                names = [r["credential_name"] for r in required if not r["available"]]
+                reasons.append(f"missing: {', '.join(names)}")
+            if any_invalid:
+                names = [r["credential_name"] for r in required if r["valid"] is False]
+                reasons.append(f"invalid: {', '.join(names)}")
+            response["error"] = "; ".join(reasons)
+            return web.json_response(response, status=424)
+
+        return web.json_response(response)
+    except Exception as e:
+        logger.exception(f"Error checking agent credentials: {e}")
+        return web.json_response({"error": str(e)}, status=500)
+
+
+def register_routes(app: web.Application) -> None:
+    """Register credential routes on the application."""
+    # check-agent must be registered BEFORE the {credential_id} wildcard
+    app.router.add_post("/api/credentials/check-agent", handle_check_agent)
+    app.router.add_get("/api/credentials", handle_list_credentials)
+    app.router.add_post("/api/credentials", handle_save_credential)
+    app.router.add_get("/api/credentials/{credential_id}", handle_get_credential)
+    app.router.add_delete("/api/credentials/{credential_id}", handle_delete_credential)

core/framework/server/routes_events.py

@@ -0,0 +1,123 @@
+"""SSE event streaming route."""
+
+import asyncio
+import logging
+
+from aiohttp import web
+
+from framework.runtime.event_bus import EventType
+from framework.server.app import resolve_session
+
+logger = logging.getLogger(__name__)
+
+# Default event types streamed to clients
+DEFAULT_EVENT_TYPES = [
+    EventType.CLIENT_OUTPUT_DELTA,
+    EventType.CLIENT_INPUT_REQUESTED,
+    EventType.LLM_TEXT_DELTA,
+    EventType.TOOL_CALL_STARTED,
+    EventType.TOOL_CALL_COMPLETED,
+    EventType.EXECUTION_STARTED,
+    EventType.EXECUTION_COMPLETED,
+    EventType.EXECUTION_FAILED,
+    EventType.EXECUTION_PAUSED,
+    EventType.NODE_LOOP_STARTED,
+    EventType.NODE_LOOP_ITERATION,
+    EventType.NODE_LOOP_COMPLETED,
+    EventType.NODE_ACTION_PLAN,
+    EventType.EDGE_TRAVERSED,
+    EventType.GOAL_PROGRESS,
+    EventType.QUEEN_INTERVENTION_REQUESTED,
+    EventType.WORKER_ESCALATION_TICKET,
+    EventType.NODE_INTERNAL_OUTPUT,
+    EventType.NODE_STALLED,
+    EventType.NODE_RETRY,
+    EventType.NODE_TOOL_DOOM_LOOP,
+    EventType.CONTEXT_COMPACTED,
+    EventType.WORKER_LOADED,
+]
+
+# Keepalive interval in seconds
+KEEPALIVE_INTERVAL = 15.0
+
+
+def _parse_event_types(query_param: str | None) -> list[EventType]:
+    """Parse comma-separated event type names into EventType values.
+
+    Falls back to DEFAULT_EVENT_TYPES if param is empty or invalid.
+    """
+    if not query_param:
+        return DEFAULT_EVENT_TYPES
+
+    result = []
+    for name in query_param.split(","):
+        name = name.strip()
+        try:
+            result.append(EventType(name))
+        except ValueError:
+            logger.warning(f"Unknown event type filter: {name}")
+
+    return result or DEFAULT_EVENT_TYPES
+
+
+async def handle_events(request: web.Request) -> web.StreamResponse:
+    """SSE event stream for a session.
+
+    Query params:
+        types: Comma-separated event type names to filter (optional).
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    # Session always has an event_bus — no runtime guard needed
+    event_bus = session.event_bus
+    event_types = _parse_event_types(request.query.get("types"))
+
+    # Per-client buffer queue
+    queue: asyncio.Queue = asyncio.Queue(maxsize=1000)
+
+    async def on_event(event) -> None:
+        """Push event dict into queue; drop if full."""
+        try:
+            queue.put_nowait(event.to_dict())
+        except asyncio.QueueFull:
+            pass  # Drop oldest-undelivered; client will catch up
+
+    # Subscribe to EventBus
+    from framework.server.sse import SSEResponse
+
+    sub_id = event_bus.subscribe(
+        event_types=event_types,
+        handler=on_event,
+    )
+
+    sse = SSEResponse()
+    await sse.prepare(request)
+
+    try:
+        while True:
+            try:
+                data = await asyncio.wait_for(queue.get(), timeout=KEEPALIVE_INTERVAL)
+                await sse.send_event(data)
+            except TimeoutError:
+                await sse.send_keepalive()
+            except (ConnectionResetError, ConnectionError):
+                break
+            except RuntimeError as exc:
+                if "closing transport" in str(exc).lower():
+                    break
+                raise
+    except asyncio.CancelledError:
+        pass
+    finally:
+        event_bus.unsubscribe(sub_id)
+        logger.debug("SSE client disconnected from session '%s'", session.id)
+
+    return sse.response
+
+
+def register_routes(app: web.Application) -> None:
+    """Register SSE event streaming routes."""
+    # Session-primary route
+    app.router.add_get("/api/sessions/{session_id}/events", handle_events)

core/framework/server/routes_execution.py

@@ -0,0 +1,305 @@
+"""Execution control routes — trigger, inject, chat, resume, stop, replay."""
+
+import json
+import logging
+
+from aiohttp import web
+
+from framework.server.app import resolve_session, safe_path_segment, sessions_dir
+
+logger = logging.getLogger(__name__)
+
+
+async def handle_trigger(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/trigger — start an execution.
+
+    Body: {"entry_point_id": "default", "input_data": {...}, "session_state": {...}?}
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    body = await request.json()
+    entry_point_id = body.get("entry_point_id", "default")
+    input_data = body.get("input_data", {})
+    session_state = body.get("session_state") or {}
+
+    # Scope the worker execution to the live session ID
+    if "resume_session_id" not in session_state:
+        session_state["resume_session_id"] = session.id
+
+    execution_id = await session.worker_runtime.trigger(
+        entry_point_id,
+        input_data,
+        session_state=session_state,
+    )
+
+    return web.json_response({"execution_id": execution_id})
+
+
+async def handle_inject(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/inject — inject input into a waiting node.
+
+    Body: {"node_id": "...", "content": "...", "graph_id": "..."}
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    body = await request.json()
+    node_id = body.get("node_id")
+    content = body.get("content", "")
+    graph_id = body.get("graph_id")
+
+    if not node_id:
+        return web.json_response({"error": "node_id is required"}, status=400)
+
+    delivered = await session.worker_runtime.inject_input(node_id, content, graph_id=graph_id)
+    return web.json_response({"delivered": delivered})
+
+
+async def handle_chat(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/chat — convenience endpoint.
+
+    Routing priority:
+    1. Worker awaiting input → inject into worker node
+    2. Queen active → inject into queen conversation
+    3. Error — no handler available
+
+    Body: {"message": "hello"}
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    body = await request.json()
+    message = body.get("message", "")
+
+    if not message:
+        return web.json_response({"error": "message is required"}, status=400)
+
+    # 1. Check if worker is awaiting input → inject to worker
+    if session.worker_runtime:
+        node_id, graph_id = session.worker_runtime.find_awaiting_node()
+
+        if node_id:
+            delivered = await session.worker_runtime.inject_input(
+                node_id,
+                message,
+                graph_id=graph_id,
+                is_client_input=True,
+            )
+            return web.json_response(
+                {
+                    "status": "injected",
+                    "node_id": node_id,
+                    "delivered": delivered,
+                }
+            )
+
+    # 2. Queen active → inject into queen conversation
+    queen_executor = session.queen_executor
+    if queen_executor is not None:
+        node = queen_executor.node_registry.get("queen")
+        if node is not None and hasattr(node, "inject_event"):
+            await node.inject_event(message, is_client_input=True)
+            return web.json_response(
+                {
+                    "status": "queen",
+                    "delivered": True,
+                }
+            )
+
+    # 3. No queen or worker available
+    return web.json_response({"error": "No worker or queen available"}, status=503)
+
+
+async def handle_goal_progress(request: web.Request) -> web.Response:
+    """GET /api/sessions/{session_id}/goal-progress — evaluate goal progress."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    progress = await session.worker_runtime.get_goal_progress()
+    return web.json_response(progress, dumps=lambda obj: json.dumps(obj, default=str))
+
+
+async def handle_resume(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/resume — resume a paused execution.
+
+    Body: {"session_id": "...", "checkpoint_id": "..." (optional)}
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    body = await request.json()
+    worker_session_id = body.get("session_id")
+    checkpoint_id = body.get("checkpoint_id")
+
+    if not worker_session_id:
+        return web.json_response({"error": "session_id is required"}, status=400)
+
+    worker_session_id = safe_path_segment(worker_session_id)
+    if checkpoint_id:
+        checkpoint_id = safe_path_segment(checkpoint_id)
+
+    # Read session state
+    session_dir = sessions_dir(session) / worker_session_id
+    state_path = session_dir / "state.json"
+    if not state_path.exists():
+        return web.json_response({"error": "Session not found"}, status=404)
+
+    try:
+        state = json.loads(state_path.read_text())
+    except (json.JSONDecodeError, OSError) as e:
+        return web.json_response({"error": f"Failed to read session: {e}"}, status=500)
+
+    if checkpoint_id:
+        resume_session_state = {
+            "resume_session_id": worker_session_id,
+            "resume_from_checkpoint": checkpoint_id,
+        }
+    else:
+        progress = state.get("progress", {})
+        paused_at = progress.get("paused_at") or progress.get("resume_from")
+        resume_session_state = {
+            "resume_session_id": worker_session_id,
+            "memory": state.get("memory", {}),
+            "execution_path": progress.get("path", []),
+            "node_visit_counts": progress.get("node_visit_counts", {}),
+        }
+        if paused_at:
+            resume_session_state["paused_at"] = paused_at
+
+    entry_points = session.worker_runtime.get_entry_points()
+    if not entry_points:
+        return web.json_response({"error": "No entry points available"}, status=400)
+
+    input_data = state.get("input_data", {})
+
+    execution_id = await session.worker_runtime.trigger(
+        entry_points[0].id,
+        input_data=input_data,
+        session_state=resume_session_state,
+    )
+
+    return web.json_response(
+        {
+            "execution_id": execution_id,
+            "resumed_from": worker_session_id,
+            "checkpoint_id": checkpoint_id,
+        }
+    )
+
+
+async def handle_stop(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/stop — cancel a running execution.
+
+    Body: {"execution_id": "..."}
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    body = await request.json()
+    execution_id = body.get("execution_id")
+
+    if not execution_id:
+        return web.json_response({"error": "execution_id is required"}, status=400)
+
+    for graph_id in session.worker_runtime.list_graphs():
+        reg = session.worker_runtime.get_graph_registration(graph_id)
+        if reg is None:
+            continue
+        for _ep_id, stream in reg.streams.items():
+            cancelled = await stream.cancel_execution(execution_id)
+            if cancelled:
+                return web.json_response(
+                    {
+                        "stopped": True,
+                        "execution_id": execution_id,
+                    }
+                )
+
+    return web.json_response({"stopped": False, "error": "Execution not found"}, status=404)
+
+
+async def handle_replay(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/replay — re-run from a checkpoint.
+
+    Body: {"session_id": "...", "checkpoint_id": "..."}
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    body = await request.json()
+    worker_session_id = body.get("session_id")
+    checkpoint_id = body.get("checkpoint_id")
+
+    if not worker_session_id:
+        return web.json_response({"error": "session_id is required"}, status=400)
+    if not checkpoint_id:
+        return web.json_response({"error": "checkpoint_id is required"}, status=400)
+
+    worker_session_id = safe_path_segment(worker_session_id)
+    checkpoint_id = safe_path_segment(checkpoint_id)
+
+    cp_path = sessions_dir(session) / worker_session_id / "checkpoints" / f"{checkpoint_id}.json"
+    if not cp_path.exists():
+        return web.json_response({"error": "Checkpoint not found"}, status=404)
+
+    entry_points = session.worker_runtime.get_entry_points()
+    if not entry_points:
+        return web.json_response({"error": "No entry points available"}, status=400)
+
+    replay_session_state = {
+        "resume_session_id": worker_session_id,
+        "resume_from_checkpoint": checkpoint_id,
+    }
+
+    execution_id = await session.worker_runtime.trigger(
+        entry_points[0].id,
+        input_data={},
+        session_state=replay_session_state,
+    )
+
+    return web.json_response(
+        {
+            "execution_id": execution_id,
+            "replayed_from": worker_session_id,
+            "checkpoint_id": checkpoint_id,
+        }
+    )
+
+
+def register_routes(app: web.Application) -> None:
+    """Register execution control routes."""
+    # Session-primary routes
+    app.router.add_post("/api/sessions/{session_id}/trigger", handle_trigger)
+    app.router.add_post("/api/sessions/{session_id}/inject", handle_inject)
+    app.router.add_post("/api/sessions/{session_id}/chat", handle_chat)
+    app.router.add_post("/api/sessions/{session_id}/pause", handle_stop)
+    app.router.add_post("/api/sessions/{session_id}/resume", handle_resume)
+    app.router.add_post("/api/sessions/{session_id}/stop", handle_stop)
+    app.router.add_post("/api/sessions/{session_id}/replay", handle_replay)
+    app.router.add_get("/api/sessions/{session_id}/goal-progress", handle_goal_progress)

core/framework/server/routes_graphs.py

@@ -0,0 +1,224 @@
+"""Graph and node inspection routes — node list, node detail, node criteria."""
+
+import json
+import logging
+
+from aiohttp import web
+
+from framework.server.app import resolve_session, safe_path_segment
+
+logger = logging.getLogger(__name__)
+
+
+def _get_graph_spec(session, graph_id: str):
+    """Get GraphSpec for a graph_id. Returns (graph_spec, None) or (None, error_response)."""
+    if not session.worker_runtime:
+        return None, web.json_response({"error": "No worker loaded in this session"}, status=503)
+    reg = session.worker_runtime.get_graph_registration(graph_id)
+    if reg is None:
+        return None, web.json_response({"error": f"Graph '{graph_id}' not found"}, status=404)
+    return reg.graph, None
+
+
+def _node_to_dict(node) -> dict:
+    """Serialize a NodeSpec to a JSON-friendly dict."""
+    return {
+        "id": node.id,
+        "name": node.name,
+        "description": node.description,
+        "node_type": node.node_type,
+        "input_keys": node.input_keys,
+        "output_keys": node.output_keys,
+        "nullable_output_keys": node.nullable_output_keys,
+        "tools": node.tools,
+        "routes": node.routes,
+        "max_retries": node.max_retries,
+        "max_node_visits": node.max_node_visits,
+        "client_facing": node.client_facing,
+        "success_criteria": node.success_criteria,
+        "system_prompt": node.system_prompt or "",
+    }
+
+
+async def handle_list_nodes(request: web.Request) -> web.Response:
+    """List nodes in a graph."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    graph_id = request.match_info["graph_id"]
+    graph, err = _get_graph_spec(session, graph_id)
+    if err:
+        return err
+
+    nodes = [_node_to_dict(n) for n in graph.nodes]
+
+    # Optionally enrich with session progress
+    worker_session_id = request.query.get("session_id")
+    if worker_session_id and session.worker_path:
+        worker_session_id = safe_path_segment(worker_session_id)
+        from pathlib import Path
+
+        state_path = (
+            Path.home()
+            / ".hive"
+            / "agents"
+            / session.worker_path.name
+            / "sessions"
+            / worker_session_id
+            / "state.json"
+        )
+        if state_path.exists():
+            try:
+                state = json.loads(state_path.read_text())
+                progress = state.get("progress", {})
+                visit_counts = progress.get("node_visit_counts", {})
+                failures = progress.get("nodes_with_failures", [])
+                current = progress.get("current_node")
+                path = progress.get("path", [])
+
+                for node in nodes:
+                    nid = node["id"]
+                    node["visit_count"] = visit_counts.get(nid, 0)
+                    node["has_failures"] = nid in failures
+                    node["is_current"] = nid == current
+                    node["in_path"] = nid in path
+            except (json.JSONDecodeError, OSError):
+                pass
+
+    edges = [
+        {"source": e.source, "target": e.target, "condition": e.condition, "priority": e.priority}
+        for e in graph.edges
+    ]
+    return web.json_response(
+        {
+            "nodes": nodes,
+            "edges": edges,
+            "entry_node": graph.entry_node,
+        }
+    )
+
+
+async def handle_get_node(request: web.Request) -> web.Response:
+    """Get node detail."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    graph_id = request.match_info["graph_id"]
+    node_id = request.match_info["node_id"]
+
+    graph, err = _get_graph_spec(session, graph_id)
+    if err:
+        return err
+
+    node_spec = graph.get_node(node_id)
+    if node_spec is None:
+        return web.json_response({"error": f"Node '{node_id}' not found"}, status=404)
+
+    data = _node_to_dict(node_spec)
+    edges = [
+        {"target": e.target, "condition": e.condition, "priority": e.priority}
+        for e in graph.edges
+        if e.source == node_id
+    ]
+    data["edges"] = edges
+
+    return web.json_response(data)
+
+
+async def handle_node_criteria(request: web.Request) -> web.Response:
+    """Get node success criteria and last execution info."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    graph_id = request.match_info["graph_id"]
+    node_id = request.match_info["node_id"]
+
+    graph, err = _get_graph_spec(session, graph_id)
+    if err:
+        return err
+
+    node_spec = graph.get_node(node_id)
+    if node_spec is None:
+        return web.json_response({"error": f"Node '{node_id}' not found"}, status=404)
+
+    result: dict = {
+        "node_id": node_id,
+        "success_criteria": node_spec.success_criteria,
+        "output_keys": node_spec.output_keys,
+    }
+
+    worker_session_id = request.query.get("session_id")
+    if worker_session_id and session.worker_runtime:
+        log_store = getattr(session.worker_runtime, "_runtime_log_store", None)
+        if log_store:
+            details = await log_store.load_details(worker_session_id)
+            if details:
+                node_details = [n for n in details.nodes if n.node_id == node_id]
+                if node_details:
+                    latest = node_details[-1]
+                    result["last_execution"] = {
+                        "success": latest.success,
+                        "error": latest.error,
+                        "retry_count": latest.retry_count,
+                        "needs_attention": latest.needs_attention,
+                        "attention_reasons": latest.attention_reasons,
+                    }
+
+    return web.json_response(result, dumps=lambda obj: json.dumps(obj, default=str))
+
+
+async def handle_node_tools(request: web.Request) -> web.Response:
+    """Get tools available to a node."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    graph_id = request.match_info["graph_id"]
+    node_id = request.match_info["node_id"]
+
+    graph, err = _get_graph_spec(session, graph_id)
+    if err:
+        return err
+
+    node_spec = graph.get_node(node_id)
+    if node_spec is None:
+        return web.json_response({"error": f"Node '{node_id}' not found"}, status=404)
+
+    tools_out = []
+    registry = getattr(session.runner, "_tool_registry", None) if session.runner else None
+    all_tools = registry.get_tools() if registry else {}
+
+    for name in node_spec.tools:
+        tool = all_tools.get(name)
+        if tool:
+            tools_out.append(
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": tool.parameters,
+                }
+            )
+        else:
+            tools_out.append({"name": name, "description": "", "parameters": {}})
+
+    return web.json_response({"tools": tools_out})
+
+
+def register_routes(app: web.Application) -> None:
+    """Register graph/node inspection routes."""
+    # Session-primary routes
+    app.router.add_get("/api/sessions/{session_id}/graphs/{graph_id}/nodes", handle_list_nodes)
+    app.router.add_get(
+        "/api/sessions/{session_id}/graphs/{graph_id}/nodes/{node_id}", handle_get_node
+    )
+    app.router.add_get(
+        "/api/sessions/{session_id}/graphs/{graph_id}/nodes/{node_id}/criteria",
+        handle_node_criteria,
+    )
+    app.router.add_get(
+        "/api/sessions/{session_id}/graphs/{graph_id}/nodes/{node_id}/tools",
+        handle_node_tools,
+    )

core/framework/server/routes_logs.py

@@ -0,0 +1,114 @@
+"""Log and observability routes — agent logs, node-scoped logs."""
+
+import json
+import logging
+
+from aiohttp import web
+
+from framework.server.app import resolve_session
+
+logger = logging.getLogger(__name__)
+
+
+async def handle_logs(request: web.Request) -> web.Response:
+    """Session-level logs.
+
+    Query params:
+        session_id: Scope to a specific worker session (optional).
+        level: "summary" | "details" | "tools" (default: "summary").
+        limit: Max results when listing summaries (default: 20).
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    log_store = getattr(session.worker_runtime, "_runtime_log_store", None)
+    if log_store is None:
+        return web.json_response({"error": "Logging not enabled for this agent"}, status=404)
+
+    worker_session_id = request.query.get("session_id")
+    level = request.query.get("level", "summary")
+    try:
+        limit = min(int(request.query.get("limit", "20")), 1000)
+    except (ValueError, TypeError):
+        limit = 20
+
+    if not worker_session_id:
+        summaries = await log_store.list_runs(limit=limit)
+        return web.json_response(
+            {"logs": [s.model_dump() for s in summaries]},
+            dumps=lambda obj: json.dumps(obj, default=str),
+        )
+
+    if level == "details":
+        details = await log_store.load_details(worker_session_id)
+        if details is None:
+            return web.json_response({"error": "No detail logs found"}, status=404)
+        return web.json_response(
+            {"session_id": worker_session_id, "nodes": [n.model_dump() for n in details.nodes]},
+            dumps=lambda obj: json.dumps(obj, default=str),
+        )
+    elif level == "tools":
+        tool_logs = await log_store.load_tool_logs(worker_session_id)
+        if tool_logs is None:
+            return web.json_response({"error": "No tool logs found"}, status=404)
+        return web.json_response(
+            {"session_id": worker_session_id, "steps": [s.model_dump() for s in tool_logs.steps]},
+            dumps=lambda obj: json.dumps(obj, default=str),
+        )
+    else:
+        summary = await log_store.load_summary(worker_session_id)
+        if summary is None:
+            return web.json_response({"error": "No summary log found"}, status=404)
+        return web.json_response(
+            summary.model_dump(),
+            dumps=lambda obj: json.dumps(obj, default=str),
+        )
+
+
+async def handle_node_logs(request: web.Request) -> web.Response:
+    """Node-scoped logs."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    node_id = request.match_info["node_id"]
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    log_store = getattr(session.worker_runtime, "_runtime_log_store", None)
+    if log_store is None:
+        return web.json_response({"error": "Logging not enabled"}, status=404)
+
+    worker_session_id = request.query.get("session_id")
+    if not worker_session_id:
+        return web.json_response({"error": "session_id query param is required"}, status=400)
+
+    level = request.query.get("level", "all")
+    result: dict = {"session_id": worker_session_id, "node_id": node_id}
+
+    if level in ("details", "all"):
+        details = await log_store.load_details(worker_session_id)
+        if details:
+            result["details"] = [n.model_dump() for n in details.nodes if n.node_id == node_id]
+
+    if level in ("tools", "all"):
+        tool_logs = await log_store.load_tool_logs(worker_session_id)
+        if tool_logs:
+            result["tool_logs"] = [s.model_dump() for s in tool_logs.steps if s.node_id == node_id]
+
+    return web.json_response(result, dumps=lambda obj: json.dumps(obj, default=str))
+
+
+def register_routes(app: web.Application) -> None:
+    """Register log routes."""
+    # Session-primary routes
+    app.router.add_get("/api/sessions/{session_id}/logs", handle_logs)
+    app.router.add_get(
+        "/api/sessions/{session_id}/graphs/{graph_id}/nodes/{node_id}/logs",
+        handle_node_logs,
+    )

core/framework/server/routes_sessions.py

@@ -0,0 +1,613 @@
+"""Session lifecycle, info, and worker-session browsing routes.
+
+Session-primary routes:
+- POST   /api/sessions                               — create session (with or without worker)
+- GET    /api/sessions                               — list all active sessions
+- GET    /api/sessions/{session_id}                  — session detail
+- DELETE /api/sessions/{session_id}                  — stop session entirely
+- POST   /api/sessions/{session_id}/worker           — load a worker into session
+- DELETE /api/sessions/{session_id}/worker           — unload worker from session
+- GET    /api/sessions/{session_id}/stats            — runtime statistics
+- GET    /api/sessions/{session_id}/entry-points     — list entry points
+- GET    /api/sessions/{session_id}/graphs           — list graph IDs
+
+Worker session browsing (persisted execution runs on disk):
+- GET    /api/sessions/{session_id}/worker-sessions                             — list
+- GET    /api/sessions/{session_id}/worker-sessions/{ws_id}                     — detail
+- DELETE /api/sessions/{session_id}/worker-sessions/{ws_id}                     — delete
+- GET    /api/sessions/{session_id}/worker-sessions/{ws_id}/checkpoints         — list CPs
+- POST   /api/sessions/{session_id}/worker-sessions/{ws_id}/checkpoints/{cp}/restore
+- GET    /api/sessions/{session_id}/worker-sessions/{ws_id}/messages            — messages
+
+"""
+
+import json
+import logging
+import shutil
+import time
+from pathlib import Path
+
+from aiohttp import web
+
+from framework.server.app import resolve_session, safe_path_segment, sessions_dir
+from framework.server.session_manager import SessionManager
+
+logger = logging.getLogger(__name__)
+
+
+def _get_manager(request: web.Request) -> SessionManager:
+    return request.app["manager"]
+
+
+def _session_to_live_dict(session) -> dict:
+    """Serialize a live Session to the session-primary JSON shape."""
+    info = session.worker_info
+    return {
+        "session_id": session.id,
+        "worker_id": session.worker_id,
+        "worker_name": info.name if info else session.worker_id,
+        "has_worker": session.worker_runtime is not None,
+        "agent_path": str(session.worker_path) if session.worker_path else "",
+        "description": info.description if info else "",
+        "goal": info.goal_name if info else "",
+        "node_count": info.node_count if info else 0,
+        "loaded_at": session.loaded_at,
+        "uptime_seconds": round(time.time() - session.loaded_at, 1),
+        "intro_message": getattr(session.runner, "intro_message", "") or "",
+    }
+
+
+# ------------------------------------------------------------------
+# Session lifecycle
+# ------------------------------------------------------------------
+
+
+async def handle_create_session(request: web.Request) -> web.Response:
+    """POST /api/sessions — create a session.
+
+    Body: {
+        "agent_path": "..." (optional — if provided, creates session with worker),
+        "agent_id": "..." (optional — worker ID override),
+        "session_id": "..." (optional — custom session ID),
+        "model": "..." (optional),
+    }
+
+    When agent_path is provided, creates a session with a worker in one step
+    (equivalent to the old POST /api/agents). Otherwise creates a queen-only
+    session that can later have a worker loaded via POST /sessions/{id}/worker.
+    """
+    manager = _get_manager(request)
+    body = await request.json() if request.can_read_body else {}
+    agent_path = body.get("agent_path")
+    agent_id = body.get("agent_id")
+    session_id = body.get("session_id")
+    model = body.get("model")
+
+    try:
+        if agent_path:
+            # One-step: create session + load worker
+            session = await manager.create_session_with_worker(
+                agent_path,
+                agent_id=agent_id,
+                model=model,
+            )
+        else:
+            # Queen-only session
+            session = await manager.create_session(
+                session_id=session_id,
+                model=model,
+            )
+    except ValueError as e:
+        msg = str(e)
+        if "currently loading" in msg:
+            resolved_id = agent_id or (Path(agent_path).name if agent_path else "")
+            return web.json_response(
+                {"error": msg, "worker_id": resolved_id, "loading": True},
+                status=409,
+            )
+        return web.json_response({"error": msg}, status=409)
+    except FileNotFoundError as e:
+        return web.json_response({"error": str(e)}, status=404)
+    except Exception as e:
+        logger.exception("Error creating session: %s", e)
+        return web.json_response({"error": str(e)}, status=500)
+
+    return web.json_response(_session_to_live_dict(session), status=201)
+
+
+async def handle_list_live_sessions(request: web.Request) -> web.Response:
+    """GET /api/sessions — list all active sessions."""
+    manager = _get_manager(request)
+    sessions = [_session_to_live_dict(s) for s in manager.list_sessions()]
+    return web.json_response({"sessions": sessions})
+
+
+async def handle_get_live_session(request: web.Request) -> web.Response:
+    """GET /api/sessions/{session_id} — get session detail."""
+    manager = _get_manager(request)
+    session_id = request.match_info["session_id"]
+    session = manager.get_session(session_id)
+
+    if session is None:
+        if manager.is_loading(session_id):
+            return web.json_response(
+                {"session_id": session_id, "loading": True},
+                status=202,
+            )
+        return web.json_response(
+            {"error": f"Session '{session_id}' not found"},
+            status=404,
+        )
+
+    data = _session_to_live_dict(session)
+
+    if session.worker_runtime:
+        data["entry_points"] = [
+            {
+                "id": ep.id,
+                "name": ep.name,
+                "entry_node": ep.entry_node,
+                "trigger_type": ep.trigger_type,
+            }
+            for ep in session.worker_runtime.get_entry_points()
+        ]
+        data["graphs"] = session.worker_runtime.list_graphs()
+
+    return web.json_response(data)
+
+
+async def handle_stop_session(request: web.Request) -> web.Response:
+    """DELETE /api/sessions/{session_id} — stop a session entirely."""
+    manager = _get_manager(request)
+    session_id = request.match_info["session_id"]
+
+    stopped = await manager.stop_session(session_id)
+    if not stopped:
+        return web.json_response(
+            {"error": f"Session '{session_id}' not found"},
+            status=404,
+        )
+
+    return web.json_response({"session_id": session_id, "stopped": True})
+
+
+# ------------------------------------------------------------------
+# Worker lifecycle
+# ------------------------------------------------------------------
+
+
+async def handle_load_worker(request: web.Request) -> web.Response:
+    """POST /api/sessions/{session_id}/worker — load a worker into a session.
+
+    Body: {"agent_path": "...", "worker_id": "..." (optional), "model": "..." (optional)}
+    """
+    manager = _get_manager(request)
+    session_id = request.match_info["session_id"]
+    body = await request.json()
+
+    agent_path = body.get("agent_path")
+    if not agent_path:
+        return web.json_response({"error": "agent_path is required"}, status=400)
+
+    worker_id = body.get("worker_id")
+    model = body.get("model")
+
+    try:
+        session = await manager.load_worker(
+            session_id,
+            agent_path,
+            worker_id=worker_id,
+            model=model,
+        )
+    except ValueError as e:
+        return web.json_response({"error": str(e)}, status=409)
+    except FileNotFoundError as e:
+        return web.json_response({"error": str(e)}, status=404)
+    except Exception as e:
+        logger.exception("Error loading worker: %s", e)
+        return web.json_response({"error": str(e)}, status=500)
+
+    return web.json_response(_session_to_live_dict(session))
+
+
+async def handle_unload_worker(request: web.Request) -> web.Response:
+    """DELETE /api/sessions/{session_id}/worker — unload worker, keep queen alive."""
+    manager = _get_manager(request)
+    session_id = request.match_info["session_id"]
+
+    removed = await manager.unload_worker(session_id)
+    if not removed:
+        session = manager.get_session(session_id)
+        if session is None:
+            return web.json_response(
+                {"error": f"Session '{session_id}' not found"},
+                status=404,
+            )
+        return web.json_response(
+            {"error": "No worker loaded in this session"},
+            status=409,
+        )
+
+    return web.json_response({"session_id": session_id, "worker_unloaded": True})
+
+
+# ------------------------------------------------------------------
+# Session info (worker details)
+# ------------------------------------------------------------------
+
+
+async def handle_session_stats(request: web.Request) -> web.Response:
+    """GET /api/sessions/{session_id}/stats — runtime statistics."""
+    manager = _get_manager(request)
+    session_id = request.match_info["session_id"]
+    session = manager.get_session(session_id)
+
+    if session is None:
+        return web.json_response(
+            {"error": f"Session '{session_id}' not found"},
+            status=404,
+        )
+
+    stats = session.worker_runtime.get_stats() if session.worker_runtime else {}
+    return web.json_response(stats)
+
+
+async def handle_session_entry_points(request: web.Request) -> web.Response:
+    """GET /api/sessions/{session_id}/entry-points — list entry points."""
+    manager = _get_manager(request)
+    session_id = request.match_info["session_id"]
+    session = manager.get_session(session_id)
+
+    if session is None:
+        return web.json_response(
+            {"error": f"Session '{session_id}' not found"},
+            status=404,
+        )
+
+    eps = session.worker_runtime.get_entry_points() if session.worker_runtime else []
+    return web.json_response(
+        {
+            "entry_points": [
+                {
+                    "id": ep.id,
+                    "name": ep.name,
+                    "entry_node": ep.entry_node,
+                    "trigger_type": ep.trigger_type,
+                }
+                for ep in eps
+            ]
+        }
+    )
+
+
+async def handle_session_graphs(request: web.Request) -> web.Response:
+    """GET /api/sessions/{session_id}/graphs — list loaded graphs."""
+    manager = _get_manager(request)
+    session_id = request.match_info["session_id"]
+    session = manager.get_session(session_id)
+
+    if session is None:
+        return web.json_response(
+            {"error": f"Session '{session_id}' not found"},
+            status=404,
+        )
+
+    graphs = session.worker_runtime.list_graphs() if session.worker_runtime else []
+    return web.json_response({"graphs": graphs})
+
+
+# ------------------------------------------------------------------
+# Worker session browsing (persisted execution runs on disk)
+# ------------------------------------------------------------------
+
+
+async def handle_list_worker_sessions(request: web.Request) -> web.Response:
+    """List worker sessions on disk."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_path:
+        return web.json_response({"sessions": []})
+
+    sess_dir = sessions_dir(session)
+    if not sess_dir.exists():
+        return web.json_response({"sessions": []})
+
+    sessions = []
+    for d in sorted(sess_dir.iterdir(), reverse=True):
+        if not d.is_dir() or not d.name.startswith("session_"):
+            continue
+
+        entry: dict = {"session_id": d.name}
+
+        state_path = d / "state.json"
+        if state_path.exists():
+            try:
+                state = json.loads(state_path.read_text())
+                entry["status"] = state.get("status", "unknown")
+                entry["started_at"] = state.get("started_at")
+                entry["completed_at"] = state.get("completed_at")
+                progress = state.get("progress", {})
+                entry["steps"] = progress.get("steps_executed", 0)
+                entry["paused_at"] = progress.get("paused_at")
+            except (json.JSONDecodeError, OSError):
+                entry["status"] = "error"
+
+        cp_dir = d / "checkpoints"
+        if cp_dir.exists():
+            entry["checkpoint_count"] = sum(1 for f in cp_dir.iterdir() if f.suffix == ".json")
+        else:
+            entry["checkpoint_count"] = 0
+
+        sessions.append(entry)
+
+    return web.json_response({"sessions": sessions})
+
+
+async def handle_get_worker_session(request: web.Request) -> web.Response:
+    """Get worker session detail from disk."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_path:
+        return web.json_response({"error": "No worker loaded"}, status=503)
+
+    # Support both URL param names: ws_id (new) or session_id (legacy)
+    ws_id = request.match_info.get("ws_id") or request.match_info.get("session_id", "")
+    ws_id = safe_path_segment(ws_id)
+
+    state_path = sessions_dir(session) / ws_id / "state.json"
+    if not state_path.exists():
+        return web.json_response({"error": "Session not found"}, status=404)
+
+    try:
+        state = json.loads(state_path.read_text())
+    except (json.JSONDecodeError, OSError) as e:
+        return web.json_response({"error": f"Failed to read session: {e}"}, status=500)
+
+    return web.json_response(state)
+
+
+async def handle_list_checkpoints(request: web.Request) -> web.Response:
+    """List checkpoints for a worker session."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_path:
+        return web.json_response({"error": "No worker loaded"}, status=503)
+
+    ws_id = request.match_info.get("ws_id") or request.match_info.get("session_id", "")
+    ws_id = safe_path_segment(ws_id)
+
+    cp_dir = sessions_dir(session) / ws_id / "checkpoints"
+    if not cp_dir.exists():
+        return web.json_response({"checkpoints": []})
+
+    checkpoints = []
+    for f in sorted(cp_dir.iterdir(), reverse=True):
+        if f.suffix != ".json":
+            continue
+        try:
+            data = json.loads(f.read_text())
+            checkpoints.append(
+                {
+                    "checkpoint_id": f.stem,
+                    "current_node": data.get("current_node"),
+                    "next_node": data.get("next_node"),
+                    "is_clean": data.get("is_clean", False),
+                    "timestamp": data.get("timestamp"),
+                }
+            )
+        except (json.JSONDecodeError, OSError):
+            checkpoints.append({"checkpoint_id": f.stem, "error": "unreadable"})
+
+    return web.json_response({"checkpoints": checkpoints})
+
+
+async def handle_delete_worker_session(request: web.Request) -> web.Response:
+    """Delete a worker session from disk."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_path:
+        return web.json_response({"error": "No worker loaded"}, status=503)
+
+    ws_id = request.match_info.get("ws_id") or request.match_info.get("session_id", "")
+    ws_id = safe_path_segment(ws_id)
+
+    session_path = sessions_dir(session) / ws_id
+    if not session_path.exists():
+        return web.json_response({"error": "Session not found"}, status=404)
+
+    shutil.rmtree(session_path)
+    return web.json_response({"deleted": ws_id})
+
+
+async def handle_restore_checkpoint(request: web.Request) -> web.Response:
+    """Restore from a checkpoint."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_runtime:
+        return web.json_response({"error": "No worker loaded in this session"}, status=503)
+
+    ws_id = request.match_info.get("ws_id") or request.match_info.get("session_id", "")
+    ws_id = safe_path_segment(ws_id)
+    checkpoint_id = safe_path_segment(request.match_info["checkpoint_id"])
+
+    cp_path = sessions_dir(session) / ws_id / "checkpoints" / f"{checkpoint_id}.json"
+    if not cp_path.exists():
+        return web.json_response({"error": "Checkpoint not found"}, status=404)
+
+    entry_points = session.worker_runtime.get_entry_points()
+    if not entry_points:
+        return web.json_response({"error": "No entry points available"}, status=400)
+
+    restore_session_state = {
+        "resume_session_id": ws_id,
+        "resume_from_checkpoint": checkpoint_id,
+    }
+
+    execution_id = await session.worker_runtime.trigger(
+        entry_points[0].id,
+        input_data={},
+        session_state=restore_session_state,
+    )
+
+    return web.json_response(
+        {
+            "execution_id": execution_id,
+            "restored_from": ws_id,
+            "checkpoint_id": checkpoint_id,
+        }
+    )
+
+
+async def handle_messages(request: web.Request) -> web.Response:
+    """Get messages for a worker session."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    if not session.worker_path:
+        return web.json_response({"error": "No worker loaded"}, status=503)
+
+    ws_id = request.match_info.get("ws_id") or request.match_info.get("session_id", "")
+    ws_id = safe_path_segment(ws_id)
+
+    convs_dir = sessions_dir(session) / ws_id / "conversations"
+    if not convs_dir.exists():
+        return web.json_response({"messages": []})
+
+    filter_node = request.query.get("node_id")
+    all_messages = []
+
+    for node_dir in convs_dir.iterdir():
+        if not node_dir.is_dir():
+            continue
+        if filter_node and node_dir.name != filter_node:
+            continue
+
+        parts_dir = node_dir / "parts"
+        if not parts_dir.exists():
+            continue
+
+        for part_file in sorted(parts_dir.iterdir()):
+            if part_file.suffix != ".json":
+                continue
+            try:
+                part = json.loads(part_file.read_text())
+                part["_node_id"] = node_dir.name
+                all_messages.append(part)
+            except (json.JSONDecodeError, OSError):
+                continue
+
+    all_messages.sort(key=lambda m: m.get("seq", 0))
+
+    client_only = request.query.get("client_only", "").lower() in ("true", "1")
+    if client_only:
+        client_facing_nodes: set[str] = set()
+        if session.runner and hasattr(session.runner, "graph"):
+            for node in session.runner.graph.nodes:
+                if node.client_facing:
+                    client_facing_nodes.add(node.id)
+
+        if client_facing_nodes:
+            all_messages = [
+                m
+                for m in all_messages
+                if not m.get("is_transition_marker")
+                and m["role"] != "tool"
+                and not (m["role"] == "assistant" and m.get("tool_calls"))
+                and (
+                    (m["role"] == "user" and m.get("is_client_input"))
+                    or (m["role"] == "assistant" and m.get("_node_id") in client_facing_nodes)
+                )
+            ]
+
+    return web.json_response({"messages": all_messages})
+
+
+# ------------------------------------------------------------------
+# Agent discovery (not session-specific)
+# ------------------------------------------------------------------
+
+
+async def handle_discover(request: web.Request) -> web.Response:
+    """GET /api/discover — discover agents from filesystem."""
+    from framework.tui.screens.agent_picker import discover_agents
+
+    manager = _get_manager(request)
+    loaded_paths = {str(s.worker_path) for s in manager.list_sessions() if s.worker_path}
+
+    groups = discover_agents()
+    result = {}
+    for category, entries in groups.items():
+        result[category] = [
+            {
+                "path": str(entry.path),
+                "name": entry.name,
+                "description": entry.description,
+                "category": entry.category,
+                "session_count": entry.session_count,
+                "node_count": entry.node_count,
+                "tool_count": entry.tool_count,
+                "tags": entry.tags,
+                "last_active": entry.last_active,
+                "is_loaded": str(entry.path) in loaded_paths,
+            }
+            for entry in entries
+        ]
+    return web.json_response(result)
+
+
+# ------------------------------------------------------------------
+# Route registration
+# ------------------------------------------------------------------
+
+
+def register_routes(app: web.Application) -> None:
+    """Register session routes."""
+    # Discovery
+    app.router.add_get("/api/discover", handle_discover)
+
+    # Session lifecycle
+    app.router.add_post("/api/sessions", handle_create_session)
+    app.router.add_get("/api/sessions", handle_list_live_sessions)
+    app.router.add_get("/api/sessions/{session_id}", handle_get_live_session)
+    app.router.add_delete("/api/sessions/{session_id}", handle_stop_session)
+
+    # Worker lifecycle
+    app.router.add_post("/api/sessions/{session_id}/worker", handle_load_worker)
+    app.router.add_delete("/api/sessions/{session_id}/worker", handle_unload_worker)
+
+    # Session info
+    app.router.add_get("/api/sessions/{session_id}/stats", handle_session_stats)
+    app.router.add_get("/api/sessions/{session_id}/entry-points", handle_session_entry_points)
+    app.router.add_get("/api/sessions/{session_id}/graphs", handle_session_graphs)
+
+    # Worker session browsing (session-primary)
+    app.router.add_get("/api/sessions/{session_id}/worker-sessions", handle_list_worker_sessions)
+    app.router.add_get(
+        "/api/sessions/{session_id}/worker-sessions/{ws_id}", handle_get_worker_session
+    )
+    app.router.add_delete(
+        "/api/sessions/{session_id}/worker-sessions/{ws_id}", handle_delete_worker_session
+    )
+    app.router.add_get(
+        "/api/sessions/{session_id}/worker-sessions/{ws_id}/checkpoints",
+        handle_list_checkpoints,
+    )
+    app.router.add_post(
+        "/api/sessions/{session_id}/worker-sessions/{ws_id}/checkpoints/{checkpoint_id}/restore",
+        handle_restore_checkpoint,
+    )
+    app.router.add_get(
+        "/api/sessions/{session_id}/worker-sessions/{ws_id}/messages",
+        handle_messages,
+    )

core/framework/server/session_manager.py

@@ -0,0 +1,666 @@
+"""Session-primary lifecycle manager for the HTTP API server.
+
+Sessions (queen) are the primary entity. Workers are optional and can be
+loaded/unloaded while the queen stays alive.
+
+Architecture:
+- Session owns EventBus + LLM, shared with queen and worker
+- Queen is always present once a session starts
+- Worker is optional — loaded into an existing session
+- Judge is active only when a worker is loaded
+"""
+
+import asyncio
+import json
+import logging
+import time
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Session:
+    """A live session with a queen and optional worker."""
+
+    id: str
+    event_bus: Any  # EventBus — owned by session
+    llm: Any  # LLMProvider — owned by session
+    loaded_at: float
+    # Queen (always present once started)
+    queen_executor: Any = None  # GraphExecutor for queen input injection
+    queen_task: asyncio.Task | None = None
+    # Worker (optional)
+    worker_id: str | None = None
+    worker_path: Path | None = None
+    runner: Any | None = None  # AgentRunner
+    worker_runtime: Any | None = None  # AgentRuntime
+    worker_info: Any | None = None  # AgentInfo
+    # Judge (active when worker is loaded)
+    judge_task: asyncio.Task | None = None
+    escalation_sub: str | None = None
+
+
+class SessionManager:
+    """Manages session lifecycles.
+
+    Thread-safe via asyncio.Lock. Workers are loaded via run_in_executor
+    (blocking I/O) then started on the event loop.
+    """
+
+    def __init__(self, model: str | None = None) -> None:
+        self._sessions: dict[str, Session] = {}
+        self._loading: set[str] = set()
+        self._model = model
+        self._lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------
+    # Session lifecycle
+    # ------------------------------------------------------------------
+
+    async def _create_session_core(
+        self,
+        session_id: str | None = None,
+        model: str | None = None,
+    ) -> Session:
+        """Create session infrastructure (EventBus, LLM) without starting queen.
+
+        Internal helper — use create_session() or create_session_with_worker().
+        """
+        from framework.config import RuntimeConfig
+        from framework.llm.litellm import LiteLLMProvider
+        from framework.runtime.event_bus import EventBus
+
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        resolved_id = session_id or f"session_{ts}_{uuid.uuid4().hex[:8]}"
+
+        async with self._lock:
+            if resolved_id in self._sessions:
+                raise ValueError(f"Session '{resolved_id}' already exists")
+
+        # Load LLM config from ~/.hive/configuration.json
+        rc = RuntimeConfig(model=model or self._model or RuntimeConfig().model)
+
+        # Session owns these — shared with queen and worker
+        llm = LiteLLMProvider(
+            model=rc.model,
+            api_key=rc.api_key,
+            api_base=rc.api_base,
+            **rc.extra_kwargs,
+        )
+        event_bus = EventBus()
+
+        session = Session(
+            id=resolved_id,
+            event_bus=event_bus,
+            llm=llm,
+            loaded_at=time.time(),
+        )
+
+        async with self._lock:
+            self._sessions[resolved_id] = session
+
+        return session
+
+    async def create_session(
+        self,
+        session_id: str | None = None,
+        model: str | None = None,
+    ) -> Session:
+        """Create a new session with a queen but no worker.
+
+        The queen starts immediately with MCP coding tools.
+        A worker can be loaded later via load_worker().
+        """
+        session = await self._create_session_core(session_id=session_id, model=model)
+
+        # Start queen immediately (queen-only, no worker tools yet)
+        await self._start_queen(session, worker_identity=None)
+
+        logger.info("Session '%s' created (queen-only)", session.id)
+        return session
+
+    async def create_session_with_worker(
+        self,
+        agent_path: str | Path,
+        agent_id: str | None = None,
+        model: str | None = None,
+    ) -> Session:
+        """Create a session and load a worker in one step.
+
+        Backward-compatible with the old POST /api/agents flow.
+        Loads the worker FIRST so the queen starts with full lifecycle
+        and monitoring tools available.
+
+        The session gets an auto-generated unique ID. The agent name
+        becomes the worker_id (used by the frontend as backendAgentId).
+        """
+        from framework.tools.queen_lifecycle_tools import build_worker_profile
+
+        agent_path = Path(agent_path)
+        resolved_worker_id = agent_id or agent_path.name
+
+        # Auto-generate session ID (not the agent name)
+        session = await self._create_session_core(model=model)
+        try:
+            # Load worker FIRST (before queen) so queen gets full tools
+            await self._load_worker_core(
+                session,
+                agent_path,
+                worker_id=resolved_worker_id,
+                model=model,
+            )
+
+            # Start queen with worker profile + lifecycle + monitoring tools
+            worker_identity = (
+                build_worker_profile(session.worker_runtime) if session.worker_runtime else None
+            )
+            await self._start_queen(session, worker_identity=worker_identity)
+
+            # Start health judge
+            if agent_path.name != "hive_coder" and session.worker_runtime:
+                await self._start_judge(session, session.runner._storage_path)
+
+        except Exception:
+            # If anything fails, tear down the session
+            await self.stop_session(session.id)
+            raise
+        return session
+
+    # ------------------------------------------------------------------
+    # Worker lifecycle
+    # ------------------------------------------------------------------
+
+    async def _load_worker_core(
+        self,
+        session: Session,
+        agent_path: str | Path,
+        worker_id: str | None = None,
+        model: str | None = None,
+    ) -> None:
+        """Load a worker agent into a session (core logic).
+
+        Sets up the runner, runtime, and session fields. Does NOT start the
+        judge or notify the queen — callers handle those steps.
+        """
+        from framework.runner import AgentRunner
+
+        agent_path = Path(agent_path)
+        resolved_worker_id = worker_id or agent_path.name
+
+        if session.worker_runtime is not None:
+            raise ValueError(f"Session '{session.id}' already has worker '{session.worker_id}'")
+
+        async with self._lock:
+            if session.id in self._loading:
+                raise ValueError(f"Session '{session.id}' is currently loading a worker")
+            self._loading.add(session.id)
+
+        try:
+            # Blocking I/O — load in executor
+            loop = asyncio.get_running_loop()
+            resolved_model = model or self._model
+            runner = await loop.run_in_executor(
+                None,
+                lambda: AgentRunner.load(
+                    agent_path,
+                    model=resolved_model,
+                    interactive=False,
+                ),
+            )
+
+            # Setup with session's event bus
+            if runner._agent_runtime is None:
+                await loop.run_in_executor(
+                    None,
+                    lambda: runner._setup(event_bus=session.event_bus),
+                )
+
+            runtime = runner._agent_runtime
+
+            # Start runtime on event loop
+            if runtime and not runtime.is_running:
+                await runtime.start()
+
+            info = runner.info()
+
+            # Update session
+            session.worker_id = resolved_worker_id
+            session.worker_path = agent_path
+            session.runner = runner
+            session.worker_runtime = runtime
+            session.worker_info = info
+
+            async with self._lock:
+                self._loading.discard(session.id)
+
+            logger.info(
+                "Worker '%s' loaded into session '%s'",
+                resolved_worker_id,
+                session.id,
+            )
+
+        except Exception:
+            async with self._lock:
+                self._loading.discard(session.id)
+            raise
+
+    async def load_worker(
+        self,
+        session_id: str,
+        agent_path: str | Path,
+        worker_id: str | None = None,
+        model: str | None = None,
+    ) -> Session:
+        """Load a worker agent into an existing session (with running queen).
+
+        Starts the worker runtime, health judge, and notifies the queen.
+        """
+        agent_path = Path(agent_path)
+
+        session = self._sessions.get(session_id)
+        if session is None:
+            raise ValueError(f"Session '{session_id}' not found")
+
+        await self._load_worker_core(
+            session,
+            agent_path,
+            worker_id=worker_id,
+            model=model,
+        )
+
+        # Start judge + notify queen (skip for hive_coder itself)
+        if agent_path.name != "hive_coder" and session.worker_runtime:
+            await self._start_judge(session, session.runner._storage_path)
+            await self._notify_queen_worker_loaded(session)
+
+        # Emit SSE event so the frontend can update UI
+        await self._emit_worker_loaded(session)
+
+        return session
+
+    async def unload_worker(self, session_id: str) -> bool:
+        """Unload the worker from a session. Queen stays alive."""
+        session = self._sessions.get(session_id)
+        if session is None:
+            return False
+        if session.worker_runtime is None:
+            return False
+
+        # Stop judge + escalation
+        self._stop_judge(session)
+
+        # Cleanup worker
+        if session.runner:
+            try:
+                await session.runner.cleanup_async()
+            except Exception as e:
+                logger.error("Error cleaning up worker '%s': %s", session.worker_id, e)
+
+        worker_id = session.worker_id
+        session.worker_id = None
+        session.worker_path = None
+        session.runner = None
+        session.worker_runtime = None
+        session.worker_info = None
+
+        # Notify queen
+        await self._notify_queen_worker_unloaded(session)
+
+        logger.info("Worker '%s' unloaded from session '%s'", worker_id, session_id)
+        return True
+
+    # ------------------------------------------------------------------
+    # Session teardown
+    # ------------------------------------------------------------------
+
+    async def stop_session(self, session_id: str) -> bool:
+        """Stop a session entirely — unload worker + cancel queen."""
+        async with self._lock:
+            session = self._sessions.pop(session_id, None)
+
+        if session is None:
+            return False
+
+        # Stop judge
+        self._stop_judge(session)
+
+        # Stop queen
+        if session.queen_task is not None:
+            session.queen_task.cancel()
+            session.queen_task = None
+        session.queen_executor = None
+
+        # Cleanup worker
+        if session.runner:
+            try:
+                await session.runner.cleanup_async()
+            except Exception as e:
+                logger.error("Error cleaning up worker: %s", e)
+
+        logger.info("Session '%s' stopped", session_id)
+        return True
+
+    # ------------------------------------------------------------------
+    # Queen startup
+    # ------------------------------------------------------------------
+
+    async def _start_queen(
+        self,
+        session: Session,
+        worker_identity: str | None,
+    ) -> None:
+        """Start the queen executor for a session."""
+        from framework.agents.hive_coder.agent import (
+            queen_goal,
+            queen_graph as _queen_graph,
+        )
+        from framework.graph.executor import GraphExecutor
+        from framework.runner.tool_registry import ToolRegistry
+        from framework.runtime.core import Runtime
+
+        hive_home = Path.home() / ".hive"
+        queen_dir = hive_home / "queen" / "session" / session.id
+        queen_dir.mkdir(parents=True, exist_ok=True)
+
+        # Register MCP coding tools
+        queen_registry = ToolRegistry()
+        import framework.agents.hive_coder as _hive_coder_pkg
+
+        hive_coder_dir = Path(_hive_coder_pkg.__file__).parent
+        mcp_config = hive_coder_dir / "mcp_servers.json"
+        if mcp_config.exists():
+            try:
+                queen_registry.load_mcp_config(mcp_config)
+                logger.info("Queen: loaded MCP tools from %s", mcp_config)
+            except Exception:
+                logger.warning("Queen: MCP config failed to load", exc_info=True)
+
+        # Always register lifecycle tools — they check session.worker_runtime
+        # at call time, so they work even if no worker is loaded yet.
+        from framework.tools.queen_lifecycle_tools import register_queen_lifecycle_tools
+
+        register_queen_lifecycle_tools(
+            queen_registry,
+            session=session,
+            session_id=session.id,
+        )
+
+        # Monitoring tools need concrete worker paths — only register when present
+        if session.worker_runtime:
+            from framework.tools.worker_monitoring_tools import register_worker_monitoring_tools
+
+            register_worker_monitoring_tools(
+                queen_registry,
+                session.event_bus,
+                session.worker_path,
+                stream_id="queen",
+                worker_graph_id=session.worker_runtime._graph_id,
+            )
+
+        queen_tools = list(queen_registry.get_tools().values())
+        queen_tool_executor = queen_registry.get_executor()
+
+        # Build queen graph with adjusted prompt + tools
+        _orig_node = _queen_graph.nodes[0]
+        base_prompt = _orig_node.system_prompt or ""
+
+        if worker_identity is None:
+            worker_identity = (
+                "\n\n# Worker Profile\n"
+                "No worker agent loaded. You are operating independently.\n"
+                "Handle all tasks directly using your coding tools."
+            )
+
+        registered_tool_names = set(queen_registry.get_tools().keys())
+        declared_tools = _orig_node.tools or []
+        available_tools = [t for t in declared_tools if t in registered_tool_names]
+
+        node_updates: dict = {
+            "system_prompt": base_prompt + worker_identity,
+        }
+        if set(available_tools) != set(declared_tools):
+            missing = sorted(set(declared_tools) - registered_tool_names)
+            if missing:
+                logger.warning("Queen: tools not available: %s", missing)
+            node_updates["tools"] = available_tools
+
+        adjusted_node = _orig_node.model_copy(update=node_updates)
+        queen_graph = _queen_graph.model_copy(update={"nodes": [adjusted_node]})
+
+        queen_runtime = Runtime(hive_home / "queen")
+
+        async def _queen_loop():
+            try:
+                executor = GraphExecutor(
+                    runtime=queen_runtime,
+                    llm=session.llm,
+                    tools=queen_tools,
+                    tool_executor=queen_tool_executor,
+                    event_bus=session.event_bus,
+                    stream_id="queen",
+                    storage_path=queen_dir,
+                    loop_config=queen_graph.loop_config,
+                )
+                session.queen_executor = executor
+                logger.info(
+                    "Queen starting with %d tools: %s",
+                    len(queen_tools),
+                    [t.name for t in queen_tools],
+                )
+                await executor.execute(
+                    graph=queen_graph,
+                    goal=queen_goal,
+                    input_data={"greeting": "Session started."},
+                    session_state={"resume_session_id": session.id},
+                )
+                logger.warning("Queen executor returned (should be forever-alive)")
+            except Exception:
+                logger.error("Queen conversation crashed", exc_info=True)
+            finally:
+                session.queen_executor = None
+
+        session.queen_task = asyncio.create_task(_queen_loop())
+
+    # ------------------------------------------------------------------
+    # Judge startup / teardown
+    # ------------------------------------------------------------------
+
+    async def _start_judge(
+        self,
+        session: Session,
+        worker_storage_path: str | Path,
+    ) -> None:
+        """Start the health judge for a session's worker."""
+        from framework.graph.executor import GraphExecutor
+        from framework.monitoring import judge_goal, judge_graph
+        from framework.runner.tool_registry import ToolRegistry
+        from framework.runtime.core import Runtime
+        from framework.runtime.event_bus import EventType as _ET
+        from framework.tools.worker_monitoring_tools import register_worker_monitoring_tools
+
+        worker_storage_path = Path(worker_storage_path)
+
+        try:
+            # Monitoring tools
+            monitoring_registry = ToolRegistry()
+            register_worker_monitoring_tools(
+                monitoring_registry,
+                session.event_bus,
+                worker_storage_path,
+                worker_graph_id=session.worker_runtime._graph_id,
+            )
+
+            hive_home = Path.home() / ".hive"
+            judge_dir = hive_home / "judge" / "session" / session.id
+            judge_dir.mkdir(parents=True, exist_ok=True)
+
+            judge_runtime = Runtime(hive_home / "judge")
+            monitoring_tools = list(monitoring_registry.get_tools().values())
+            monitoring_executor = monitoring_registry.get_executor()
+
+            async def _judge_loop():
+                interval = 120
+                first = True
+                while True:
+                    if not first:
+                        await asyncio.sleep(interval)
+                    first = False
+                    try:
+                        executor = GraphExecutor(
+                            runtime=judge_runtime,
+                            llm=session.llm,
+                            tools=monitoring_tools,
+                            tool_executor=monitoring_executor,
+                            event_bus=session.event_bus,
+                            stream_id="judge",
+                            storage_path=judge_dir,
+                            loop_config=judge_graph.loop_config,
+                        )
+                        await executor.execute(
+                            graph=judge_graph,
+                            goal=judge_goal,
+                            input_data={
+                                "event": {"source": "timer", "reason": "scheduled"},
+                            },
+                            session_state={"resume_session_id": session.id},
+                        )
+                    except Exception:
+                        logger.error("Health judge tick failed", exc_info=True)
+
+            session.judge_task = asyncio.create_task(_judge_loop())
+
+            # Escalation: judge → queen
+            async def _on_escalation(event):
+                ticket = event.data.get("ticket", {})
+                executor = session.queen_executor
+                if executor is None:
+                    logger.warning("Escalation received but queen executor is None")
+                    return
+                node = executor.node_registry.get("queen")
+                if node is not None and hasattr(node, "inject_event"):
+                    msg = "[ESCALATION TICKET from Health Judge]\n" + json.dumps(
+                        ticket, indent=2, ensure_ascii=False
+                    )
+                    await node.inject_event(msg)
+                else:
+                    logger.warning("Escalation received but queen node not ready")
+
+            session.escalation_sub = session.event_bus.subscribe(
+                event_types=[_ET.WORKER_ESCALATION_TICKET],
+                handler=_on_escalation,
+            )
+
+            logger.info("Judge started for session '%s'", session.id)
+
+        except Exception as e:
+            logger.error(
+                "Failed to start judge for session '%s': %s",
+                session.id,
+                e,
+                exc_info=True,
+            )
+
+    def _stop_judge(self, session: Session) -> None:
+        """Cancel judge task and unsubscribe escalation events."""
+        if session.judge_task is not None:
+            session.judge_task.cancel()
+            session.judge_task = None
+        if session.escalation_sub is not None:
+            try:
+                session.event_bus.unsubscribe(session.escalation_sub)
+            except Exception:
+                pass
+            session.escalation_sub = None
+
+    # ------------------------------------------------------------------
+    # Queen notifications
+    # ------------------------------------------------------------------
+
+    async def _notify_queen_worker_loaded(self, session: Session) -> None:
+        """Inject a system message into the queen about the loaded worker."""
+        from framework.tools.queen_lifecycle_tools import build_worker_profile
+
+        executor = session.queen_executor
+        if executor is None:
+            return
+        node = executor.node_registry.get("queen")
+        if node is None or not hasattr(node, "inject_event"):
+            return
+
+        profile = build_worker_profile(session.worker_runtime)
+        await node.inject_event(f"[SYSTEM] Worker loaded.{profile}")
+
+    async def _emit_worker_loaded(self, session: Session) -> None:
+        """Publish a WORKER_LOADED event so the frontend can update."""
+        from framework.runtime.event_bus import AgentEvent, EventType
+
+        info = session.worker_info
+        await session.event_bus.publish(
+            AgentEvent(
+                type=EventType.WORKER_LOADED,
+                stream_id="queen",
+                data={
+                    "worker_id": session.worker_id,
+                    "worker_name": info.name if info else session.worker_id,
+                    "agent_path": str(session.worker_path) if session.worker_path else "",
+                    "goal": info.goal_name if info else "",
+                    "node_count": info.node_count if info else 0,
+                },
+            )
+        )
+
+    async def _notify_queen_worker_unloaded(self, session: Session) -> None:
+        """Notify the queen that the worker has been unloaded."""
+        executor = session.queen_executor
+        if executor is None:
+            return
+        node = executor.node_registry.get("queen")
+        if node is None or not hasattr(node, "inject_event"):
+            return
+
+        await node.inject_event(
+            "[SYSTEM] Worker unloaded. You are now operating independently. "
+            "Handle all tasks directly using your coding tools."
+        )
+
+    # ------------------------------------------------------------------
+    # Lookups
+    # ------------------------------------------------------------------
+
+    def get_session(self, session_id: str) -> Session | None:
+        return self._sessions.get(session_id)
+
+    def get_session_by_worker_id(self, worker_id: str) -> Session | None:
+        """Find a session by its loaded worker's ID."""
+        for s in self._sessions.values():
+            if s.worker_id == worker_id:
+                return s
+        return None
+
+    def get_session_for_agent(self, agent_id: str) -> Session | None:
+        """Resolve an agent_id to a session (backward compat).
+
+        Checks session.id first, then session.worker_id.
+        """
+        s = self._sessions.get(agent_id)
+        if s:
+            return s
+        return self.get_session_by_worker_id(agent_id)
+
+    def is_loading(self, session_id: str) -> bool:
+        return session_id in self._loading
+
+    def list_sessions(self) -> list[Session]:
+        return list(self._sessions.values())
+
+    async def shutdown_all(self) -> None:
+        """Gracefully stop all sessions. Called on server shutdown."""
+        session_ids = list(self._sessions.keys())
+        for sid in session_ids:
+            await self.stop_session(sid)
+        logger.info("All sessions stopped")

core/framework/server/sse.py

@@ -0,0 +1,73 @@
+"""Server-Sent Events helper wrapping aiohttp StreamResponse."""
+
+import json
+import logging
+
+from aiohttp import web
+
+logger = logging.getLogger(__name__)
+
+
+class SSEResponse:
+    """Thin wrapper around aiohttp StreamResponse for SSE streaming.
+
+    Usage:
+        sse = SSEResponse()
+        await sse.prepare(request)
+        await sse.send_event({"key": "value"}, event="update")
+        await sse.send_keepalive()
+    """
+
+    def __init__(self) -> None:
+        self._response: web.StreamResponse | None = None
+
+    async def prepare(self, request: web.Request) -> web.StreamResponse:
+        """Prepare the SSE response with correct headers."""
+        self._response = web.StreamResponse(
+            status=200,
+            headers={
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+        await self._response.prepare(request)
+        return self._response
+
+    async def send_event(
+        self,
+        data: dict,
+        event: str | None = None,
+        id: str | None = None,
+    ) -> None:
+        """Serialize and send an SSE event.
+
+        Args:
+            data: JSON-serializable dict to send as the data field.
+            event: Optional SSE event type.
+            id: Optional SSE event id.
+        """
+        if self._response is None:
+            raise RuntimeError("SSEResponse not prepared; call prepare() first")
+
+        parts: list[str] = []
+        if id is not None:
+            parts.append(f"id: {id}\n")
+        if event is not None:
+            parts.append(f"event: {event}\n")
+        payload = json.dumps(data, default=str)
+        parts.append(f"data: {payload}\n")
+        parts.append("\n")
+
+        await self._response.write("".join(parts).encode("utf-8"))
+
+    async def send_keepalive(self) -> None:
+        """Send an SSE comment as a keepalive heartbeat."""
+        if self._response is None:
+            raise RuntimeError("SSEResponse not prepared; call prepare() first")
+        await self._response.write(b": keepalive\n\n")
+
+    @property
+    def response(self) -> web.StreamResponse | None:
+        return self._response

core/framework/storage/conversation_store.py

@@ -4,14 +4,20 @@ Each conversation part is stored as a separate JSON file under a
 ``parts/`` subdirectory.  Meta and cursor are stored as ``meta.json``
 and ``cursor.json`` in the base directory.
 
+The store is flat — all nodes in a continuous conversation share one
+directory.  Each part carries a ``phase_id`` to identify which node
+produced it.
+
 Directory layout::
 
-    {base_path}/
-        meta.json
-        cursor.json
+    {base_path}/          (typically ``{session}/conversations/``)
+        meta.json         current node config (overwritten on transition)
+        cursor.json       iteration counter, accumulator outputs, stall state
         parts/
-            0000000000.json
-            0000000001.json
+            0000000000.json   (phase_id=node_a)
+            0000000001.json   (phase_id=node_a)
+            0000000002.json   (transition marker)
+            0000000003.json   (phase_id=node_b)
             ...
 """
 

core/framework/storage/session_store.py

@@ -24,7 +24,7 @@ class SessionStore:
     Manages sessions in the new structure:
       {base_path}/sessions/session_YYYYMMDD_HHMMSS_{uuid}/
         ├── state.json            # Single source of truth
-        ├── conversations/        # Per-node EventLoop state
+        ├── conversations/        # Flat EventLoop state (parts carry phase_id)
         ├── artifacts/            # Spillover data
         └── logs/                 # L1/L2/L3 observability
             ├── summary.json

core/framework/testing/__init__.py

@@ -26,9 +26,9 @@ Testing tools are integrated into the main agent_builder_server.py:
 ## CLI Commands
 
 ```bash
-uv run python -m framework test-run <agent_path> --goal <goal_id>
-uv run python -m framework test-debug <goal_id> <test_id>
-uv run python -m framework test-list <agent_path> --goal <goal_id>
+    uv run python -m framework test-run <agent_path> --goal <goal_id>
+    uv run python -m framework test-debug <agent_path> <test_name>
+    uv run python -m framework test-list <agent_path> --goal <goal_id>
 ```
 """