feat: allow multiple questions

docs: rename and expand contributing guidelines

AGENTS.md

@@ -2,10 +2,6 @@
 
 Shared agent instructions for this workspace.
 
-## Deprecations
-
-- **TUI is deprecated.** The terminal UI (`hive tui`) is no longer maintained. Use the browser-based interface (`hive open`) instead.
-
 ## Coding Agent Notes
 
 - 

README.md

@@ -111,7 +111,7 @@ This sets up:
 - **LLM provider** - Interactive default model configuration
 - All required Python dependencies with `uv`
 
-- At last, it will initiate the open hive interface in your browser
+- Finally, it will open the Hive interface in your browser
 
 > **Tip:** To reopen the dashboard later, run `hive open` from the project directory.
 
@@ -125,18 +125,18 @@ Type the agent you want to build in the home input box
 
 ### Use Template Agents
 
-Click "Try a sample agent" and check the templates. You can run a templates directly or choose to build your version on top of the existing template.
+Click "Try a sample agent" and check the templates. You can run a template directly or choose to build your version on top of the existing template.
 
 ### Run Agents
 
-Now you can run an agent by selectiing the agent (either an existing agent or example agent). You can click the Run button on the top left, or talk to the queen agent and it can run the agent for you.
+Now you can run an agent by selecting the agent (either an existing agent or example agent). You can click the Run button on the top left, or talk to the queen agent and it can run the agent for you.
 
 <img width="2500" height="1214" alt="Image" src="https://github.com/user-attachments/assets/71c38206-2ad5-49aa-bde8-6698d0bc55f5" />
 
 ## Features
 
 - **Browser-Use** - Control the browser on your computer to achieve hard tasks
-- **Parallel Execution** - Execute the generated graph in parallel. This way you can have multiple agent compelteing the jobs for you
+- **Parallel Execution** - Execute the generated graph in parallel. This way you can have multiple agents completing the jobs for you
 - **[Goal-Driven Generation](docs/key_concepts/goals_outcome.md)** - Define objectives in natural language; the coding agent generates the agent graph and connection code to achieve them
 - **[Adaptiveness](docs/key_concepts/evolution.md)** - Framework captures failures, calibrates according to the objectives, and evolves the agent graph
 - **[Dynamic Node Connections](docs/key_concepts/graph.md)** - No predefined edges; connection code is generated by any capable LLM based on your goals

SECURITY.md

@@ -39,8 +39,8 @@ We consider security research conducted in accordance with this policy to be:
 ## Security Best Practices for Users
 
 1. **Keep Updated**: Always run the latest version
-2. **Secure Configuration**: Review `config.yaml` settings, especially in production
-3. **Environment Variables**: Never commit `.env` files or `config.yaml` with secrets
+2. **Secure Configuration**: Review your `~/.hive/configuration.json`, `.mcp.json`, and environment variable settings, especially in production
+3. **Environment Variables**: Never commit `.env` files or any configuration files that contain secrets
 4. **Network Security**: Use HTTPS in production, configure firewalls appropriately
 5. **Database Security**: Use strong passwords, limit network access
 

core/demos/event_loop_wss_demo.py

@@ -601,7 +601,7 @@ async def handle_ws(websocket):
         )
         node = EventLoopNode(
             event_bus=bus,
-            config=LoopConfig(max_iterations=10_000, max_history_tokens=32_000),
+            config=LoopConfig(max_iterations=10_000, max_context_tokens=32_000),
             conversation_store=STORE,
             tool_executor=tool_executor,
         )

core/demos/github_outreach_demo.py

@@ -1769,7 +1769,7 @@ async def _run_pipeline(websocket, initial_message: str):
             config=LoopConfig(
                 max_iterations=30,
                 max_tool_calls_per_turn=30,
-                max_history_tokens=64000,
+                max_context_tokens=64000,
                 max_tool_result_chars=8_000,
                 spillover_dir=str(_DATA_DIR),
             ),

core/demos/handoff_demo.py

@@ -752,7 +752,7 @@ async def _run_pipeline(websocket, topic: str):
         config=LoopConfig(
             max_iterations=20,
             max_tool_calls_per_turn=30,
-            max_history_tokens=32_000,
+            max_context_tokens=32_000,
         ),
         conversation_store=store_a,
         tool_executor=tool_executor,
@@ -850,7 +850,7 @@ async def _run_pipeline(websocket, topic: str):
         config=LoopConfig(
             max_iterations=10,
             max_tool_calls_per_turn=30,
-            max_history_tokens=32_000,
+            max_context_tokens=32_000,
         ),
         conversation_store=store_b,
     )

core/demos/org_demo.py

@@ -1258,7 +1258,7 @@ async def _run_org_pipeline(websocket, topic: str):
             config=LoopConfig(
                 max_iterations=30,
                 max_tool_calls_per_turn=30,
-                max_history_tokens=32_000,
+                max_context_tokens=32_000,
             ),
             conversation_store=store,
             tool_executor=executor,

core/framework/__init__.py

@@ -22,7 +22,6 @@ The framework includes a Goal-Based Testing system (Goal → Agent → Eval):
 See `framework.testing` for details.
 """
 
-from framework.builder.query import BuilderQuery
 from framework.llm import AnthropicProvider, LLMProvider
 from framework.runner import AgentOrchestrator, AgentRunner
 from framework.runtime.core import Runtime
@@ -51,8 +50,6 @@ __all__ = [
     "Problem",
     # Runtime
     "Runtime",
-    # Builder
-    "BuilderQuery",
     # LLM
     "LLMProvider",
     "AnthropicProvider",

core/framework/agents/credential_tester/__main__.py

@@ -10,13 +10,14 @@ from .agent import CredentialTesterAgent
 
 
 def setup_logging(verbose=False, debug=False):
+    from framework.observability import configure_logging
+
     if debug:
-        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+        configure_logging(level="DEBUG")
     elif verbose:
-        level, fmt = logging.INFO, "%(message)s"
+        configure_logging(level="INFO")
     else:
-        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
-    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+        configure_logging(level="WARNING")
 
 
 def pick_account(agent: CredentialTesterAgent) -> dict | None:
@@ -51,42 +52,6 @@ def cli():
     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)

core/framework/agents/credential_tester/agent.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from framework.config import get_max_context_tokens
 from framework.graph import Goal, NodeSpec, SuccessCriterion
 from framework.graph.checkpoint_config import CheckpointConfig
 from framework.graph.edge import GraphSpec
@@ -455,7 +456,6 @@ identity_prompt = (
 loop_config = {
     "max_iterations": 50,
     "max_tool_calls_per_turn": 30,
-    "max_history_tokens": 32000,
 }
 
 # ---------------------------------------------------------------------------
@@ -541,7 +541,7 @@ class CredentialTesterAgent:
             loop_config={
                 "max_iterations": 50,
                 "max_tool_calls_per_turn": 30,
-                "max_history_tokens": 32000,
+                "max_context_tokens": get_max_context_tokens(),
             },
             conversation_mode="continuous",
             identity_prompt=(

core/framework/agents/discovery.py

@@ -0,0 +1,151 @@
+"""Agent discovery — scan known directories and return categorised AgentEntry lists."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class AgentEntry:
+    """Lightweight agent metadata for the picker / API discover endpoint."""
+
+    path: Path
+    name: str
+    description: str
+    category: str
+    session_count: int = 0
+    node_count: int = 0
+    tool_count: int = 0
+    tags: list[str] = field(default_factory=list)
+    last_active: str | None = None
+
+
+def _get_last_active(agent_name: str) -> str | None:
+    """Return the most recent updated_at timestamp across all sessions."""
+    sessions_dir = Path.home() / ".hive" / "agents" / agent_name / "sessions"
+    if not sessions_dir.exists():
+        return None
+    latest: str | None = None
+    for session_dir in sessions_dir.iterdir():
+        if not session_dir.is_dir() or not session_dir.name.startswith("session_"):
+            continue
+        state_file = session_dir / "state.json"
+        if not state_file.exists():
+            continue
+        try:
+            data = json.loads(state_file.read_text(encoding="utf-8"))
+            ts = data.get("timestamps", {}).get("updated_at")
+            if ts and (latest is None or ts > latest):
+                latest = ts
+        except Exception:
+            continue
+    return latest
+
+
+def _count_sessions(agent_name: str) -> int:
+    """Count session directories under ~/.hive/agents/{agent_name}/sessions/."""
+    sessions_dir = Path.home() / ".hive" / "agents" / agent_name / "sessions"
+    if not sessions_dir.exists():
+        return 0
+    return sum(1 for d in sessions_dir.iterdir() if d.is_dir() and d.name.startswith("session_"))
+
+
+def _extract_agent_stats(agent_path: Path) -> tuple[int, int, list[str]]:
+    """Extract node count, tool count, and tags from an agent directory.
+
+    Prefers agent.py (AST-parsed) over agent.json for node/tool counts
+    since agent.json may be stale.  Tags are only available from agent.json.
+    """
+    import ast
+
+    node_count, tool_count, tags = 0, 0, []
+
+    agent_py = agent_path / "agent.py"
+    if agent_py.exists():
+        try:
+            tree = ast.parse(agent_py.read_text(encoding="utf-8"))
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Assign):
+                    for target in node.targets:
+                        if isinstance(target, ast.Name) and target.id == "nodes":
+                            if isinstance(node.value, ast.List):
+                                node_count = len(node.value.elts)
+        except Exception:
+            pass
+
+    agent_json = agent_path / "agent.json"
+    if agent_json.exists():
+        try:
+            data = json.loads(agent_json.read_text(encoding="utf-8"))
+            json_nodes = data.get("graph", {}).get("nodes", []) or data.get("nodes", [])
+            if node_count == 0:
+                node_count = len(json_nodes)
+            tools: set[str] = set()
+            for n in json_nodes:
+                tools.update(n.get("tools", []))
+            tool_count = len(tools)
+            tags = data.get("agent", {}).get("tags", [])
+        except Exception:
+            pass
+
+    return node_count, tool_count, tags
+
+
+def discover_agents() -> dict[str, list[AgentEntry]]:
+    """Discover agents from all known sources grouped by category."""
+    from framework.runner.cli import (
+        _extract_python_agent_metadata,
+        _get_framework_agents_dir,
+        _is_valid_agent_dir,
+    )
+
+    groups: dict[str, list[AgentEntry]] = {}
+    sources = [
+        ("Your Agents", Path("exports")),
+        ("Framework", _get_framework_agents_dir()),
+        ("Examples", Path("examples/templates")),
+    ]
+
+    for category, base_dir in sources:
+        if not base_dir.exists():
+            continue
+        entries: list[AgentEntry] = []
+        for path in sorted(base_dir.iterdir(), key=lambda p: p.name):
+            if not _is_valid_agent_dir(path):
+                continue
+
+            name, desc = _extract_python_agent_metadata(path)
+            config_fallback_name = path.name.replace("_", " ").title()
+            used_config = name != config_fallback_name
+
+            node_count, tool_count, tags = _extract_agent_stats(path)
+            if not used_config:
+                agent_json = path / "agent.json"
+                if agent_json.exists():
+                    try:
+                        data = json.loads(agent_json.read_text(encoding="utf-8"))
+                        meta = data.get("agent", {})
+                        name = meta.get("name", name)
+                        desc = meta.get("description", desc)
+                    except Exception:
+                        pass
+
+            entries.append(
+                AgentEntry(
+                    path=path,
+                    name=name,
+                    description=desc,
+                    category=category,
+                    session_count=_count_sessions(path.name),
+                    node_count=node_count,
+                    tool_count=tool_count,
+                    tags=tags,
+                    last_active=_get_last_active(path.name),
+                )
+            )
+        if entries:
+            groups[category] = entries
+
+    return groups

core/framework/agents/queen/agent.py

@@ -35,6 +35,5 @@ queen_graph = GraphSpec(
     loop_config={
         "max_iterations": 999_999,
         "max_tool_calls_per_turn": 30,
-        "max_history_tokens": 32000,
     },
 )

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

@@ -77,6 +77,10 @@ _QUEEN_PLANNING_TOOLS = [
     "list_agent_sessions",
     "list_agent_checkpoints",
     "get_agent_checkpoint",
+    # Draft graph (visual-only, no code) — new planning workflow
+    "save_agent_draft",
+    "confirm_and_build",
+    # Scaffold + transition to building (requires confirm_and_build first)
     "initialize_and_build_agent",
     # Load existing agent (after user confirms)
     "load_built_agent",
@@ -87,6 +91,7 @@ _QUEEN_BUILDING_TOOLS = _SHARED_TOOLS + [
     "load_built_agent",
     "list_credentials",
     "replan_agent",
+    "save_agent_draft",  # Re-draft during building → auto-dissolves + updates flowchart
     "write_to_diary",  # Episodic memory — available in all phases
 ]
 
@@ -185,18 +190,21 @@ docs. Always run list_agent_tools() to see what actually exists.
 
 # Tool Discovery (MANDATORY before designing)
 
-Before designing any agent, run list_agent_tools() with NO arguments \
-to see ALL available tools (names + descriptions, grouped by category). \
-ONLY use tools from this list in your node definitions. \
+Before designing any agent, discover tools progressively — start compact, drill into \
+what you need. ONLY use tools from this list in your node definitions. \
 NEVER guess or fabricate tool names from memory.
 
-  list_agent_tools()  # ALWAYS call this first (simple mode)
-  list_agent_tools(group="google", output_schema="full")  # drill into a provider
+  list_agent_tools()                                                      # Step 1: provider summary (counts + credential status)
+  list_agent_tools(group="google", output_schema="summary")               # Step 2: service breakdown within a provider
+  list_agent_tools(group="google", service="gmail")                       # Step 3: tool names for one service
+  list_agent_tools(group="google", service="gmail", output_schema="full") # Step 4: full detail for specific tools
 
-NEVER skip the first call. Always start with the full list \
-so you know what providers and tools exist before drilling in. \
-Simple mode truncates long descriptions — use group + "full" to \
-get the complete description and input_schema for the tools you need.
+Step 1 is MANDATORY. Returns provider names, tool counts, credential availability — very compact. \
+Step 2 breaks a provider into services (e.g. google → gmail/calendar/sheets/drive). Only do this \
+for providers that are relevant to the task. \
+Step 3 gets tool names for a specific service — no descriptions, minimal tokens. \
+Step 4 only for services you plan to actually use. \
+Use credentials="available" at any step to filter to tools whose credentials are already configured.
 
 # Discovery & Design Workflow
 
@@ -299,9 +307,31 @@ Present a short **Framework Fit Assessment**:
 - **Gaps/Deal-breakers**: Only list genuinely missing capabilities after checking \
 both list_agent_tools() and built-in features like GCU
 
-## 3: Design Graph and Propose
+### Credential Check (MANDATORY)
 
-Act like an experienced AI solution architect Design the agent architecture:
+The summary from list_agent_tools() includes `credentials_required` and \
+`credentials_available` per provider. **Before designing the graph**, check \
+which providers the design will need and whether credentials are available.
+
+For each provider whose tools you plan to use and where \
+`credentials_available` is false:
+- Tell the user which credential is missing and what it's needed for
+- Ask if they have access to set it up (e.g., API key, OAuth, service account)
+- If they don't have access, adjust the design to work without that provider \
+or suggest alternatives
+
+**Do NOT proceed to the design step with tools that require unavailable \
+credentials without the user acknowledging it.** Finding out at runtime that \
+credentials are missing wastes everyone's time. Surface this early.
+
+Example:
+> "The design needs Google Sheets tools, but the `google` credential isn't \
+configured yet. Do you have a Google service account or OAuth credentials \
+you can set up? If not, I can use CSV file output instead."
+
+## 3: Design Graph and Create Draft
+
+Act like an experienced AI solution architect. Design the agent architecture:
 - Goal: id, name, description, 3-5 success criteria, 2-4 constraints
 - Nodes: **3-6 nodes** (HARD RULE: never fewer than 3, never more than 6). \
 2 nodes is ALWAYS wrong — it means you under-decomposed the task. \
@@ -333,9 +363,140 @@ Read reference agents before designing:
   read_file("exports/deep_research_agent/agent.py")
   read_file("exports/deep_research_agent/nodes/__init__.py")
 
-Present the design to the user. Lead with a large ASCII graph inside \
-a code block so it renders in monospace. Make it visually prominent — \
-use box-drawing characters and clear flow arrows:
+**IMPORTANT: Call save_agent_draft() early and often.** \
+The flowchart is a live collaboration artifact, not a final deliverable. \
+Call save_agent_draft() as soon as you have a rough shape — even before \
+all details are finalized. Then **update it interactively** as the \
+conversation progresses:
+
+- After the user gives feedback ("add a validation step", "split that node") \
+→ immediately call save_agent_draft() with the updated graph so they see \
+the change reflected in the visualizer.
+- After you refine your understanding of requirements → update the draft.
+- When the user asks "what about X?" and it changes the design → update.
+- Don't wait until everything is perfect — iterate visually with the user.
+
+The flowchart is the shared canvas. Every structural change should be \
+visible to the user immediately. The draft captures business logic \
+(node purposes, data flow, tools) without requiring executable code. \
+Include in each node: id, name, description, planned tools, \
+input/output keys, and success criteria as high-level hints.
+
+Each node is auto-classified into an ISO 5807 flowchart symbol type \
+with a unique color. You can override auto-detection by setting \
+`flowchart_type` explicitly on a node. Common types:
+
+**Core symbols:**
+- **start** (green, stadium): Entry point / trigger
+- **terminal** (red, stadium): End of flow
+- **process** (blue, rectangle): Standard processing step
+- **decision** (amber, diamond): Conditional branching
+- **io** (purple, parallelogram): External data input/output
+- **document** (blue-grey, wavy rect): Report or document generation
+- **subprocess** (teal, subroutine): Delegated sub-agent / predefined process
+- **preparation** (brown, hexagon): Setup / initialization step
+- **manual_operation** (pink, trapezoid): Human-in-the-loop / manual review
+- **delay** (orange, D-shape): Wait / throttle / cooldown
+- **display** (cyan): Present results to user
+
+**Data storage:**
+- **database** (light green, cylinder): Database or data store
+- **stored_data** (lime): Generic persistent data
+- **internal_storage** (amber): In-memory / cache
+
+**Flow operations:**
+- **merge** (indigo, inv. triangle): Combine multiple inputs
+- **extract** (indigo, triangle): Split or filter data
+- **connector** (grey, circle): On-page link
+- **offpage_connector** (dark grey, pentagon): Cross-page link
+
+**Domain-specific:**
+- **browser** (dark indigo, hexagon): GCU browser automation
+- **subagent** (dark teal, subroutine): Planning-only sub-agent delegation \
+(dissolved into parent's sub_agents at build time)
+
+Auto-detection works well for most cases: first node → start, nodes with \
+no outgoing edges → terminal, nodes with multiple conditional outgoing \
+edges → decision, GCU nodes → browser, nodes mentioning "database" → \
+database, nodes mentioning "report/document" → document, etc. Set \
+flowchart_type explicitly only when auto-detection would be wrong. \
+Note: `subagent` is never auto-detected — you must set it explicitly.
+
+## Decision Nodes — Planning-Only Conditional Branching
+
+Decision nodes (amber diamonds) are **planning-only** visual elements. They \
+let you show explicit conditional logic in the flowchart so the user can see \
+and approve branching behavior. At `confirm_and_build()`, decision nodes are \
+automatically **dissolved** into the runtime graph:
+
+- The decision clause is merged into the predecessor node's `success_criteria`
+- The yes/no edges are rewired as the predecessor's `on_success`/`on_failure` edges
+- The original flowchart (with decision diamonds) is preserved for display
+
+**When to use decision nodes:**
+- When a workflow has a meaningful condition that determines the next step \
+(e.g., "Did we find enough results?", "Is the data valid?", "Amount > $100?")
+- When the branching logic is important for the user to understand and approve
+- When different outcomes lead to genuinely different processing paths
+
+**How to create a decision node:**
+- Set `flowchart_type: "decision"` on the node
+- Set `decision_clause` to the condition text (e.g., "Data passes validation?")
+- Add two outgoing edges with `label: "Yes"` and `label: "No"` pointing \
+to the respective target nodes
+
+**Good flowcharts display conditions explicitly.** During planning, the user \
+sees the full flowchart with decision diamonds. This is different from the \
+building/running phase where conditions are embedded inside node criteria. \
+The flowchart is the user-facing contract — make branching logic visible.
+
+Example with a decision node:
+```
+gather → [Valid data?] →Yes→ transform → deliver
+                       →No→  notify_user
+```
+In the draft: the `[Valid data?]` node has `flowchart_type: "decision"`, \
+`decision_clause: "Data passes validation checks?"`, with labeled yes/no edges.
+
+## Sub-Agent Nodes — Planning-Only Delegation
+
+Sub-agent nodes (dark teal subroutines) are **planning-only** visual elements \
+that show which nodes delegate to sub-agents. At `confirm_and_build()`, \
+sub-agent nodes are **dissolved** into their parent node:
+
+- The sub-agent node's ID is added to the predecessor's `sub_agents` list
+- The sub-agent node and its connecting edge are removed
+- At runtime, the parent node can invoke the sub-agent via `delegate_to_sub_agent`
+
+**Rules for sub-agent nodes (INCLUDING GCU nodes):**
+- Set `flowchart_type: "subagent"` explicitly (never auto-detected)
+- Connect from the managing parent node to the sub-agent node
+- Sub-agent nodes must be **leaf nodes** — NO outgoing edges to other nodes
+- The sub-agent node's ID must match a real node ID in the runtime graph \
+(the node it represents will be invokable as a sub-agent)
+
+**CRITICAL: GCU nodes (`node_type: "gcu"`) are ALWAYS sub-agents.** \
+They MUST NOT appear in the linear flow. NEVER chain GCU nodes \
+sequentially (A → gcu1 → gcu2 → B is WRONG). Instead, attach them \
+as leaves to the parent that orchestrates them:
+```
+WRONG:  intake → gcu_find_prospect → gcu_scan_mutuals → check_results
+RIGHT:  intake (sub_agents: [gcu_find, gcu_scan]) → check_results
+```
+The parent node delegates to its GCU sub-agents and collects results. \
+The main flow continues from the parent, not from the GCU node.
+
+**How to show delegation in the flowchart:**
+```
+research → (deep_searcher)   ← subagent node, leaf
+research → [Enough results?] ← decision node
+```
+After dissolution: `research` node gets `sub_agents: ["deep_searcher"]` \
+and `success_criteria: "Enough results?"`.
+
+After calling save_agent_draft(), also present an ASCII graph in your message \
+alongside a brief summary of each node's purpose. The user sees both the \
+interactive visualizer AND your textual explanation.
 
 ```
 ┌─────────────────────────┐
@@ -371,18 +532,25 @@ When building the agent, design the entry node's `input_keys` to \
 match what the queen will provide at run time. Worker nodes should \
 use `escalate` for blockers.
 
-Follow the graph with a brief summary of each node's purpose. \
-Get user approval before implementing.
+## 4: Get User Confirmation (MANDATORY GATE)
 
-## 4: Get User Confirmation by ask_user
+**This is a hard boundary between planning and building.** \
+You MUST get explicit user approval before ANY code is generated.
 
-**WAIT for user response.** You MUST get explicit user approval before \
-calling `initialize_and_build_agent`.
-- If **Proceed**: Move to implementing (call `initialize_and_build_agent`)
-- If **Adjust scope**: Discuss what to change, update your notes, re-assess if needed
-- If **More questions**: Answer them honestly, then ask again
-- If **Reconsider**: Discuss alternatives. If they decide to proceed anyway, \
-that's their informed choice
+1. Call ask_user() with options like \
+["Approve and build", "Adjust the design", "I have questions"]
+2. **WAIT for user response.** Do NOT proceed without it.
+3. Handle the response:
+   - If **Approve / Proceed**: Call confirm_and_build(), then \
+   initialize_and_build_agent(agent_name, nodes)
+   - If **Adjust scope**: Discuss changes, update the draft with \
+   save_agent_draft() again, and re-ask
+   - If **More questions**: Answer them honestly, then ask again
+   - If **Reconsider**: Discuss alternatives. If they decide to proceed, \
+   that's their informed choice
+
+**NEVER call initialize_and_build_agent without first calling \
+confirm_and_build().** The system will block the transition if you try.
 """
 
 _building_knowledge = """\
@@ -410,11 +578,10 @@ hashline=True for anchors in results
 - undo_changes(path?) — restore from git snapshot
 
 ## Meta-Agent
-- list_agent_tools(server_config_path?, output_schema?, group?) — discover \
-available tools grouped by category. output_schema: "simple" (default, \
-descriptions truncated to ~200 chars) or "full" (complete descriptions + \
-input_schema). group: "all" (default) or a provider like "google". \
-Call FIRST before designing.
+- list_agent_tools(group?, service?, output_schema?, credentials?) — discover tools \
+progressively: no args=provider summary; group+output_schema="summary"=service breakdown; \
+group+service=tool names; group+service+output_schema="full"=full details. \
+credentials="available" filters to configured tools. Call FIRST before designing.
 - validate_agent_package(agent_name) — run ALL validation checks in one call \
 (class validation, runner load, tool validation, tests). Call after building.
 - list_agents() — list all agent packages in exports/ with session counts
@@ -440,7 +607,9 @@ When a user says "my agent is failing" or "debug this agent":
 
 ## 5. Implement
 
-**Please make sure you have propose the design to the user before implementing**
+**You should only reach this step after the user has approved the draft design \
+in the planning phase. The draft metadata will pre-populate descriptions, \
+goals, success criteria, and node metadata in the generated files.**
 
 Call `initialize_and_build_agent(agent_name, nodes)` to generate all package \
 files. The agent_name must be snake_case (e.g., "my_agent"). Pass node names \
@@ -551,24 +720,44 @@ but no write/edit tools.
 - run_command(command, cwd?, timeout?) — Read-only commands only (grep, ls, git log). \
 Never use this to write files, run scripts, or modify the filesystem — transition \
 to BUILDING phase for that.
-- list_agent_tools(server_config_path?, output_schema?, group?) \
-— Discover available tools for design
+- list_agent_tools(server_config_path?, output_schema?, group?, credentials?) \
+— Discover available tools for design (summary → names → full)
 - list_agents() — See existing agent packages for reference
 - list_agent_sessions(agent_name, status?, limit?) — Inspect past runs of an agent
 - list_agent_checkpoints(agent_name, session_id) — View execution history
 - get_agent_checkpoint(agent_name, session_id, checkpoint_id?) — Load a checkpoint
-- initialize_and_build_agent(agent_name?, nodes?) — With agent_name: scaffold a \
-new agent and transition to BUILDING phase. Without agent_name: transition to \
-BUILDING to fix the currently loaded agent (requires a loaded worker).
+
+## Draft Graph Workflow (new agents)
+- save_agent_draft(agent_name, goal, nodes, edges?, terminal_nodes?, ...) — \
+Create an ISO 5807 color-coded flowchart draft. No code is generated. Each \
+node is auto-classified into a standard flowchart symbol (process, decision, \
+document, database, subprocess, etc.) with unique shapes and colors. Set \
+flowchart_type on a node to override. Nodes need only an id. \
+Use decision nodes (flowchart_type: "decision", with decision_clause and \
+labeled yes/no edges) to make conditional branching explicit. \
+Use subagent nodes (flowchart_type: "subagent") as leaf nodes connected \
+to a parent to show sub-agent delegation visually.
+- confirm_and_build() — Record user confirmation of the draft. Dissolves \
+planning-only nodes (decision → predecessor criteria; subagent → predecessor \
+sub_agents list). Call this ONLY after the user explicitly approves via ask_user.
+- initialize_and_build_agent(agent_name?, nodes?) — Scaffold the agent package \
+and transition to BUILDING phase. For new agents, this REQUIRES \
+save_agent_draft() + confirm_and_build() first. The draft metadata is used to \
+pre-populate the generated files. Without agent_name: transition to BUILDING \
+to fix the currently loaded agent (no draft required).
+
+## Loading existing agents
 - load_built_agent(agent_path) — Load an existing agent and switch to STAGING \
 phase. Only use this when the user explicitly asks to work with an existing agent \
 (e.g. "load my_agent", "run the research agent"). Confirm with the user first.
 
-Focus on understanding requirements and proposing an agent architecture \
-with ASCII graph art. Use ask_user to get user approval, then call \
-initialize_and_build_agent to begin building. If the user wants to work with \
-an existing agent instead, use load_built_agent after confirming. \
-If you are diagnosing an existing agent, call initialize_and_build_agent() \
+## Workflow summary
+1. Understand requirements → discover tools → design graph
+2. Call save_agent_draft() to create visual draft → present to user
+3. Call ask_user() to get explicit approval
+4. Call confirm_and_build() to record approval
+5. Call initialize_and_build_agent() to scaffold and start building
+For diagnosis of existing agents, call initialize_and_build_agent() \
 (no args) after agreeing on a fix plan with the user.
 """
 
@@ -583,6 +772,14 @@ list_agents, list_agent_sessions, \
 list_agent_checkpoints, get_agent_checkpoint
 - load_built_agent(agent_path) — Load the agent and switch to STAGING phase
 - list_credentials(credential_id?) — List authorized credentials
+- save_agent_draft(...) — **Re-draft the flowchart during building.** When \
+called during building, planning-only nodes (decision, subagent) are \
+dissolved automatically — no re-confirmation needed. The user sees the \
+updated flowchart immediately. Use this when you make structural changes \
+(add/remove nodes, change edges) so the flowchart stays in sync.
+- replan_agent() — Switch back to PLANNING phase. The previous draft is \
+restored (with decision/subagent nodes intact) so you can edit it. Use \
+when the user requests a major redesign that needs their approval.
 
 When you finish building an agent, call load_built_agent(path) to stage it.
 """
@@ -627,28 +824,44 @@ To just stop without modifying, call stop_worker().
 _queen_behavior_always = """
 # Behavior
 
-## CRITICAL RULE — ask_user tool
+## CRITICAL RULE — ask_user / ask_user_multiple
 
 Every response that ends with a question, a prompt, or expects user \
-input MUST finish with a call to ask_user(prompt, options). \
+input MUST finish with a call to ask_user or ask_user_multiple. \
 The system CANNOT detect that you are waiting for \
-input unless you call ask_user. You MUST call ask_user as the LAST \
+input unless you call one of these tools. You MUST call it as the LAST \
 action in your response.
 
 NEVER end a response with a question in text without calling ask_user. \
 NEVER rely on the user seeing your text and replying — call ask_user.
 
+**When you have 2+ questions**, use ask_user_multiple instead of ask_user. \
+This renders all questions at once so the user answers in one interaction \
+instead of going back and forth. ALWAYS prefer ask_user_multiple when \
+you need to clarify multiple things. \
+**IMPORTANT: When using ask_user_multiple, do NOT repeat the questions \
+in your text response.** The widget renders the questions with options — \
+duplicating them in text wastes the user's time and delays the widget \
+appearing. Keep your text to a brief context/intro sentence only.
+
 Always provide 2-4 short options that cover the most likely answers. \
 The user can always type a custom response.
 
-Examples:
+Examples (single question):
 - ask_user("What do you need?",
   ["Build a new agent", "Run the loaded worker", "Help with code"])
-- ask_user("Which pattern?",
-  ["Simple 3-node", "Rich with feedback", "Custom"])
 - ask_user("Ready to proceed?",
   ["Yes, go ahead", "Let me change something"])
 
+Example (multiple questions — ALWAYS use ask_user_multiple):
+- ask_user_multiple(questions=[
+    {"id": "goal", "prompt": "What should this agent do?"},
+    {"id": "tools", "prompt": "Which integrations?",
+     "options": ["Slack", "Gmail", "Google Sheets"]},
+    {"id": "schedule", "prompt": "How often should it run?",
+     "options": ["On demand", "Every hour", "Daily"]}
+  ])
+
 ## Greeting
 
 When the user greets you, respond concisely (under 10 lines) with worker \
@@ -690,9 +903,26 @@ You are in planning mode. Your job is to:
 3. Discover available tools with list_agent_tools()
 4. Assess framework fit and gaps
 5. Consider multiple approaches and their trade-offs
-6. Design the agent graph and present it as ASCII art
-7. Use ask_user to get explicit user approval and clarify the approach
-8. Call initialize_and_build_agent(agent_name, nodes) to scaffold and start building
+6. Design the agent graph — call save_agent_draft() **as soon as you have a \
+rough shape**, even before finalizing all details
+7. **Iterate on the draft interactively** — every time the user gives feedback \
+that changes the structure, call save_agent_draft() again so they see the \
+update in real-time. The flowchart is a live collaboration tool.
+8. When the design is stable, use ask_user to get explicit approval
+9. Call confirm_and_build() after the user approves
+10. Call initialize_and_build_agent(agent_name, nodes) to scaffold and start building
+
+**The flowchart is your shared whiteboard.** Don't describe changes in text \
+and then ask "should I update the draft?" — just update it. If the user says \
+"add a validation step," immediately call save_agent_draft() with the new \
+node added. If they say "remove that," update and re-draft. The user should \
+see every structural change reflected in the visualizer as you discuss it.
+
+**CRITICAL: Planning → Building boundary.** You MUST get explicit user \
+confirmation before moving to building. The sequence is:
+  save_agent_draft() → iterate with user → ask_user() → confirm_and_build() → \
+  initialize_and_build_agent()
+Skipping any of these steps will be blocked by the system.
 
 Remember: DO NOT write or edit any files yet. This is a read-only exploration \
 and planning phase. You have read-only tools but no write/edit tools in this \
@@ -745,6 +975,21 @@ run_agent_with_input(task) (if in staging) or load then run (if in building)
 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.
+
+## Keeping the flowchart in sync during building
+
+When you make structural changes to the agent (add/remove/rename nodes, \
+change edges, modify sub-agent assignments), call save_agent_draft() to \
+update the flowchart. During building, this auto-dissolves planning-only \
+nodes without needing user re-confirmation. The user sees the updated \
+flowchart immediately.
+
+- **Minor changes** (add a node, rename, adjust edges): call \
+save_agent_draft() with the updated graph and keep building.
+- **Major redesign** (user requests fundamental restructuring): call \
+replan_agent() to go back to planning. The previous draft is restored \
+so you can edit it with the user rather than starting from scratch. \
+After they approve, confirm_and_build() → continue building.
 """
 
 # -- STAGING phase behavior --
@@ -931,8 +1176,10 @@ _queen_tools_docs = (
     + "\n\n### RUNNING phase (worker is executing)\n"
     + _queen_tools_running.strip()
     + "\n\n### Phase transitions\n"
-    "- initialize_and_build_agent(agent_name?, nodes?) → with name: scaffolds package; "
-    "without name: switches to BUILDING for existing agent\n"
+    "- save_agent_draft(...) → creates visual-only draft graph (stays in PLANNING)\n"
+    "- confirm_and_build() → records user approval of draft (stays in PLANNING)\n"
+    "- initialize_and_build_agent(agent_name?, nodes?) → scaffolds package + switches to "
+    "BUILDING (requires draft + confirmation for new agents)\n"
     "- replan_agent() → switches back to PLANNING phase (only when user explicitly requests)\n"
     "- load_built_agent(path) → switches to STAGING phase\n"
     "- run_agent_with_input(task) → starts worker, switches to RUNNING phase\n"

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

@@ -180,7 +180,7 @@ 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}
+loop_config = {"max_iterations": 100, "max_tool_calls_per_turn": 20, "max_context_tokens": 32000}
 
 
 class MyAgent:

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

@@ -226,7 +226,7 @@ Only three valid keys:
 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
+    "max_context_tokens": 32000,    # Triggers conversation compaction
 }
 ```
 **INVALID keys** (do NOT use): `"strategy"`, `"mode"`, `"timeout"`,

core/framework/builder/__init__.py

@@ -1,7 +0,0 @@
-"""Builder interface for analyzing and building agents."""
-
-from framework.builder.query import BuilderQuery
-
-__all__ = [
-    "BuilderQuery",
-]

core/framework/builder/query.py

@@ -1,501 +0,0 @@
-"""
-Builder Query Interface - How I (Builder) analyze agent runs.
-
-This is designed around the questions I need to answer:
-1. What happened? (summaries, narratives)
-2. Why did it fail? (failure analysis, decision traces)
-3. What patterns emerge? (across runs, across nodes)
-4. What should we change? (suggestions)
-"""
-
-from collections import defaultdict
-from pathlib import Path
-from typing import Any
-
-from framework.schemas.decision import Decision
-from framework.schemas.run import Run, RunStatus, RunSummary
-from framework.storage.backend import FileStorage
-
-
-class FailureAnalysis:
-    """Structured analysis of why a run failed."""
-
-    def __init__(
-        self,
-        run_id: str,
-        failure_point: str,
-        root_cause: str,
-        decision_chain: list[str],
-        problems: list[str],
-        suggestions: list[str],
-    ):
-        self.run_id = run_id
-        self.failure_point = failure_point
-        self.root_cause = root_cause
-        self.decision_chain = decision_chain
-        self.problems = problems
-        self.suggestions = suggestions
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "run_id": self.run_id,
-            "failure_point": self.failure_point,
-            "root_cause": self.root_cause,
-            "decision_chain": self.decision_chain,
-            "problems": self.problems,
-            "suggestions": self.suggestions,
-        }
-
-    def __str__(self) -> str:
-        lines = [
-            f"=== Failure Analysis for {self.run_id} ===",
-            "",
-            f"Failure Point: {self.failure_point}",
-            f"Root Cause: {self.root_cause}",
-            "",
-            "Decision Chain Leading to Failure:",
-        ]
-        for i, dec in enumerate(self.decision_chain, 1):
-            lines.append(f"  {i}. {dec}")
-
-        if self.problems:
-            lines.append("")
-            lines.append("Reported Problems:")
-            for prob in self.problems:
-                lines.append(f"  - {prob}")
-
-        if self.suggestions:
-            lines.append("")
-            lines.append("Suggestions:")
-            for sug in self.suggestions:
-                lines.append(f"  → {sug}")
-
-        return "\n".join(lines)
-
-
-class PatternAnalysis:
-    """Patterns detected across multiple runs."""
-
-    def __init__(
-        self,
-        goal_id: str,
-        run_count: int,
-        success_rate: float,
-        common_failures: list[tuple[str, int]],
-        problematic_nodes: list[tuple[str, float]],
-        decision_patterns: dict[str, Any],
-    ):
-        self.goal_id = goal_id
-        self.run_count = run_count
-        self.success_rate = success_rate
-        self.common_failures = common_failures
-        self.problematic_nodes = problematic_nodes
-        self.decision_patterns = decision_patterns
-
-    def to_dict(self) -> dict[str, Any]:
-        return {
-            "goal_id": self.goal_id,
-            "run_count": self.run_count,
-            "success_rate": self.success_rate,
-            "common_failures": self.common_failures,
-            "problematic_nodes": self.problematic_nodes,
-            "decision_patterns": self.decision_patterns,
-        }
-
-    def __str__(self) -> str:
-        lines = [
-            f"=== Pattern Analysis for Goal {self.goal_id} ===",
-            "",
-            f"Runs Analyzed: {self.run_count}",
-            f"Success Rate: {self.success_rate:.1%}",
-        ]
-
-        if self.common_failures:
-            lines.append("")
-            lines.append("Common Failures:")
-            for failure, count in self.common_failures:
-                lines.append(f"  - {failure} ({count} occurrences)")
-
-        if self.problematic_nodes:
-            lines.append("")
-            lines.append("Problematic Nodes (failure rate):")
-            for node, rate in self.problematic_nodes:
-                lines.append(f"  - {node}: {rate:.1%} failure rate")
-
-        return "\n".join(lines)
-
-
-class BuilderQuery:
-    """
-    The interface I (Builder) use to understand what agents are doing.
-
-    This is optimized for the questions I need to answer when analyzing
-    agent behavior and deciding what to improve.
-    """
-
-    def __init__(self, storage_path: str | Path):
-        self.storage = FileStorage(storage_path)
-
-    # === WHAT HAPPENED? ===
-
-    def get_run_summary(self, run_id: str) -> RunSummary | None:
-        """Get a quick summary of a run."""
-        return self.storage.load_summary(run_id)
-
-    def get_full_run(self, run_id: str) -> Run | None:
-        """Get the complete run with all decisions."""
-        return self.storage.load_run(run_id)
-
-    def list_runs_for_goal(self, goal_id: str) -> list[RunSummary]:
-        """Get summaries of all runs for a goal."""
-        run_ids = self.storage.get_runs_by_goal(goal_id)
-        summaries = []
-        for run_id in run_ids:
-            summary = self.storage.load_summary(run_id)
-            if summary:
-                summaries.append(summary)
-        return summaries
-
-    def get_recent_failures(self, limit: int = 10) -> list[RunSummary]:
-        """Get recent failed runs."""
-        run_ids = self.storage.get_runs_by_status(RunStatus.FAILED)
-        summaries = []
-        for run_id in run_ids[:limit]:
-            summary = self.storage.load_summary(run_id)
-            if summary:
-                summaries.append(summary)
-        return summaries
-
-    # === WHY DID IT FAIL? ===
-
-    def analyze_failure(self, run_id: str) -> FailureAnalysis | None:
-        """
-        Deep analysis of why a run failed.
-
-        This is my primary tool for understanding what went wrong.
-        """
-        run = self.storage.load_run(run_id)
-        if run is None or run.status != RunStatus.FAILED:
-            return None
-
-        # Find the first failed decision
-        failed_decisions = [d for d in run.decisions if not d.was_successful]
-        if not failed_decisions:
-            failure_point = "Unknown - no decision marked as failed"
-            root_cause = "Run failed but all decisions succeeded (external cause?)"
-        else:
-            first_failure = failed_decisions[0]
-            failure_point = first_failure.summary_for_builder()
-            root_cause = first_failure.outcome.error if first_failure.outcome else "Unknown"
-
-        # Build the decision chain leading to failure
-        decision_chain = []
-        for d in run.decisions:
-            decision_chain.append(d.summary_for_builder())
-            if not d.was_successful:
-                break
-
-        # Extract problems
-        problems = [f"[{p.severity}] {p.description}" for p in run.problems]
-
-        # Generate suggestions based on the failure
-        suggestions = self._generate_suggestions(run, failed_decisions)
-
-        return FailureAnalysis(
-            run_id=run_id,
-            failure_point=failure_point,
-            root_cause=root_cause,
-            decision_chain=decision_chain,
-            problems=problems,
-            suggestions=suggestions,
-        )
-
-    def get_decision_trace(self, run_id: str) -> list[str]:
-        """Get a readable trace of all decisions in a run."""
-        run = self.storage.load_run(run_id)
-        if run is None:
-            return []
-        return [d.summary_for_builder() for d in run.decisions]
-
-    # === WHAT PATTERNS EMERGE? ===
-
-    def find_patterns(self, goal_id: str) -> PatternAnalysis | None:
-        """
-        Find patterns across runs for a goal.
-
-        This helps me understand systemic issues vs one-off failures.
-        """
-        run_ids = self.storage.get_runs_by_goal(goal_id)
-        if not run_ids:
-            return None
-
-        runs = []
-        for run_id in run_ids:
-            run = self.storage.load_run(run_id)
-            if run:
-                runs.append(run)
-
-        if not runs:
-            return None
-
-        # Calculate success rate
-        completed = [r for r in runs if r.status == RunStatus.COMPLETED]
-        success_rate = len(completed) / len(runs) if runs else 0.0
-
-        # Find common failures
-        failure_counts: dict[str, int] = defaultdict(int)
-        for run in runs:
-            for decision in run.decisions:
-                if not decision.was_successful and decision.outcome:
-                    error = decision.outcome.error or "Unknown error"
-                    failure_counts[error] += 1
-
-        common_failures = sorted(failure_counts.items(), key=lambda x: x[1], reverse=True)[:5]
-
-        # Find problematic nodes
-        node_stats: dict[str, dict[str, int]] = defaultdict(lambda: {"total": 0, "failed": 0})
-        for run in runs:
-            for decision in run.decisions:
-                node_stats[decision.node_id]["total"] += 1
-                if not decision.was_successful:
-                    node_stats[decision.node_id]["failed"] += 1
-
-        problematic_nodes = []
-        for node_id, stats in node_stats.items():
-            if stats["total"] > 0:
-                failure_rate = stats["failed"] / stats["total"]
-                if failure_rate > 0.1:  # More than 10% failure rate
-                    problematic_nodes.append((node_id, failure_rate))
-
-        problematic_nodes.sort(key=lambda x: x[1], reverse=True)
-
-        # Decision patterns
-        decision_patterns = self._analyze_decision_patterns(runs)
-
-        return PatternAnalysis(
-            goal_id=goal_id,
-            run_count=len(runs),
-            success_rate=success_rate,
-            common_failures=common_failures,
-            problematic_nodes=problematic_nodes,
-            decision_patterns=decision_patterns,
-        )
-
-    def compare_runs(self, run_id_1: str, run_id_2: str) -> dict[str, Any]:
-        """Compare two runs to understand what differed."""
-        run1 = self.storage.load_run(run_id_1)
-        run2 = self.storage.load_run(run_id_2)
-
-        if run1 is None or run2 is None:
-            return {"error": "One or both runs not found"}
-
-        return {
-            "run_1": {
-                "id": run1.id,
-                "status": run1.status.value,
-                "decisions": len(run1.decisions),
-                "success_rate": run1.metrics.success_rate,
-            },
-            "run_2": {
-                "id": run2.id,
-                "status": run2.status.value,
-                "decisions": len(run2.decisions),
-                "success_rate": run2.metrics.success_rate,
-            },
-            "differences": self._find_differences(run1, run2),
-        }
-
-    # === WHAT SHOULD WE CHANGE? ===
-
-    def suggest_improvements(self, goal_id: str) -> list[dict[str, Any]]:
-        """
-        Generate improvement suggestions based on run analysis.
-
-        This is what I use to propose changes to the human engineer.
-        """
-        patterns = self.find_patterns(goal_id)
-        if patterns is None:
-            return []
-
-        suggestions = []
-
-        # Suggestion: Fix problematic nodes
-        for node_id, failure_rate in patterns.problematic_nodes:
-            suggestions.append(
-                {
-                    "type": "node_improvement",
-                    "target": node_id,
-                    "reason": f"Node has {failure_rate:.1%} failure rate",
-                    "recommendation": (
-                        f"Review and improve node '{node_id}' - "
-                        "high failure rate suggests prompt or tool issues"
-                    ),
-                    "priority": "high" if failure_rate > 0.3 else "medium",
-                }
-            )
-
-        # Suggestion: Address common failures
-        for failure, count in patterns.common_failures:
-            if count >= 2:
-                suggestions.append(
-                    {
-                        "type": "error_handling",
-                        "target": failure,
-                        "reason": f"Error occurred {count} times",
-                        "recommendation": f"Add handling for: {failure}",
-                        "priority": "high" if count >= 5 else "medium",
-                    }
-                )
-
-        # Suggestion: Overall success rate
-        if patterns.success_rate < 0.8:
-            suggestions.append(
-                {
-                    "type": "architecture",
-                    "target": goal_id,
-                    "reason": f"Goal success rate is only {patterns.success_rate:.1%}",
-                    "recommendation": (
-                        "Consider restructuring the agent graph or improving goal definition"
-                    ),
-                    "priority": "high",
-                }
-            )
-
-        return suggestions
-
-    def get_node_performance(self, node_id: str) -> dict[str, Any]:
-        """Get performance metrics for a specific node across all runs."""
-        run_ids = self.storage.get_runs_by_node(node_id)
-
-        total_decisions = 0
-        successful_decisions = 0
-        total_latency = 0
-        total_tokens = 0
-        decision_types: dict[str, int] = defaultdict(int)
-
-        for run_id in run_ids:
-            run = self.storage.load_run(run_id)
-            if run:
-                for decision in run.decisions:
-                    if decision.node_id == node_id:
-                        total_decisions += 1
-                        if decision.was_successful:
-                            successful_decisions += 1
-                        if decision.outcome:
-                            total_latency += decision.outcome.latency_ms
-                            total_tokens += decision.outcome.tokens_used
-                        decision_types[decision.decision_type.value] += 1
-
-        return {
-            "node_id": node_id,
-            "total_decisions": total_decisions,
-            "success_rate": successful_decisions / total_decisions if total_decisions > 0 else 0,
-            "avg_latency_ms": total_latency / total_decisions if total_decisions > 0 else 0,
-            "total_tokens": total_tokens,
-            "decision_type_distribution": dict(decision_types),
-        }
-
-    # === PRIVATE HELPERS ===
-
-    def _generate_suggestions(
-        self,
-        run: Run,
-        failed_decisions: list[Decision],
-    ) -> list[str]:
-        """Generate suggestions based on failure analysis."""
-        suggestions = []
-
-        for decision in failed_decisions:
-            # Check if there were alternatives
-            if len(decision.options) > 1:
-                chosen = decision.chosen_option
-                alternatives = [o for o in decision.options if o.id != decision.chosen_option_id]
-                if alternatives:
-                    alt_desc = alternatives[0].description
-                    chosen_desc = chosen.description if chosen else "unknown"
-                    suggestions.append(
-                        f"Consider alternative: '{alt_desc}' instead of '{chosen_desc}'"
-                    )
-
-            # Check for missing context
-            if not decision.input_context:
-                suggestions.append(
-                    f"Decision '{decision.intent}' had no input context - "
-                    "ensure relevant data is passed"
-                )
-
-            # Check for constraint issues
-            if decision.active_constraints:
-                constraints = ", ".join(decision.active_constraints)
-                suggestions.append(f"Review constraints: {constraints} - may be too restrictive")
-
-        # Check for reported problems with suggestions
-        for problem in run.problems:
-            if problem.suggested_fix:
-                suggestions.append(problem.suggested_fix)
-
-        return suggestions
-
-    def _analyze_decision_patterns(self, runs: list[Run]) -> dict[str, Any]:
-        """Analyze decision patterns across runs."""
-        type_counts: dict[str, int] = defaultdict(int)
-        option_counts: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
-
-        for run in runs:
-            for decision in run.decisions:
-                type_counts[decision.decision_type.value] += 1
-
-                # Track which options are chosen for similar intents
-                intent_key = decision.intent[:50]  # Truncate for grouping
-                if decision.chosen_option:
-                    option_counts[intent_key][decision.chosen_option.description] += 1
-
-        # Find most common choices per intent
-        common_choices = {}
-        for intent, choices in option_counts.items():
-            if choices:
-                most_common = max(choices.items(), key=lambda x: x[1])
-                common_choices[intent] = {
-                    "choice": most_common[0],
-                    "count": most_common[1],
-                    "alternatives": len(choices) - 1,
-                }
-
-        return {
-            "decision_type_distribution": dict(type_counts),
-            "common_choices": common_choices,
-        }
-
-    def _find_differences(self, run1: Run, run2: Run) -> list[str]:
-        """Find key differences between two runs."""
-        differences = []
-
-        # Status difference
-        if run1.status != run2.status:
-            differences.append(f"Status: {run1.status.value} vs {run2.status.value}")
-
-        # Decision count difference
-        if len(run1.decisions) != len(run2.decisions):
-            differences.append(f"Decision count: {len(run1.decisions)} vs {len(run2.decisions)}")
-
-        # Find first divergence point
-        for i, (d1, d2) in enumerate(zip(run1.decisions, run2.decisions, strict=False)):
-            if d1.chosen_option_id != d2.chosen_option_id:
-                differences.append(
-                    f"Diverged at decision {i}: "
-                    f"chose '{d1.chosen_option_id}' vs '{d2.chosen_option_id}'"
-                )
-                break
-
-        # Node differences
-        nodes1 = set(run1.metrics.nodes_executed)
-        nodes2 = set(run2.metrics.nodes_executed)
-        if nodes1 != nodes2:
-            only_1 = nodes1 - nodes2
-            only_2 = nodes2 - nodes1
-            if only_1:
-                differences.append(f"Nodes only in run 1: {only_1}")
-            if only_2:
-                differences.append(f"Nodes only in run 2: {only_2}")
-
-        return differences

core/framework/config.py

@@ -56,6 +56,14 @@ def get_max_tokens() -> int:
     return get_hive_config().get("llm", {}).get("max_tokens", DEFAULT_MAX_TOKENS)
 
 
+DEFAULT_MAX_CONTEXT_TOKENS = 32_000
+
+
+def get_max_context_tokens() -> int:
+    """Return the configured max_context_tokens, falling back to DEFAULT_MAX_CONTEXT_TOKENS."""
+    return get_hive_config().get("llm", {}).get("max_context_tokens", DEFAULT_MAX_CONTEXT_TOKENS)
+
+
 def get_api_key() -> str | None:
     """Return the API key, supporting env var, Claude Code subscription, Codex, and ZAI Code.
 
@@ -90,6 +98,17 @@ def get_api_key() -> str | None:
         except ImportError:
             pass
 
+    # Kimi Code subscription: read API key from ~/.kimi/config.toml
+    if llm.get("use_kimi_code_subscription"):
+        try:
+            from framework.runner.runner import get_kimi_code_token
+
+            token = get_kimi_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:
@@ -108,6 +127,9 @@ def get_api_base() -> str | None:
     if llm.get("use_codex_subscription"):
         # Codex subscription routes through the ChatGPT backend, not api.openai.com.
         return "https://chatgpt.com/backend-api/codex"
+    if llm.get("use_kimi_code_subscription"):
+        # Kimi Code uses an Anthropic-compatible endpoint (no /v1 suffix).
+        return "https://api.kimi.com/coding"
     return llm.get("api_base")
 
 
@@ -164,6 +186,7 @@ class RuntimeConfig:
     model: str = field(default_factory=get_preferred_model)
     temperature: float = 0.7
     max_tokens: int = field(default_factory=get_max_tokens)
+    max_context_tokens: int = field(default_factory=get_max_context_tokens)
     api_key: str | None = field(default_factory=get_api_key)
     api_base: str | None = field(default_factory=get_api_base)
     extra_kwargs: dict[str, Any] = field(default_factory=get_llm_extra_kwargs)

core/framework/credentials/__init__.py

@@ -6,7 +6,7 @@ This module provides secure credential storage with:
 - Template-based usage: {{cred.key}} patterns for injection
 - Bipartisan model: Store stores values, tools define usage
 - Provider system: Extensible lifecycle management (refresh, validate)
-- Multiple backends: Encrypted files, env vars, HashiCorp Vault
+- Multiple backends: Encrypted files, env vars
 
 Quick Start:
     from core.framework.credentials import CredentialStore, CredentialObject
@@ -38,8 +38,6 @@ For Aden server sync:
         AdenSyncProvider,
     )
 
-For Vault integration:
-    from core.framework.credentials.vault import HashiCorpVaultStorage
 """
 
 from .key_storage import (

core/framework/credentials/key_storage.py

@@ -149,8 +149,14 @@ def delete_aden_api_key() -> None:
 
         storage = EncryptedFileStorage()
         storage.delete(ADEN_CREDENTIAL_ID)
+    except (FileNotFoundError, PermissionError) as e:
+        logger.debug("Could not delete %s from encrypted store: %s", ADEN_CREDENTIAL_ID, e)
     except Exception:
-        logger.debug("Could not delete %s from encrypted store", ADEN_CREDENTIAL_ID)
+        logger.warning(
+            "Unexpected error deleting %s from encrypted store",
+            ADEN_CREDENTIAL_ID,
+            exc_info=True,
+        )
 
     os.environ.pop(ADEN_ENV_VAR, None)
 
@@ -167,8 +173,10 @@ def _read_credential_key_file() -> str | None:
             value = CREDENTIAL_KEY_PATH.read_text(encoding="utf-8").strip()
             if value:
                 return value
+    except (FileNotFoundError, PermissionError) as e:
+        logger.debug("Could not read %s: %s", CREDENTIAL_KEY_PATH, e)
     except Exception:
-        logger.debug("Could not read %s", CREDENTIAL_KEY_PATH)
+        logger.warning("Unexpected error reading %s", CREDENTIAL_KEY_PATH, exc_info=True)
     return None
 
 
@@ -196,6 +204,12 @@ def _read_aden_from_encrypted_store() -> str | None:
         cred = storage.load(ADEN_CREDENTIAL_ID)
         if cred:
             return cred.get_key("api_key")
+    except (FileNotFoundError, PermissionError, KeyError) as e:
+        logger.debug("Could not load %s from encrypted store: %s", ADEN_CREDENTIAL_ID, e)
     except Exception:
-        logger.debug("Could not load %s from encrypted store", ADEN_CREDENTIAL_ID)
+        logger.warning(
+            "Unexpected error loading %s from encrypted store",
+            ADEN_CREDENTIAL_ID,
+            exc_info=True,
+        )
     return None

core/framework/credentials/vault/__init__.py

@@ -1,55 +0,0 @@
-"""
-HashiCorp Vault integration for the credential store.
-
-This module provides enterprise-grade secret management through
-HashiCorp Vault integration.
-
-Quick Start:
-    from core.framework.credentials import CredentialStore
-    from core.framework.credentials.vault import HashiCorpVaultStorage
-
-    # Configure Vault storage
-    storage = HashiCorpVaultStorage(
-        url="https://vault.example.com:8200",
-        # token read from VAULT_TOKEN env var
-        mount_point="secret",
-        path_prefix="hive/agents/prod"
-    )
-
-    # Create credential store with Vault backend
-    store = CredentialStore(storage=storage)
-
-    # Use normally - credentials are stored in Vault
-    credential = store.get_credential("my_api")
-
-Requirements:
-    pip install hvac
-
-Authentication:
-    Set the VAULT_TOKEN environment variable or pass the token directly:
-
-        export VAULT_TOKEN="hvs.xxxxxxxxxxxxx"
-
-    For production, consider using Vault auth methods:
-    - Kubernetes auth
-    - AppRole auth
-    - AWS IAM auth
-
-Vault Configuration:
-    Ensure KV v2 secrets engine is enabled:
-
-        vault secrets enable -path=secret kv-v2
-
-    Grant appropriate policies:
-
-        path "secret/data/hive/credentials/*" {
-            capabilities = ["create", "read", "update", "delete", "list"]
-        }
-        path "secret/metadata/hive/credentials/*" {
-            capabilities = ["list", "delete"]
-        }
-"""
-
-from .hashicorp import HashiCorpVaultStorage
-
-__all__ = ["HashiCorpVaultStorage"]

core/framework/credentials/vault/hashicorp.py

@@ -1,394 +0,0 @@
-"""
-HashiCorp Vault storage adapter.
-
-Provides integration with HashiCorp Vault for enterprise secret management.
-Requires the 'hvac' package: uv pip install hvac
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-from datetime import datetime
-from typing import Any
-
-from pydantic import SecretStr
-
-from ..models import CredentialKey, CredentialObject, CredentialType
-from ..storage import CredentialStorage
-
-logger = logging.getLogger(__name__)
-
-
-class HashiCorpVaultStorage(CredentialStorage):
-    """
-    HashiCorp Vault storage adapter.
-
-    Features:
-    - KV v2 secrets engine support
-    - Namespace support (Enterprise)
-    - Automatic secret versioning
-    - Audit logging via Vault
-
-    The adapter stores credentials in Vault's KV v2 secrets engine with
-    the following structure:
-
-        {mount_point}/data/{path_prefix}/{credential_id}
-        └── data:
-            ├── _type: "oauth2"
-            ├── access_token: "xxx"
-            ├── refresh_token: "yyy"
-            ├── _expires_access_token: "2024-01-26T12:00:00"
-            └── _provider_id: "oauth2"
-
-    Example:
-        storage = HashiCorpVaultStorage(
-            url="https://vault.example.com:8200",
-            token="hvs.xxx",  # Or use VAULT_TOKEN env var
-            mount_point="secret",
-            path_prefix="hive/credentials"
-        )
-
-        store = CredentialStore(storage=storage)
-
-        # Credentials are now stored in Vault
-        store.save_credential(credential)
-        credential = store.get_credential("my_api")
-
-    Authentication:
-        The adapter uses token-based authentication. The token can be provided:
-        1. Directly via the 'token' parameter
-        2. Via the VAULT_TOKEN environment variable
-
-        For production, consider using:
-        - Kubernetes auth method
-        - AppRole auth method
-        - AWS IAM auth method
-
-    Requirements:
-        uv pip install hvac
-    """
-
-    def __init__(
-        self,
-        url: str,
-        token: str | None = None,
-        mount_point: str = "secret",
-        path_prefix: str = "hive/credentials",
-        namespace: str | None = None,
-        verify_ssl: bool = True,
-    ):
-        """
-        Initialize Vault storage.
-
-        Args:
-            url: Vault server URL (e.g., https://vault.example.com:8200)
-            token: Vault token. If None, reads from VAULT_TOKEN env var
-            mount_point: KV secrets engine mount point (default: "secret")
-            path_prefix: Path prefix for all credentials
-            namespace: Vault namespace (Enterprise feature)
-            verify_ssl: Whether to verify SSL certificates
-
-        Raises:
-            ImportError: If hvac is not installed
-            ValueError: If authentication fails
-        """
-        try:
-            import hvac
-        except ImportError as e:
-            raise ImportError(
-                "HashiCorp Vault support requires 'hvac'. Install with: uv pip install hvac"
-            ) from e
-
-        self._url = url
-        self._token = token or os.environ.get("VAULT_TOKEN")
-        self._mount = mount_point
-        self._prefix = path_prefix
-        self._namespace = namespace
-
-        if not self._token:
-            raise ValueError(
-                "Vault token required. Set VAULT_TOKEN env var or pass token parameter."
-            )
-
-        self._client = hvac.Client(
-            url=url,
-            token=self._token,
-            namespace=namespace,
-            verify=verify_ssl,
-        )
-
-        if not self._client.is_authenticated():
-            raise ValueError("Vault authentication failed. Check token and server URL.")
-
-        logger.info(f"Connected to HashiCorp Vault at {url}")
-
-    def _path(self, credential_id: str) -> str:
-        """Build Vault path for credential."""
-        # Sanitize credential_id
-        safe_id = credential_id.replace("/", "_").replace("\\", "_")
-        return f"{self._prefix}/{safe_id}"
-
-    def save(self, credential: CredentialObject) -> None:
-        """Save credential to Vault KV v2."""
-        path = self._path(credential.id)
-        data = self._serialize_for_vault(credential)
-
-        try:
-            self._client.secrets.kv.v2.create_or_update_secret(
-                path=path,
-                secret=data,
-                mount_point=self._mount,
-            )
-            logger.debug(f"Saved credential '{credential.id}' to Vault at {path}")
-        except Exception as e:
-            logger.error(f"Failed to save credential '{credential.id}' to Vault: {e}")
-            raise
-
-    def load(self, credential_id: str) -> CredentialObject | None:
-        """Load credential from Vault."""
-        path = self._path(credential_id)
-
-        try:
-            response = self._client.secrets.kv.v2.read_secret_version(
-                path=path,
-                mount_point=self._mount,
-            )
-            data = response["data"]["data"]
-            return self._deserialize_from_vault(credential_id, data)
-        except Exception as e:
-            # Check if it's a "not found" error
-            error_str = str(e).lower()
-            if "not found" in error_str or "404" in error_str:
-                logger.debug(f"Credential '{credential_id}' not found in Vault")
-                return None
-            logger.error(f"Failed to load credential '{credential_id}' from Vault: {e}")
-            raise
-
-    def delete(self, credential_id: str) -> bool:
-        """Delete credential from Vault (all versions)."""
-        path = self._path(credential_id)
-
-        try:
-            self._client.secrets.kv.v2.delete_metadata_and_all_versions(
-                path=path,
-                mount_point=self._mount,
-            )
-            logger.debug(f"Deleted credential '{credential_id}' from Vault")
-            return True
-        except Exception as e:
-            error_str = str(e).lower()
-            if "not found" in error_str or "404" in error_str:
-                return False
-            logger.error(f"Failed to delete credential '{credential_id}' from Vault: {e}")
-            raise
-
-    def list_all(self) -> list[str]:
-        """List all credentials under the prefix."""
-        try:
-            response = self._client.secrets.kv.v2.list_secrets(
-                path=self._prefix,
-                mount_point=self._mount,
-            )
-            keys = response.get("data", {}).get("keys", [])
-            # Remove trailing slashes from folder names
-            return [k.rstrip("/") for k in keys]
-        except Exception as e:
-            error_str = str(e).lower()
-            if "not found" in error_str or "404" in error_str:
-                return []
-            logger.error(f"Failed to list credentials from Vault: {e}")
-            raise
-
-    def exists(self, credential_id: str) -> bool:
-        """Check if credential exists in Vault."""
-        try:
-            path = self._path(credential_id)
-            self._client.secrets.kv.v2.read_secret_version(
-                path=path,
-                mount_point=self._mount,
-            )
-            return True
-        except Exception:
-            return False
-
-    def _serialize_for_vault(self, credential: CredentialObject) -> dict[str, Any]:
-        """Convert credential to Vault secret format."""
-        data: dict[str, Any] = {
-            "_type": credential.credential_type.value,
-        }
-
-        if credential.provider_id:
-            data["_provider_id"] = credential.provider_id
-
-        if credential.description:
-            data["_description"] = credential.description
-
-        if credential.auto_refresh:
-            data["_auto_refresh"] = "true"
-
-        # Store each key
-        for key_name, key in credential.keys.items():
-            data[key_name] = key.get_secret_value()
-
-            if key.expires_at:
-                data[f"_expires_{key_name}"] = key.expires_at.isoformat()
-
-            if key.metadata:
-                data[f"_metadata_{key_name}"] = str(key.metadata)
-
-        return data
-
-    def _deserialize_from_vault(self, credential_id: str, data: dict[str, Any]) -> CredentialObject:
-        """Reconstruct credential from Vault secret."""
-        # Extract metadata fields
-        cred_type = CredentialType(data.pop("_type", "api_key"))
-        provider_id = data.pop("_provider_id", None)
-        description = data.pop("_description", "")
-        auto_refresh = data.pop("_auto_refresh", "") == "true"
-
-        # Build keys dict
-        keys: dict[str, CredentialKey] = {}
-
-        # Find all non-metadata keys
-        key_names = [k for k in data.keys() if not k.startswith("_")]
-
-        for key_name in key_names:
-            value = data[key_name]
-
-            # Check for expiration
-            expires_at = None
-            expires_key = f"_expires_{key_name}"
-            if expires_key in data:
-                try:
-                    expires_at = datetime.fromisoformat(data[expires_key])
-                except (ValueError, TypeError):
-                    pass
-
-            # Check for metadata
-            metadata: dict[str, Any] = {}
-            metadata_key = f"_metadata_{key_name}"
-            if metadata_key in data:
-                try:
-                    import ast
-
-                    metadata = ast.literal_eval(data[metadata_key])
-                except (ValueError, SyntaxError):
-                    pass
-
-            keys[key_name] = CredentialKey(
-                name=key_name,
-                value=SecretStr(value),
-                expires_at=expires_at,
-                metadata=metadata,
-            )
-
-        return CredentialObject(
-            id=credential_id,
-            credential_type=cred_type,
-            keys=keys,
-            provider_id=provider_id,
-            description=description,
-            auto_refresh=auto_refresh,
-        )
-
-    # --- Vault-Specific Operations ---
-
-    def get_secret_metadata(self, credential_id: str) -> dict[str, Any] | None:
-        """
-        Get Vault metadata for a secret (version info, timestamps, etc.).
-
-        Args:
-            credential_id: The credential identifier
-
-        Returns:
-            Metadata dict or None if not found
-        """
-        path = self._path(credential_id)
-
-        try:
-            response = self._client.secrets.kv.v2.read_secret_metadata(
-                path=path,
-                mount_point=self._mount,
-            )
-            return response.get("data", {})
-        except Exception:
-            return None
-
-    def soft_delete(self, credential_id: str, versions: list[int] | None = None) -> bool:
-        """
-        Soft delete specific versions (can be recovered).
-
-        Args:
-            credential_id: The credential identifier
-            versions: Version numbers to delete. If None, deletes latest.
-
-        Returns:
-            True if successful
-        """
-        path = self._path(credential_id)
-
-        try:
-            if versions:
-                self._client.secrets.kv.v2.delete_secret_versions(
-                    path=path,
-                    versions=versions,
-                    mount_point=self._mount,
-                )
-            else:
-                self._client.secrets.kv.v2.delete_latest_version_of_secret(
-                    path=path,
-                    mount_point=self._mount,
-                )
-            return True
-        except Exception as e:
-            logger.error(f"Soft delete failed for '{credential_id}': {e}")
-            return False
-
-    def undelete(self, credential_id: str, versions: list[int]) -> bool:
-        """
-        Recover soft-deleted versions.
-
-        Args:
-            credential_id: The credential identifier
-            versions: Version numbers to recover
-
-        Returns:
-            True if successful
-        """
-        path = self._path(credential_id)
-
-        try:
-            self._client.secrets.kv.v2.undelete_secret_versions(
-                path=path,
-                versions=versions,
-                mount_point=self._mount,
-            )
-            return True
-        except Exception as e:
-            logger.error(f"Undelete failed for '{credential_id}': {e}")
-            return False
-
-    def load_version(self, credential_id: str, version: int) -> CredentialObject | None:
-        """
-        Load a specific version of a credential.
-
-        Args:
-            credential_id: The credential identifier
-            version: Version number to load
-
-        Returns:
-            CredentialObject or None
-        """
-        path = self._path(credential_id)
-
-        try:
-            response = self._client.secrets.kv.v2.read_secret_version(
-                path=path,
-                version=version,
-                mount_point=self._mount,
-            )
-            data = response["data"]["data"]
-            return self._deserialize_from_vault(credential_id, data)
-        except Exception:
-            return None

core/framework/graph/conversation.py

@@ -307,13 +307,13 @@ class NodeConversation:
     def __init__(
         self,
         system_prompt: str = "",
-        max_history_tokens: int = 32000,
+        max_context_tokens: int = 32000,
         compaction_threshold: float = 0.8,
         output_keys: list[str] | None = None,
         store: ConversationStore | None = None,
     ) -> None:
         self._system_prompt = system_prompt
-        self._max_history_tokens = max_history_tokens
+        self._max_context_tokens = max_context_tokens
         self._compaction_threshold = compaction_threshold
         self._output_keys = output_keys
         self._store = store
@@ -525,16 +525,16 @@ class NodeConversation:
         self._last_api_input_tokens = actual_input_tokens
 
     def usage_ratio(self) -> float:
-        """Current token usage as a fraction of *max_history_tokens*.
+        """Current token usage as a fraction of *max_context_tokens*.
 
-        Returns 0.0 when ``max_history_tokens`` is zero (unlimited).
+        Returns 0.0 when ``max_context_tokens`` is zero (unlimited).
         """
-        if self._max_history_tokens <= 0:
+        if self._max_context_tokens <= 0:
             return 0.0
-        return self.estimate_tokens() / self._max_history_tokens
+        return self.estimate_tokens() / self._max_context_tokens
 
     def needs_compaction(self) -> bool:
-        return self.estimate_tokens() >= self._max_history_tokens * self._compaction_threshold
+        return self.estimate_tokens() >= self._max_context_tokens * self._compaction_threshold
 
     # --- Output-key extraction ---------------------------------------------
 
@@ -1029,7 +1029,7 @@ class NodeConversation:
         await self._store.write_meta(
             {
                 "system_prompt": self._system_prompt,
-                "max_history_tokens": self._max_history_tokens,
+                "max_context_tokens": self._max_context_tokens,
                 "compaction_threshold": self._compaction_threshold,
                 "output_keys": self._output_keys,
             }
@@ -1062,7 +1062,7 @@ class NodeConversation:
 
         conv = cls(
             system_prompt=meta.get("system_prompt", ""),
-            max_history_tokens=meta.get("max_history_tokens", 32000),
+            max_context_tokens=meta.get("max_context_tokens", 32000),
             compaction_threshold=meta.get("compaction_threshold", 0.8),
             output_keys=meta.get("output_keys"),
             store=store,

core/framework/graph/conversation_judge.py

@@ -37,7 +37,7 @@ async def evaluate_phase_completion(
     phase_description: str,
     success_criteria: str,
     accumulator_state: dict[str, Any],
-    max_history_tokens: int = 8_196,
+    max_context_tokens: int = 8_196,
 ) -> PhaseVerdict:
     """Level 2 judge: read the conversation and evaluate quality.
 
@@ -50,7 +50,7 @@ async def evaluate_phase_completion(
         phase_description: Description of the phase
         success_criteria: Natural-language criteria for phase completion
         accumulator_state: Current output key values
-        max_history_tokens: Main conversation token budget (judge gets 20%)
+        max_context_tokens: Main conversation token budget (judge gets 20%)
 
     Returns:
         PhaseVerdict with action and optional feedback
@@ -89,7 +89,7 @@ FEEDBACK: (reason if RETRY, empty if ACCEPT)"""
         response = await llm.acomplete(
             messages=[{"role": "user", "content": user_prompt}],
             system=system_prompt,
-            max_tokens=max(1024, max_history_tokens // 5),
+            max_tokens=max(1024, max_context_tokens // 5),
             max_retries=1,
         )
         if not response.content or not response.content.strip():

core/framework/graph/event_loop_node.py

@@ -73,6 +73,7 @@ class _EscalationReceiver:
     def __init__(self) -> None:
         self._event = asyncio.Event()
         self._response: str | None = None
+        self._awaiting_input = True  # So inject_worker_message() can prefer us
 
     async def inject_event(self, content: str, *, is_client_input: bool = False) -> None:
         """Called by ExecutionStream.inject_input() when the user responds."""
@@ -134,7 +135,7 @@ class SubagentJudge:
     async def evaluate(self, context: dict[str, Any]) -> JudgeVerdict:
         missing = context.get("missing_keys", [])
         if not missing:
-            return JudgeVerdict(action="ACCEPT")
+            return JudgeVerdict(action="ACCEPT", feedback="")
 
         iteration = context.get("iteration", 0)
         remaining = self._max_iterations - iteration - 1
@@ -169,7 +170,7 @@ class LoopConfig:
     judge_every_n_turns: int = 1
     stall_detection_threshold: int = 3
     stall_similarity_threshold: float = 0.85
-    max_history_tokens: int = 32_000
+    max_context_tokens: int = 32_000
     store_prefix: str = ""
 
     # Overflow margin for max_tool_calls_per_turn.  Tool calls are only
@@ -511,7 +512,7 @@ class EventLoopNode(NodeProtocol):
 
                 conversation = NodeConversation(
                     system_prompt=system_prompt,
-                    max_history_tokens=self._config.max_history_tokens,
+                    max_context_tokens=self._config.max_context_tokens,
                     output_keys=ctx.node_spec.output_keys or None,
                     store=self._conversation_store,
                 )
@@ -548,6 +549,8 @@ class EventLoopNode(NodeProtocol):
             tools.append(set_output_tool)
         if ctx.node_spec.client_facing and not ctx.event_triggered:
             tools.append(self._build_ask_user_tool())
+            if stream_id == "queen":
+                tools.append(self._build_ask_user_multiple_tool())
         # Workers/subagents can escalate blockers to the queen.
         if stream_id not in ("queen", "judge"):
             tools.append(self._build_escalate_tool())
@@ -634,6 +637,7 @@ class EventLoopNode(NodeProtocol):
                 _synthetic_names = {
                     "set_output",
                     "ask_user",
+                    "ask_user_multiple",
                     "escalate",
                     "delegate_to_sub_agent",
                     "report_to_parent",
@@ -684,6 +688,7 @@ class EventLoopNode(NodeProtocol):
                         queen_input_requested,
                         request_system_prompt,
                         request_messages,
+                        reported_to_parent,
                     ) = await self._run_single_turn(
                         ctx, conversation, tools, iteration, accumulator
                     )
@@ -710,6 +715,7 @@ class EventLoopNode(NodeProtocol):
                         model=turn_tokens.get("model", ""),
                         input_tokens=turn_tokens.get("input", 0),
                         output_tokens=turn_tokens.get("output", 0),
+                        cached_tokens=turn_tokens.get("cached", 0),
                         execution_id=execution_id,
                         iteration=iteration,
                     )
@@ -885,6 +891,7 @@ class EventLoopNode(NodeProtocol):
                 and not outputs_set
                 and not user_input_requested
                 and not queen_input_requested
+                and not reported_to_parent
             )
             if truly_empty and accumulator is not None:
                 missing = self._get_missing_output_keys(
@@ -1055,7 +1062,9 @@ class EventLoopNode(NodeProtocol):
             mcp_tool_calls = [
                 tc
                 for tc in logged_tool_calls
-                if tc.get("tool_name") not in ("set_output", "ask_user", "escalate")
+                if tc.get("tool_name") not in (
+                    "set_output", "ask_user", "ask_user_multiple", "escalate",
+                )
             ]
             if mcp_tool_calls:
                 fps = self._fingerprint_tool_calls(mcp_tool_calls)
@@ -1249,8 +1258,12 @@ class EventLoopNode(NodeProtocol):
                     iteration,
                     _cf_auto,
                 )
+                # Check for multi-question batch from ask_user_multiple
+                multi_qs = getattr(self, "_pending_multi_questions", None)
+                self._pending_multi_questions = None
                 got_input = await self._await_user_input(
-                    ctx, prompt=_cf_prompt, options=ask_user_options
+                    ctx, prompt=_cf_prompt, options=ask_user_options,
+                    questions=multi_qs,
                 )
                 logger.info("[%s] iter=%d: unblocked, got_input=%s", node_id, iteration, got_input)
                 if not got_input:
@@ -1733,6 +1746,7 @@ class EventLoopNode(NodeProtocol):
         prompt: str = "",
         *,
         options: list[str] | None = None,
+        questions: list[dict] | None = None,
         emit_client_request: bool = True,
     ) -> bool:
         """Block until user input arrives or shutdown is signaled.
@@ -1747,6 +1761,8 @@ class EventLoopNode(NodeProtocol):
             options: Optional predefined choices for the user (from ask_user).
                 Passed through to the CLIENT_INPUT_REQUESTED event so the
                 frontend can render a QuestionWidget with buttons.
+            questions: Optional list of question dicts for ask_user_multiple.
+                Each dict has id, prompt, and optional options.
             emit_client_request: When False, wait silently without publishing
                 CLIENT_INPUT_REQUESTED. Used for worker waits where input is
                 expected from the queen via inject_worker_message().
@@ -1771,6 +1787,7 @@ class EventLoopNode(NodeProtocol):
                 prompt=prompt,
                 execution_id=ctx.execution_id or "",
                 options=options,
+                questions=questions,
             )
 
         self._awaiting_input = True
@@ -1803,12 +1820,13 @@ class EventLoopNode(NodeProtocol):
         bool,
         str,
         list[dict[str, Any]],
+        bool,
     ]:
         """Run a single LLM turn with streaming and tool execution.
 
         Returns (assistant_text, real_tool_results, outputs_set, token_counts, logged_tool_calls,
         user_input_requested, ask_user_prompt, ask_user_options, queen_input_requested,
-        system_prompt, messages).
+        system_prompt, messages, reported_to_parent).
 
         ``real_tool_results`` contains only results from actual tools (web_search,
         etc.), NOT from synthetic framework tools such as ``set_output``,
@@ -1829,7 +1847,7 @@ class EventLoopNode(NodeProtocol):
         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}
+        token_counts: dict[str, int] = {"input": 0, "output": 0, "cached": 0}
         tool_call_count = 0
         final_text = ""
         final_system_prompt = conversation.system_prompt
@@ -1840,6 +1858,7 @@ class EventLoopNode(NodeProtocol):
         ask_user_prompt = ""
         ask_user_options: list[str] | None = None
         queen_input_requested = False
+        reported_to_parent = False
         # Accumulate ALL tool calls across inner iterations for L3 logging.
         # Unlike real_tool_results (reset each inner iteration), this persists.
         logged_tool_calls: list[dict] = []
@@ -1909,6 +1928,7 @@ class EventLoopNode(NodeProtocol):
                     elif isinstance(event, FinishEvent):
                         token_counts["input"] += event.input_tokens
                         token_counts["output"] += event.output_tokens
+                        token_counts["cached"] += event.cached_tokens
                         token_counts["stop_reason"] = event.stop_reason
                         token_counts["model"] = event.model
 
@@ -1993,6 +2013,7 @@ class EventLoopNode(NodeProtocol):
                     queen_input_requested,
                     final_system_prompt,
                     final_messages,
+                    reported_to_parent,
                 )
 
             # Execute tool calls — framework tools (set_output, ask_user)
@@ -2136,6 +2157,59 @@ class EventLoopNode(NodeProtocol):
                     )
                     results_by_id[tc.tool_use_id] = result
 
+                elif tc.tool_name == "ask_user_multiple":
+                    # --- Framework-level ask_user_multiple ---
+                    user_input_requested = True
+                    raw_questions = tc.tool_input.get("questions", [])
+                    if not isinstance(raw_questions, list) or len(raw_questions) < 2:
+                        result = ToolResult(
+                            tool_use_id=tc.tool_use_id,
+                            content=(
+                                "ERROR: questions must be an array of at "
+                                "least 2 question objects. Use ask_user "
+                                "for single questions."
+                            ),
+                            is_error=True,
+                        )
+                        results_by_id[tc.tool_use_id] = result
+                        user_input_requested = False
+                        continue
+
+                    # Normalize each question entry
+                    questions: list[dict] = []
+                    for i, q in enumerate(raw_questions):
+                        if not isinstance(q, dict):
+                            continue
+                        qid = str(q.get("id", f"q{i+1}"))
+                        prompt = str(q.get("prompt", ""))
+                        opts = q.get("options", None)
+                        if isinstance(opts, list):
+                            opts = [str(o) for o in opts if o]
+                            if len(opts) < 2:
+                                opts = None
+                        else:
+                            opts = None
+                        questions.append({
+                            "id": qid,
+                            "prompt": prompt,
+                            **({"options": opts} if opts else {}),
+                        })
+
+                    # Store as multi-question prompt/options for
+                    # the event emission path
+                    ask_user_prompt = ""
+                    ask_user_options = None
+                    # Pass the full questions list via a special
+                    # key that the event emitter picks up
+                    self._pending_multi_questions = questions
+
+                    result = ToolResult(
+                        tool_use_id=tc.tool_use_id,
+                        content="Waiting for user input...",
+                        is_error=False,
+                    )
+                    results_by_id[tc.tool_use_id] = result
+
                 elif tc.tool_name == "escalate":
                     # --- Framework-level escalate handling ---
                     reason = str(tc.tool_input.get("reason", "")).strip()
@@ -2194,6 +2268,7 @@ class EventLoopNode(NodeProtocol):
 
                 elif tc.tool_name == "report_to_parent":
                     # --- Report from sub-agent to parent (optionally blocking) ---
+                    reported_to_parent = True
                     msg = tc.tool_input.get("message", "")
                     data = tc.tool_input.get("data")
                     wait = tc.tool_input.get("wait_for_response", False)
@@ -2381,6 +2456,7 @@ class EventLoopNode(NodeProtocol):
                 if tc.tool_name not in (
                     "set_output",
                     "ask_user",
+                    "ask_user_multiple",
                     "escalate",
                     "delegate_to_sub_agent",
                     "report_to_parent",
@@ -2450,7 +2526,7 @@ class EventLoopNode(NodeProtocol):
                 # next turn.  The char-based token estimator underestimates
                 # actual API tokens, so the standard compaction check in the
                 # outer loop may not trigger in time.
-                protect = max(2000, self._config.max_history_tokens // 12)
+                protect = max(2000, self._config.max_context_tokens // 12)
                 pruned = await conversation.prune_old_tool_results(
                     protect_tokens=protect,
                     min_prune_tokens=max(1000, protect // 3),
@@ -2459,7 +2535,7 @@ class EventLoopNode(NodeProtocol):
                     logger.info(
                         "Post-limit pruning: cleared %d old tool results (budget: %d)",
                         pruned,
-                        self._config.max_history_tokens,
+                        self._config.max_context_tokens,
                     )
                 # Limit hit — return from this turn so the judge can
                 # evaluate instead of looping back for another stream.
@@ -2475,11 +2551,12 @@ class EventLoopNode(NodeProtocol):
                     queen_input_requested,
                     final_system_prompt,
                     final_messages,
+                    reported_to_parent,
                 )
 
             # --- Mid-turn pruning: prevent context blowup within a single turn ---
             if conversation.usage_ratio() >= 0.6:
-                protect = max(2000, self._config.max_history_tokens // 12)
+                protect = max(2000, self._config.max_context_tokens // 12)
                 pruned = await conversation.prune_old_tool_results(
                     protect_tokens=protect,
                     min_prune_tokens=max(1000, protect // 3),
@@ -2506,6 +2583,7 @@ class EventLoopNode(NodeProtocol):
                     queen_input_requested,
                     final_system_prompt,
                     final_messages,
+                    reported_to_parent,
                 )
 
             # Tool calls processed -- loop back to stream with updated conversation
@@ -2571,6 +2649,73 @@ class EventLoopNode(NodeProtocol):
             },
         )
 
+    def _build_ask_user_multiple_tool(self) -> Tool:
+        """Build the synthetic ask_user_multiple tool for batched questions.
+
+        Queen-only tool that presents multiple questions at once so the user
+        can answer them all in a single interaction rather than one at a time.
+        """
+        return Tool(
+            name="ask_user_multiple",
+            description=(
+                "Ask the user multiple questions at once. Use this instead of "
+                "ask_user when you have 2 or more questions to ask in the same "
+                "turn — it lets the user answer everything in one go rather than "
+                "going back and forth. Each question can have its own predefined "
+                "options (2-3 choices) or be free-form. The UI renders all "
+                "questions together with a single Submit button. "
+                "ALWAYS prefer this over ask_user when you have multiple things "
+                "to clarify. "
+                "IMPORTANT: Do NOT repeat the questions in your text response — "
+                "the widget renders them. Keep your text to a brief intro only. "
+                'Example: {"questions": ['
+                '  {"id": "scope", "prompt": "What scope?", "options": ["Full", "Partial"]},'
+                '  {"id": "format", "prompt": "Output format?", "options": ["PDF", "CSV", "JSON"]},'
+                '  {"id": "details", "prompt": "Any special requirements?"}'
+                "]}"
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "questions": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "id": {
+                                    "type": "string",
+                                    "description": (
+                                        "Short identifier for this question "
+                                        "(used in the response)."
+                                    ),
+                                },
+                                "prompt": {
+                                    "type": "string",
+                                    "description": "The question text shown to the user.",
+                                },
+                                "options": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                    "description": (
+                                        "2-3 predefined choices. The UI appends an "
+                                        "'Other' free-text input automatically. "
+                                        "Omit only when the user must type a free-form answer."
+                                    ),
+                                    "minItems": 2,
+                                    "maxItems": 3,
+                                },
+                            },
+                            "required": ["id", "prompt"],
+                        },
+                        "minItems": 2,
+                        "maxItems": 8,
+                        "description": "List of questions to present to the user.",
+                    },
+                },
+                "required": ["questions"],
+            },
+        )
+
     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:
@@ -2905,7 +3050,7 @@ class EventLoopNode(NodeProtocol):
                 phase_description=ctx.node_spec.description,
                 success_criteria=ctx.node_spec.success_criteria,
                 accumulator_state=accumulator.to_dict(),
-                max_history_tokens=self._config.max_history_tokens,
+                max_context_tokens=self._config.max_context_tokens,
             )
             if verdict.action != "ACCEPT":
                 return JudgeVerdict(
@@ -2913,7 +3058,7 @@ class EventLoopNode(NodeProtocol):
                     feedback=verdict.feedback or "Phase criteria not met.",
                 )
 
-        return JudgeVerdict(action="ACCEPT")
+        return JudgeVerdict(action="ACCEPT", feedback="")
 
     # -------------------------------------------------------------------
     # Helpers
@@ -3345,7 +3490,7 @@ class EventLoopNode(NodeProtocol):
         phase_grad = getattr(ctx, "continuous_mode", False)
 
         # --- Step 1: Prune old tool results (free, no LLM) ---
-        protect = max(2000, self._config.max_history_tokens // 12)
+        protect = max(2000, self._config.max_context_tokens // 12)
         pruned = await conversation.prune_old_tool_results(
             protect_tokens=protect,
             min_prune_tokens=max(1000, protect // 3),
@@ -3451,7 +3596,7 @@ class EventLoopNode(NodeProtocol):
                 accumulator,
                 formatted,
             )
-            summary_budget = max(1024, self._config.max_history_tokens // 2)
+            summary_budget = max(1024, self._config.max_context_tokens // 2)
             try:
                 response = await ctx.llm.acomplete(
                     messages=[{"role": "user", "content": prompt}],
@@ -3554,7 +3699,7 @@ class EventLoopNode(NodeProtocol):
         elif spec.output_keys:
             ctx_lines.append(f"OUTPUTS STILL NEEDED: {', '.join(spec.output_keys)}")
 
-        target_tokens = self._config.max_history_tokens // 2
+        target_tokens = self._config.max_context_tokens // 2
         target_chars = target_tokens * 4
         node_ctx = "\n".join(ctx_lines)
 
@@ -4022,6 +4167,7 @@ class EventLoopNode(NodeProtocol):
         model: str,
         input_tokens: int,
         output_tokens: int,
+        cached_tokens: int = 0,
         execution_id: str = "",
         iteration: int | None = None,
     ) -> None:
@@ -4033,6 +4179,7 @@ class EventLoopNode(NodeProtocol):
                 model=model,
                 input_tokens=input_tokens,
                 output_tokens=output_tokens,
+                cached_tokens=cached_tokens,
                 execution_id=execution_id,
                 iteration=iteration,
             )
@@ -4315,22 +4462,18 @@ class EventLoopNode(NodeProtocol):
 
             registry[escalation_id] = receiver
             try:
-                # Stream message to user (parent's node_id so TUI shows parent talking)
-                await self._event_bus.emit_client_output_delta(
-                    stream_id=ctx.node_id,
-                    node_id=ctx.node_id,
-                    content=message,
-                    snapshot=message,
-                    execution_id=ctx.execution_id,
-                )
-                # Request input (escalation_id for routing response back)
-                await self._event_bus.emit_client_input_requested(
-                    stream_id=ctx.node_id,
+                # Escalate to the queen instead of asking the user directly.
+                # The queen handles the request and injects the response via
+                # inject_worker_message(), which finds this receiver through
+                # its _awaiting_input flag.
+                await self._event_bus.emit_escalation_requested(
+                    stream_id=ctx.stream_id or ctx.node_id,
                     node_id=escalation_id,
-                    prompt=message,
+                    reason=f"Subagent report (wait_for_response) from {agent_id}",
+                    context=message,
                     execution_id=ctx.execution_id,
                 )
-                # Block until user responds
+                # Block until queen responds
                 return await receiver.wait()
             finally:
                 registry.pop(escalation_id, None)
@@ -4437,7 +4580,7 @@ class EventLoopNode(NodeProtocol):
                 max_iterations=max_iter,  # Tighter budget
                 max_tool_calls_per_turn=self._config.max_tool_calls_per_turn,
                 tool_call_overflow_margin=self._config.tool_call_overflow_margin,
-                max_history_tokens=self._config.max_history_tokens,
+                max_context_tokens=self._config.max_context_tokens,
                 stall_detection_threshold=self._config.stall_detection_threshold,
                 max_tool_result_chars=self._config.max_tool_result_chars,
                 spillover_dir=subagent_spillover,

core/framework/graph/executor.py

@@ -330,7 +330,7 @@ class GraphExecutor:
                 _depth,
             )
         else:
-            max_tokens = getattr(conversation, "_max_history_tokens", 32000)
+            max_tokens = getattr(conversation, "_max_context_tokens", 32000)
             target_tokens = max_tokens // 2
             target_chars = target_tokens * 4
 
@@ -1872,7 +1872,7 @@ class GraphExecutor:
                     max_tool_calls_per_turn=lc.get("max_tool_calls_per_turn", 30),
                     tool_call_overflow_margin=lc.get("tool_call_overflow_margin", 0.5),
                     stall_detection_threshold=lc.get("stall_detection_threshold", 3),
-                    max_history_tokens=lc.get("max_history_tokens", 32000),
+                    max_context_tokens=lc.get("max_context_tokens", 32000),
                     max_tool_result_chars=lc.get("max_tool_result_chars", 30_000),
                     spillover_dir=spillover,
                     hooks=lc.get("hooks", {}),

core/framework/graph/hitl.py

@@ -1,203 +0,0 @@
-"""
-Standardized HITL (Human-In-The-Loop) Protocol
-
-This module defines the formal structure for pause/resume interactions
-where agents need to gather input from humans.
-"""
-
-from dataclasses import dataclass, field
-from enum import StrEnum
-from typing import Any
-
-
-class HITLInputType(StrEnum):
-    """Type of input expected from human."""
-
-    FREE_TEXT = "free_text"  # Open-ended text response
-    STRUCTURED = "structured"  # Specific fields to fill
-    SELECTION = "selection"  # Choose from options
-    APPROVAL = "approval"  # Yes/no/modify decision
-    MULTI_FIELD = "multi_field"  # Multiple related inputs
-
-
-@dataclass
-class HITLQuestion:
-    """A single question to ask the human."""
-
-    id: str
-    question: str
-    input_type: HITLInputType = HITLInputType.FREE_TEXT
-
-    # For SELECTION type
-    options: list[str] = field(default_factory=list)
-
-    # For STRUCTURED type
-    fields: dict[str, str] = field(default_factory=dict)  # {field_name: description}
-
-    # Metadata
-    required: bool = True
-    help_text: str = ""
-
-
-@dataclass
-class HITLRequest:
-    """
-    Formal request for human input at a pause node.
-
-    This is what the agent produces when it needs human input.
-    """
-
-    # Context
-    objective: str  # What we're trying to accomplish
-    current_state: str  # Where we are in the process
-
-    # What we need
-    questions: list[HITLQuestion] = field(default_factory=list)
-    missing_info: list[str] = field(default_factory=list)
-
-    # Guidance
-    instructions: str = ""
-    examples: list[str] = field(default_factory=list)
-
-    # Metadata
-    request_id: str = ""
-    node_id: str = ""
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "objective": self.objective,
-            "current_state": self.current_state,
-            "questions": [
-                {
-                    "id": q.id,
-                    "question": q.question,
-                    "input_type": q.input_type.value,
-                    "options": q.options,
-                    "fields": q.fields,
-                    "required": q.required,
-                    "help_text": q.help_text,
-                }
-                for q in self.questions
-            ],
-            "missing_info": self.missing_info,
-            "instructions": self.instructions,
-            "examples": self.examples,
-            "request_id": self.request_id,
-            "node_id": self.node_id,
-        }
-
-
-@dataclass
-class HITLResponse:
-    """
-    Human's response to a HITL request.
-
-    This is what gets passed back when resuming from a pause.
-    """
-
-    # Original request reference
-    request_id: str
-
-    # Human's answers
-    answers: dict[str, Any] = field(default_factory=dict)  # {question_id: answer}
-    raw_input: str = ""  # Raw text if provided
-
-    # Metadata
-    response_time_ms: int = 0
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "request_id": self.request_id,
-            "answers": self.answers,
-            "raw_input": self.raw_input,
-            "response_time_ms": self.response_time_ms,
-        }
-
-
-class HITLProtocol:
-    """
-    Standardized protocol for HITL interactions.
-
-    Usage in pause nodes:
-
-    1. Pause Node: Generates HITLRequest with questions
-    2. Executor: Saves state and returns request to user
-    3. User: Provides HITLResponse with answers
-    4. Resume Node: Processes response and merges into context
-    """
-
-    @staticmethod
-    def create_request(
-        objective: str,
-        questions: list[HITLQuestion],
-        missing_info: list[str] | None = None,
-        node_id: str = "",
-    ) -> HITLRequest:
-        """Create a standardized HITL request."""
-        return HITLRequest(
-            objective=objective,
-            current_state="Awaiting clarification",
-            questions=questions,
-            missing_info=missing_info or [],
-            request_id=f"{node_id}_{hash(objective) % 10000}",
-            node_id=node_id,
-        )
-
-    @staticmethod
-    def parse_response(
-        raw_input: str,
-        request: HITLRequest,
-        use_haiku: bool = True,
-    ) -> HITLResponse:
-        """
-        Parse human's raw input into structured response.
-
-        Maps the raw input to the first question. For multi-question HITL,
-        the caller should present one question at a time.
-        """
-        response = HITLResponse(request_id=request.request_id, raw_input=raw_input)
-
-        # If no questions, just return raw input
-        if not request.questions:
-            return response
-
-        # Map raw input to first question
-        response.answers[request.questions[0].id] = raw_input
-        return response
-
-    @staticmethod
-    def format_for_display(request: HITLRequest) -> str:
-        """Format HITL request for user-friendly display."""
-        parts = []
-
-        if request.objective:
-            parts.append(f"📋 Objective: {request.objective}")
-
-        if request.current_state:
-            parts.append(f"📍 Current State: {request.current_state}")
-
-        if request.instructions:
-            parts.append(f"\n{request.instructions}")
-
-        if request.questions:
-            parts.append(f"\n❓ Questions ({len(request.questions)}):")
-            for i, q in enumerate(request.questions, 1):
-                parts.append(f"{i}. {q.question}")
-                if q.help_text:
-                    parts.append(f"   💡 {q.help_text}")
-                if q.options:
-                    parts.append(f"   Options: {', '.join(q.options)}")
-
-        if request.missing_info:
-            parts.append("\n📝 Missing Information:")
-            for info in request.missing_info:
-                parts.append(f"  • {info}")
-
-        if request.examples:
-            parts.append("\n📚 Examples:")
-            for example in request.examples:
-                parts.append(f"  • {example}")
-
-        return "\n".join(parts)

core/framework/llm/litellm.py

@@ -119,6 +119,19 @@ RATE_LIMIT_BACKOFF_BASE = 2  # seconds
 RATE_LIMIT_MAX_DELAY = 120  # seconds - cap to prevent absurd waits
 MINIMAX_API_BASE = "https://api.minimax.io/v1"
 
+# Providers that accept cache_control on message content blocks.
+# Anthropic: native ephemeral caching. MiniMax & Z-AI/GLM: pass-through to their APIs.
+# (OpenAI caches automatically server-side; Groq/Gemini/etc. strip the header.)
+_CACHE_CONTROL_PREFIXES = ("anthropic/", "claude-", "minimax/", "minimax-", "MiniMax-", "zai-glm", "glm-")
+
+
+def _model_supports_cache_control(model: str) -> bool:
+    return any(model.startswith(p) for p in _CACHE_CONTROL_PREFIXES)
+# Kimi For Coding uses an Anthropic-compatible endpoint (no /v1 suffix).
+# Claude Code integration uses this format; the /v1 OpenAI-compatible endpoint
+# enforces a coding-agent whitelist that blocks unknown User-Agents.
+KIMI_API_BASE = "https://api.kimi.com/coding"
+
 # Empty-stream retries use a short fixed delay, not the rate-limit backoff.
 # Conversation-structure issues are deterministic — long waits don't help.
 EMPTY_STREAM_MAX_RETRIES = 3
@@ -323,9 +336,21 @@ class LiteLLMProvider(LLMProvider):
             api_base: Custom API base URL (for proxies or local deployments)
             **kwargs: Additional arguments passed to litellm.completion()
         """
+        # Kimi For Coding exposes an Anthropic-compatible endpoint at
+        # https://api.kimi.com/coding (the same format Claude Code uses natively).
+        # Translate kimi/ prefix to anthropic/ so litellm uses the Anthropic
+        # Messages API handler and routes to that endpoint — no special headers needed.
+        _original_model = model
+        if model.lower().startswith("kimi/"):
+            model = "anthropic/" + model[len("kimi/") :]
+            # Normalise api_base: litellm's Anthropic handler appends /v1/messages,
+            # so the base must be https://api.kimi.com/coding (no /v1 suffix).
+            # Strip a trailing /v1 in case the user's saved config has the old value.
+            if api_base and api_base.rstrip("/").endswith("/v1"):
+                api_base = api_base.rstrip("/")[:-3]
         self.model = model
         self.api_key = api_key
-        self.api_base = api_base or self._default_api_base_for_model(model)
+        self.api_base = api_base or self._default_api_base_for_model(_original_model)
         self.extra_kwargs = kwargs
         # The Codex ChatGPT backend (chatgpt.com/backend-api/codex) rejects
         # several standard OpenAI params: max_output_tokens, stream_options.
@@ -350,6 +375,8 @@ class LiteLLMProvider(LLMProvider):
         model_lower = model.lower()
         if model_lower.startswith("minimax/") or model_lower.startswith("minimax-"):
             return MINIMAX_API_BASE
+        if model_lower.startswith("kimi/"):
+            return KIMI_API_BASE
         return None
 
     def _completion_with_rate_limit_retry(
@@ -689,7 +716,10 @@ class LiteLLMProvider(LLMProvider):
 
         full_messages: list[dict[str, Any]] = []
         if system:
-            full_messages.append({"role": "system", "content": system})
+            sys_msg: dict[str, Any] = {"role": "system", "content": system}
+            if _model_supports_cache_control(self.model):
+                sys_msg["cache_control"] = {"type": "ephemeral"}
+            full_messages.append(sys_msg)
         full_messages.extend(messages)
 
         if json_mode:
@@ -860,7 +890,10 @@ class LiteLLMProvider(LLMProvider):
 
         full_messages: list[dict[str, Any]] = []
         if system:
-            full_messages.append({"role": "system", "content": system})
+            sys_msg: dict[str, Any] = {"role": "system", "content": system}
+            if _model_supports_cache_control(self.model):
+                sys_msg["cache_control"] = {"type": "ephemeral"}
+            full_messages.append(sys_msg)
         full_messages.extend(messages)
 
         # Codex Responses API requires an `instructions` field (system prompt).
@@ -925,9 +958,26 @@ class LiteLLMProvider(LLMProvider):
                 response = await litellm.acompletion(**kwargs)  # type: ignore[union-attr]
 
                 async for chunk in response:
-                    choice = chunk.choices[0] if chunk.choices else None
-                    if not choice:
+                    # Capture usage from the trailing usage-only chunk that
+                    # stream_options={"include_usage": True} sends with empty choices.
+                    if not chunk.choices:
+                        usage = getattr(chunk, "usage", None)
+                        if usage:
+                            input_tokens = getattr(usage, "prompt_tokens", 0) or 0
+                            output_tokens = getattr(usage, "completion_tokens", 0) or 0
+                            logger.debug(
+                                "[tokens] trailing usage chunk: input=%d output=%d model=%s",
+                                input_tokens,
+                                output_tokens,
+                                self.model,
+                            )
+                        else:
+                            logger.debug(
+                                "[tokens] empty-choices chunk with no usage (model=%s)",
+                                self.model,
+                            )
                         continue
+                    choice = chunk.choices[0]
 
                     delta = choice.delta
 
@@ -1000,19 +1050,90 @@ class LiteLLMProvider(LLMProvider):
                             tail_events.append(TextEndEvent(full_text=accumulated_text))
 
                         usage = getattr(chunk, "usage", None)
+                        logger.debug(
+                            "[tokens] finish-chunk raw usage: %r (type=%s)",
+                            usage,
+                            type(usage).__name__,
+                        )
+                        cached_tokens = 0
                         if usage:
                             input_tokens = getattr(usage, "prompt_tokens", 0) or 0
                             output_tokens = getattr(usage, "completion_tokens", 0) or 0
+                            _details = getattr(usage, "prompt_tokens_details", None)
+                            cached_tokens = (
+                                getattr(_details, "cached_tokens", 0) or 0
+                                if _details is not None
+                                else getattr(usage, "cache_read_input_tokens", 0) or 0
+                            )
+                            logger.debug(
+                                "[tokens] finish-chunk usage: input=%d output=%d cached=%d model=%s",
+                                input_tokens,
+                                output_tokens,
+                                cached_tokens,
+                                self.model,
+                            )
 
+                        logger.debug(
+                            "[tokens] finish event: input=%d output=%d cached=%d stop=%s model=%s",
+                            input_tokens,
+                            output_tokens,
+                            cached_tokens,
+                            choice.finish_reason,
+                            self.model,
+                        )
                         tail_events.append(
                             FinishEvent(
                                 stop_reason=choice.finish_reason,
                                 input_tokens=input_tokens,
                                 output_tokens=output_tokens,
+                                cached_tokens=cached_tokens,
                                 model=self.model,
                             )
                         )
 
+                # Fallback: LiteLLM strips usage from yielded chunks before
+                # returning them to us, but appends the original chunk (with
+                # usage intact) to response.chunks first.  Use LiteLLM's own
+                # calculate_total_usage() on that accumulated list.
+                if input_tokens == 0 and output_tokens == 0:
+                    try:
+                        from litellm.litellm_core_utils.streaming_handler import (
+                            calculate_total_usage,
+                        )
+
+                        _chunks = getattr(response, "chunks", None)
+                        if _chunks:
+                            _usage = calculate_total_usage(chunks=_chunks)
+                            input_tokens = _usage.prompt_tokens or 0
+                            output_tokens = _usage.completion_tokens or 0
+                            _details = getattr(_usage, "prompt_tokens_details", None)
+                            cached_tokens = (
+                                getattr(_details, "cached_tokens", 0) or 0
+                                if _details is not None
+                                else getattr(_usage, "cache_read_input_tokens", 0) or 0
+                            )
+                            logger.debug(
+                                "[tokens] post-loop chunks fallback:"
+                                " input=%d output=%d cached=%d model=%s",
+                                input_tokens,
+                                output_tokens,
+                                cached_tokens,
+                                self.model,
+                            )
+                            # Patch the FinishEvent already queued with 0 tokens
+                            for _i, _ev in enumerate(tail_events):
+                                if isinstance(_ev, FinishEvent) and _ev.input_tokens == 0:
+                                    tail_events[_i] = FinishEvent(
+                                        stop_reason=_ev.stop_reason,
+                                        input_tokens=input_tokens,
+                                        output_tokens=output_tokens,
+                                        cached_tokens=cached_tokens,
+                                        model=_ev.model,
+                                    )
+                                    break
+                    except Exception as _e:
+                        logger.debug("[tokens] chunks fallback failed: %s", _e)
+
                 # Check whether the stream produced any real content.
                 # (If text deltas were yielded above, has_content is True
                 # and we skip the retry path — nothing was yielded in vain.)

core/framework/llm/stream_events.py

@@ -71,6 +71,7 @@ class FinishEvent:
     stop_reason: str = ""
     input_tokens: int = 0
     output_tokens: int = 0
+    cached_tokens: int = 0
     model: str = ""
 
 

core/framework/mcp/__init__.py

@@ -1,4 +0,0 @@
-"""MCP servers for worker-bee."""
-
-# Don't auto-import servers to avoid double-import issues when running with -m
-__all__ = []

core/framework/monitoring/judge.py

@@ -253,6 +253,6 @@ judge_graph = GraphSpec(
     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
+        "max_context_tokens": 16000,  # Compact — judge only needs recent context
     },
 )

core/framework/observability/logging.py

@@ -148,8 +148,9 @@ class HumanReadableFormatter(logging.Formatter):
         if record_event is not None:
             event = f" [{record_event}]"
 
-        # Format message: [LEVEL] [trace context] message
-        return f"{color}[{level}]{reset} {context_prefix}{record.getMessage()}{event}"
+        timestamp = self.formatTime(record, "%Y-%m-%d %H:%M:%S")
+        # Format message: TIMESTAMP [LEVEL] [trace context] message
+        return f"{timestamp} {color}[{level}]{reset} {context_prefix}{record.getMessage()}{event}"
 
 
 def configure_logging(

core/framework/runner/cli.py

@@ -51,11 +51,7 @@ def register_commands(subparsers: argparse._SubParsersAction) -> None:
         action="store_true",
         help="Show detailed execution logs (steps, LLM calls, etc.)",
     )
-    run_parser.add_argument(
-        "--tui",
-        action="store_true",
-        help="Launch interactive terminal dashboard",
-    )
+
     run_parser.add_argument(
         "--model",
         "-m",
@@ -194,143 +190,6 @@ def register_commands(subparsers: argparse._SubParsersAction) -> None:
     shell_parser.set_defaults(func=cmd_shell)
 
     # tui command (interactive agent dashboard)
-    tui_parser = subparsers.add_parser(
-        "tui",
-        help="Launch interactive TUI dashboard",
-        description="Browse available agents and launch the terminal dashboard.",
-    )
-    tui_parser.add_argument(
-        "--model",
-        "-m",
-        type=str,
-        default=None,
-        help="LLM model to use (any LiteLLM-compatible name)",
-    )
-    tui_parser.set_defaults(func=cmd_tui)
-
-    # sessions command group (checkpoint/resume management)
-    sessions_parser = subparsers.add_parser(
-        "sessions",
-        help="Manage agent sessions",
-        description="List, inspect, and manage agent execution sessions.",
-    )
-    sessions_subparsers = sessions_parser.add_subparsers(
-        dest="sessions_cmd",
-        help="Session management commands",
-    )
-
-    # sessions list
-    sessions_list_parser = sessions_subparsers.add_parser(
-        "list",
-        help="List agent sessions",
-        description="List all sessions for an agent.",
-    )
-    sessions_list_parser.add_argument(
-        "agent_path",
-        type=str,
-        help="Path to agent folder",
-    )
-    sessions_list_parser.add_argument(
-        "--status",
-        choices=["all", "active", "failed", "completed", "paused"],
-        default="all",
-        help="Filter by session status (default: all)",
-    )
-    sessions_list_parser.add_argument(
-        "--has-checkpoints",
-        action="store_true",
-        help="Show only sessions with checkpoints",
-    )
-    sessions_list_parser.set_defaults(func=cmd_sessions_list)
-
-    # sessions show
-    sessions_show_parser = sessions_subparsers.add_parser(
-        "show",
-        help="Show session details",
-        description="Display detailed information about a specific session.",
-    )
-    sessions_show_parser.add_argument(
-        "agent_path",
-        type=str,
-        help="Path to agent folder",
-    )
-    sessions_show_parser.add_argument(
-        "session_id",
-        type=str,
-        help="Session ID to inspect",
-    )
-    sessions_show_parser.add_argument(
-        "--json",
-        action="store_true",
-        help="Output as JSON",
-    )
-    sessions_show_parser.set_defaults(func=cmd_sessions_show)
-
-    # sessions checkpoints
-    sessions_checkpoints_parser = sessions_subparsers.add_parser(
-        "checkpoints",
-        help="List session checkpoints",
-        description="List all checkpoints for a session.",
-    )
-    sessions_checkpoints_parser.add_argument(
-        "agent_path",
-        type=str,
-        help="Path to agent folder",
-    )
-    sessions_checkpoints_parser.add_argument(
-        "session_id",
-        type=str,
-        help="Session ID",
-    )
-    sessions_checkpoints_parser.set_defaults(func=cmd_sessions_checkpoints)
-
-    # pause command
-    pause_parser = subparsers.add_parser(
-        "pause",
-        help="Pause running session",
-        description="Request graceful pause of a running agent session.",
-    )
-    pause_parser.add_argument(
-        "agent_path",
-        type=str,
-        help="Path to agent folder",
-    )
-    pause_parser.add_argument(
-        "session_id",
-        type=str,
-        help="Session ID to pause",
-    )
-    pause_parser.set_defaults(func=cmd_pause)
-
-    # resume command
-    resume_parser = subparsers.add_parser(
-        "resume",
-        help="Resume session from checkpoint",
-        description="Resume a paused or failed session from a checkpoint.",
-    )
-    resume_parser.add_argument(
-        "agent_path",
-        type=str,
-        help="Path to agent folder",
-    )
-    resume_parser.add_argument(
-        "session_id",
-        type=str,
-        help="Session ID to resume",
-    )
-    resume_parser.add_argument(
-        "--checkpoint",
-        "-c",
-        type=str,
-        help="Specific checkpoint ID to resume from (default: latest)",
-    )
-    resume_parser.add_argument(
-        "--tui",
-        action="store_true",
-        help="Resume in TUI dashboard mode",
-    )
-    resume_parser.set_defaults(func=cmd_resume)
-
     # setup-credentials command
     setup_creds_parser = subparsers.add_parser(
         "setup-credentials",
@@ -384,6 +243,12 @@ def register_commands(subparsers: argparse._SubParsersAction) -> None:
         action="store_true",
         help="Open dashboard in browser after server starts",
     )
+    serve_parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Enable INFO log level"
+    )
+    serve_parser.add_argument(
+        "--debug", action="store_true", help="Enable DEBUG log level"
+    )
     serve_parser.set_defaults(func=cmd_serve)
 
     # open command (serve + auto-open browser)
@@ -421,6 +286,12 @@ def register_commands(subparsers: argparse._SubParsersAction) -> None:
         default=None,
         help="LLM model for preloaded agents",
     )
+    open_parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Enable INFO log level"
+    )
+    open_parser.add_argument(
+        "--debug", action="store_true", help="Enable DEBUG log level"
+    )
     open_parser.set_defaults(func=cmd_open)
 
 
@@ -521,13 +392,15 @@ def cmd_run(args: argparse.Namespace) -> int:
     from framework.credentials.models import CredentialError
     from framework.runner import AgentRunner
 
+    from framework.observability import configure_logging
+
     # Set logging level (quiet by default for cleaner output)
     if args.quiet:
-        logging.basicConfig(level=logging.ERROR, format="%(message)s")
+        configure_logging(level="ERROR")
     elif getattr(args, "verbose", False):
-        logging.basicConfig(level=logging.INFO, format="%(message)s")
+        configure_logging(level="INFO")
     else:
-        logging.basicConfig(level=logging.WARNING, format="%(message)s")
+        configure_logging(level="WARNING")
 
     # Load input context
     context = {}
@@ -562,128 +435,67 @@ def cmd_run(args: argparse.Namespace) -> int:
             )
             return 1
 
-    # Run the agent (with TUI or standard)
-    if getattr(args, "tui", False):
-        from framework.tui.app import AdenTUI
+    # Standard execution
+    # AgentRunner handles credential setup interactively when stdin is a TTY.
+    try:
+        runner = AgentRunner.load(
+            args.agent_path,
+            model=args.model,
+        )
+    except CredentialError as e:
+        print(f"\n{e}", file=sys.stderr)
+        return 1
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
 
-        async def run_with_tui():
-            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,
-                        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
+    # 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
 
-                # 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:
-                    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:
-                    await runner._agent_runtime.start()
-
-                app = AdenTUI(
-                    runner._agent_runtime,
-                    resume_session=getattr(args, "resume_session", None),
-                    resume_checkpoint=getattr(args, "checkpoint", None),
-                )
-
-                # TUI handles execution via ChatRepl — user submits input,
-                # ChatRepl calls runtime.trigger_and_wait(). No auto-launch.
-                await app.run_async()
-            except Exception as e:
-                import traceback
-
-                traceback.print_exc()
-                print(f"TUI error: {e}")
-
-            await runner.cleanup_async()
-            return None
-
-        asyncio.run(run_with_tui())
-        print("TUI session ended.")
-        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,
-                model=args.model,
+    # Load session/checkpoint state for resume (headless mode)
+    session_state = None
+    resume_session = getattr(args, "resume_session", None)
+    checkpoint = getattr(args, "checkpoint", None)
+    if resume_session:
+        session_state = _load_resume_state(args.agent_path, resume_session, checkpoint)
+        if session_state is None:
+            print(
+                f"Error: Could not load session state for {resume_session}",
+                file=sys.stderr,
             )
-        except CredentialError as e:
-            print(f"\n{e}", file=sys.stderr)
             return 1
-        except FileNotFoundError as e:
-            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)
-        checkpoint = getattr(args, "checkpoint", None)
-        if resume_session:
-            session_state = _load_resume_state(args.agent_path, resume_session, checkpoint)
-            if session_state is None:
-                print(
-                    f"Error: Could not load session state for {resume_session}",
-                    file=sys.stderr,
-                )
-                return 1
-            if not args.quiet:
-                resume_node = session_state.get("paused_at", "unknown")
-                if checkpoint:
-                    print(f"Resuming from checkpoint: {checkpoint}")
-                else:
-                    print(f"Resuming session: {resume_session}")
-                print(f"Resume point: {resume_node}")
-                print()
-
-        # Auto-inject user_id if the agent expects it but it's not provided
-        entry_input_keys = runner.graph.nodes[0].input_keys if runner.graph.nodes else []
-        if "user_id" in entry_input_keys and context.get("user_id") is None:
-            import os
-
-            context["user_id"] = os.environ.get("USER", "default_user")
-
         if not args.quiet:
-            info = runner.info()
-            print(f"Agent: {info.name}")
-            print(f"Goal: {info.goal_name}")
-            print(f"Steps: {info.node_count}")
-            print(f"Input: {json.dumps(context)}")
-            print()
-            print("=" * 60)
-            print("Executing agent...")
-            print("=" * 60)
+            resume_node = session_state.get("paused_at", "unknown")
+            if checkpoint:
+                print(f"Resuming from checkpoint: {checkpoint}")
+            else:
+                print(f"Resuming session: {resume_session}")
+            print(f"Resume point: {resume_node}")
             print()
 
-        result = asyncio.run(runner.run(context, session_state=session_state))
+    # Auto-inject user_id if the agent expects it but it's not provided
+    entry_input_keys = runner.graph.nodes[0].input_keys if runner.graph.nodes else []
+    if "user_id" in entry_input_keys and context.get("user_id") is None:
+        import os
+
+        context["user_id"] = os.environ.get("USER", "default_user")
+
+    if not args.quiet:
+        info = runner.info()
+        print(f"Agent: {info.name}")
+        print(f"Goal: {info.goal_name}")
+        print(f"Steps: {info.node_count}")
+        print(f"Input: {json.dumps(context)}")
+        print()
+        print("=" * 60)
+        print("Executing agent...")
+        print("=" * 60)
+        print()
+
+    result = asyncio.run(runner.run(context, session_state=session_state))
 
     # Format output
     output = {
@@ -944,6 +756,17 @@ def cmd_dispatch(args: argparse.Namespace) -> int:
     if args.agents:
         # Use specific agents
         for agent_name in args.agents:
+            # Guard against full paths: if the name contains path separators
+            # (e.g. "exports/my_agent"), it will be doubled with agents_dir
+            agent_name_path = Path(agent_name)
+            if len(agent_name_path.parts) > 1:
+                print(
+                    f"Error: --agents expects agent names, not paths. "
+                    f"Use: --agents {agent_name_path.name} "
+                    f"instead of --agents {agent_name}",
+                    file=sys.stderr,
+                )
+                return 1
             agent_path = agents_dir / agent_name
             if not _is_valid_agent_dir(agent_path):
                 print(f"Agent not found: {agent_path}", file=sys.stderr)
@@ -1114,11 +937,9 @@ def cmd_shell(args: argparse.Namespace) -> int:
     from framework.credentials.models import CredentialError
     from framework.runner import AgentRunner
 
-    # Configure logging to show runtime visibility
-    logging.basicConfig(
-        level=logging.INFO,
-        format="%(message)s",  # Simple format for clean output
-    )
+    from framework.observability import configure_logging
+
+    configure_logging(level="INFO")
 
     agents_dir = Path(args.agents_dir)
 
@@ -1349,74 +1170,6 @@ def _get_framework_agents_dir() -> Path:
     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
-
-    async def run_with_tui():
-        # AgentRunner handles credential setup interactively when stdin is a TTY.
-        try:
-            runner = AgentRunner.load(
-                agent_path,
-                model=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
-
-        if runner._agent_runtime and not runner._agent_runtime.is_running:
-            await runner._agent_runtime.start()
-
-        app = AdenTUI(runner._agent_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 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 _extract_python_agent_metadata(agent_path: Path) -> tuple[str, str]:
     """Extract name and description from a Python-based agent's config.py.
 
@@ -1769,56 +1522,6 @@ def _interactive_multi(agents_dir: Path) -> int:
     return 0
 
 
-def cmd_sessions_list(args: argparse.Namespace) -> int:
-    """List agent sessions."""
-    print("⚠ Sessions list command not yet implemented")
-    print("This will be available once checkpoint infrastructure is complete.")
-    print(f"\nAgent: {args.agent_path}")
-    print(f"Status filter: {args.status}")
-    print(f"Has checkpoints: {args.has_checkpoints}")
-    return 1
-
-
-def cmd_sessions_show(args: argparse.Namespace) -> int:
-    """Show detailed session information."""
-    print("⚠ Session show command not yet implemented")
-    print("This will be available once checkpoint infrastructure is complete.")
-    print(f"\nAgent: {args.agent_path}")
-    print(f"Session: {args.session_id}")
-    return 1
-
-
-def cmd_sessions_checkpoints(args: argparse.Namespace) -> int:
-    """List checkpoints for a session."""
-    print("⚠ Session checkpoints command not yet implemented")
-    print("This will be available once checkpoint infrastructure is complete.")
-    print(f"\nAgent: {args.agent_path}")
-    print(f"Session: {args.session_id}")
-    return 1
-
-
-def cmd_pause(args: argparse.Namespace) -> int:
-    """Pause a running session."""
-    print("⚠ Pause command not yet implemented")
-    print("This will be available once executor pause integration is complete.")
-    print(f"\nAgent: {args.agent_path}")
-    print(f"Session: {args.session_id}")
-    return 1
-
-
-def cmd_resume(args: argparse.Namespace) -> int:
-    """Resume a session from checkpoint."""
-    print("⚠ Resume command not yet implemented")
-    print("This will be available once checkpoint resume integration is complete.")
-    print(f"\nAgent: {args.agent_path}")
-    print(f"Session: {args.session_id}")
-    if args.checkpoint:
-        print(f"Checkpoint: {args.checkpoint}")
-    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
@@ -1942,10 +1645,12 @@ def cmd_serve(args: argparse.Namespace) -> int:
 
     from framework.server.app import create_app
 
-    logging.basicConfig(
-        level=logging.INFO,
-        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
-    )
+    from framework.observability import configure_logging
+
+    if getattr(args, "debug", False):
+        configure_logging(level="DEBUG")
+    else:
+        configure_logging(level="INFO")
 
     model = getattr(args, "model", None)
     app = create_app(model=model)

core/framework/runner/mcp_client.py

@@ -68,6 +68,7 @@ class MCPClient:
         self._read_stream = None
         self._write_stream = None
         self._stdio_context = None  # Context manager for stdio_client
+        self._errlog_handle = None  # Track errlog file handle for cleanup
         self._http_client: httpx.Client | None = None
         self._tools: dict[str, MCPTool] = {}
         self._connected = False
@@ -200,7 +201,8 @@ class MCPClient:
                         if os.name == "nt":
                             errlog = sys.stderr
                         else:
-                            errlog = open(os.devnull, "w")  # noqa: SIM115
+                            self._errlog_handle = open(os.devnull, "w")
+                            errlog = self._errlog_handle
                         self._stdio_context = stdio_client(server_params, errlog=errlog)
                         (
                             self._read_stream,
@@ -475,6 +477,15 @@ class MCPClient:
         finally:
             self._stdio_context = None
 
+        # Third: close errlog file handle if we opened one
+        if self._errlog_handle is not None:
+            try:
+                self._errlog_handle.close()
+            except Exception as e:
+                logger.debug(f"Error closing errlog handle: {e}")
+            finally:
+                self._errlog_handle = None
+
     def disconnect(self) -> None:
         """Disconnect from the MCP server."""
         # Clean up persistent STDIO connection
@@ -545,6 +556,7 @@ class MCPClient:
             self._write_stream = None
             self._loop = None
             self._loop_thread = None
+            self._errlog_handle = None
 
         # Clean up HTTP client
         if self._http_client:

core/framework/runner/runner.py

@@ -9,7 +9,7 @@ from datetime import UTC
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from framework.config import get_hive_config, get_preferred_model
+from framework.config import get_hive_config, get_max_context_tokens, get_preferred_model
 from framework.credentials.validation import (
     ensure_credential_key_env as _ensure_credential_key_env,
 )
@@ -517,6 +517,41 @@ def get_codex_account_id() -> str | None:
     return None
 
 
+# ---------------------------------------------------------------------------
+# Kimi Code subscription token helpers
+# ---------------------------------------------------------------------------
+
+
+def get_kimi_code_token() -> str | None:
+    """Get the API key from a Kimi Code CLI installation.
+
+    Reads the API key from ``~/.kimi/config.toml``, which is created when
+    the user runs ``kimi /login`` in the Kimi Code CLI.
+
+    Returns:
+        The API key if available, None otherwise.
+    """
+    import tomllib
+
+    config_path = Path.home() / ".kimi" / "config.toml"
+    if not config_path.exists():
+        return None
+
+    try:
+        with open(config_path, "rb") as f:
+            config = tomllib.load(f)
+        providers = config.get("providers", {})
+        # kimi-cli stores credentials under providers.kimi-for-coding
+        for provider_cfg in providers.values():
+            if isinstance(provider_cfg, dict):
+                key = provider_cfg.get("api_key")
+                if key:
+                    return key
+    except Exception:
+        pass
+    return None
+
+
 @dataclass
 class AgentInfo:
     """Information about an exported agent."""
@@ -891,10 +926,31 @@ class AgentRunner:
 
             if agent_config and hasattr(agent_config, "max_tokens"):
                 max_tokens = agent_config.max_tokens
+                logger.info(
+                    "Agent default_config overrides max_tokens: %d (configuration.json value ignored)",
+                    max_tokens,
+                )
             else:
                 hive_config = get_hive_config()
                 max_tokens = hive_config.get("llm", {}).get("max_tokens", DEFAULT_MAX_TOKENS)
 
+            # Resolve max_context_tokens with priority:
+            #   1. agent loop_config["max_context_tokens"] (explicit, wins silently)
+            #   2. agent default_config.max_context_tokens (logged)
+            #   3. configuration.json llm.max_context_tokens
+            #   4. hardcoded default (32_000)
+            agent_loop_config: dict = dict(getattr(agent_module, "loop_config", {}))
+            if "max_context_tokens" not in agent_loop_config:
+                if agent_config and hasattr(agent_config, "max_context_tokens"):
+                    agent_loop_config["max_context_tokens"] = agent_config.max_context_tokens
+                    logger.info(
+                        "Agent default_config overrides max_context_tokens: %d"
+                        " (configuration.json value ignored)",
+                        agent_config.max_context_tokens,
+                    )
+                else:
+                    agent_loop_config["max_context_tokens"] = get_max_context_tokens()
+
             # Read intro_message from agent metadata (shown on TUI load)
             agent_metadata = getattr(agent_module, "metadata", None)
             intro_message = ""
@@ -914,7 +970,7 @@ class AgentRunner:
                 "nodes": nodes,
                 "edges": edges,
                 "max_tokens": max_tokens,
-                "loop_config": getattr(agent_module, "loop_config", {}),
+                "loop_config": agent_loop_config,
             }
             # Only pass optional fields if explicitly defined by the agent module
             conversation_mode = getattr(agent_module, "conversation_mode", None)
@@ -1104,6 +1160,7 @@ class AgentRunner:
             llm_config = config.get("llm", {})
             use_claude_code = llm_config.get("use_claude_code_subscription", False)
             use_codex = llm_config.get("use_codex_subscription", False)
+            use_kimi_code = llm_config.get("use_kimi_code_subscription", False)
             api_base = llm_config.get("api_base")
 
             api_key = None
@@ -1119,6 +1176,12 @@ class AgentRunner:
                 if not api_key:
                     print("Warning: Codex subscription configured but no token found.")
                     print("Run 'codex' to authenticate, then try again.")
+            elif use_kimi_code:
+                # Get API key from Kimi Code CLI config (~/.kimi/config.toml)
+                api_key = get_kimi_code_token()
+                if not api_key:
+                    print("Warning: Kimi Code subscription configured but no key found.")
+                    print("Run 'kimi /login' to authenticate, then try again.")
 
             if api_key and use_claude_code:
                 # Use litellm's built-in Anthropic OAuth support.
@@ -1149,6 +1212,14 @@ class AgentRunner:
                     store=False,
                     allowed_openai_params=["store"],
                 )
+            elif api_key and use_kimi_code:
+                # Kimi Code subscription uses the Kimi coding API (OpenAI-compatible).
+                # The api_base is set automatically by LiteLLMProvider for kimi/ models.
+                self._llm = LiteLLMProvider(
+                    model=self.model,
+                    api_key=api_key,
+                    api_base=api_base,
+                )
             else:
                 # Local models (e.g. Ollama) don't need an API key
                 if self._is_local_model(self.model):
@@ -1314,6 +1385,8 @@ class AgentRunner:
             return "TOGETHER_API_KEY"
         elif model_lower.startswith("minimax/") or model_lower.startswith("minimax-"):
             return "MINIMAX_API_KEY"
+        elif model_lower.startswith("kimi/"):
+            return "KIMI_API_KEY"
         else:
             # Default: assume OpenAI-compatible
             return "OPENAI_API_KEY"
@@ -1334,6 +1407,8 @@ class AgentRunner:
             cred_id = "anthropic"
         elif model_lower.startswith("minimax/") or model_lower.startswith("minimax-"):
             cred_id = "minimax"
+        elif model_lower.startswith("kimi/"):
+            cred_id = "kimi"
         # Add more mappings as providers are added to LLM_CREDENTIALS
 
         if cred_id is None:

core/framework/runtime/agent_runtime.py

@@ -1531,6 +1531,11 @@ class AgentRuntime:
                 for executor in stream._active_executors.values():
                     for node_id, node in executor.node_registry.items():
                         if getattr(node, "_awaiting_input", False):
+                            # Skip escalation receivers — those are handled
+                            # by the queen via inject_worker_message(), not
+                            # by the user directly.
+                            if ":escalation:" in node_id:
+                                continue
                             return node_id, graph_id
         return None, None
 

core/framework/runtime/event_bus.py

@@ -137,6 +137,12 @@ class EventType(StrEnum):
     WORKER_LOADED = "worker_loaded"
     CREDENTIALS_REQUIRED = "credentials_required"
 
+    # Draft graph (planning phase — lightweight graph preview)
+    DRAFT_GRAPH_UPDATED = "draft_graph_updated"
+
+    # Flowchart map updated (after reconciliation with runtime graph)
+    FLOWCHART_MAP_UPDATED = "flowchart_map_updated"
+
     # Queen phase changes (building <-> staging <-> running)
     QUEEN_PHASE_CHANGED = "queen_phase_changed"
 
@@ -616,6 +622,7 @@ class EventBus:
         model: str,
         input_tokens: int,
         output_tokens: int,
+        cached_tokens: int = 0,
         execution_id: str | None = None,
         iteration: int | None = None,
     ) -> None:
@@ -625,6 +632,7 @@ class EventBus:
             "model": model,
             "input_tokens": input_tokens,
             "output_tokens": output_tokens,
+            "cached_tokens": cached_tokens,
         }
         if iteration is not None:
             data["iteration"] = iteration
@@ -722,16 +730,23 @@ class EventBus:
         prompt: str = "",
         execution_id: str | None = None,
         options: list[str] | None = None,
+        questions: list[dict] | None = None,
     ) -> None:
         """Emit client input requested event (client_facing=True nodes).
 
         Args:
             options: Optional predefined choices for the user (1-3 items).
-                     The frontend appends an "Other" free-text option automatically.
+                     The frontend appends an "Other" free-text option
+                     automatically.
+            questions: Optional list of question dicts for multi-question
+                       batches (from ask_user_multiple). Each dict has id,
+                       prompt, and optional options.
         """
         data: dict[str, Any] = {"prompt": prompt}
         if options:
             data["options"] = options
+        if questions:
+            data["questions"] = questions
         await self.publish(
             AgentEvent(
                 type=EventType.CLIENT_INPUT_REQUESTED,

core/framework/runtime/execution_stream.py

@@ -9,6 +9,7 @@ Each stream has:
 
 import asyncio
 import logging
+import os
 import time
 import uuid
 from collections import OrderedDict
@@ -963,6 +964,9 @@ class ExecutionStream:
             if error:
                 state.result.error = error
 
+            # Stamp the owning process ID for cross-process stale detection
+            state.pid = os.getpid()
+
             # Write state.json
             await self._session_store.write_state(execution_id, state)
             logger.debug(f"Wrote state.json for session {execution_id} (status={status})")

core/framework/schemas/session_state.py

@@ -134,6 +134,9 @@ class SessionState(BaseModel):
     # Input data (for debugging/replay)
     input_data: dict[str, Any] = Field(default_factory=dict)
 
+    # Process ID of the owning process (for cross-process stale session detection)
+    pid: int | None = None
+
     # Isolation level (from ExecutionContext)
     isolation_level: str = "shared"
 

core/framework/server/agent_manager.py

@@ -1,36 +0,0 @@
-"""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/queen_orchestrator.py

@@ -137,6 +137,11 @@ async def create_queen(
     phase_state.staging_tools = [t for t in queen_tools if t.name in staging_names]
     phase_state.running_tools = [t for t in queen_tools if t.name in running_names]
 
+    # ---- Cross-session memory ----------------------------------------
+    from framework.agents.queen.queen_memory import seed_if_missing
+
+    seed_if_missing()
+
     # ---- Compose phase-specific prompts ------------------------------
     _orig_node = _queen_graph.nodes[0]
 
@@ -203,8 +208,7 @@ async def create_queen(
                     data={"persona": persona},
                 )
             )
-        body = _planning_body if phase_state.phase == "planning" else _building_body
-        return HookResult(system_prompt=persona + "\n\n" + body)
+        return HookResult(system_prompt=persona + "\n\n" + phase_state.get_current_prompt())
 
     # ---- Graph preparation -------------------------------------------
     initial_prompt_text = phase_state.get_current_prompt()

core/framework/server/routes_events.py

@@ -40,6 +40,7 @@ DEFAULT_EVENT_TYPES = [
     EventType.CREDENTIALS_REQUIRED,
     EventType.SUBAGENT_REPORT,
     EventType.QUEEN_PHASE_CHANGED,
+    EventType.DRAFT_GRAPH_UPDATED,
 ]
 
 # Keepalive interval in seconds

core/framework/server/routes_graphs.py

@@ -234,8 +234,69 @@ async def handle_node_tools(request: web.Request) -> web.Response:
     return web.json_response({"tools": tools_out})
 
 
+async def handle_draft_graph(request: web.Request) -> web.Response:
+    """Return the current draft graph from planning phase (if any)."""
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    phase_state = getattr(session, "phase_state", None)
+    if phase_state is None or phase_state.draft_graph is None:
+        return web.json_response({"draft": None})
+
+    return web.json_response({"draft": phase_state.draft_graph})
+
+
+async def handle_flowchart_map(request: web.Request) -> web.Response:
+    """Return the flowchart→runtime node mapping and the original (pre-dissolution) draft.
+
+    Available after confirm_and_build() dissolves decision nodes, or loaded
+    from the agent's flowchart.json file, or synthesized from the runtime graph.
+    """
+    session, err = resolve_session(request)
+    if err:
+        return err
+
+    phase_state = getattr(session, "phase_state", None)
+
+    # Fast path: already in memory
+    if phase_state is not None and phase_state.original_draft_graph is not None:
+        return web.json_response({
+            "map": phase_state.flowchart_map,
+            "original_draft": phase_state.original_draft_graph,
+        })
+
+    # Try loading from flowchart.json in the agent folder
+    worker_path = getattr(session, "worker_path", None)
+    if worker_path is not None:
+        from pathlib import Path
+
+        target = Path(worker_path) / "flowchart.json"
+        if target.is_file():
+            try:
+                data = json.loads(target.read_text(encoding="utf-8"))
+                original_draft = data.get("original_draft")
+                fmap = data.get("flowchart_map")
+                # Cache in phase_state for future requests
+                if phase_state is not None and original_draft:
+                    phase_state.original_draft_graph = original_draft
+                    phase_state.flowchart_map = fmap
+                return web.json_response({
+                    "map": fmap,
+                    "original_draft": original_draft,
+                })
+            except Exception:
+                logger.warning("Failed to read flowchart.json from %s", worker_path)
+
+    return web.json_response({"map": None, "original_draft": None})
+
+
 def register_routes(app: web.Application) -> None:
     """Register graph/node inspection routes."""
+    # Draft graph (planning phase — visual only, no loaded worker required)
+    app.router.add_get("/api/sessions/{session_id}/draft-graph", handle_draft_graph)
+    # Flowchart map (post-dissolution — maps runtime nodes to original draft nodes)
+    app.router.add_get("/api/sessions/{session_id}/flowchart-map", handle_flowchart_map)
     # Session-primary routes
     app.router.add_get("/api/sessions/{session_id}/graphs/{graph_id}/nodes", handle_list_nodes)
     app.router.add_get(

core/framework/server/routes_sessions.py

@@ -731,7 +731,7 @@ async def handle_delete_history_session(request: web.Request) -> web.Response:
 
 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
+    from framework.agents.discovery import discover_agents
 
     manager = _get_manager(request)
     loaded_paths = {str(s.worker_path) for s in manager.list_sessions() if s.worker_path}

core/framework/server/session_manager.py

@@ -278,11 +278,20 @@ class SessionManager:
         When a new runtime starts, any on-disk session still marked 'active'
         is from a process that no longer exists. 'Paused' sessions are left
         intact so they remain resumable.
+
+        Two-layer protection against corrupting live sessions:
+        1. In-memory: skip any session ID currently tracked in self._sessions
+           (guaranteed alive in this process).
+        2. PID validation: if state.json contains a ``pid`` field, check whether
+           that process is still running on the host. If it is, the session is
+           owned by another healthy worker process, so leave it alone.
         """
         sessions_path = Path.home() / ".hive" / "agents" / agent_path.name / "sessions"
         if not sessions_path.exists():
             return
 
+        live_session_ids = set(self._sessions.keys())
+
         for d in sessions_path.iterdir():
             if not d.is_dir() or not d.name.startswith("session_"):
                 continue
@@ -293,6 +302,26 @@ class SessionManager:
                 state = json.loads(state_path.read_text(encoding="utf-8"))
                 if state.get("status") != "active":
                     continue
+
+                # Layer 1: skip sessions that are alive in this process
+                session_id = state.get("session_id", d.name)
+                if session_id in live_session_ids or d.name in live_session_ids:
+                    logger.debug(
+                        "Skipping live in-memory session '%s' during stale cleanup",
+                        d.name,
+                    )
+                    continue
+
+                # Layer 2: skip sessions whose owning process is still alive
+                recorded_pid = state.get("pid")
+                if recorded_pid is not None and self._is_pid_alive(recorded_pid):
+                    logger.debug(
+                        "Skipping session '%s' — owning process %d is still running",
+                        d.name,
+                        recorded_pid,
+                    )
+                    continue
+
                 state["status"] = "cancelled"
                 state.setdefault("result", {})["error"] = "Stale session: runtime restarted"
                 state.setdefault("timestamps", {})["updated_at"] = datetime.now().isoformat()
@@ -303,6 +332,34 @@ class SessionManager:
             except (json.JSONDecodeError, OSError) as e:
                 logger.warning("Failed to clean up stale session %s: %s", d.name, e)
 
+    @staticmethod
+    def _is_pid_alive(pid: int) -> bool:
+        """Check whether a process with the given PID is still running."""
+        import os
+        import platform
+
+        if platform.system() == "Windows":
+            import ctypes
+
+            # PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+            kernel32 = ctypes.windll.kernel32
+            handle = kernel32.OpenProcess(0x1000, False, pid)
+            if not handle:
+                # 5 is ERROR_ACCESS_DENIED, meaning the process exists but is protected
+                return kernel32.GetLastError() == 5
+
+            exit_code = ctypes.c_ulong()
+            kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code))
+            kernel32.CloseHandle(handle)
+            # 259 is STILL_ACTIVE
+            return exit_code.value == 259
+        else:
+            try:
+                os.kill(pid, 0)
+            except OSError:
+                return False
+            return True
+
     async def load_worker(
         self,
         session_id: str,

core/framework/server/tests/test_api.py

@@ -37,6 +37,7 @@ class MockNodeSpec:
     client_facing: bool = False
     success_criteria: str | None = None
     system_prompt: str | None = None
+    sub_agents: list = field(default_factory=list)
 
 
 @dataclass
@@ -67,6 +68,7 @@ class MockEntryPoint:
     name: str = "Default"
     entry_node: str = "start"
     trigger_type: str = "manual"
+    trigger_config: dict = field(default_factory=dict)
 
 
 @dataclass
@@ -130,6 +132,9 @@ class MockRuntime:
     def get_stats(self):
         return {"running": True, "executions": 1}
 
+    def get_timer_next_fire_in(self, ep_id):
+        return None
+
 
 class MockAgentInfo:
     name: str = "test_agent"
@@ -1556,3 +1561,106 @@ class TestErrorMiddleware:
         async with TestClient(TestServer(app)) as client:
             resp = await client.get("/api/nonexistent")
             assert resp.status == 404
+
+
+class TestCleanupStaleActiveSessions:
+    """Tests for _cleanup_stale_active_sessions with two-layer protection."""
+
+    def _make_manager(self):
+        from framework.server.session_manager import SessionManager
+
+        return SessionManager()
+
+    def _write_state(self, session_dir: Path, status: str, pid: int | None = None) -> None:
+        session_dir.mkdir(parents=True, exist_ok=True)
+        state: dict = {"status": status, "session_id": session_dir.name}
+        if pid is not None:
+            state["pid"] = pid
+        (session_dir / "state.json").write_text(json.dumps(state))
+
+    def _read_state(self, session_dir: Path) -> dict:
+        return json.loads((session_dir / "state.json").read_text())
+
+    def test_stale_session_is_cancelled(self, tmp_path, monkeypatch):
+        """Truly stale active sessions (no live tracking, no PID) get cancelled."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        agent_path = Path("my_agent")
+        sessions_dir = tmp_path / ".hive" / "agents" / "my_agent" / "sessions"
+        session_dir = sessions_dir / "session_stale_001"
+
+        self._write_state(session_dir, "active")
+
+        mgr = self._make_manager()
+        mgr._cleanup_stale_active_sessions(agent_path)
+
+        state = self._read_state(session_dir)
+        assert state["status"] == "cancelled"
+        assert "Stale session" in state["result"]["error"]
+
+    def test_live_in_memory_session_is_skipped(self, tmp_path, monkeypatch):
+        """Sessions tracked in self._sessions must NOT be cancelled (Layer 1)."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        agent_path = Path("my_agent")
+        sessions_dir = tmp_path / ".hive" / "agents" / "my_agent" / "sessions"
+        session_dir = sessions_dir / "session_live_002"
+
+        self._write_state(session_dir, "active")
+
+        mgr = self._make_manager()
+        # Simulate a live session in the manager's in-memory map
+        mgr._sessions["session_live_002"] = MagicMock()
+
+        mgr._cleanup_stale_active_sessions(agent_path)
+
+        state = self._read_state(session_dir)
+        assert state["status"] == "active", "Live in-memory session should NOT be cancelled"
+
+    def test_session_with_live_pid_is_skipped(self, tmp_path, monkeypatch):
+        """Sessions whose owning PID is still alive must NOT be cancelled (Layer 2)."""
+        import os
+
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        agent_path = Path("my_agent")
+        sessions_dir = tmp_path / ".hive" / "agents" / "my_agent" / "sessions"
+        session_dir = sessions_dir / "session_pid_003"
+
+        # Use the current process PID — guaranteed to be alive
+        self._write_state(session_dir, "active", pid=os.getpid())
+
+        mgr = self._make_manager()
+        mgr._cleanup_stale_active_sessions(agent_path)
+
+        state = self._read_state(session_dir)
+        assert state["status"] == "active", "Session with live PID should NOT be cancelled"
+
+    def test_session_with_dead_pid_is_cancelled(self, tmp_path, monkeypatch):
+        """Sessions whose owning PID is dead should be cancelled."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        agent_path = Path("my_agent")
+        sessions_dir = tmp_path / ".hive" / "agents" / "my_agent" / "sessions"
+        session_dir = sessions_dir / "session_dead_004"
+
+        # Use a PID that is almost certainly not running
+        self._write_state(session_dir, "active", pid=999999999)
+
+        mgr = self._make_manager()
+        mgr._cleanup_stale_active_sessions(agent_path)
+
+        state = self._read_state(session_dir)
+        assert state["status"] == "cancelled"
+        assert "Stale session" in state["result"]["error"]
+
+    def test_paused_session_is_never_touched(self, tmp_path, monkeypatch):
+        """Paused sessions should remain intact regardless of PID or tracking."""
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        agent_path = Path("my_agent")
+        sessions_dir = tmp_path / ".hive" / "agents" / "my_agent" / "sessions"
+        session_dir = sessions_dir / "session_paused_005"
+
+        self._write_state(session_dir, "paused")
+
+        mgr = self._make_manager()
+        mgr._cleanup_stale_active_sessions(agent_path)
+
+        state = self._read_state(session_dir)
+        assert state["status"] == "paused", "Paused sessions must remain untouched"

core/framework/storage/state_writer.py

@@ -1,179 +0,0 @@
-"""
-State Writer - Dual-write adapter for migration period.
-
-Writes execution state to both old (Run/RunSummary) and new (state.json) formats
-to maintain backward compatibility during the transition period.
-"""
-
-import logging
-import os
-from datetime import datetime
-
-from framework.schemas.run import Problem, Run, RunMetrics, RunStatus
-from framework.schemas.session_state import SessionState, SessionStatus
-from framework.storage.concurrent import ConcurrentStorage
-from framework.storage.session_store import SessionStore
-
-logger = logging.getLogger(__name__)
-
-
-class StateWriter:
-    """
-    Writes execution state to both old and new formats during migration.
-
-    During the dual-write phase:
-    - New format (state.json) is written when USE_UNIFIED_SESSIONS=true
-    - Old format (Run/RunSummary) is always written for backward compatibility
-    """
-
-    def __init__(self, old_storage: ConcurrentStorage, session_store: SessionStore):
-        """
-        Initialize state writer.
-
-        Args:
-            old_storage: ConcurrentStorage for old format (runs/, summaries/)
-            session_store: SessionStore for new format (sessions/*/state.json)
-        """
-        self.old = old_storage
-        self.new = session_store
-        self.dual_write_enabled = os.getenv("USE_UNIFIED_SESSIONS", "false").lower() == "true"
-
-    async def write_execution_state(
-        self,
-        session_id: str,
-        state: SessionState,
-    ) -> None:
-        """
-        Write execution state to both old and new formats.
-
-        Args:
-            session_id: Session ID
-            state: SessionState to write
-        """
-        # Write to new format if enabled
-        if self.dual_write_enabled:
-            try:
-                await self.new.write_state(session_id, state)
-                logger.debug(f"Wrote state.json for session {session_id}")
-            except Exception as e:
-                logger.error(f"Failed to write state.json for {session_id}: {e}")
-                # Don't fail - old format is still written
-
-        # Always write to old format for backward compatibility
-        try:
-            run = self._convert_to_run(state)
-            await self.old.save_run(run)
-            logger.debug(f"Wrote Run object for session {session_id}")
-        except Exception as e:
-            logger.error(f"Failed to write Run object for {session_id}: {e}")
-            # This is more critical - reraise if old format fails
-            raise
-
-    def _convert_to_run(self, state: SessionState) -> Run:
-        """
-        Convert SessionState to legacy Run object.
-
-        Args:
-            state: SessionState to convert
-
-        Returns:
-            Run object
-        """
-        # Map SessionStatus to RunStatus
-        status_mapping = {
-            SessionStatus.ACTIVE: RunStatus.RUNNING,
-            SessionStatus.PAUSED: RunStatus.RUNNING,  # Paused is still "running" in old format
-            SessionStatus.COMPLETED: RunStatus.COMPLETED,
-            SessionStatus.FAILED: RunStatus.FAILED,
-            SessionStatus.CANCELLED: RunStatus.CANCELLED,
-        }
-        run_status = status_mapping.get(state.status, RunStatus.FAILED)
-
-        # Convert timestamps
-        started_at = datetime.fromisoformat(state.timestamps.started_at)
-        completed_at = (
-            datetime.fromisoformat(state.timestamps.completed_at)
-            if state.timestamps.completed_at
-            else None
-        )
-
-        # Build RunMetrics
-        metrics = RunMetrics(
-            total_decisions=state.metrics.decision_count,
-            successful_decisions=state.metrics.decision_count
-            - len(state.progress.nodes_with_failures),  # Approximate
-            failed_decisions=len(state.progress.nodes_with_failures),
-            total_tokens=state.metrics.total_input_tokens + state.metrics.total_output_tokens,
-            total_latency_ms=state.progress.total_latency_ms,
-            nodes_executed=state.metrics.nodes_executed,
-            edges_traversed=state.metrics.edges_traversed,
-        )
-
-        # Convert problems (SessionState stores as dicts, Run expects Problem objects)
-        problems = []
-        for p_dict in state.problems:
-            # Handle both old Problem objects and new dict format
-            if isinstance(p_dict, dict):
-                problems.append(Problem(**p_dict))
-            else:
-                problems.append(p_dict)
-
-        # Convert decisions (SessionState stores as dicts, Run expects Decision objects)
-        from framework.schemas.decision import Decision
-
-        decisions = []
-        for d_dict in state.decisions:
-            # Handle both old Decision objects and new dict format
-            if isinstance(d_dict, dict):
-                try:
-                    decisions.append(Decision(**d_dict))
-                except Exception:
-                    # Skip invalid decisions
-                    continue
-            else:
-                decisions.append(d_dict)
-
-        # Create Run object
-        run = Run(
-            id=state.session_id,  # Use session_id as run_id
-            goal_id=state.goal_id,
-            started_at=started_at,
-            status=run_status,
-            completed_at=completed_at,
-            decisions=decisions,
-            problems=problems,
-            metrics=metrics,
-            goal_description="",  # Not stored in SessionState
-            input_data=state.input_data,
-            output_data=state.result.output,
-        )
-
-        return run
-
-    async def read_state(
-        self,
-        session_id: str,
-        prefer_new: bool = True,
-    ) -> SessionState | None:
-        """
-        Read execution state from either format.
-
-        Args:
-            session_id: Session ID
-            prefer_new: If True, try new format first (default)
-
-        Returns:
-            SessionState or None if not found
-        """
-        if prefer_new:
-            # Try new format first
-            state = await self.new.read_state(session_id)
-            if state:
-                return state
-
-        # Fall back to old format
-        run = await self.old.load_run(session_id)
-        if run:
-            return SessionState.from_legacy_run(run, session_id)
-
-        return None

core/framework/tui/screens/__init__.py

@@ -1,13 +0,0 @@
-"""TUI screens package."""
-
-from .account_selection import AccountSelectionScreen
-from .add_local_credential import AddLocalCredentialScreen
-from .agent_picker import AgentPickerScreen
-from .credential_setup import CredentialSetupScreen
-
-__all__ = [
-    "AccountSelectionScreen",
-    "AddLocalCredentialScreen",
-    "AgentPickerScreen",
-    "CredentialSetupScreen",
-]

core/framework/tui/screens/account_selection.py

@@ -1,111 +0,0 @@
-"""Account selection ModalScreen for picking a connected account before agent start."""
-
-from __future__ import annotations
-
-from rich.text import Text
-from textual.app import ComposeResult
-from textual.binding import Binding
-from textual.containers import Vertical
-from textual.screen import ModalScreen
-from textual.widgets import Label, OptionList
-from textual.widgets._option_list import Option
-
-
-class AccountSelectionScreen(ModalScreen[dict | None]):
-    """Modal screen showing connected accounts for pre-run selection.
-
-    Returns the selected account dict, or None if dismissed.
-    """
-
-    SCOPED_CSS = False
-
-    BINDINGS = [
-        Binding("escape", "dismiss_picker", "Cancel"),
-    ]
-
-    DEFAULT_CSS = """
-    AccountSelectionScreen {
-        align: center middle;
-    }
-    #acct-container {
-        width: 70%;
-        max-width: 80;
-        height: 60%;
-        background: $surface;
-        border: heavy $primary;
-        padding: 1 2;
-    }
-    #acct-title {
-        text-align: center;
-        text-style: bold;
-        width: 100%;
-        color: $text;
-    }
-    #acct-subtitle {
-        text-align: center;
-        width: 100%;
-        margin-bottom: 1;
-    }
-    #acct-footer {
-        text-align: center;
-        width: 100%;
-        margin-top: 1;
-    }
-    """
-
-    def __init__(self, accounts: list[dict]) -> None:
-        super().__init__()
-        self._accounts = accounts
-
-    def compose(self) -> ComposeResult:
-        n = len(self._accounts)
-        with Vertical(id="acct-container"):
-            yield Label("Select Account to Test", id="acct-title")
-            yield Label(
-                f"[dim]{n} connected account{'s' if n != 1 else ''}[/dim]",
-                id="acct-subtitle",
-            )
-            option_list = OptionList(id="acct-list")
-            # Group: Aden accounts first, then local
-            aden = [a for a in self._accounts if a.get("source") != "local"]
-            local = [a for a in self._accounts if a.get("source") == "local"]
-            ordered = aden + local
-            for i, acct in enumerate(ordered):
-                provider = acct.get("provider", "unknown")
-                alias = acct.get("alias", "unknown")
-                identity = acct.get("identity", {})
-                source = acct.get("source", "aden")
-                # Build identity label: prefer email, then username/workspace
-                identity_label = (
-                    identity.get("email")
-                    or identity.get("username")
-                    or identity.get("workspace")
-                    or ""
-                )
-                label = Text()
-                label.append(f"{provider}/", style="bold")
-                label.append(alias, style="bold cyan")
-                if source == "local":
-                    label.append("  [local]", style="dim yellow")
-                if identity_label:
-                    label.append(f"  ({identity_label})", style="dim")
-                option_list.add_option(Option(label, id=f"acct-{i}"))
-            # Keep ordered list for index lookups
-            self._accounts = ordered
-            yield option_list
-            yield Label(
-                "[dim]Enter[/dim] Select  [dim]Esc[/dim] Cancel",
-                id="acct-footer",
-            )
-
-    def on_mount(self) -> None:
-        ol = self.query_one("#acct-list", OptionList)
-        ol.styles.height = "1fr"
-
-    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
-        idx = event.option_index
-        if 0 <= idx < len(self._accounts):
-            self.dismiss(self._accounts[idx])
-
-    def action_dismiss_picker(self) -> None:
-        self.dismiss(None)

core/framework/tui/screens/add_local_credential.py

@@ -1,244 +0,0 @@
-"""Add Local Credential ModalScreen for storing named local API key accounts."""
-
-from __future__ import annotations
-
-from textual.app import ComposeResult
-from textual.binding import Binding
-from textual.containers import Vertical, VerticalScroll
-from textual.screen import ModalScreen
-from textual.widgets import Button, Input, Label, OptionList
-from textual.widgets._option_list import Option
-
-
-class AddLocalCredentialScreen(ModalScreen[dict | None]):
-    """Modal screen for adding a named local API key credential.
-
-    Phase 1: Pick credential type from list.
-    Phase 2: Enter alias + API key, run health check, save.
-
-    Returns a dict with credential_id, alias, and identity on success, or None on cancel.
-    """
-
-    BINDINGS = [
-        Binding("escape", "dismiss_screen", "Cancel"),
-    ]
-
-    DEFAULT_CSS = """
-    AddLocalCredentialScreen {
-        align: center middle;
-    }
-    #alc-container {
-        width: 80%;
-        max-width: 90;
-        height: 80%;
-        background: $surface;
-        border: heavy $primary;
-        padding: 1 2;
-    }
-    #alc-title {
-        text-align: center;
-        text-style: bold;
-        width: 100%;
-        color: $text;
-    }
-    #alc-subtitle {
-        text-align: center;
-        width: 100%;
-        margin-bottom: 1;
-    }
-    #alc-type-list {
-        height: 1fr;
-    }
-    #alc-form {
-        height: 1fr;
-    }
-    .alc-field {
-        margin-bottom: 1;
-        height: auto;
-    }
-    .alc-field Label {
-        margin-bottom: 0;
-    }
-    #alc-status {
-        width: 100%;
-        height: auto;
-        margin-top: 1;
-        padding: 1;
-        background: $panel;
-    }
-    .alc-buttons {
-        height: auto;
-        margin-top: 1;
-        align: center middle;
-    }
-    .alc-buttons Button {
-        margin: 0 1;
-    }
-    #alc-footer {
-        text-align: center;
-        width: 100%;
-        margin-top: 1;
-    }
-    """
-
-    def __init__(self) -> None:
-        super().__init__()
-        # Load credential specs that support direct API keys
-        self._specs: list[tuple[str, object]] = self._load_specs()
-        # Selected credential spec (set in phase 2)
-        self._selected_id: str = ""
-        self._selected_spec: object = None
-        self._phase: int = 1  # 1 = type selection, 2 = form
-
-    @staticmethod
-    def _load_specs() -> list[tuple[str, object]]:
-        """Return (credential_id, spec) pairs for direct-API-key credentials."""
-        try:
-            from aden_tools.credentials import CREDENTIAL_SPECS
-
-            return [
-                (cid, spec)
-                for cid, spec in CREDENTIAL_SPECS.items()
-                if getattr(spec, "direct_api_key_supported", False)
-            ]
-        except Exception:
-            return []
-
-    # ------------------------------------------------------------------
-    # Compose
-    # ------------------------------------------------------------------
-
-    def compose(self) -> ComposeResult:
-        with Vertical(id="alc-container"):
-            yield Label("Add Local Credential", id="alc-title")
-            yield Label("[dim]Store a named API key account[/dim]", id="alc-subtitle")
-            # Phase 1: type selection
-            option_list = OptionList(id="alc-type-list")
-            for cid, spec in self._specs:
-                description = getattr(spec, "description", cid)
-                option_list.add_option(Option(f"{cid}  [dim]{description}[/dim]", id=f"type-{cid}"))
-            yield option_list
-            # Phase 2: form (hidden initially)
-            with VerticalScroll(id="alc-form"):
-                with Vertical(classes="alc-field"):
-                    yield Label("[bold]Alias[/bold]  [dim](e.g. work, personal)[/dim]")
-                    yield Input(value="default", id="alc-alias")
-                with Vertical(classes="alc-field"):
-                    yield Label("[bold]API Key[/bold]")
-                    yield Input(placeholder="Paste API key...", password=True, id="alc-key")
-                yield Label("", id="alc-status")
-                with Vertical(classes="alc-buttons"):
-                    yield Button("Test & Save", variant="primary", id="btn-save")
-                    yield Button("Back", variant="default", id="btn-back")
-            yield Label(
-                "[dim]Enter[/dim] Select  [dim]Esc[/dim] Cancel",
-                id="alc-footer",
-            )
-
-    def on_mount(self) -> None:
-        self._show_phase(1)
-
-    # ------------------------------------------------------------------
-    # Phase switching
-    # ------------------------------------------------------------------
-
-    def _show_phase(self, phase: int) -> None:
-        self._phase = phase
-        type_list = self.query_one("#alc-type-list", OptionList)
-        form = self.query_one("#alc-form", VerticalScroll)
-        if phase == 1:
-            type_list.display = True
-            form.display = False
-            subtitle = self.query_one("#alc-subtitle", Label)
-            subtitle.update("[dim]Select the credential type to add[/dim]")
-        else:
-            type_list.display = False
-            form.display = True
-            spec = self._selected_spec
-            description = (
-                getattr(spec, "description", self._selected_id) if spec else self._selected_id
-            )
-            subtitle = self.query_one("#alc-subtitle", Label)
-            subtitle.update(f"[dim]{self._selected_id}[/dim]  {description}")
-            self._clear_status()
-            # Focus the alias input
-            self.query_one("#alc-alias", Input).focus()
-
-    # ------------------------------------------------------------------
-    # Event handlers
-    # ------------------------------------------------------------------
-
-    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
-        if self._phase != 1:
-            return
-        option_id = event.option.id or ""
-        if option_id.startswith("type-"):
-            cid = option_id[5:]  # strip "type-" prefix
-            self._selected_id = cid
-            self._selected_spec = next(
-                (spec for spec_id, spec in self._specs if spec_id == cid), None
-            )
-            self._show_phase(2)
-
-    def on_button_pressed(self, event: Button.Pressed) -> None:
-        if event.button.id == "btn-save":
-            self._do_save()
-        elif event.button.id == "btn-back":
-            self._show_phase(1)
-
-    # ------------------------------------------------------------------
-    # Save logic
-    # ------------------------------------------------------------------
-
-    def _do_save(self) -> None:
-        alias = self.query_one("#alc-alias", Input).value.strip() or "default"
-        api_key = self.query_one("#alc-key", Input).value.strip()
-
-        if not api_key:
-            self._set_status("[red]API key cannot be empty.[/red]")
-            return
-
-        self._set_status("[dim]Running health check...[/dim]")
-        # Disable save button while running
-        btn = self.query_one("#btn-save", Button)
-        btn.disabled = True
-
-        try:
-            from framework.credentials.local.registry import LocalCredentialRegistry
-
-            registry = LocalCredentialRegistry.default()
-            info, health_result = registry.save_account(
-                credential_id=self._selected_id,
-                alias=alias,
-                api_key=api_key,
-                run_health_check=True,
-            )
-
-            if health_result is not None and not health_result.valid:
-                self._set_status(
-                    f"[yellow]Saved with failed health check:[/yellow] {health_result.message}\n"
-                    "[dim]You can re-validate later via validate_credential().[/dim]"
-                )
-            else:
-                identity = info.identity.to_dict()
-                identity_str = ""
-                if identity:
-                    parts = [f"{k}: {v}" for k, v in identity.items() if v]
-                    identity_str = "  " + ", ".join(parts) if parts else ""
-                self._set_status(f"[green]Saved:[/green] {info.storage_id}{identity_str}")
-                # Dismiss with result so callers can react
-                self.set_timer(1.0, lambda: self.dismiss(info.to_account_dict()))
-                return
-        except Exception as e:
-            self._set_status(f"[red]Error:[/red] {e}")
-        finally:
-            btn.disabled = False
-
-    def _set_status(self, markup: str) -> None:
-        self.query_one("#alc-status", Label).update(markup)
-
-    def _clear_status(self) -> None:
-        self.query_one("#alc-status", Label).update("")
-
-    def action_dismiss_screen(self) -> None:
-        self.dismiss(None)

core/framework/tui/screens/agent_picker.py

@@ -1,362 +0,0 @@
-"""Agent picker ModalScreen for selecting agents within the TUI."""
-
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass, field
-from enum import Enum
-from pathlib import Path
-
-from rich.console import Group
-from rich.text import Text
-from textual.app import ComposeResult
-from textual.binding import Binding
-from textual.containers import Vertical
-from textual.screen import ModalScreen
-from textual.widgets import Label, OptionList, TabbedContent, TabPane
-from textual.widgets._option_list import Option
-
-
-class GetStartedAction(Enum):
-    """Actions available in the Get Started tab."""
-
-    RUN_EXAMPLES = "run_examples"
-    RUN_EXISTING = "run_existing"
-    BUILD_EDIT = "build_edit"
-
-
-@dataclass
-class AgentEntry:
-    """Lightweight agent metadata for the picker."""
-
-    path: Path
-    name: str
-    description: str
-    category: str
-    session_count: int = 0
-    node_count: int = 0
-    tool_count: int = 0
-    tags: list[str] = field(default_factory=list)
-    last_active: str | None = None
-
-
-def _get_last_active(agent_name: str) -> str | None:
-    """Return the most recent updated_at timestamp across all sessions."""
-    sessions_dir = Path.home() / ".hive" / "agents" / agent_name / "sessions"
-    if not sessions_dir.exists():
-        return None
-    latest: str | None = None
-    for session_dir in sessions_dir.iterdir():
-        if not session_dir.is_dir() or not session_dir.name.startswith("session_"):
-            continue
-        state_file = session_dir / "state.json"
-        if not state_file.exists():
-            continue
-        try:
-            data = json.loads(state_file.read_text(encoding="utf-8"))
-            ts = data.get("timestamps", {}).get("updated_at")
-            if ts and (latest is None or ts > latest):
-                latest = ts
-        except Exception:
-            continue
-    return latest
-
-
-def _count_sessions(agent_name: str) -> int:
-    """Count session directories under ~/.hive/agents/{agent_name}/sessions/."""
-    sessions_dir = Path.home() / ".hive" / "agents" / agent_name / "sessions"
-    if not sessions_dir.exists():
-        return 0
-    return sum(1 for d in sessions_dir.iterdir() if d.is_dir() and d.name.startswith("session_"))
-
-
-def _extract_agent_stats(agent_path: Path) -> tuple[int, int, list[str]]:
-    """Extract node count, tool count, and tags from an agent directory.
-
-    Prefers agent.py (AST-parsed) over agent.json for node/tool counts
-    since agent.json may be stale.  Tags are only available from agent.json.
-    """
-    import ast
-
-    node_count, tool_count, tags = 0, 0, []
-
-    # Try agent.py first — source of truth for nodes
-    agent_py = agent_path / "agent.py"
-    if agent_py.exists():
-        try:
-            tree = ast.parse(agent_py.read_text(encoding="utf-8"))
-            for node in ast.walk(tree):
-                # Find `nodes = [...]` assignment
-                if isinstance(node, ast.Assign):
-                    for target in node.targets:
-                        if isinstance(target, ast.Name) and target.id == "nodes":
-                            if isinstance(node.value, ast.List):
-                                node_count = len(node.value.elts)
-        except Exception:
-            pass
-
-    # Fall back to / supplement from agent.json
-    agent_json = agent_path / "agent.json"
-    if agent_json.exists():
-        try:
-            data = json.loads(agent_json.read_text(encoding="utf-8"))
-            json_nodes = data.get("nodes", [])
-            if node_count == 0:
-                node_count = len(json_nodes)
-            # Tool count: use whichever source gave us nodes, but agent.json
-            # has the structured tool lists so prefer it for tool counting
-            tools: set[str] = set()
-            for n in json_nodes:
-                tools.update(n.get("tools", []))
-            tool_count = len(tools)
-            tags = data.get("agent", {}).get("tags", [])
-        except Exception:
-            pass
-
-    return node_count, tool_count, tags
-
-
-def discover_agents() -> dict[str, list[AgentEntry]]:
-    """Discover agents from all known sources grouped by category."""
-    from framework.runner.cli import (
-        _extract_python_agent_metadata,
-        _get_framework_agents_dir,
-        _is_valid_agent_dir,
-    )
-
-    groups: dict[str, list[AgentEntry]] = {}
-    sources = [
-        ("Your Agents", Path("exports")),
-        ("Framework", _get_framework_agents_dir()),
-        ("Examples", Path("examples/templates")),
-    ]
-
-    for category, base_dir in sources:
-        if not base_dir.exists():
-            continue
-        entries: list[AgentEntry] = []
-        for path in sorted(base_dir.iterdir(), key=lambda p: p.name):
-            if not _is_valid_agent_dir(path):
-                continue
-
-            # config.py is source of truth for name/description
-            name, desc = _extract_python_agent_metadata(path)
-            config_fallback_name = path.name.replace("_", " ").title()
-            used_config = name != config_fallback_name
-
-            node_count, tool_count, tags = _extract_agent_stats(path)
-            if not used_config:
-                # config.py didn't provide values, fall back to agent.json
-                agent_json = path / "agent.json"
-                if agent_json.exists():
-                    try:
-                        data = json.loads(agent_json.read_text(encoding="utf-8"))
-                        meta = data.get("agent", {})
-                        name = meta.get("name", name)
-                        desc = meta.get("description", desc)
-                    except Exception:
-                        pass
-
-            entries.append(
-                AgentEntry(
-                    path=path,
-                    name=name,
-                    description=desc,
-                    category=category,
-                    session_count=_count_sessions(path.name),
-                    node_count=node_count,
-                    tool_count=tool_count,
-                    tags=tags,
-                    last_active=_get_last_active(path.name),
-                )
-            )
-        if entries:
-            groups[category] = entries
-
-    return groups
-
-
-def _render_agent_option(agent: AgentEntry) -> Group:
-    """Build a Rich renderable for a single agent option."""
-    # Line 1: name + session badge
-    line1 = Text()
-    line1.append(agent.name, style="bold")
-    if agent.session_count:
-        line1.append(f"  {agent.session_count} sessions", style="dim cyan")
-
-    # Line 2: description (word-wrapped by the widget)
-    desc = agent.description if agent.description else "No description"
-    line2 = Text(desc, style="dim")
-
-    # Line 3: stats chips
-    chips = Text()
-    if agent.node_count:
-        chips.append(f" {agent.node_count} nodes ", style="on dark_green white")
-        chips.append(" ")
-    if agent.tool_count:
-        chips.append(f" {agent.tool_count} tools ", style="on dark_blue white")
-        chips.append(" ")
-    for tag in agent.tags[:3]:
-        chips.append(f" {tag} ", style="on grey37 white")
-        chips.append(" ")
-
-    parts = [line1, line2]
-    if chips.plain.strip():
-        parts.append(chips)
-    return Group(*parts)
-
-
-def _render_get_started_option(title: str, description: str, icon: str = "→") -> Group:
-    """Build a Rich renderable for a Get Started option."""
-    line1 = Text()
-    line1.append(f"{icon} ", style="bold cyan")
-    line1.append(title, style="bold")
-    line2 = Text(description, style="dim")
-    return Group(line1, line2)
-
-
-class AgentPickerScreen(ModalScreen[str | None]):
-    """Modal screen showing available agents organized by tabbed categories.
-
-    Returns the selected agent path as a string, or None if dismissed.
-    For Get Started actions, returns a special prefix like "action:run_examples".
-    """
-
-    BINDINGS = [
-        Binding("escape", "dismiss_picker", "Cancel"),
-    ]
-
-    DEFAULT_CSS = """
-    AgentPickerScreen {
-        align: center middle;
-    }
-    #picker-container {
-        width: 90%;
-        max-width: 120;
-        height: 85%;
-        background: $surface;
-        border: heavy $primary;
-        padding: 1 2;
-    }
-    #picker-title {
-        text-align: center;
-        text-style: bold;
-        width: 100%;
-        color: $text;
-    }
-    #picker-subtitle {
-        text-align: center;
-        width: 100%;
-        margin-bottom: 1;
-    }
-    #picker-footer {
-        text-align: center;
-        width: 100%;
-        margin-top: 1;
-    }
-    TabPane {
-        padding: 0;
-    }
-    OptionList {
-        height: 1fr;
-    }
-    OptionList > .option-list--option {
-        padding: 1 2;
-    }
-    """
-
-    def __init__(
-        self,
-        agent_groups: dict[str, list[AgentEntry]],
-        show_get_started: bool = False,
-    ) -> None:
-        super().__init__()
-        self._groups = agent_groups
-        self._show_get_started = show_get_started
-        # Map (tab_id, option_index) -> AgentEntry
-        self._option_map: dict[str, dict[int, AgentEntry]] = {}
-
-    def compose(self) -> ComposeResult:
-        total = sum(len(v) for v in self._groups.values())
-        with Vertical(id="picker-container"):
-            yield Label("Hive Agent Launcher", id="picker-title")
-            yield Label(
-                f"[dim]{total} agents available[/dim]",
-                id="picker-subtitle",
-            )
-            with TabbedContent():
-                # Get Started tab (only on initial launch)
-                if self._show_get_started:
-                    with TabPane("Get Started", id="get-started"):
-                        option_list = OptionList(id="list-get-started")
-                        option_list.add_option(
-                            Option(
-                                _render_get_started_option(
-                                    "Test and run example agents",
-                                    "Try pre-built example agents to learn how Hive works",
-                                    "📚",
-                                ),
-                                id="action:run_examples",
-                            )
-                        )
-                        option_list.add_option(
-                            Option(
-                                _render_get_started_option(
-                                    "Test and run existing agent",
-                                    "Load and run an agent you've already built (from exports/)",
-                                    "🚀",
-                                ),
-                                id="action:run_existing",
-                            )
-                        )
-                        option_list.add_option(
-                            Option(
-                                _render_get_started_option(
-                                    "Build or edit agent",
-                                    "Create a new agent or modify an existing one",
-                                    "🛠️ ",
-                                ),
-                                id="action:build_edit",
-                            )
-                        )
-                        yield option_list
-
-                # Agent category tabs
-                for category, agents in self._groups.items():
-                    tab_id = category.lower().replace(" ", "-")
-                    with TabPane(f"{category} ({len(agents)})", id=tab_id):
-                        option_list = OptionList(id=f"list-{tab_id}")
-                        self._option_map[f"list-{tab_id}"] = {}
-                        for i, agent in enumerate(agents):
-                            option_list.add_option(
-                                Option(
-                                    _render_agent_option(agent),
-                                    id=str(agent.path),
-                                )
-                            )
-                            self._option_map[f"list-{tab_id}"][i] = agent
-                        yield option_list
-            yield Label(
-                "[dim]Enter[/dim] Select  [dim]Tab[/dim] Switch category  [dim]Esc[/dim] Cancel",
-                id="picker-footer",
-            )
-
-    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
-        list_id = event.option_list.id or ""
-
-        # Handle Get Started tab options
-        if list_id == "list-get-started":
-            option = event.option
-            if option and option.id:
-                self.dismiss(option.id)  # Returns "action:run_examples", etc.
-            return
-
-        # Handle agent selection from other tabs
-        idx = event.option_index
-        agent_map = self._option_map.get(list_id, {})
-        agent = agent_map.get(idx)
-        if agent:
-            self.dismiss(str(agent.path))
-
-    def action_dismiss_picker(self) -> None:
-        self.dismiss(None)

core/framework/tui/screens/credential_setup.py

@@ -1,304 +0,0 @@
-"""Credential setup ModalScreen for configuring missing agent credentials."""
-
-from __future__ import annotations
-
-import os
-
-from textual.app import ComposeResult
-from textual.binding import Binding
-from textual.containers import Vertical, VerticalScroll
-from textual.screen import ModalScreen
-from textual.widgets import Button, Input, Label
-
-from framework.credentials.setup import CredentialSetupSession, MissingCredential
-
-
-class CredentialSetupScreen(ModalScreen[bool | None]):
-    """Modal screen for configuring missing agent credentials.
-
-    Shows a form with one password Input per missing credential.
-    For Aden-backed credentials (``aden_supported=True``), prompts for
-    ``ADEN_API_KEY`` and runs the Aden sync flow instead of storing a
-    raw value.
-
-    Returns True on successful save, or None on cancel/skip.
-    """
-
-    BINDINGS = [
-        Binding("escape", "dismiss_setup", "Cancel"),
-    ]
-
-    DEFAULT_CSS = """
-    CredentialSetupScreen {
-        align: center middle;
-    }
-    #cred-container {
-        width: 80%;
-        max-width: 100;
-        height: 80%;
-        background: $surface;
-        border: heavy $primary;
-        padding: 1 2;
-    }
-    #cred-title {
-        text-align: center;
-        text-style: bold;
-        width: 100%;
-        color: $text;
-    }
-    #cred-subtitle {
-        text-align: center;
-        width: 100%;
-        margin-bottom: 1;
-    }
-    #cred-scroll {
-        height: 1fr;
-    }
-    .cred-entry {
-        margin-bottom: 1;
-        padding: 1;
-        background: $panel;
-        height: auto;
-    }
-    .cred-entry Input {
-        margin-top: 1;
-    }
-    .cred-buttons {
-        height: auto;
-        margin-top: 1;
-        align: center middle;
-    }
-    .cred-buttons Button {
-        margin: 0 1;
-    }
-    #cred-footer {
-        text-align: center;
-        width: 100%;
-        margin-top: 1;
-    }
-    """
-
-    def __init__(self, session: CredentialSetupSession) -> None:
-        super().__init__()
-        self._session = session
-        self._missing: list[MissingCredential] = session.missing
-        # Track which credentials need Aden sync vs direct API key
-        self._aden_creds: set[int] = set()
-        self._needs_aden_key = False
-        for i, cred in enumerate(self._missing):
-            if cred.aden_supported and not cred.direct_api_key_supported:
-                self._aden_creds.add(i)
-                self._needs_aden_key = True
-
-    def compose(self) -> ComposeResult:
-        n = len(self._missing)
-        with Vertical(id="cred-container"):
-            yield Label("Credential Setup", id="cred-title")
-            yield Label(
-                f"[dim]{n} credential{'s' if n != 1 else ''} needed to run this agent[/dim]",
-                id="cred-subtitle",
-            )
-            with VerticalScroll(id="cred-scroll"):
-                # If any credential needs Aden, show ADEN_API_KEY input first
-                if self._needs_aden_key:
-                    aden_key = os.environ.get("ADEN_API_KEY", "")
-                    with Vertical(classes="cred-entry"):
-                        yield Label("[bold]ADEN_API_KEY[/bold]")
-                        aden_names = [
-                            self._missing[i].credential_name for i in sorted(self._aden_creds)
-                        ]
-                        yield Label(f"[dim]Required for OAuth sync: {', '.join(aden_names)}[/dim]")
-                        yield Label("[cyan]Get key:[/cyan] https://hive.adenhq.com")
-                        yield Input(
-                            placeholder="Paste ADEN_API_KEY..."
-                            if not aden_key
-                            else "Already set (leave blank to keep)",
-                            password=True,
-                            id="key-aden",
-                        )
-
-                # Show direct API key inputs for non-Aden credentials
-                for i, cred in enumerate(self._missing):
-                    if i in self._aden_creds:
-                        continue  # Handled via Aden sync above
-                    with Vertical(classes="cred-entry"):
-                        yield Label(f"[bold]{cred.env_var}[/bold]")
-                        affected = cred.tools or cred.node_types
-                        if affected:
-                            yield Label(f"[dim]Required by: {', '.join(affected)}[/dim]")
-                        if cred.description:
-                            yield Label(f"[dim]{cred.description}[/dim]")
-                        if cred.help_url:
-                            yield Label(f"[cyan]Get key:[/cyan] {cred.help_url}")
-                        yield Input(
-                            placeholder="Paste API key...",
-                            password=True,
-                            id=f"key-{i}",
-                        )
-            with Vertical(classes="cred-buttons"):
-                yield Button("Save & Continue", variant="primary", id="btn-save")
-                yield Button("Skip", variant="default", id="btn-skip")
-            yield Label(
-                "[dim]Enter[/dim] Submit  [dim]Esc[/dim] Cancel",
-                id="cred-footer",
-            )
-
-    def on_button_pressed(self, event: Button.Pressed) -> None:
-        if event.button.id == "btn-save":
-            self._save_credentials()
-        elif event.button.id == "btn-skip":
-            self.dismiss(None)
-
-    def _save_credentials(self) -> None:
-        """Collect inputs, store credentials, and dismiss."""
-        self._session._ensure_credential_key()
-
-        configured = 0
-
-        # Handle Aden-backed credentials
-        if self._needs_aden_key:
-            aden_input = self.query_one("#key-aden", Input)
-            aden_key = aden_input.value.strip()
-            if aden_key:
-                from framework.credentials.key_storage import save_aden_api_key
-
-                save_aden_api_key(aden_key)
-                configured += 1  # ADEN_API_KEY itself counts as configured
-
-            # Run Aden sync for all Aden-backed creds (best-effort)
-            if aden_key or os.environ.get("ADEN_API_KEY"):
-                self._sync_aden_credentials()
-
-        # Handle direct API key credentials
-        for i, cred in enumerate(self._missing):
-            if i in self._aden_creds:
-                continue
-            input_widget = self.query_one(f"#key-{i}", Input)
-            value = input_widget.value.strip()
-            if not value:
-                continue
-            try:
-                self._session._store_credential(cred, value)
-                configured += 1
-            except Exception as e:
-                self.notify(f"Error storing {cred.env_var}: {e}", severity="error")
-
-        if configured > 0:
-            self.dismiss(True)
-        else:
-            self.notify("No credentials configured", severity="warning", timeout=3)
-
-    def _sync_aden_credentials(self) -> int:
-        """Sync Aden-backed credentials and return count of successfully synced."""
-        # Build the Aden sync components directly so we get real errors
-        # instead of CredentialStore.with_aden_sync() silently falling back.
-        try:
-            from framework.credentials.aden import (
-                AdenCachedStorage,
-                AdenClientConfig,
-                AdenCredentialClient,
-                AdenSyncProvider,
-            )
-            from framework.credentials.storage import EncryptedFileStorage
-
-            client = AdenCredentialClient(AdenClientConfig(base_url="https://api.adenhq.com"))
-            provider = AdenSyncProvider(client=client)
-            local_storage = EncryptedFileStorage()
-            cached_storage = AdenCachedStorage(
-                local_storage=local_storage,
-                aden_provider=provider,
-            )
-        except Exception as e:
-            self.notify(
-                f"Aden setup error: {e}",
-                severity="error",
-                timeout=8,
-            )
-            return 0
-
-        # Sync all integrations from Aden to get the provider index populated
-        try:
-            from framework.credentials import CredentialStore
-
-            store = CredentialStore(
-                storage=cached_storage,
-                providers=[provider],
-                auto_refresh=True,
-            )
-            num_synced = provider.sync_all(store)
-            if num_synced == 0:
-                self.notify(
-                    "No active integrations found in Aden. "
-                    "Connect integrations at hive.adenhq.com.",
-                    severity="warning",
-                    timeout=8,
-                )
-        except Exception as e:
-            self.notify(
-                f"Aden sync error: {e}",
-                severity="error",
-                timeout=8,
-            )
-            return 0
-
-        synced = 0
-        for i in sorted(self._aden_creds):
-            cred = self._missing[i]
-            cred_id = cred.credential_id or cred.credential_name
-            if store.is_available(cred_id):
-                try:
-                    value = store.get_key(cred_id, cred.credential_key)
-                    if value:
-                        os.environ[cred.env_var] = value
-                        self._persist_to_local_store(cred_id, cred.credential_key, value)
-                        synced += 1
-                    else:
-                        self.notify(
-                            f"{cred.credential_name}: key "
-                            f"'{cred.credential_key}' not found "
-                            f"in credential '{cred_id}'",
-                            severity="warning",
-                            timeout=8,
-                        )
-                except Exception as e:
-                    self.notify(
-                        f"{cred.credential_name} extraction failed: {e}",
-                        severity="error",
-                        timeout=8,
-                    )
-            else:
-                self.notify(
-                    f"{cred.credential_name} (id='{cred_id}') "
-                    f"not found in Aden. Connect this "
-                    f"integration at hive.adenhq.com first.",
-                    severity="warning",
-                    timeout=8,
-                )
-        return synced
-
-    @staticmethod
-    def _persist_to_local_store(cred_id: str, key_name: str, value: str) -> None:
-        """Save a synced token to the local encrypted store under the canonical ID."""
-        try:
-            from pydantic import SecretStr
-
-            from framework.credentials.models import CredentialKey, CredentialObject, CredentialType
-            from framework.credentials.storage import EncryptedFileStorage
-
-            cred_obj = CredentialObject(
-                id=cred_id,
-                credential_type=CredentialType.OAUTH2,
-                keys={
-                    key_name: CredentialKey(
-                        name=key_name,
-                        value=SecretStr(value),
-                    ),
-                },
-                auto_refresh=True,
-            )
-            EncryptedFileStorage().save(cred_obj)
-        except Exception:
-            pass  # Best-effort; env var is the primary delivery mechanism
-
-    def action_dismiss_setup(self) -> None:
-        self.dismiss(None)

core/framework/tui/widgets/file_browser.py

@@ -1,139 +0,0 @@
-"""
-Native OS file dialog for PDF selection.
-
-Launches the platform's native file picker (macOS: NSOpenPanel via osascript,
-Linux: zenity/kdialog, Windows: PowerShell OpenFileDialog) in a background
-thread so Textual's event loop stays responsive.
-
-Falls back to None when no GUI is available (SSH, headless).
-"""
-
-import asyncio
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-
-def _has_gui() -> bool:
-    """Detect whether a GUI display is available."""
-    if sys.platform == "darwin":
-        # macOS: GUI is available unless running over SSH without display forwarding.
-        return "SSH_CONNECTION" not in os.environ or "DISPLAY" in os.environ
-    elif sys.platform == "win32":
-        return True
-    else:
-        # Linux/BSD: Need X11 or Wayland.
-        return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
-
-
-def _linux_file_dialog() -> subprocess.CompletedProcess | None:
-    """Try zenity, then kdialog, on Linux. Returns CompletedProcess or None."""
-    # Try zenity (GTK)
-    try:
-        return subprocess.run(
-            [
-                "zenity",
-                "--file-selection",
-                "--title=Select a PDF file",
-                "--file-filter=PDF files (*.pdf)|*.pdf",
-            ],
-            encoding="utf-8",
-            capture_output=True,
-            text=True,
-            timeout=300,
-        )
-    except FileNotFoundError:
-        pass
-
-    # Try kdialog (KDE)
-    try:
-        return subprocess.run(
-            [
-                "kdialog",
-                "--getopenfilename",
-                ".",
-                "PDF files (*.pdf)",
-            ],
-            encoding="utf-8",
-            capture_output=True,
-            text=True,
-            timeout=300,
-        )
-    except FileNotFoundError:
-        pass
-
-    return None
-
-
-def _pick_pdf_subprocess() -> Path | None:
-    """Run the native file dialog. BLOCKS until user picks or cancels.
-
-    Returns a Path on success, None on cancel or error.
-    Must be called from a non-main thread (via asyncio.to_thread).
-    """
-    try:
-        if sys.platform == "darwin":
-            result = subprocess.run(
-                [
-                    "osascript",
-                    "-e",
-                    'POSIX path of (choose file of type {"com.adobe.pdf"} '
-                    'with prompt "Select a PDF file")',
-                ],
-                encoding="utf-8",
-                capture_output=True,
-                text=True,
-                timeout=300,
-            )
-        elif sys.platform == "win32":
-            ps_script = (
-                "Add-Type -AssemblyName System.Windows.Forms; "
-                "$f = New-Object System.Windows.Forms.OpenFileDialog; "
-                "$f.Filter = 'PDF files (*.pdf)|*.pdf'; "
-                "$f.Title = 'Select a PDF file'; "
-                "if ($f.ShowDialog() -eq 'OK') { $f.FileName }"
-            )
-            result = subprocess.run(
-                ["powershell", "-NoProfile", "-Command", ps_script],
-                encoding="utf-8",
-                capture_output=True,
-                text=True,
-                timeout=300,
-            )
-        else:
-            result = _linux_file_dialog()
-            if result is None:
-                return None
-
-        if result.returncode != 0:
-            return None
-
-        path_str = result.stdout.strip()
-        if not path_str:
-            return None
-
-        path = Path(path_str)
-        if path.is_file() and path.suffix.lower() == ".pdf":
-            return path
-
-        return None
-
-    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
-        return None
-
-
-async def pick_pdf_file() -> Path | None:
-    """Open a native OS file dialog to pick a PDF file.
-
-    Non-blocking: runs the dialog subprocess in a background thread via
-    asyncio.to_thread(), so the calling event loop stays responsive.
-
-    Returns:
-        Path to the selected PDF, or None if the user cancelled,
-        no GUI is available, or the dialog command was not found.
-    """
-    if not _has_gui():
-        return None
-
-    return await asyncio.to_thread(_pick_pdf_subprocess)

core/framework/tui/widgets/graph_view.py

@@ -1,585 +0,0 @@
-"""
-Graph/Tree Overview Widget - Displays real agent graph structure.
-
-Supports rendering loops (back-edges) via right-side return channels:
-arrows drawn on the right margin that visually point back up to earlier nodes.
-"""
-
-from __future__ import annotations
-
-import re
-import time
-
-from textual.app import ComposeResult
-from textual.containers import Vertical
-
-from framework.runtime.agent_runtime import AgentRuntime
-from framework.runtime.event_bus import EventType
-from framework.tui.widgets.selectable_rich_log import SelectableRichLog as RichLog
-
-# Width of each return-channel column (padding + │ + gap)
-_CHANNEL_WIDTH = 5
-
-# Regex to strip Rich markup tags for measuring visible width
-_MARKUP_RE = re.compile(r"\[/?[^\]]*\]")
-
-
-def _plain_len(s: str) -> int:
-    """Return the visible character length of a Rich-markup string."""
-    return len(_MARKUP_RE.sub("", s))
-
-
-class GraphOverview(Vertical):
-    """Widget to display Agent execution graph/tree with real data."""
-
-    DEFAULT_CSS = """
-    GraphOverview {
-        width: 100%;
-        height: 100%;
-        background: $panel;
-    }
-
-    GraphOverview > RichLog {
-        width: 100%;
-        height: 100%;
-        background: $panel;
-        border: none;
-        scrollbar-background: $surface;
-        scrollbar-color: $primary;
-    }
-    """
-
-    def __init__(self, runtime: AgentRuntime):
-        super().__init__()
-        self.runtime = runtime
-        self._override_graph = None  # Set by switch_graph() for secondary graphs
-        self.active_node: str | None = None
-        self.execution_path: list[str] = []
-        # Per-node status strings shown next to the node in the graph display.
-        # e.g. {"planner": "thinking...", "searcher": "web_search..."}
-        self._node_status: dict[str, str] = {}
-
-    @property
-    def _graph(self):
-        """The graph currently being displayed (may be a secondary graph)."""
-        return self._override_graph or self.runtime.graph
-
-    def switch_graph(self, graph) -> None:
-        """Switch to displaying a different graph and refresh."""
-        self._override_graph = graph
-        self.active_node = None
-        self.execution_path = []
-        self._node_status = {}
-        self._display_graph()
-
-    def compose(self) -> ComposeResult:
-        # Use RichLog for formatted output
-        yield RichLog(id="graph-display", highlight=True, markup=True)
-
-    def on_mount(self) -> None:
-        """Display initial graph structure."""
-        self._display_graph()
-        # Refresh every 1s so timer countdowns stay current
-        if self.runtime._timer_next_fire is not None:
-            self.set_interval(1.0, self._display_graph)
-
-    # ------------------------------------------------------------------
-    # Graph analysis helpers
-    # ------------------------------------------------------------------
-
-    def _topo_order(self) -> list[str]:
-        """BFS from entry_node following edges."""
-        graph = self._graph
-        visited: list[str] = []
-        seen: set[str] = set()
-        queue = [graph.entry_node]
-        while queue:
-            nid = queue.pop(0)
-            if nid in seen:
-                continue
-            seen.add(nid)
-            visited.append(nid)
-            for edge in graph.get_outgoing_edges(nid):
-                if edge.target not in seen:
-                    queue.append(edge.target)
-        # Append orphan nodes not reachable from entry
-        for node in graph.nodes:
-            if node.id not in seen:
-                visited.append(node.id)
-        return visited
-
-    def _detect_back_edges(self, ordered: list[str]) -> list[dict]:
-        """Find edges where target appears before (or equal to) source in topo order.
-
-        Returns a list of dicts with keys: edge, source, target, source_idx, target_idx.
-        """
-        order_idx = {nid: i for i, nid in enumerate(ordered)}
-        back_edges: list[dict] = []
-        for node_id in ordered:
-            for edge in self._graph.get_outgoing_edges(node_id):
-                target_idx = order_idx.get(edge.target, -1)
-                source_idx = order_idx.get(node_id, -1)
-                if target_idx != -1 and target_idx <= source_idx:
-                    back_edges.append(
-                        {
-                            "edge": edge,
-                            "source": node_id,
-                            "target": edge.target,
-                            "source_idx": source_idx,
-                            "target_idx": target_idx,
-                        }
-                    )
-        return back_edges
-
-    def _is_back_edge(self, source: str, target: str, order_idx: dict[str, int]) -> bool:
-        """Check whether an edge from *source* to *target* is a back-edge."""
-        si = order_idx.get(source, -1)
-        ti = order_idx.get(target, -1)
-        return ti != -1 and ti <= si
-
-    # ------------------------------------------------------------------
-    # Line rendering (Pass 1)
-    # ------------------------------------------------------------------
-
-    def _render_node_line(self, node_id: str) -> str:
-        """Render a single node with status symbol and optional status text."""
-        graph = self._graph
-        is_terminal = node_id in (graph.terminal_nodes or [])
-        is_active = node_id == self.active_node
-        is_done = node_id in self.execution_path and not is_active
-        status = self._node_status.get(node_id, "")
-
-        if is_active:
-            sym = "[bold green]●[/bold green]"
-        elif is_done:
-            sym = "[dim]✓[/dim]"
-        elif is_terminal:
-            sym = "[yellow]■[/yellow]"
-        else:
-            sym = "○"
-
-        if is_active:
-            name = f"[bold green]{node_id}[/bold green]"
-        elif is_done:
-            name = f"[dim]{node_id}[/dim]"
-        else:
-            name = node_id
-
-        suffix = f"  [italic]{status}[/italic]" if status else ""
-        return f"  {sym} {name}{suffix}"
-
-    def _render_edges(self, node_id: str, order_idx: dict[str, int]) -> list[str]:
-        """Render forward-edge connectors from *node_id*.
-
-        Back-edges are excluded here — they are drawn by the return-channel
-        overlay in Pass 2.
-        """
-        all_edges = self._graph.get_outgoing_edges(node_id)
-        if not all_edges:
-            return []
-
-        # Split into forward and back
-        forward = [e for e in all_edges if not self._is_back_edge(node_id, e.target, order_idx)]
-
-        if not forward:
-            # All edges are back-edges — nothing to render here
-            return []
-
-        if len(forward) == 1:
-            return ["  │", "  ▼"]
-
-        # Fan-out: show branches
-        lines: list[str] = []
-        for i, edge in enumerate(forward):
-            connector = "└" if i == len(forward) - 1 else "├"
-            cond = ""
-            if edge.condition.value not in ("always", "on_success"):
-                cond = f" [dim]({edge.condition.value})[/dim]"
-            lines.append(f"  {connector}──▶ {edge.target}{cond}")
-        return lines
-
-    # ------------------------------------------------------------------
-    # Return-channel overlay (Pass 2)
-    # ------------------------------------------------------------------
-
-    def _overlay_return_channels(
-        self,
-        lines: list[str],
-        node_line_map: dict[str, int],
-        back_edges: list[dict],
-        available_width: int,
-    ) -> list[str]:
-        """Overlay right-side return channels onto the line buffer.
-
-        Each back-edge gets a vertical channel on the right margin.  Channels
-        are allocated left-to-right by increasing span length so that shorter
-        (inner) loops are closer to the graph body and longer (outer) loops are
-        further right.
-
-        If the terminal is too narrow to fit even one channel, we fall back to
-        simple inline ``↺`` annotations instead.
-        """
-        if not back_edges:
-            return lines
-
-        num_channels = len(back_edges)
-
-        # Sort by span length ascending → inner loops get nearest channel
-        sorted_be = sorted(back_edges, key=lambda b: b["source_idx"] - b["target_idx"])
-
-        # --- Insert dedicated connector lines for back-edge sources ---
-        # Each back-edge source gets a blank line inserted after its node
-        # section (after any forward-edge lines).  We process insertions in
-        # reverse order so that earlier indices remain valid.
-        all_node_lines_set = set(node_line_map.values())
-
-        insertions: list[tuple[int, int]] = []  # (insert_after_line, be_index)
-        for be_idx, be in enumerate(sorted_be):
-            source_node_line = node_line_map.get(be["source"])
-            if source_node_line is None:
-                continue
-            # Walk forward to find the last line in this node's section
-            last_section_line = source_node_line
-            for li in range(source_node_line + 1, len(lines)):
-                if li in all_node_lines_set:
-                    break
-                last_section_line = li
-            insertions.append((last_section_line, be_idx))
-
-        source_line_for_be: dict[int, int] = {}
-        for insert_after, be_idx in sorted(insertions, reverse=True):
-            insert_at = insert_after + 1
-            lines.insert(insert_at, "")  # placeholder for connector
-            source_line_for_be[be_idx] = insert_at
-            # Shift node_line_map entries that come after the insertion point
-            for nid in node_line_map:
-                if node_line_map[nid] > insert_after:
-                    node_line_map[nid] += 1
-            # Also shift already-assigned source lines
-            for prev_idx in source_line_for_be:
-                if prev_idx != be_idx and source_line_for_be[prev_idx] > insert_after:
-                    source_line_for_be[prev_idx] += 1
-
-        # Recompute max content width after insertions
-        max_content_w = max(_plain_len(ln) for ln in lines) if lines else 0
-
-        # Check if we have room for channels
-        channels_total_w = num_channels * _CHANNEL_WIDTH
-        if max_content_w + channels_total_w + 2 > available_width:
-            return self._inline_back_edge_fallback(lines, node_line_map, back_edges)
-
-        content_pad = max_content_w + 3  # gap between content and first channel
-
-        # Build channel info with final line positions
-        channel_info: list[dict] = []
-        for ch_idx, be in enumerate(sorted_be):
-            target_line = node_line_map.get(be["target"])
-            source_line = source_line_for_be.get(ch_idx)
-            if target_line is None or source_line is None:
-                continue
-            col = content_pad + ch_idx * _CHANNEL_WIDTH
-            channel_info.append(
-                {
-                    "target_line": target_line,
-                    "source_line": source_line,
-                    "col": col,
-                }
-            )
-
-        if not channel_info:
-            return lines
-
-        # Build overlay grid — one row per line, columns for channel area
-        total_width = content_pad + num_channels * _CHANNEL_WIDTH + 1
-        overlay_width = total_width - max_content_w
-        overlays: list[list[str]] = [[" "] * overlay_width for _ in range(len(lines))]
-
-        for ci in channel_info:
-            tl = ci["target_line"]
-            sl = ci["source_line"]
-            col_offset = ci["col"] - max_content_w
-
-            if col_offset < 0 or col_offset >= overlay_width:
-                continue
-
-            # Target line: ◄──...──┐
-            if 0 <= tl < len(overlays):
-                for c in range(col_offset):
-                    if overlays[tl][c] == " ":
-                        overlays[tl][c] = "─"
-                overlays[tl][col_offset] = "┐"
-
-            # Source line: ──...──┘
-            if 0 <= sl < len(overlays):
-                for c in range(col_offset):
-                    if overlays[sl][c] == " ":
-                        overlays[sl][c] = "─"
-                overlays[sl][col_offset] = "┘"
-
-            # Vertical lines between target+1 and source-1
-            for li in range(tl + 1, sl):
-                if 0 <= li < len(overlays) and overlays[li][col_offset] == " ":
-                    overlays[li][col_offset] = "│"
-
-        # Merge overlays into the line strings
-        result: list[str] = []
-        for i, line in enumerate(lines):
-            pw = _plain_len(line)
-            pad = max_content_w - pw
-            overlay_chars = overlays[i] if i < len(overlays) else []
-            overlay_str = "".join(overlay_chars)
-            overlay_trimmed = overlay_str.rstrip()
-            if overlay_trimmed:
-                is_target_line = any(ci["target_line"] == i for ci in channel_info)
-                if is_target_line:
-                    overlay_trimmed = "◄" + overlay_trimmed[1:]
-
-                is_source_line = any(ci["source_line"] == i for ci in channel_info)
-                if is_source_line and not line.strip():
-                    # Inserted blank line → build └───┘ connector.
-                    # "  └" = 3 chars of content prefix, so remaining pad = max_content_w - 3
-                    remaining_pad = max_content_w - 3
-                    full = list(" " * remaining_pad + overlay_trimmed)
-                    # Find the ┘ corner for this source connector
-                    corner_pos = -1
-                    for ci_s in channel_info:
-                        if ci_s["source_line"] == i:
-                            corner_pos = remaining_pad + (ci_s["col"] - max_content_w)
-                            break
-                    # Fill everything up to the corner with ─
-                    if corner_pos >= 0:
-                        for c in range(corner_pos):
-                            if full[c] not in ("│", "┘", "┐"):
-                                full[c] = "─"
-                    connector = "  └" + "".join(full).rstrip()
-                    result.append(f"[dim]{connector}[/dim]")
-                    continue
-
-                colored_overlay = f"[dim]{' ' * pad}{overlay_trimmed}[/dim]"
-                result.append(f"{line}{colored_overlay}")
-            else:
-                result.append(line)
-
-        return result
-
-    def _inline_back_edge_fallback(
-        self,
-        lines: list[str],
-        node_line_map: dict[str, int],
-        back_edges: list[dict],
-    ) -> list[str]:
-        """Fallback: add inline ↺ annotations when terminal is too narrow for channels."""
-        # Group back-edges by source node
-        source_to_be: dict[str, list[dict]] = {}
-        for be in back_edges:
-            source_to_be.setdefault(be["source"], []).append(be)
-
-        result = list(lines)
-        # Insert annotation lines after each source node's section
-        offset = 0
-        all_node_lines = sorted(node_line_map.values())
-        for source, bes in source_to_be.items():
-            source_line = node_line_map.get(source)
-            if source_line is None:
-                continue
-            # Find end of source node section
-            end_line = source_line
-            for nl in all_node_lines:
-                if nl > source_line:
-                    end_line = nl - 1
-                    break
-            else:
-                end_line = len(lines) - 1
-            # Insert after last content line of this node's section
-            insert_at = end_line + offset + 1
-            for be in bes:
-                cond = ""
-                edge = be["edge"]
-                if edge.condition.value not in ("always", "on_success"):
-                    cond = f" [dim]({edge.condition.value})[/dim]"
-                annotation = f"  [yellow]↺[/yellow] {be['target']}{cond}"
-                result.insert(insert_at, annotation)
-                insert_at += 1
-                offset += 1
-
-        return result
-
-    # ------------------------------------------------------------------
-    # Main display
-    # ------------------------------------------------------------------
-
-    def _display_graph(self) -> None:
-        """Display the graph as an ASCII DAG with edge connectors and loop channels."""
-        display = self.query_one("#graph-display", RichLog)
-        display.clear()
-
-        graph = self._graph
-        display.write(f"[bold cyan]Agent Graph:[/bold cyan] {graph.id}\n")
-
-        ordered = self._topo_order()
-        order_idx = {nid: i for i, nid in enumerate(ordered)}
-
-        # --- Pass 1: Build line buffer ---
-        lines: list[str] = []
-        node_line_map: dict[str, int] = {}
-
-        for node_id in ordered:
-            node_line_map[node_id] = len(lines)
-            lines.append(self._render_node_line(node_id))
-            for edge_line in self._render_edges(node_id, order_idx):
-                lines.append(edge_line)
-
-        # --- Pass 2: Overlay return channels for back-edges ---
-        back_edges = self._detect_back_edges(ordered)
-        if back_edges:
-            # Try to get actual widget width; default to a reasonable value
-            try:
-                available_width = self.size.width or 60
-            except Exception:
-                available_width = 60
-            lines = self._overlay_return_channels(lines, node_line_map, back_edges, available_width)
-
-        # Write all lines
-        for line in lines:
-            display.write(line)
-
-        # Execution path footer
-        if self.execution_path:
-            display.write("")
-            display.write(f"[dim]Path:[/dim] {' → '.join(self.execution_path[-5:])}")
-
-        # Event sources section
-        self._render_event_sources(display)
-
-    # ------------------------------------------------------------------
-    # Event sources display
-    # ------------------------------------------------------------------
-
-    def _render_event_sources(self, display: RichLog) -> None:
-        """Render event source info (webhooks, timers) below the graph."""
-        entry_points = self.runtime.get_entry_points()
-
-        # Filter to non-manual entry points (webhooks, timers, events)
-        event_sources = [ep for ep in entry_points if ep.trigger_type not in ("manual",)]
-        if not event_sources:
-            return
-
-        display.write("")
-        display.write("[bold cyan]Event Sources[/bold cyan]")
-
-        config = self.runtime._config
-
-        for ep in event_sources:
-            if ep.trigger_type == "timer":
-                cron_expr = ep.trigger_config.get("cron")
-                interval = ep.trigger_config.get("interval_minutes", "?")
-                schedule_label = f"cron: {cron_expr}" if cron_expr else f"every {interval} min"
-                display.write(f"  [green]⏱[/green]  {ep.name} [dim]→ {ep.entry_node}[/dim]")
-                # Show schedule + next fire countdown
-                next_fire = self.runtime._timer_next_fire.get(ep.id)
-                if next_fire is not None:
-                    remaining = max(0, next_fire - time.monotonic())
-                    hours, rem = divmod(int(remaining), 3600)
-                    mins, secs = divmod(rem, 60)
-                    if hours > 0:
-                        countdown = f"{hours}h {mins:02d}m {secs:02d}s"
-                    else:
-                        countdown = f"{mins}m {secs:02d}s"
-                    display.write(f"     [dim]{schedule_label} — next in {countdown}[/dim]")
-                else:
-                    display.write(f"     [dim]{schedule_label}[/dim]")
-
-            elif ep.trigger_type in ("event", "webhook"):
-                display.write(f"  [yellow]⚡[/yellow] {ep.name} [dim]→ {ep.entry_node}[/dim]")
-                # Show webhook endpoint if configured
-                route = None
-                for r in config.webhook_routes:
-                    src = r.get("source_id", "")
-                    if src and src in ep.id:
-                        route = r
-                        break
-                if not route and config.webhook_routes:
-                    # Fall back to first route
-                    route = config.webhook_routes[0]
-
-                if route:
-                    host = config.webhook_host
-                    port = config.webhook_port
-                    path = route.get("path", "/webhook")
-                    display.write(f"     [dim]{host}:{port}{path}[/dim]")
-                else:
-                    event_types = ep.trigger_config.get("event_types", [])
-                    if event_types:
-                        display.write(f"     [dim]events: {', '.join(event_types)}[/dim]")
-
-    # ------------------------------------------------------------------
-    # Public API (called by app.py)
-    # ------------------------------------------------------------------
-
-    def update_active_node(self, node_id: str) -> None:
-        """Update the currently active node."""
-        self.active_node = node_id
-        if node_id not in self.execution_path:
-            self.execution_path.append(node_id)
-        self._display_graph()
-
-    def update_execution(self, event) -> None:
-        """Update the displayed node status based on execution lifecycle events."""
-        if event.type == EventType.EXECUTION_STARTED:
-            self._node_status.clear()
-            self.execution_path.clear()
-            entry_node = event.data.get("entry_node") or (
-                self._graph.entry_node if self.runtime else None
-            )
-            if entry_node:
-                self.update_active_node(entry_node)
-
-        elif event.type == EventType.EXECUTION_COMPLETED:
-            self.active_node = None
-            self._node_status.clear()
-            self._display_graph()
-
-        elif event.type == EventType.EXECUTION_FAILED:
-            error = event.data.get("error", "Unknown error")
-            if self.active_node:
-                self._node_status[self.active_node] = f"[red]FAILED: {error}[/red]"
-            self.active_node = None
-            self._display_graph()
-
-    # -- Event handlers called by app.py _handle_event --
-
-    def handle_node_loop_started(self, node_id: str) -> None:
-        """A node's event loop has started."""
-        self._node_status[node_id] = "thinking..."
-        self.update_active_node(node_id)
-
-    def handle_node_loop_iteration(self, node_id: str, iteration: int) -> None:
-        """A node advanced to a new loop iteration."""
-        self._node_status[node_id] = f"step {iteration}"
-        self._display_graph()
-
-    def handle_node_loop_completed(self, node_id: str) -> None:
-        """A node's event loop completed."""
-        self._node_status.pop(node_id, None)
-        if self.active_node == node_id:
-            self.active_node = None
-        self._display_graph()
-
-    def handle_tool_call(self, node_id: str, tool_name: str, *, started: bool) -> None:
-        """Show tool activity next to the active node."""
-        if started:
-            self._node_status[node_id] = f"{tool_name}..."
-        else:
-            # Restore to generic thinking status after tool completes
-            self._node_status[node_id] = "thinking..."
-        self._display_graph()
-
-    def handle_stalled(self, node_id: str, reason: str) -> None:
-        """Highlight a stalled node."""
-        self._node_status[node_id] = f"[red]stalled: {reason}[/red]"
-        self._display_graph()
-
-    def handle_edge_traversed(self, source_node: str, target_node: str) -> None:
-        """Highlight an edge being traversed."""
-        self._node_status[source_node] = f"[dim]→ {target_node}[/dim]"
-        self._display_graph()

core/framework/tui/widgets/log_pane.py

@@ -1,172 +0,0 @@
-"""
-Log formatting utilities and LogPane widget.
-
-The module-level functions (format_event, extract_event_text, format_python_log)
-can be used by any widget that needs to render log lines without instantiating LogPane.
-"""
-
-import logging
-from datetime import datetime
-
-from textual.app import ComposeResult
-from textual.containers import Container
-
-from framework.runtime.event_bus import AgentEvent, EventType
-from framework.tui.widgets.selectable_rich_log import SelectableRichLog as RichLog
-
-# --- Module-level formatting constants ---
-
-EVENT_FORMAT: dict[EventType, tuple[str, str]] = {
-    EventType.EXECUTION_STARTED: (">>", "bold cyan"),
-    EventType.EXECUTION_COMPLETED: ("<<", "bold green"),
-    EventType.EXECUTION_FAILED: ("!!", "bold red"),
-    EventType.TOOL_CALL_STARTED: ("->", "yellow"),
-    EventType.TOOL_CALL_COMPLETED: ("<-", "green"),
-    EventType.NODE_LOOP_STARTED: ("@@", "cyan"),
-    EventType.NODE_LOOP_ITERATION: ("..", "dim"),
-    EventType.NODE_LOOP_COMPLETED: ("@@", "dim"),
-    EventType.LLM_TURN_COMPLETE: ("◆", "green"),
-    EventType.NODE_STALLED: ("!!", "bold yellow"),
-    EventType.NODE_INPUT_BLOCKED: ("!!", "yellow"),
-    EventType.GOAL_PROGRESS: ("%%", "blue"),
-    EventType.GOAL_ACHIEVED: ("**", "bold green"),
-    EventType.CONSTRAINT_VIOLATION: ("!!", "bold red"),
-    EventType.STATE_CHANGED: ("~~", "dim"),
-    EventType.CLIENT_INPUT_REQUESTED: ("??", "magenta"),
-}
-
-LOG_LEVEL_COLORS: dict[int, str] = {
-    logging.DEBUG: "dim",
-    logging.INFO: "",
-    logging.WARNING: "yellow",
-    logging.ERROR: "red",
-    logging.CRITICAL: "bold red",
-}
-
-
-# --- Module-level formatting functions ---
-
-
-def extract_event_text(event: AgentEvent) -> str:
-    """Extract human-readable text from an event's data dict."""
-    et = event.type
-    data = event.data
-
-    if et == EventType.EXECUTION_STARTED:
-        return "Execution started"
-    elif et == EventType.EXECUTION_COMPLETED:
-        return "Execution completed"
-    elif et == EventType.EXECUTION_FAILED:
-        return f"Execution FAILED: {data.get('error', 'unknown')}"
-    elif et == EventType.TOOL_CALL_STARTED:
-        return f"Tool call: {data.get('tool_name', 'unknown')}"
-    elif et == EventType.TOOL_CALL_COMPLETED:
-        name = data.get("tool_name", "unknown")
-        if data.get("is_error"):
-            preview = str(data.get("result", ""))[:80]
-            return f"Tool error: {name} - {preview}"
-        return f"Tool done: {name}"
-    elif et == EventType.NODE_LOOP_STARTED:
-        return f"Node started: {event.node_id or 'unknown'}"
-    elif et == EventType.NODE_LOOP_ITERATION:
-        return f"{event.node_id or 'unknown'} iteration {data.get('iteration', '?')}"
-    elif et == EventType.NODE_LOOP_COMPLETED:
-        return f"Node done: {event.node_id or 'unknown'}"
-    elif et == EventType.NODE_STALLED:
-        reason = data.get("reason", "")
-        node = event.node_id or "unknown"
-        return f"Node stalled: {node} - {reason}" if reason else f"Node stalled: {node}"
-    elif et == EventType.NODE_INPUT_BLOCKED:
-        return f"Node input blocked: {event.node_id or 'unknown'}"
-    elif et == EventType.GOAL_PROGRESS:
-        return f"Goal progress: {data.get('progress', '?')}"
-    elif et == EventType.GOAL_ACHIEVED:
-        return "Goal achieved"
-    elif et == EventType.CONSTRAINT_VIOLATION:
-        return f"Constraint violated: {data.get('description', 'unknown')}"
-    elif et == EventType.STATE_CHANGED:
-        return f"State changed: {data.get('key', 'unknown')}"
-    elif et == EventType.CLIENT_INPUT_REQUESTED:
-        return "Waiting for user input"
-    elif et == EventType.LLM_TURN_COMPLETE:
-        stop = data.get("stop_reason", "?")
-        model = data.get("model", "?")
-        inp = data.get("input_tokens", 0)
-        out = data.get("output_tokens", 0)
-        return f"{model} → {stop} ({inp}+{out} tokens)"
-    else:
-        return f"{et.value}: {data}"
-
-
-def format_event(event: AgentEvent) -> str:
-    """Format an AgentEvent as a Rich markup string with timestamp + symbol."""
-    ts = event.timestamp.strftime("%H:%M:%S")
-    symbol, color = EVENT_FORMAT.get(event.type, ("--", "dim"))
-    text = extract_event_text(event)
-    return f"[dim]{ts}[/dim] [{color}]{symbol} {text}[/{color}]"
-
-
-def format_python_log(record: logging.LogRecord) -> str:
-    """Format a Python log record as a Rich markup string with timestamp and severity color."""
-    ts = datetime.fromtimestamp(record.created).strftime("%H:%M:%S")
-    color = LOG_LEVEL_COLORS.get(record.levelno, "")
-    msg = record.getMessage()
-    if color:
-        return f"[dim]{ts}[/dim] [{color}]{record.levelname}[/{color}] {msg}"
-    else:
-        return f"[dim]{ts}[/dim] {record.levelname} {msg}"
-
-
-# --- LogPane widget (kept for backward compatibility) ---
-
-
-class LogPane(Container):
-    """Widget to display logs with reliable rendering."""
-
-    DEFAULT_CSS = """
-    LogPane {
-        width: 100%;
-        height: 100%;
-    }
-
-    LogPane > RichLog {
-        width: 100%;
-        height: 100%;
-        background: $surface;
-        border: none;
-        scrollbar-background: $panel;
-        scrollbar-color: $primary;
-    }
-    """
-
-    def compose(self) -> ComposeResult:
-        yield RichLog(id="main-log", highlight=True, markup=True, auto_scroll=False)
-
-    def write_event(self, event: AgentEvent) -> None:
-        """Format an AgentEvent with timestamp + symbol and write to the log."""
-        self.write_log(format_event(event))
-
-    def write_python_log(self, record: logging.LogRecord) -> None:
-        """Format a Python log record with timestamp and severity color."""
-        self.write_log(format_python_log(record))
-
-    def write_log(self, message: str) -> None:
-        """Write a log message to the log pane."""
-        try:
-            if not self.is_mounted:
-                return
-
-            log = self.query_one("#main-log", RichLog)
-
-            if not log.is_mounted:
-                return
-
-            was_at_bottom = log.is_vertical_scroll_end
-
-            log.write(message)
-
-            if was_at_bottom:
-                log.scroll_end(animate=False)
-
-        except Exception:
-            pass

core/framework/tui/widgets/selectable_rich_log.py

@@ -1,229 +0,0 @@
-"""
-SelectableRichLog - RichLog with mouse-driven text selection and clipboard copy.
-
-Drop-in replacement for RichLog. Click-and-drag to select text, which is
-visually highlighted. Press Ctrl+C to copy selection to clipboard (handled
-by app.py). Press Escape or single-click to clear selection.
-"""
-
-from __future__ import annotations
-
-import subprocess
-import sys
-
-from rich.segment import Segment as RichSegment
-from rich.style import Style
-from textual.geometry import Offset
-from textual.selection import Selection
-from textual.strip import Strip
-from textual.widgets import RichLog
-
-# Highlight style for selected text
-_HIGHLIGHT_STYLE = Style(bgcolor="blue", color="white")
-
-
-class SelectableRichLog(RichLog):
-    """RichLog with mouse-driven text selection."""
-
-    DEFAULT_CSS = """
-    SelectableRichLog {
-        pointer: text;
-    }
-    """
-
-    def __init__(self, **kwargs) -> None:
-        super().__init__(**kwargs)
-        self._sel_anchor: Offset | None = None
-        self._sel_end: Offset | None = None
-        self._selecting: bool = False
-
-    # -- Internal helpers --
-
-    def _apply_highlight(self, strip: Strip) -> Strip:
-        """Apply highlight with correct precedence (highlight wins over base style)."""
-        segments = []
-        for text, style, control in strip._segments:
-            if control:
-                segments.append(RichSegment(text, style, control))
-            else:
-                new_style = (style + _HIGHLIGHT_STYLE) if style else _HIGHLIGHT_STYLE
-                segments.append(RichSegment(text, new_style, control))
-        return Strip(segments, strip.cell_length)
-
-    # -- Selection helpers --
-
-    @property
-    def selection(self) -> Selection | None:
-        """Build a Selection from current anchor/end, or None if no selection."""
-        if self._sel_anchor is None or self._sel_end is None:
-            return None
-        if self._sel_anchor == self._sel_end:
-            return None
-        return Selection.from_offsets(self._sel_anchor, self._sel_end)
-
-    def _mouse_to_content(self, event_x: int, event_y: int) -> Offset:
-        """Convert viewport mouse coords to content (line, col) coords."""
-        scroll_x, scroll_y = self.scroll_offset
-        return Offset(scroll_x + event_x, scroll_y + event_y)
-
-    def clear_selection(self) -> None:
-        """Clear any active selection."""
-        had_selection = self._sel_anchor is not None
-        self._sel_anchor = None
-        self._sel_end = None
-        self._selecting = False
-        if had_selection:
-            self.refresh()
-
-    # -- Mouse handlers (left button only) --
-
-    def on_mouse_down(self, event) -> None:
-        """Start selection on left mouse button."""
-        if event.button != 1:
-            return
-        self._sel_anchor = self._mouse_to_content(event.x, event.y)
-        self._sel_end = self._sel_anchor
-        self._selecting = True
-        self.capture_mouse()
-        self.refresh()
-
-    def on_mouse_move(self, event) -> None:
-        """Extend selection while dragging."""
-        if not self._selecting:
-            return
-        self._sel_end = self._mouse_to_content(event.x, event.y)
-        self.refresh()
-
-    def on_mouse_up(self, event) -> None:
-        """End selection on mouse release."""
-        if not self._selecting:
-            return
-        self._selecting = False
-        self.release_mouse()
-
-        # Single-click (no drag) clears selection
-        if self._sel_anchor == self._sel_end:
-            self.clear_selection()
-
-    # -- Keyboard handlers --
-
-    def on_key(self, event) -> None:
-        """Clear selection on Escape."""
-        if event.key == "escape":
-            self.clear_selection()
-
-    # -- Rendering with highlight --
-
-    def render_line(self, y: int) -> Strip:
-        """Override to apply selection highlight on top of the base strip."""
-        strip = super().render_line(y)
-
-        sel = self.selection
-        if sel is None:
-            return strip
-
-        # Determine which content line this viewport row corresponds to
-        _, scroll_y = self.scroll_offset
-        content_y = scroll_y + y
-
-        span = sel.get_span(content_y)
-        if span is None:
-            return strip
-
-        start_x, end_x = span
-        cell_len = strip.cell_length
-        if cell_len == 0:
-            return strip
-
-        scroll_x, _ = self.scroll_offset
-
-        # -1 means "to end of content line" — use viewport end
-        if end_x == -1:
-            end_x = cell_len
-        else:
-            # Convert content-space x to viewport-space x
-            end_x = end_x - scroll_x
-
-        # Convert content-space x to viewport-space x
-        start_x = start_x - scroll_x
-
-        # Clamp to viewport strip bounds
-        start_x = max(0, start_x)
-        end_x = min(end_x, cell_len)
-
-        if start_x >= end_x:
-            return strip
-
-        # Divide strip into [before, selected, after] and highlight the middle
-        parts = strip.divide([start_x, end_x])
-        if len(parts) < 2:
-            return strip
-
-        highlighted_parts: list[Strip] = []
-        for i, part in enumerate(parts):
-            if i == 1:
-                highlighted_parts.append(self._apply_highlight(part))
-            else:
-                highlighted_parts.append(part)
-
-        return Strip.join(highlighted_parts)
-
-    # -- Text extraction & clipboard --
-
-    def get_selected_text(self) -> str | None:
-        """Extract the plain text of the current selection, or None."""
-        sel = self.selection
-        if sel is None:
-            return None
-
-        # Build full text from all lines
-        all_text = "\n".join(strip.text for strip in self.lines)
-        try:
-            extracted = sel.extract(all_text)
-        except (IndexError, ValueError):
-            # Selection coordinates can exceed line count when the virtual
-            # canvas is larger than the actual content (e.g. after scroll).
-            return None
-        return extracted if extracted else None
-
-    def copy_selection(self) -> str | None:
-        """Copy selected text to system clipboard. Returns text or None."""
-        text = self.get_selected_text()
-        if not text:
-            return None
-        _copy_to_clipboard(text)
-        return text
-
-
-def _copy_to_clipboard(text: str) -> None:
-    """Copy text to system clipboard using platform-native tools."""
-    try:
-        if sys.platform == "darwin":
-            subprocess.run(["pbcopy"], encoding="utf-8", input=text.encode(), check=True, timeout=5)
-        elif sys.platform == "win32":
-            subprocess.run(
-                ["clip.exe"],
-                encoding="utf-8",
-                input=text.encode("utf-16le"),
-                check=True,
-                timeout=5,
-            )
-        elif sys.platform.startswith("linux"):
-            try:
-                subprocess.run(
-                    ["xclip", "-selection", "clipboard"],
-                    encoding="utf-8",
-                    input=text.encode(),
-                    check=True,
-                    timeout=5,
-                )
-            except (subprocess.SubprocessError, FileNotFoundError):
-                subprocess.run(
-                    ["xsel", "--clipboard", "--input"],
-                    encoding="utf-8",
-                    input=text.encode(),
-                    check=True,
-                    timeout=5,
-                )
-    except (subprocess.SubprocessError, FileNotFoundError):
-        pass

core/frontend/src/api/graphs.ts

@@ -1,5 +1,5 @@
 import { api } from "./client";
-import type { GraphTopology, NodeDetail, NodeCriteria, ToolInfo } from "./types";
+import type { GraphTopology, NodeDetail, NodeCriteria, ToolInfo, DraftGraph, FlowchartMap } from "./types";
 
 export const graphsApi = {
   nodes: (sessionId: string, graphId: string, workerSessionId?: string) =>
@@ -26,4 +26,14 @@ export const graphsApi = {
     api.get<{ tools: ToolInfo[] }>(
       `/sessions/${sessionId}/graphs/${graphId}/nodes/${nodeId}/tools`,
     ),
+
+  draftGraph: (sessionId: string) =>
+    api.get<{ draft: DraftGraph | null }>(
+      `/sessions/${sessionId}/draft-graph`,
+    ),
+
+  flowchartMap: (sessionId: string) =>
+    api.get<FlowchartMap>(
+      `/sessions/${sessionId}/flowchart-map`,
+    ),
 };

core/frontend/src/api/types.ts

@@ -191,6 +191,56 @@ export interface GraphTopology {
   entry_points?: EntryPoint[];
 }
 
+// --- Draft graph types (planning phase) ---
+
+export interface DraftNode {
+  id: string;
+  name: string;
+  description: string;
+  node_type: string;
+  tools: string[];
+  input_keys: string[];
+  output_keys: string[];
+  success_criteria: string;
+  sub_agents: string[];
+  /** For decision nodes: the yes/no question evaluated during dissolution. */
+  decision_clause?: string;
+  flowchart_type: string;
+  flowchart_shape: string;
+  flowchart_color: string;
+}
+
+export interface DraftEdge {
+  id: string;
+  source: string;
+  target: string;
+  condition: string;
+  description: string;
+  /** Short label shown on the flowchart edge (e.g. "Yes", "No"). */
+  label?: string;
+}
+
+export interface DraftGraph {
+  agent_name: string;
+  goal: string;
+  description: string;
+  success_criteria: string[];
+  constraints: string[];
+  nodes: DraftNode[];
+  edges: DraftEdge[];
+  entry_node: string;
+  terminal_nodes: string[];
+  flowchart_legend: Record<string, { shape: string; color: string }>;
+}
+
+/** Mapping from runtime graph nodes → original flowchart draft nodes. */
+export interface FlowchartMap {
+  /** runtime_node_id → list of original draft node IDs it absorbed. */
+  map: Record<string, string[]> | null;
+  /** Original draft graph preserved before planning-node dissolution (decision + subagent). */
+  original_draft: DraftGraph | null;
+}
+
 export interface NodeCriteria {
   node_id: string;
   success_criteria: string | null;
@@ -276,7 +326,9 @@ export type EventTypeName =
   | "worker_loaded"
   | "credentials_required"
   | "queen_phase_changed"
-  | "subagent_report";
+  | "subagent_report"
+  | "draft_graph_updated"
+  | "flowchart_map_updated";
 
 export interface AgentEvent {
   type: EventTypeName;

core/frontend/src/components/ChatPanel.tsx

@@ -2,6 +2,7 @@ import { memo, useState, useRef, useEffect } from "react";
 import { Send, Square, Crown, Cpu, Check, Loader2 } from "lucide-react";
 import MarkdownContent from "@/components/MarkdownContent";
 import QuestionWidget from "@/components/QuestionWidget";
+import MultiQuestionWidget from "@/components/MultiQuestionWidget";
 
 export interface ChatMessage {
   id: string;
@@ -34,8 +35,12 @@ interface ChatPanelProps {
   pendingQuestion?: string | null;
   /** Options for the pending question */
   pendingOptions?: string[] | null;
+  /** Multiple questions from ask_user_multiple */
+  pendingQuestions?: { id: string; prompt: string; options?: string[] }[] | null;
   /** Called when user submits an answer to the pending question */
   onQuestionSubmit?: (answer: string, isOther: boolean) => void;
+  /** Called when user submits answers to multiple questions */
+  onMultiQuestionSubmit?: (answers: Record<string, string>) => void;
   /** Called when user dismisses the pending question without answering */
   onQuestionDismiss?: () => void;
   /** Queen operating phase — shown as a tag on queen messages */
@@ -222,7 +227,7 @@ const MessageBubble = memo(function MessageBubble({ msg, queenPhase }: { msg: Ch
   );
 }, (prev, next) => prev.msg.id === next.msg.id && prev.msg.content === next.msg.content && prev.queenPhase === next.queenPhase);
 
-export default function ChatPanel({ messages, onSend, isWaiting, isWorkerWaiting, isBusy, activeThread, disabled, onCancel, pendingQuestion, pendingOptions, onQuestionSubmit, onQuestionDismiss, queenPhase }: ChatPanelProps) {
+export default function ChatPanel({ messages, onSend, isWaiting, isWorkerWaiting, isBusy, activeThread, disabled, onCancel, pendingQuestion, pendingOptions, pendingQuestions, onQuestionSubmit, onMultiQuestionSubmit, onQuestionDismiss, queenPhase }: ChatPanelProps) {
   const [input, setInput] = useState("");
   const [readMap, setReadMap] = useState<Record<string, number>>({});
   const bottomRef = useRef<HTMLDivElement>(null);
@@ -332,7 +337,13 @@ export default function ChatPanel({ messages, onSend, isWaiting, isWorkerWaiting
       </div>
 
       {/* Input area — question widget replaces textarea when a question is pending */}
-      {pendingQuestion && pendingOptions && onQuestionSubmit ? (
+      {pendingQuestions && pendingQuestions.length >= 2 && onMultiQuestionSubmit ? (
+        <MultiQuestionWidget
+          questions={pendingQuestions}
+          onSubmit={onMultiQuestionSubmit}
+          onDismiss={onQuestionDismiss}
+        />
+      ) : pendingQuestion && pendingOptions && onQuestionSubmit ? (
         <QuestionWidget
           question={pendingQuestion}
           options={pendingOptions}

core/frontend/src/components/DraftGraph.tsx

@@ -0,0 +1,848 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { DraftGraph as DraftGraphData, DraftNode } from "@/api/types";
+import type { GraphNode } from "./AgentGraph";
+
+type DraftNodeStatus = "pending" | "running" | "complete" | "error";
+
+interface DraftGraphProps {
+  draft: DraftGraphData;
+  onNodeClick?: (node: DraftNode) => void;
+  /** Runtime node ID → list of original draft node IDs (post-dissolution mapping). */
+  flowchartMap?: Record<string, string[]>;
+  /** Current runtime graph nodes with live status (for overlay during execution). */
+  runtimeNodes?: GraphNode[];
+  /** Called when a draft node is clicked in overlay mode — receives the runtime node ID. */
+  onRuntimeNodeClick?: (runtimeNodeId: string) => void;
+}
+
+// Layout constants — tuned for a ~500px panel (484px after px-2 padding)
+const NODE_H = 52;
+const GAP_Y = 48;
+const TOP_Y = 28;
+const MARGIN_X = 16;
+const GAP_X = 16;
+
+function truncateLabel(label: string, availablePx: number, fontSize: number): string {
+  const avgCharW = fontSize * 0.58;
+  const maxChars = Math.floor(availablePx / avgCharW);
+  if (label.length <= maxChars) return label;
+  return label.slice(0, Math.max(maxChars - 1, 1)) + "\u2026";
+}
+
+/**
+ * Render an ISO 5807 flowchart shape as an SVG element.
+ */
+function FlowchartShape({
+  shape,
+  x,
+  y,
+  w,
+  h,
+  color,
+  selected,
+}: {
+  shape: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  color: string;
+  selected: boolean;
+}) {
+  const fill = selected ? `${color}28` : `${color}18`;
+  const stroke = selected ? color : `${color}80`;
+  const common = { fill, stroke, strokeWidth: 1.2 };
+
+  switch (shape) {
+    case "stadium":
+      return <rect x={x} y={y} width={w} height={h} rx={h / 2} {...common} />;
+
+    case "rectangle":
+      return <rect x={x} y={y} width={w} height={h} rx={4} {...common} />;
+
+    case "rounded_rect":
+      return <rect x={x} y={y} width={w} height={h} rx={12} {...common} />;
+
+    case "diamond": {
+      const cx = x + w / 2;
+      const cy = y + h / 2;
+      // Keep diamond within bounding box
+      return (
+        <polygon
+          points={`${cx},${y} ${x + w},${cy} ${cx},${y + h} ${x},${cy}`}
+          {...common}
+        />
+      );
+    }
+
+    case "parallelogram": {
+      const skew = 12;
+      return (
+        <polygon
+          points={`${x + skew},${y} ${x + w},${y} ${x + w - skew},${y + h} ${x},${y + h}`}
+          {...common}
+        />
+      );
+    }
+
+    case "document": {
+      const d = `M ${x} ${y + 4} Q ${x} ${y}, ${x + 8} ${y} L ${x + w - 8} ${y} Q ${x + w} ${y}, ${x + w} ${y + 4} L ${x + w} ${y + h - 8} C ${x + w * 0.75} ${y + h + 2}, ${x + w * 0.25} ${y + h - 10}, ${x} ${y + h - 4} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    case "multi_document": {
+      const off = 3;
+      const d = `M ${x} ${y + 4 + off} Q ${x} ${y + off}, ${x + 8} ${y + off} L ${x + w - 8 - off} ${y + off} Q ${x + w - off} ${y + off}, ${x + w - off} ${y + 4 + off} L ${x + w - off} ${y + h - 8} C ${x + (w - off) * 0.75} ${y + h + 2}, ${x + (w - off) * 0.25} ${y + h - 10}, ${x} ${y + h - 4} Z`;
+      return (
+        <g>
+          <rect x={x + off * 2} y={y} width={w - off * 2} height={h - off} rx={4} fill={fill} stroke={stroke} strokeWidth={1.2} opacity={0.4} />
+          <rect x={x + off} y={y + off / 2} width={w - off} height={h - off} rx={4} fill={fill} stroke={stroke} strokeWidth={1.2} opacity={0.6} />
+          <path d={d} {...common} />
+        </g>
+      );
+    }
+
+    case "subroutine": {
+      const inset = 7;
+      return (
+        <g>
+          <rect x={x} y={y} width={w} height={h} rx={4} {...common} />
+          <line x1={x + inset} y1={y} x2={x + inset} y2={y + h} stroke={stroke} strokeWidth={1.2} />
+          <line x1={x + w - inset} y1={y} x2={x + w - inset} y2={y + h} stroke={stroke} strokeWidth={1.2} />
+        </g>
+      );
+    }
+
+    case "hexagon": {
+      const inset = 14;
+      return (
+        <polygon
+          points={`${x + inset},${y} ${x + w - inset},${y} ${x + w},${y + h / 2} ${x + w - inset},${y + h} ${x + inset},${y + h} ${x},${y + h / 2}`}
+          {...common}
+        />
+      );
+    }
+
+    case "manual_input":
+      return (
+        <polygon
+          points={`${x},${y + 10} ${x + w},${y} ${x + w},${y + h} ${x},${y + h}`}
+          {...common}
+        />
+      );
+
+    case "trapezoid": {
+      const inset = 12;
+      return (
+        <polygon
+          points={`${x},${y} ${x + w},${y} ${x + w - inset},${y + h} ${x + inset},${y + h}`}
+          {...common}
+        />
+      );
+    }
+
+    case "delay": {
+      const d = `M ${x} ${y + 4} Q ${x} ${y}, ${x + 4} ${y} L ${x + w * 0.65} ${y} A ${w * 0.35} ${h / 2} 0 0 1 ${x + w * 0.65} ${y + h} L ${x + 4} ${y + h} Q ${x} ${y + h}, ${x} ${y + h - 4} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    case "display": {
+      const d = `M ${x + 16} ${y} L ${x + w * 0.65} ${y} A ${w * 0.35} ${h / 2} 0 0 1 ${x + w * 0.65} ${y + h} L ${x + 16} ${y + h} L ${x} ${y + h / 2} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    case "cylinder": {
+      const ry = 7;
+      return (
+        <g>
+          <path
+            d={`M ${x} ${y + ry} L ${x} ${y + h - ry} A ${w / 2} ${ry} 0 0 0 ${x + w} ${y + h - ry} L ${x + w} ${y + ry}`}
+            {...common}
+          />
+          <ellipse cx={x + w / 2} cy={y + ry} rx={w / 2} ry={ry} {...common} />
+          <ellipse cx={x + w / 2} cy={y + h - ry} rx={w / 2} ry={ry} fill={fill} stroke={stroke} strokeWidth={1.2} />
+        </g>
+      );
+    }
+
+    case "stored_data": {
+      const d = `M ${x + 14} ${y} L ${x + w} ${y} A 10 ${h / 2} 0 0 0 ${x + w} ${y + h} L ${x + 14} ${y + h} A 10 ${h / 2} 0 0 1 ${x + 14} ${y} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    case "internal_storage":
+      return (
+        <g>
+          <rect x={x} y={y} width={w} height={h} rx={4} {...common} />
+          <line x1={x + 10} y1={y} x2={x + 10} y2={y + h} stroke={stroke} strokeWidth={0.8} opacity={0.5} />
+          <line x1={x} y1={y + 10} x2={x + w} y2={y + 10} stroke={stroke} strokeWidth={0.8} opacity={0.5} />
+        </g>
+      );
+
+    case "circle": {
+      const r = Math.min(w, h) / 2 - 2;
+      return <circle cx={x + w / 2} cy={y + h / 2} r={r} {...common} />;
+    }
+
+    case "pentagon":
+      return (
+        <polygon
+          points={`${x},${y} ${x + w},${y} ${x + w},${y + h * 0.6} ${x + w / 2},${y + h} ${x},${y + h * 0.6}`}
+          {...common}
+        />
+      );
+
+    case "triangle_inv":
+      return (
+        <polygon
+          points={`${x},${y} ${x + w},${y} ${x + w / 2},${y + h}`}
+          {...common}
+        />
+      );
+
+    case "triangle":
+      return (
+        <polygon
+          points={`${x + w / 2},${y} ${x + w},${y + h} ${x},${y + h}`}
+          {...common}
+        />
+      );
+
+    case "hourglass":
+      return (
+        <polygon
+          points={`${x},${y} ${x + w},${y} ${x + w / 2},${y + h / 2} ${x + w},${y + h} ${x},${y + h} ${x + w / 2},${y + h / 2}`}
+          {...common}
+        />
+      );
+
+    case "circle_cross": {
+      const r = Math.min(w, h) / 2 - 2;
+      const cx = x + w / 2;
+      const cy = y + h / 2;
+      return (
+        <g>
+          <circle cx={cx} cy={cy} r={r} {...common} />
+          <line x1={cx - r * 0.7} y1={cy - r * 0.7} x2={cx + r * 0.7} y2={cy + r * 0.7} stroke={stroke} strokeWidth={1} />
+          <line x1={cx + r * 0.7} y1={cy - r * 0.7} x2={cx - r * 0.7} y2={cy + r * 0.7} stroke={stroke} strokeWidth={1} />
+        </g>
+      );
+    }
+
+    case "circle_bar": {
+      const r = Math.min(w, h) / 2 - 2;
+      const cx = x + w / 2;
+      const cy = y + h / 2;
+      return (
+        <g>
+          <circle cx={cx} cy={cy} r={r} {...common} />
+          <line x1={cx} y1={cy - r} x2={cx} y2={cy + r} stroke={stroke} strokeWidth={1} />
+          <line x1={cx - r} y1={cy} x2={cx + r} y2={cy} stroke={stroke} strokeWidth={1} />
+        </g>
+      );
+    }
+
+    case "flag": {
+      const d = `M ${x} ${y} L ${x + w} ${y} L ${x + w - 8} ${y + h / 2} L ${x + w} ${y + h} L ${x} ${y + h} Z`;
+      return <path d={d} {...common} />;
+    }
+
+    default:
+      return <rect x={x} y={y} width={w} height={h} rx={8} {...common} />;
+  }
+}
+
+/** HTML tooltip positioned over the graph container */
+function Tooltip({ node, style }: { node: DraftNode; style: React.CSSProperties }) {
+  const lines: string[] = [];
+  if (node.description) lines.push(node.description);
+  if (node.tools.length > 0) lines.push(`Tools: ${node.tools.join(", ")}`);
+  if (node.success_criteria) lines.push(`Criteria: ${node.success_criteria}`);
+  if (lines.length === 0) return null;
+
+  return (
+    <div
+      className="absolute z-20 pointer-events-none px-2.5 py-2 rounded-md border border-border/40 bg-popover/95 backdrop-blur-sm shadow-lg max-w-[260px]"
+      style={style}
+    >
+      {lines.map((line, i) => (
+        <p key={i} className="text-[10px] text-muted-foreground leading-[1.4] mb-0.5 last:mb-0">
+          {line}
+        </p>
+      ))}
+    </div>
+  );
+}
+
+export default function DraftGraph({ draft, onNodeClick, flowchartMap, runtimeNodes, onRuntimeNodeClick }: DraftGraphProps) {
+  const [hoveredNode, setHoveredNode] = useState<string | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [containerW, setContainerW] = useState(484);
+
+  // Measure actual container width so layout fills it exactly
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const ro = new ResizeObserver((entries) => {
+      const w = entries[0]?.contentRect.width;
+      if (w && w > 0) setContainerW(w);
+    });
+    ro.observe(el);
+    // Capture initial width
+    setContainerW(el.clientWidth || 484);
+    return () => ro.disconnect();
+  }, []);
+
+  // Invert flowchartMap: draftNodeId → runtimeNodeId
+  const draftToRuntime = useMemo<Record<string, string>>(() => {
+    if (!flowchartMap) return {};
+    const map: Record<string, string> = {};
+    for (const [runtimeId, draftIds] of Object.entries(flowchartMap)) {
+      for (const did of draftIds) {
+        map[did] = runtimeId;
+      }
+    }
+    return map;
+  }, [flowchartMap]);
+
+  // Compute draft node statuses from runtime overlay
+  const nodeStatuses = useMemo<Record<string, DraftNodeStatus>>(() => {
+    if (!runtimeNodes?.length || !Object.keys(draftToRuntime).length) return {};
+    // Build runtime status lookup
+    const runtimeStatus: Record<string, DraftNodeStatus> = {};
+    for (const rn of runtimeNodes) {
+      const s = rn.status;
+      runtimeStatus[rn.id] =
+        s === "running" || s === "looping" ? "running"
+        : s === "complete" ? "complete"
+        : s === "error" ? "error"
+        : "pending";
+    }
+    // Map to draft nodes
+    const result: Record<string, DraftNodeStatus> = {};
+    for (const [draftId, runtimeId] of Object.entries(draftToRuntime)) {
+      result[draftId] = runtimeStatus[runtimeId] ?? "pending";
+    }
+    return result;
+  }, [draftToRuntime, runtimeNodes]);
+
+  const hasStatusOverlay = Object.keys(nodeStatuses).length > 0;
+
+  const { nodes, edges } = draft;
+
+  const idxMap = useMemo(
+    () => Object.fromEntries(nodes.map((n, i) => [n.id, i])),
+    [nodes],
+  );
+
+  const forwardEdges = useMemo(() => {
+    const fwd: { fromIdx: number; toIdx: number; fanCount: number; fanIndex: number; label?: string }[] = [];
+    const grouped = new Map<number, { toIdx: number; label?: string }[]>();
+    for (const e of edges) {
+      const fromIdx = idxMap[e.source];
+      const toIdx = idxMap[e.target];
+      if (fromIdx === undefined || toIdx === undefined) continue;
+      if (toIdx <= fromIdx) continue;
+      const list = grouped.get(fromIdx) || [];
+      list.push({ toIdx, label: e.label || (e.condition !== "on_success" && e.condition !== "always" ? e.condition : e.description || undefined) });
+      grouped.set(fromIdx, list);
+    }
+    for (const [fromIdx, targets] of grouped) {
+      targets.forEach((t, fi) => {
+        fwd.push({ fromIdx, toIdx: t.toIdx, fanCount: targets.length, fanIndex: fi, label: t.label });
+      });
+    }
+    return fwd;
+  }, [edges, idxMap]);
+
+  const backEdges = useMemo(() => {
+    const back: { fromIdx: number; toIdx: number }[] = [];
+    for (const e of edges) {
+      const fromIdx = idxMap[e.source];
+      const toIdx = idxMap[e.target];
+      if (fromIdx === undefined || toIdx === undefined) continue;
+      if (toIdx <= fromIdx) back.push({ fromIdx, toIdx });
+    }
+    return back;
+  }, [edges, idxMap]);
+
+  // Layer-based layout with parent-aware column placement
+  const layout = useMemo(() => {
+    if (nodes.length === 0) {
+      return { layers: [] as number[], nodeW: 200, firstColX: MARGIN_X, nodeXPositions: [] as number[] };
+    }
+
+    // Build parent and children maps
+    const parents = new Map<number, number[]>();
+    const children = new Map<number, number[]>();
+    nodes.forEach((_, i) => { parents.set(i, []); children.set(i, []); });
+    forwardEdges.forEach((e) => {
+      parents.get(e.toIdx)!.push(e.fromIdx);
+      children.get(e.fromIdx)!.push(e.toIdx);
+    });
+
+    // Assign layers (longest path from root)
+    const layers = new Array(nodes.length).fill(0);
+    for (let i = 0; i < nodes.length; i++) {
+      const pars = parents.get(i) || [];
+      if (pars.length > 0) {
+        layers[i] = Math.max(...pars.map((p) => layers[p])) + 1;
+      }
+    }
+
+    const layerGroups = new Map<number, number[]>();
+    layers.forEach((l, i) => {
+      const group = layerGroups.get(l) || [];
+      group.push(i);
+      layerGroups.set(l, group);
+    });
+
+    let maxCols = 1;
+    layerGroups.forEach((group) => {
+      maxCols = Math.max(maxCols, group.length);
+    });
+
+    // Compute node width
+    const backEdgeMargin = backEdges.length > 0 ? 30 + backEdges.length * 14 : 8;
+    const totalMargin = MARGIN_X * 2 + backEdgeMargin;
+    const availW = containerW - totalMargin;
+    const nodeW = Math.min(360, Math.floor((availW - (maxCols - 1) * GAP_X) / maxCols));
+
+    // Parent-aware column placement using fractional positions.
+    // Instead of snapping to a fixed grid, nodes inherit positions from parents
+    // and fan-out children spread around the parent's position.
+    const colPos = new Array(nodes.length).fill(0); // fractional column positions
+    const maxLayer = Math.max(...layers);
+
+    // Process layers top-down
+    for (let layer = 0; layer <= maxLayer; layer++) {
+      const group = layerGroups.get(layer) || [];
+      if (layer === 0) {
+        // Root layer: spread evenly across available columns
+        if (group.length === 1) {
+          colPos[group[0]] = (maxCols - 1) / 2;
+        } else {
+          const offset = (maxCols - group.length) / 2;
+          group.forEach((nodeIdx, i) => { colPos[nodeIdx] = offset + i; });
+        }
+        continue;
+      }
+
+      // For each node, compute ideal position from parents
+      const ideals: { idx: number; pos: number }[] = [];
+      for (const nodeIdx of group) {
+        const pars = parents.get(nodeIdx) || [];
+        if (pars.length === 0) {
+          ideals.push({ idx: nodeIdx, pos: (maxCols - 1) / 2 });
+          continue;
+        }
+        // Average parent column — weighted center
+        const avgCol = pars.reduce((s, p) => s + colPos[p], 0) / pars.length;
+
+        // If this node is one of multiple children of a parent, offset from center
+        // Find the parent with the most children to determine fan-out
+        let bestOffset = 0;
+        for (const p of pars) {
+          const siblings = (children.get(p) || []).filter(c => layers[c] === layer);
+          if (siblings.length > 1) {
+            const sibIdx = siblings.indexOf(nodeIdx);
+            if (sibIdx >= 0) {
+              bestOffset = sibIdx - (siblings.length - 1) / 2;
+              // Scale so siblings don't exceed available columns
+              bestOffset *= Math.min(1, (maxCols - 1) / Math.max(siblings.length - 1, 1));
+            }
+          }
+        }
+        ideals.push({ idx: nodeIdx, pos: avgCol + bestOffset });
+      }
+
+      // Sort by ideal position, then assign while preventing overlaps
+      ideals.sort((a, b) => a.pos - b.pos);
+
+      // Ensure minimum spacing of 1 column between nodes in the same layer
+      const assigned: number[] = [];
+      for (const item of ideals) {
+        let pos = item.pos;
+        // Clamp to valid range
+        pos = Math.max(0, Math.min(maxCols - 1, pos));
+        // Push right if overlapping previous
+        if (assigned.length > 0) {
+          const prev = assigned[assigned.length - 1];
+          if (pos < prev + 1) pos = prev + 1;
+        }
+        assigned.push(pos);
+        colPos[item.idx] = pos;
+      }
+
+      // If we pushed nodes too far right, shift the whole group left
+      const maxPos = assigned[assigned.length - 1];
+      if (maxPos > maxCols - 1) {
+        const shift = maxPos - (maxCols - 1);
+        for (const item of ideals) {
+          colPos[item.idx] = Math.max(0, colPos[item.idx] - shift);
+        }
+      }
+    }
+
+    // Convert fractional column positions to pixel X positions
+    const colSpacing = nodeW + GAP_X;
+    const usedMin = Math.min(...colPos);
+    const usedMax = Math.max(...colPos);
+    const usedSpan = usedMax - usedMin || 1;
+    const totalNodesW = usedSpan * colSpacing;
+    const firstColX = MARGIN_X + (availW - totalNodesW) / 2;
+
+    const nodeXPositions = colPos.map((c: number) => firstColX + (c - usedMin) * colSpacing);
+
+    return { layers, nodeW, firstColX, nodeXPositions };
+  }, [nodes, forwardEdges, backEdges.length, containerW]);
+
+  if (nodes.length === 0) {
+    return (
+      <div className="flex flex-col h-full">
+        <div className="px-4 pt-4 pb-2">
+          <p className="text-[11px] text-muted-foreground font-medium uppercase tracking-wider">
+            Draft
+          </p>
+        </div>
+        <div className="flex-1 flex items-center justify-center px-4">
+          <p className="text-xs text-muted-foreground/60 text-center italic">
+            No draft graph yet.
+            <br />
+            Describe your workflow to get started.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  const { layers, nodeW, nodeXPositions } = layout;
+
+  const nodePos = (i: number) => ({
+    x: nodeXPositions[i],
+    y: TOP_Y + layers[i] * (NODE_H + GAP_Y),
+  });
+
+  const maxLayer = Math.max(...layers);
+  const svgHeight = TOP_Y + (maxLayer + 1) * NODE_H + maxLayer * GAP_Y + 16;
+
+  // Compute group areas for multi-node runtime groups
+  const groupAreas = useMemo(() => {
+    if (!flowchartMap || !runtimeNodes?.length) return [];
+    const groups: { runtimeId: string; label: string; draftIds: string[] }[] = [];
+    for (const [runtimeId, draftIds] of Object.entries(flowchartMap)) {
+      if (draftIds.length < 2) continue;
+      const rn = runtimeNodes.find(n => n.id === runtimeId);
+      groups.push({ runtimeId, label: rn?.label ?? runtimeId, draftIds });
+    }
+    return groups;
+  }, [flowchartMap, runtimeNodes]);
+
+  // Legend
+  const usedTypes = (() => {
+    const seen = new Map<string, { shape: string; color: string }>();
+    for (const n of nodes) {
+      if (!seen.has(n.flowchart_type)) {
+        seen.set(n.flowchart_type, { shape: n.flowchart_shape, color: n.flowchart_color });
+      }
+    }
+    return [...seen.entries()];
+  })();
+  const legendH = usedTypes.length * 18 + 20;
+  const totalH = svgHeight + legendH;
+
+  // Find hovered node for tooltip positioning
+  const hoveredNodeData = hoveredNode ? nodes.find(n => n.id === hoveredNode) : null;
+  const hoveredIdx = hoveredNode ? idxMap[hoveredNode] : -1;
+  const hoveredPos = hoveredIdx >= 0 ? nodePos(hoveredIdx) : null;
+
+  const renderEdge = (edge: typeof forwardEdges[number], i: number) => {
+    const from = nodePos(edge.fromIdx);
+    const to = nodePos(edge.toIdx);
+    const fromCenterX = from.x + nodeW / 2;
+    const toCenterX = to.x + nodeW / 2;
+    const y1 = from.y + NODE_H;
+    const y2 = to.y;
+
+    let startX = fromCenterX;
+    if (edge.fanCount > 1) {
+      const spread = nodeW * 0.4;
+      const step = edge.fanCount > 1 ? spread / (edge.fanCount - 1) : 0;
+      startX = fromCenterX - spread / 2 + edge.fanIndex * step;
+    }
+
+    const midY = (y1 + y2) / 2;
+    const d = `M ${startX} ${y1} C ${startX} ${midY}, ${toCenterX} ${midY}, ${toCenterX} ${y2}`;
+
+    return (
+      <g key={`fwd-${i}`}>
+        <path d={d} fill="none" stroke="hsl(220,10%,30%)" strokeWidth={1.2} />
+        <polygon
+          points={`${toCenterX - 3},${y2 - 5} ${toCenterX + 3},${y2 - 5} ${toCenterX},${y2 - 1}`}
+          fill="hsl(220,10%,35%)"
+        />
+        {edge.label && (
+          <text
+            x={(startX + toCenterX) / 2}
+            y={midY - 3}
+            fill="hsl(220,10%,45%)"
+            fontSize={9}
+            fontStyle="italic"
+            textAnchor="middle"
+          >
+            {truncateLabel(edge.label, 80, 9)}
+          </text>
+        )}
+      </g>
+    );
+  };
+
+  const renderBackEdge = (edge: typeof backEdges[number], i: number) => {
+    const from = nodePos(edge.fromIdx);
+    const to = nodePos(edge.toIdx);
+    const rightX = Math.max(from.x, to.x) + nodeW;
+    const rightOffset = 20 + i * 14;
+    const startX = from.x + nodeW;
+    const startY = from.y + NODE_H / 2;
+    const endX = to.x + nodeW;
+    const endY = to.y + NODE_H / 2;
+    const curveX = rightX + rightOffset;
+    const r = 10;
+
+    const path = `M ${startX} ${startY} C ${startX + r} ${startY}, ${curveX} ${startY}, ${curveX} ${startY - r} L ${curveX} ${endY + r} C ${curveX} ${endY}, ${endX + r} ${endY}, ${endX + 5} ${endY}`;
+
+    return (
+      <g key={`back-${i}`}>
+        <path d={path} fill="none" stroke="hsl(220,10%,25%)" strokeWidth={1.2} strokeDasharray="4 3" />
+        <polygon
+          points={`${endX + 5},${endY - 2.5} ${endX + 5},${endY + 2.5} ${endX},${endY}`}
+          fill="hsl(220,10%,30%)"
+        />
+      </g>
+    );
+  };
+
+  const STATUS_COLORS: Record<DraftNodeStatus, string> = {
+    running: "#F59E0B",  // amber
+    complete: "#22C55E", // green
+    error: "#EF4444",    // red
+    pending: "",         // no overlay
+  };
+
+  const renderNode = (node: DraftNode, i: number) => {
+    const pos = nodePos(i);
+    const isHovered = hoveredNode === node.id;
+    const status = nodeStatuses[node.id] as DraftNodeStatus | undefined;
+    const statusColor = status ? STATUS_COLORS[status] : "";
+    const fontSize = 13;
+    const labelAvailW = nodeW - 28;
+    const displayLabel = truncateLabel(node.name, labelAvailW, fontSize);
+    const descAvailW = nodeW - 24;
+    const descLabel = node.description
+      ? truncateLabel(node.description, descAvailW, 9.5)
+      : node.flowchart_type.replace(/_/g, " ");
+    const textX = pos.x + nodeW / 2;
+    const textY = pos.y + NODE_H / 2;
+
+    return (
+      <g
+        key={node.id}
+        onClick={() => {
+          if (hasStatusOverlay && onRuntimeNodeClick) {
+            const runtimeId = draftToRuntime[node.id];
+            if (runtimeId) onRuntimeNodeClick(runtimeId);
+          } else {
+            onNodeClick?.(node);
+          }
+        }}
+        onMouseEnter={() => setHoveredNode(node.id)}
+        onMouseLeave={() => setHoveredNode(null)}
+        style={{ cursor: "pointer" }}
+      >
+        <title>{`${node.name}\n${node.flowchart_type}`}</title>
+
+        {/* Status glow ring (runtime overlay) */}
+        {hasStatusOverlay && statusColor && (
+          <rect
+            x={pos.x - 3}
+            y={pos.y - 3}
+            width={nodeW + 6}
+            height={NODE_H + 6}
+            rx={8}
+            fill="none"
+            stroke={statusColor}
+            strokeWidth={2}
+            opacity={status === "running" ? 0.8 : 0.6}
+          >
+            {status === "running" && (
+              <animate attributeName="opacity" values="0.4;0.9;0.4" dur="1.5s" repeatCount="indefinite" />
+            )}
+          </rect>
+        )}
+
+        <FlowchartShape
+          shape={node.flowchart_shape}
+          x={pos.x}
+          y={pos.y}
+          w={nodeW}
+          h={NODE_H}
+          color={node.flowchart_color}
+          selected={isHovered}
+        />
+
+        <text
+          x={textX}
+          y={textY - 5}
+          fill={isHovered ? "hsl(0,0%,92%)" : "hsl(0,0%,78%)"}
+          fontSize={fontSize}
+          fontWeight={500}
+          textAnchor="middle"
+          dominantBaseline="middle"
+        >
+          {displayLabel}
+        </text>
+
+        <text
+          x={textX}
+          y={textY + 11}
+          fill="hsl(220,10%,50%)"
+          fontSize={9.5}
+          textAnchor="middle"
+          dominantBaseline="middle"
+        >
+          {descLabel}
+        </text>
+
+        {/* Status dot indicator */}
+        {hasStatusOverlay && statusColor && (
+          <circle
+            cx={pos.x + nodeW - 6}
+            cy={pos.y + 6}
+            r={4}
+            fill={statusColor}
+          >
+            {status === "running" && (
+              <animate attributeName="r" values="3;5;3" dur="1s" repeatCount="indefinite" />
+            )}
+          </circle>
+        )}
+      </g>
+    );
+  };
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Header */}
+      <div className="px-4 pt-3 pb-1.5 flex items-center gap-2">
+        <p className="text-[11px] text-muted-foreground font-medium uppercase tracking-wider">
+          {hasStatusOverlay ? "Flowchart" : "Draft"}
+        </p>
+        <span className={`text-[9px] font-mono font-medium rounded px-1 py-0.5 leading-none border ${hasStatusOverlay ? "text-emerald-500/60 border-emerald-500/20" : "text-amber-500/60 border-amber-500/20"}`}>
+          {hasStatusOverlay ? "live" : "planning"}
+        </span>
+      </div>
+
+      {/* Agent name + goal */}
+      <div className="px-4 pb-2.5 border-b border-border/20">
+        <p className="text-[11px] font-medium text-foreground/80 truncate">
+          {draft.agent_name}
+        </p>
+        {draft.goal && (
+          <p className="text-[10px] text-muted-foreground/60 mt-0.5 line-clamp-2 leading-snug">
+            {draft.goal}
+          </p>
+        )}
+      </div>
+
+      {/* Graph */}
+      <div ref={containerRef} className="flex-1 overflow-y-auto overflow-x-hidden px-2 pb-2 relative">
+        <svg
+          width="100%"
+          viewBox={`0 0 ${containerW} ${totalH}`}
+          preserveAspectRatio="xMidYMin meet"
+          className="select-none"
+          style={{ fontFamily: "'Inter', system-ui, sans-serif" }}
+        >
+          {/* Group areas — dashed boxes behind multi-node runtime groups */}
+          {groupAreas.map((group) => {
+            const memberIndices = group.draftIds
+              .map(id => idxMap[id])
+              .filter((idx): idx is number => idx !== undefined);
+            if (memberIndices.length < 2) return null;
+            const positions = memberIndices.map(i => nodePos(i));
+            const pad = 10;
+            const minX = Math.min(...positions.map(p => p.x)) - pad;
+            const minY = Math.min(...positions.map(p => p.y)) - pad - 14; // extra space for label
+            const maxX = Math.max(...positions.map(p => p.x + nodeW)) + pad;
+            const maxY = Math.max(...positions.map(p => p.y + NODE_H)) + pad;
+            return (
+              <g key={`group-${group.runtimeId}`}>
+                <rect
+                  x={minX}
+                  y={minY}
+                  width={maxX - minX}
+                  height={maxY - minY}
+                  rx={8}
+                  fill="hsl(220,15%,18%)"
+                  fillOpacity={0.35}
+                  stroke="hsl(220,10%,40%)"
+                  strokeWidth={1}
+                  strokeDasharray="5 3"
+                />
+                <text
+                  x={minX + 8}
+                  y={minY + 11}
+                  fill="hsl(220,10%,50%)"
+                  fontSize={9}
+                  fontWeight={500}
+                >
+                  {truncateLabel(group.label, maxX - minX - 16, 9)}
+                </text>
+              </g>
+            );
+          })}
+
+          {forwardEdges.map((e, i) => renderEdge(e, i))}
+          {backEdges.map((e, i) => renderBackEdge(e, i))}
+          {nodes.map((n, i) => renderNode(n, i))}
+
+          {/* Legend */}
+          <g transform={`translate(${MARGIN_X}, ${svgHeight + 4})`}>
+            <text fill="hsl(220,10%,40%)" fontSize={9} fontWeight={600} y={4}>
+              LEGEND
+            </text>
+            {usedTypes.map(([type, meta], i) => (
+              <g key={type} transform={`translate(0, ${14 + i * 18})`}>
+                <FlowchartShape
+                  shape={meta.shape}
+                  x={0}
+                  y={0}
+                  w={16}
+                  h={12}
+                  color={meta.color}
+                  selected={false}
+                />
+                <text x={22} y={9} fill="hsl(220,10%,55%)" fontSize={9.5}>
+                  {type.replace(/_/g, " ")}
+                </text>
+              </g>
+            ))}
+          </g>
+        </svg>
+
+        {/* HTML tooltip — rendered outside SVG so it's not clipped */}
+        {hoveredNodeData && hoveredPos && (
+          <Tooltip
+            node={hoveredNodeData}
+            style={{
+              left: 8,
+              right: 8,
+              // Position below the hovered node, scaled to container width
+              top: `calc(${((hoveredPos.y + NODE_H + 4) / totalH) * 100}%)`,
+            }}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

core/frontend/src/components/MultiQuestionWidget.tsx

@@ -0,0 +1,215 @@
+import { useState, useRef, useEffect, useCallback } from "react";
+import { Send, MessageCircleQuestion, X } from "lucide-react";
+
+export interface QuestionItem {
+  id: string;
+  prompt: string;
+  options?: string[];
+}
+
+export interface MultiQuestionWidgetProps {
+  questions: QuestionItem[];
+  onSubmit: (answers: Record<string, string>) => void;
+  onDismiss?: () => void;
+}
+
+export default function MultiQuestionWidget({ questions, onSubmit, onDismiss }: MultiQuestionWidgetProps) {
+  // Per-question state: selected index (null = nothing, options.length = "Other")
+  const [selections, setSelections] = useState<(number | null)[]>(
+    () => questions.map(() => null),
+  );
+  const [customTexts, setCustomTexts] = useState<string[]>(
+    () => questions.map(() => ""),
+  );
+  const [submitted, setSubmitted] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Scroll the first unanswered question into view when it changes
+  useEffect(() => {
+    containerRef.current?.scrollTo({ top: 0, behavior: "smooth" });
+  }, []);
+
+  const canSubmit = questions.every((q, i) => {
+    const sel = selections[i];
+    if (sel === null) return false;
+    const isOther = q.options ? sel === q.options.length : true;
+    if (isOther && !customTexts[i].trim()) return false;
+    return true;
+  });
+
+  const handleSubmit = useCallback(() => {
+    if (!canSubmit || submitted) return;
+    setSubmitted(true);
+    const answers: Record<string, string> = {};
+    for (let i = 0; i < questions.length; i++) {
+      const q = questions[i];
+      const sel = selections[i]!;
+      const isOther = q.options ? sel === q.options.length : true;
+      answers[q.id] = isOther ? customTexts[i].trim() : q.options![sel];
+    }
+    onSubmit(answers);
+  }, [canSubmit, submitted, questions, selections, customTexts, onSubmit]);
+
+  // Enter to submit (only when not focused on a text input)
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (submitted) return;
+      const target = e.target as HTMLElement;
+      const inInput = target.tagName === "INPUT" || target.tagName === "TEXTAREA";
+      if (e.key === "Enter" && !e.shiftKey && !inInput) {
+        e.preventDefault();
+        handleSubmit();
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [handleSubmit, submitted]);
+
+  if (submitted) return null;
+
+  const answeredCount = selections.filter((s) => s !== null).length;
+
+  return (
+    <div className="p-4">
+      <div className="bg-card border border-border rounded-xl shadow-sm overflow-hidden">
+        {/* Header */}
+        <div className="px-5 pt-4 pb-2 flex items-center gap-3">
+          <div className="w-7 h-7 rounded-lg bg-primary/10 border border-primary/20 flex items-center justify-center flex-shrink-0">
+            <MessageCircleQuestion className="w-3.5 h-3.5 text-primary" />
+          </div>
+          <div className="flex-1 min-w-0">
+            <p className="text-sm font-medium text-foreground">
+              {questions.length} questions
+            </p>
+            <p className="text-[11px] text-muted-foreground">
+              {answeredCount}/{questions.length} answered
+            </p>
+          </div>
+          {onDismiss && (
+            <button
+              onClick={onDismiss}
+              className="p-1 rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/60 transition-colors flex-shrink-0"
+            >
+              <X className="w-4 h-4" />
+            </button>
+          )}
+        </div>
+
+        {/* Questions */}
+        <div
+          ref={containerRef}
+          className="px-5 pb-3 space-y-4 max-h-[400px] overflow-y-auto"
+        >
+          {questions.map((q, qi) => {
+            const sel = selections[qi];
+            const hasOptions = q.options && q.options.length >= 2;
+            const otherIndex = hasOptions ? q.options!.length : 0;
+            const isOtherSelected = sel === otherIndex;
+
+            return (
+              <div key={q.id} className="space-y-1.5">
+                <p className="text-sm font-medium text-foreground">
+                  <span className="text-xs text-muted-foreground mr-1.5">
+                    {qi + 1}.
+                  </span>
+                  {q.prompt}
+                </p>
+
+                {hasOptions ? (
+                  <>
+                    {q.options!.map((opt, oi) => (
+                      <button
+                        key={oi}
+                        onClick={() => {
+                          setSelections((prev) => {
+                            const next = [...prev];
+                            next[qi] = oi;
+                            return next;
+                          });
+                        }}
+                        className={`w-full text-left px-4 py-2 rounded-lg border text-sm transition-colors ${
+                          sel === oi
+                            ? "border-primary bg-primary/10 text-foreground"
+                            : "border-border/60 bg-muted/20 text-foreground hover:border-primary/40 hover:bg-muted/40"
+                        }`}
+                      >
+                        {opt}
+                      </button>
+                    ))}
+                    <input
+                      type="text"
+                      value={customTexts[qi]}
+                      onFocus={() => {
+                        setSelections((prev) => {
+                          const next = [...prev];
+                          next[qi] = otherIndex;
+                          return next;
+                        });
+                      }}
+                      onChange={(e) => {
+                        setSelections((prev) => {
+                          const next = [...prev];
+                          next[qi] = otherIndex;
+                          return next;
+                        });
+                        setCustomTexts((prev) => {
+                          const next = [...prev];
+                          next[qi] = e.target.value;
+                          return next;
+                        });
+                      }}
+                      placeholder="Type a custom response..."
+                      className={`w-full px-4 py-2 rounded-lg border border-dashed text-sm transition-colors bg-transparent placeholder:text-muted-foreground focus:outline-none ${
+                        isOtherSelected
+                          ? "border-primary bg-primary/10 text-foreground"
+                          : "border-border text-muted-foreground hover:border-primary/40"
+                      }`}
+                    />
+                  </>
+                ) : (
+                  <input
+                    type="text"
+                    value={customTexts[qi]}
+                    onFocus={() => {
+                      setSelections((prev) => {
+                        const next = [...prev];
+                        next[qi] = 0;
+                        return next;
+                      });
+                    }}
+                    onChange={(e) => {
+                      setSelections((prev) => {
+                        const next = [...prev];
+                        next[qi] = 0;
+                        return next;
+                      });
+                      setCustomTexts((prev) => {
+                        const next = [...prev];
+                        next[qi] = e.target.value;
+                        return next;
+                      });
+                    }}
+                    placeholder="Type your answer..."
+                    className="w-full px-4 py-2 rounded-lg border text-sm transition-colors bg-transparent placeholder:text-muted-foreground focus:outline-none border-border text-foreground hover:border-primary/40 focus:border-primary"
+                  />
+                )}
+              </div>
+            );
+          })}
+        </div>
+
+        {/* Submit */}
+        <div className="px-5 pb-4">
+          <button
+            onClick={handleSubmit}
+            disabled={!canSubmit}
+            className="w-full flex items-center justify-center gap-2 py-2.5 rounded-lg text-sm font-medium bg-primary text-primary-foreground hover:bg-primary/90 disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+          >
+            <Send className="w-3.5 h-3.5" />
+            Submit All
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

core/frontend/src/pages/workspace.tsx

@@ -3,6 +3,7 @@ import ReactDOM from "react-dom";
 import { useSearchParams, useNavigate } from "react-router-dom";
 import { Plus, KeyRound, Sparkles, Layers, ChevronLeft, Bot, Loader2, WifiOff, X } from "lucide-react";
 import AgentGraph, { type GraphNode, type NodeStatus } from "@/components/AgentGraph";
+import DraftGraph from "@/components/DraftGraph";
 import ChatPanel, { type ChatMessage } from "@/components/ChatPanel";
 import TopBar from "@/components/TopBar";
 import { TAB_STORAGE_KEY, loadPersistedTabs, savePersistedTabs, type PersistedTabState } from "@/lib/tab-persistence";
@@ -13,7 +14,7 @@ import { executionApi } from "@/api/execution";
 import { graphsApi } from "@/api/graphs";
 import { sessionsApi } from "@/api/sessions";
 import { useMultiSSE } from "@/hooks/use-sse";
-import type { LiveSession, AgentEvent, DiscoverEntry, Message, NodeSpec } from "@/api/types";
+import type { LiveSession, AgentEvent, DiscoverEntry, Message, NodeSpec, DraftGraph as DraftGraphData } from "@/api/types";
 import { backendMessageToChatMessage, sseEventToChatMessage, formatAgentDisplayName } from "@/lib/chat-helpers";
 import { topologyToGraphNodes } from "@/lib/graph-converter";
 import { ApiError } from "@/api/client";
@@ -257,6 +258,12 @@ interface AgentBackendState {
   queenBuilding: boolean;
   /** Queen operating phase — "planning" (design), "building" (coding), "staging" (loaded), or "running" (executing) */
   queenPhase: "planning" | "building" | "staging" | "running";
+  /** Draft graph from planning phase (before code generation) */
+  draftGraph: DraftGraphData | null;
+  /** Original draft (pre-dissolution) for flowchart display during runtime */
+  originalDraft: DraftGraphData | null;
+  /** Runtime node ID → list of original draft node IDs it absorbed */
+  flowchartMap: Record<string, string[]> | null;
   workerRunState: "idle" | "deploying" | "running";
   currentExecutionId: string | null;
   nodeLogs: Record<string, string[]>;
@@ -270,10 +277,14 @@ interface AgentBackendState {
   workerIsTyping: boolean;
   llmSnapshots: Record<string, string>;
   activeToolCalls: Record<string, { name: string; done: boolean; streamId: string }>;
+  /** Agent folder path — set after scaffolding, used for credential queries */
+  agentPath: string | null;
   /** Structured question text from ask_user with options */
   pendingQuestion: string | null;
   /** Predefined choices from ask_user (1-3 items); UI appends "Other" */
   pendingOptions: string[] | null;
+  /** Multiple questions from ask_user_multiple */
+  pendingQuestions: { id: string; prompt: string; options?: string[] }[] | null;
   /** Whether the pending question came from queen or worker */
   pendingQuestionSource: "queen" | "worker" | null;
 }
@@ -292,6 +303,10 @@ function defaultAgentState(): AgentBackendState {
     workerInputMessageId: null,
     queenBuilding: false,
     queenPhase: "planning",
+    draftGraph: null,
+    originalDraft: null,
+    flowchartMap: null,
+    agentPath: null,
     workerRunState: "idle",
     currentExecutionId: null,
     nodeLogs: {},
@@ -305,6 +320,7 @@ function defaultAgentState(): AgentBackendState {
     activeToolCalls: {},
     pendingQuestion: null,
     pendingOptions: null,
+    pendingQuestions: null,
     pendingQuestionSource: null,
   };
 }
@@ -1056,6 +1072,39 @@ export default function Workspace() {
     }
   }, [agentStates, fetchGraphForAgent]);
 
+  // --- Fetch draft graph when a session is in planning phase ---
+  // Covers initial load, tab switches, reconnects, and cold restores.
+  const fetchedDraftSessionsRef = useRef<Set<string>>(new Set());
+  const fetchedFlowchartMapSessionsRef = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    for (const [agentType, state] of Object.entries(agentStates)) {
+      if (!state.sessionId || !state.ready) continue;
+
+      if (state.queenPhase === "planning") {
+        // Fetch draft graph for planning phase
+        if (state.draftGraph) continue;
+        if (fetchedDraftSessionsRef.current.has(state.sessionId)) continue;
+        fetchedDraftSessionsRef.current.add(state.sessionId);
+        graphsApi.draftGraph(state.sessionId).then(({ draft }) => {
+          if (draft) updateAgentState(agentType, { draftGraph: draft });
+        }).catch(() => {});
+      } else {
+        // Fetch flowchart map for non-planning phases (staging, running, building)
+        if (state.originalDraft) continue; // already have it
+        if (fetchedFlowchartMapSessionsRef.current.has(state.sessionId)) continue;
+        fetchedFlowchartMapSessionsRef.current.add(state.sessionId);
+        graphsApi.flowchartMap(state.sessionId).then(({ map, original_draft }) => {
+          if (original_draft) {
+            updateAgentState(agentType, {
+              flowchartMap: map,
+              originalDraft: original_draft,
+            });
+          }
+        }).catch(() => {});
+      }
+    }
+  }, [agentStates, updateAgentState]);
+
   // Poll entry points every second for agents with timers to keep
   // next_fire_in countdowns fresh without re-fetching the full topology.
   useEffect(() => {
@@ -1310,6 +1359,7 @@ export default function Workspace() {
               activeToolCalls: {},
               pendingQuestion: null,
               pendingOptions: null,
+              pendingQuestions: null,
               pendingQuestionSource: null,
             });
             markAllNodesAs(agentType, ["running", "looping", "complete", "error"], "pending");
@@ -1339,6 +1389,7 @@ export default function Workspace() {
               llmSnapshots: {},
               pendingQuestion: null,
               pendingOptions: null,
+              pendingQuestions: null,
               pendingQuestionSource: null,
             });
             markAllNodesAs(agentType, ["running", "looping"], "complete");
@@ -1388,9 +1439,13 @@ export default function Workspace() {
             console.log('[CLIENT_INPUT_REQ] stream_id:', streamId, 'isQueen:', isQueen, 'node_id:', event.node_id, 'prompt:', (event.data?.prompt as string)?.slice(0, 80), 'agentType:', agentType);
             const rawOptions = event.data?.options;
             const options = Array.isArray(rawOptions) ? (rawOptions as string[]) : null;
+            const rawQuestions = event.data?.questions;
+            const questions = Array.isArray(rawQuestions)
+              ? (rawQuestions as { id: string; prompt: string; options?: string[] }[])
+              : null;
             if (isQueen) {
               const prompt = (event.data?.prompt as string) || "";
-              const isAutoBlock = !prompt && !options;
+              const isAutoBlock = !prompt && !options && !questions;
               // Queen auto-block (empty prompt, no options) should not
               // overwrite a pending worker question — the worker's
               // QuestionWidget must stay visible.  Use the updater form
@@ -1421,6 +1476,7 @@ export default function Workspace() {
                     queenBuilding: false,
                     pendingQuestion: prompt || null,
                     pendingOptions: options,
+                    pendingQuestions: questions,
                     pendingQuestionSource: "queen",
                   }
                 };
@@ -1460,14 +1516,14 @@ export default function Workspace() {
             }
           }
           if (event.type === "execution_paused") {
-            updateAgentState(agentType, { isTyping: false, isStreaming: false, queenIsTyping: false, workerIsTyping: false, awaitingInput: false, workerInputMessageId: null, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+            updateAgentState(agentType, { isTyping: false, isStreaming: false, queenIsTyping: false, workerIsTyping: false, awaitingInput: false, workerInputMessageId: null, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
             if (!isQueen) {
               updateAgentState(agentType, { workerRunState: "idle", currentExecutionId: null });
               markAllNodesAs(agentType, ["running", "looping"], "pending");
             }
           }
           if (event.type === "execution_failed") {
-            updateAgentState(agentType, { isTyping: false, isStreaming: false, queenIsTyping: false, workerIsTyping: false, awaitingInput: false, workerInputMessageId: null, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+            updateAgentState(agentType, { isTyping: false, isStreaming: false, queenIsTyping: false, workerIsTyping: false, awaitingInput: false, workerInputMessageId: null, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
             if (!isQueen) {
               updateAgentState(agentType, { workerRunState: "idle", currentExecutionId: null });
               if (event.node_id) {
@@ -1500,9 +1556,9 @@ export default function Workspace() {
         case "node_loop_iteration":
           turnCounterRef.current[turnKey] = currentTurn + 1;
           if (isQueen) {
-            updateAgentState(agentType, { isStreaming: false, activeToolCalls: {}, awaitingInput: false, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+            updateAgentState(agentType, { isStreaming: false, activeToolCalls: {}, awaitingInput: false, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
           } else {
-            updateAgentState(agentType, { isStreaming: false, workerIsTyping: true, activeToolCalls: {}, awaitingInput: false, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+            updateAgentState(agentType, { isStreaming: false, workerIsTyping: true, activeToolCalls: {}, awaitingInput: false, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
           }
           if (!isQueen && event.node_id) {
             const pendingText = agentStates[agentType]?.llmSnapshots[event.node_id];
@@ -1788,6 +1844,7 @@ export default function Workspace() {
 
         case "queen_phase_changed": {
           const rawPhase = event.data?.phase as string;
+          const eventAgentPath = (event.data?.agent_path as string) || null;
           const newPhase: "planning" | "building" | "staging" | "running" =
             rawPhase === "running" ? "running"
             : rawPhase === "staging" ? "staging"
@@ -1798,7 +1855,51 @@ export default function Workspace() {
             queenBuilding: newPhase === "building",
             // Sync workerRunState so the RunButton reflects the phase
             workerRunState: newPhase === "running" ? "running" : "idle",
+            // Clear draft graph once we leave planning; also clear dedup refs
+            // so re-entering planning or re-fetching flowchart map works
+            ...(newPhase !== "planning" ? { draftGraph: null } : { originalDraft: null, flowchartMap: null }),
+            // Store agent path for credential queries
+            ...(eventAgentPath ? { agentPath: eventAgentPath } : {}),
           });
+          {
+            const sid = agentStates[agentType]?.sessionId;
+            if (sid) {
+              if (newPhase !== "planning") {
+                fetchedDraftSessionsRef.current.delete(sid);
+                fetchedFlowchartMapSessionsRef.current.delete(sid);
+                // Fetch the flowchart map (original draft + dissolution mapping)
+                graphsApi.flowchartMap(sid).then(({ map, original_draft }) => {
+                  updateAgentState(agentType, {
+                    flowchartMap: map,
+                    originalDraft: original_draft,
+                  });
+                }).catch(() => {});
+              } else {
+                fetchedDraftSessionsRef.current.delete(sid);
+                fetchedFlowchartMapSessionsRef.current.delete(sid);
+              }
+            }
+          }
+          break;
+        }
+
+        case "draft_graph_updated": {
+          // The draft dict is published directly as event.data (not nested under a key)
+          const draft = event.data as unknown as DraftGraphData | undefined;
+          if (draft?.nodes) {
+            updateAgentState(agentType, { draftGraph: draft });
+          }
+          break;
+        }
+
+        case "flowchart_map_updated": {
+          const mapData = event.data as { map?: Record<string, string[]>; original_draft?: DraftGraphData } | undefined;
+          if (mapData) {
+            updateAgentState(agentType, {
+              flowchartMap: mapData.map ?? null,
+              originalDraft: mapData.original_draft ?? null,
+            });
+          }
           break;
         }
 
@@ -1929,7 +2030,7 @@ export default function Workspace() {
             s.id === activeSession.id ? { ...s, messages: [...s.messages, userMsg] } : s
           ),
         }));
-        updateAgentState(activeWorker, { awaitingInput: false, workerInputMessageId: null, isTyping: true, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+        updateAgentState(activeWorker, { awaitingInput: false, workerInputMessageId: null, isTyping: true, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
         executionApi.workerInput(state.sessionId, text).catch((err: unknown) => {
           const errMsg = err instanceof Error ? err.message : String(err);
           const errorChatMsg: ChatMessage = {
@@ -1951,7 +2052,7 @@ export default function Workspace() {
 
     // If queen has a pending question widget, dismiss it when user types directly
     if (agentStates[activeWorker]?.pendingQuestionSource === "queen") {
-      updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+      updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
     }
 
     const userMsg: ChatMessage = {
@@ -2018,7 +2119,7 @@ export default function Workspace() {
     }));
 
     // Clear awaiting state optimistically
-    updateAgentState(activeWorker, { awaitingInput: false, workerInputMessageId: null, isTyping: true, pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+    updateAgentState(activeWorker, { awaitingInput: false, workerInputMessageId: null, isTyping: true, pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
 
     executionApi.workerInput(state.sessionId, text).catch((err: unknown) => {
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -2046,7 +2147,7 @@ export default function Workspace() {
 
     if (isOther) {
       // "Other" free-text → route through queen for evaluation
-      updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+      updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
       if (question && opts && state?.sessionId && state?.ready) {
         const formatted = `[Worker asked: "${question}" | Options: ${opts.join(", ")}]\nUser answered: "${answer}"`;
         const userMsg: ChatMessage = {
@@ -2092,10 +2193,23 @@ export default function Workspace() {
   // --- handleQueenQuestionAnswer: submit queen's own question answer via /chat ---
   // The queen asked the question herself, so she already has context — just send the raw answer.
   const handleQueenQuestionAnswer = useCallback((answer: string, _isOther: boolean) => {
-    updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestionSource: null });
+    updateAgentState(activeWorker, { pendingQuestion: null, pendingOptions: null, pendingQuestions: null, pendingQuestionSource: null });
     handleSend(answer, activeWorker);
   }, [activeWorker, handleSend, updateAgentState]);
 
+  // --- handleMultiQuestionAnswer: submit answers to ask_user_multiple ---
+  const handleMultiQuestionAnswer = useCallback((answers: Record<string, string>) => {
+    updateAgentState(activeWorker, {
+      pendingQuestion: null, pendingOptions: null,
+      pendingQuestions: null, pendingQuestionSource: null,
+    });
+    // Format as structured text the LLM can parse
+    const lines = Object.entries(answers).map(
+      ([id, answer]) => `[${id}]: ${answer}`,
+    );
+    handleSend(lines.join("\n"), activeWorker);
+  }, [activeWorker, handleSend, updateAgentState]);
+
   // --- handleQuestionDismiss: user closed the question widget without answering ---
   // Injects a dismiss signal so the blocked node can continue.
   const handleQuestionDismiss = useCallback(() => {
@@ -2108,6 +2222,7 @@ export default function Workspace() {
     updateAgentState(activeWorker, {
       pendingQuestion: null,
       pendingOptions: null,
+      pendingQuestions: null,
       pendingQuestionSource: null,
       awaitingInput: false,
     });
@@ -2371,18 +2486,32 @@ export default function Workspace() {
       <div className="flex flex-1 min-h-0">
 
         {/* ── Pipeline graph + chat ──────────────────────────────────── */}
-        <div className="w-[300px] min-w-[240px] bg-card/30 flex flex-col border-r border-border/30">
+        <div className={`${(activeAgentState?.queenPhase === "planning" && activeAgentState?.draftGraph) || activeAgentState?.originalDraft ? "w-[500px] min-w-[400px]" : "w-[300px] min-w-[240px]"} bg-card/30 flex flex-col border-r border-border/30 transition-[width] duration-200`}>
           <div className="flex-1 min-h-0">
-            <AgentGraph
-              nodes={currentGraph.nodes}
-              title={currentGraph.title}
-              onNodeClick={(node) => setSelectedNode(prev => prev?.id === node.id ? null : node)}
-              onRun={handleRun}
-              onPause={handlePause}
-              runState={activeAgentState?.workerRunState ?? "idle"}
-              building={activeAgentState?.queenBuilding ?? false}
-              queenPhase={activeAgentState?.queenPhase ?? "building"}
-            />
+            {activeAgentState?.queenPhase === "planning" && activeAgentState.draftGraph ? (
+              <DraftGraph draft={activeAgentState.draftGraph} />
+            ) : activeAgentState?.originalDraft ? (
+              <DraftGraph
+                draft={activeAgentState.originalDraft}
+                flowchartMap={activeAgentState.flowchartMap ?? undefined}
+                runtimeNodes={currentGraph.nodes}
+                onRuntimeNodeClick={(runtimeNodeId) => {
+                  const node = currentGraph.nodes.find(n => n.id === runtimeNodeId);
+                  if (node) setSelectedNode(prev => prev?.id === node.id ? null : node);
+                }}
+              />
+            ) : (
+              <AgentGraph
+                nodes={currentGraph.nodes}
+                title={currentGraph.title}
+                onNodeClick={(node) => setSelectedNode(prev => prev?.id === node.id ? null : node)}
+                onRun={handleRun}
+                onPause={handlePause}
+                runState={activeAgentState?.workerRunState ?? "idle"}
+                building={activeAgentState?.queenBuilding ?? false}
+                queenPhase={activeAgentState?.queenPhase ?? "building"}
+              />
+            )}
           </div>
         </div>
         <div className="flex-1 min-w-0 flex">
@@ -2454,11 +2583,13 @@ export default function Workspace() {
                 queenPhase={activeAgentState?.queenPhase ?? "building"}
                 pendingQuestion={activeAgentState?.awaitingInput ? activeAgentState.pendingQuestion : null}
                 pendingOptions={activeAgentState?.awaitingInput ? activeAgentState.pendingOptions : null}
+                pendingQuestions={activeAgentState?.awaitingInput ? activeAgentState.pendingQuestions : null}
                 onQuestionSubmit={
                   activeAgentState?.pendingQuestionSource === "queen"
                     ? handleQueenQuestionAnswer
                     : handleWorkerQuestionAnswer
                 }
+                onMultiQuestionSubmit={handleMultiQuestionAnswer}
                 onQuestionDismiss={handleQuestionDismiss}
               />
             )}
@@ -2546,7 +2677,7 @@ export default function Workspace() {
       <CredentialsModal
         agentType={activeWorker}
         agentLabel={activeWorkerLabel}
-        agentPath={credentialAgentPath || (!activeWorker.startsWith("new-agent") ? activeWorker : undefined)}
+        agentPath={credentialAgentPath || activeAgentState?.agentPath || (!activeWorker.startsWith("new-agent") ? activeWorker : undefined)}
         open={credentialsOpen}
         onClose={() => { setCredentialsOpen(false); setCredentialAgentPath(null); setDismissedBanner(null); }}
         credentials={activeSession?.credentials || []}

core/pyproject.toml

@@ -11,12 +11,10 @@ dependencies = [
   "litellm>=1.81.0",
   "mcp>=1.0.0",
   "fastmcp>=2.0.0",
-  "textual>=1.0.0",
   "tools",
 ]
 
 [project.optional-dependencies]
-tui = ["textual>=0.75.0"]
 webhook = ["aiohttp>=3.9.0"]
 server = ["aiohttp>=3.9.0"]
 testing = [

core/tests/test_chat_text_area.py

@@ -1,90 +0,0 @@
-"""Tests for ChatTextArea key handling (Enter submits, Shift+Enter / Ctrl+J insert newlines)."""
-
-import pytest
-from textual.app import App, ComposeResult
-
-from framework.tui.widgets.chat_repl import ChatTextArea
-
-
-class ChatTextAreaApp(App):
-    """Minimal app that mounts a ChatTextArea for testing."""
-
-    submitted_texts: list[str]
-
-    def compose(self) -> ComposeResult:
-        yield ChatTextArea(id="input")
-
-    def on_mount(self) -> None:
-        self.submitted_texts = []
-
-    def on_chat_text_area_submitted(self, message: ChatTextArea.Submitted) -> None:
-        self.submitted_texts.append(message.text)
-
-
-@pytest.fixture
-def app():
-    return ChatTextAreaApp()
-
-
-@pytest.mark.asyncio
-async def test_enter_submits_text(app):
-    """Pressing Enter should post a Submitted message and clear the widget."""
-    async with app.run_test() as pilot:
-        await pilot.press("h", "e", "l", "l", "o")
-        await pilot.press("enter")
-
-    assert app.submitted_texts == ["hello"]
-
-
-@pytest.mark.asyncio
-async def test_enter_on_empty_does_not_submit(app):
-    """Pressing Enter with no text should not post a Submitted message."""
-    async with app.run_test() as pilot:
-        await pilot.press("enter")
-
-    assert app.submitted_texts == []
-
-
-@pytest.mark.asyncio
-async def test_shift_enter_inserts_newline(app):
-    """Shift+Enter should insert a newline, not submit."""
-    async with app.run_test() as pilot:
-        widget = app.query_one("#input", ChatTextArea)
-
-        await pilot.press("a")
-        await pilot.press("shift+enter")
-        await pilot.press("b")
-
-    assert app.submitted_texts == []
-    assert "\n" in widget.text
-    assert widget.text.startswith("a")
-    assert widget.text.endswith("b")
-
-
-@pytest.mark.asyncio
-async def test_ctrl_j_inserts_newline(app):
-    """Ctrl+J should insert a newline (fallback for terminals without Shift+Enter)."""
-    async with app.run_test() as pilot:
-        widget = app.query_one("#input", ChatTextArea)
-
-        await pilot.press("a")
-        await pilot.press("ctrl+j")
-        await pilot.press("b")
-
-    assert app.submitted_texts == []
-    assert "\n" in widget.text
-    assert widget.text.startswith("a")
-    assert widget.text.endswith("b")
-
-
-@pytest.mark.asyncio
-async def test_multiline_submit(app):
-    """Typing multiline text via Ctrl+J then pressing Enter should submit all lines."""
-    async with app.run_test() as pilot:
-        await pilot.press("a")
-        await pilot.press("ctrl+j")
-        await pilot.press("b")
-        await pilot.press("enter")
-
-    assert len(app.submitted_texts) == 1
-    assert app.submitted_texts[0] == "a\nb"

core/tests/test_event_loop_integration.py

@@ -572,7 +572,7 @@ async def test_event_loop_conversation_compaction():
     judge = CountingJudge(retry_count=3)
     node = EventLoopNode(
         judge=judge,
-        config=LoopConfig(max_iterations=10, max_history_tokens=200),
+        config=LoopConfig(max_iterations=10, max_context_tokens=200),
     )
     result = await node.execute(ctx)
 

core/tests/test_mcp_server.py

@@ -40,16 +40,3 @@ class TestMCPDependencies:
         from mcp.server import FastMCP
 
         assert FastMCP is not None
-
-
-class TestMCPPackageExports:
-    """Tests for the framework.mcp package exports."""
-
-    def test_package_importable(self):
-        """Test that framework.mcp package can be imported."""
-        if not MCP_AVAILABLE:
-            pytest.skip(MCP_SKIP_REASON)
-
-        import framework.mcp
-
-        assert framework.mcp is not None

core/tests/test_node_conversation.py

@@ -204,8 +204,8 @@ class TestNodeConversation:
 
     @pytest.mark.asyncio
     async def test_usage_ratio(self):
-        """usage_ratio returns estimate / max_history_tokens."""
-        conv = NodeConversation(max_history_tokens=1000)
+        """usage_ratio returns estimate / max_context_tokens."""
+        conv = NodeConversation(max_context_tokens=1000)
         await conv.add_user_message("a" * 400)
         assert conv.usage_ratio() == pytest.approx(0.1)  # 100/1000
 
@@ -214,15 +214,15 @@ class TestNodeConversation:
 
     @pytest.mark.asyncio
     async def test_usage_ratio_zero_budget(self):
-        """usage_ratio returns 0 when max_history_tokens is 0 (unlimited)."""
-        conv = NodeConversation(max_history_tokens=0)
+        """usage_ratio returns 0 when max_context_tokens is 0 (unlimited)."""
+        conv = NodeConversation(max_context_tokens=0)
         await conv.add_user_message("a" * 400)
         assert conv.usage_ratio() == 0.0
 
     @pytest.mark.asyncio
     async def test_needs_compaction_with_actual_tokens(self):
         """needs_compaction uses actual API token count when available."""
-        conv = NodeConversation(max_history_tokens=1000, compaction_threshold=0.8)
+        conv = NodeConversation(max_context_tokens=1000, compaction_threshold=0.8)
         await conv.add_user_message("a" * 100)  # chars/4 = 25, well under 800
 
         assert conv.needs_compaction() is False
@@ -233,7 +233,7 @@ class TestNodeConversation:
 
     @pytest.mark.asyncio
     async def test_needs_compaction(self):
-        conv = NodeConversation(max_history_tokens=100, compaction_threshold=0.8)
+        conv = NodeConversation(max_context_tokens=100, compaction_threshold=0.8)
         await conv.add_user_message("x" * 320)
         assert conv.needs_compaction() is True
 
@@ -457,7 +457,7 @@ class TestPersistence:
         store = MockConversationStore()
         assert await NodeConversation.restore(store) is None
 
-        conv = NodeConversation(system_prompt="hello", max_history_tokens=500, store=store)
+        conv = NodeConversation(system_prompt="hello", max_context_tokens=500, store=store)
         await conv.add_user_message("u1")
         await conv.add_assistant_message("a1")
 
@@ -643,7 +643,7 @@ class TestConversationIntegration:
         store = FileConversationStore(base)
         conv = NodeConversation(
             system_prompt="You are a helpful travel agent.",
-            max_history_tokens=16000,
+            max_context_tokens=16000,
             store=store,
         )
 
@@ -1314,7 +1314,7 @@ class TestLlmCompact:
         """Create a minimal EventLoopNode for testing."""
         from framework.graph.event_loop_node import EventLoopNode, LoopConfig
 
-        config = LoopConfig(max_history_tokens=32000)
+        config = LoopConfig(max_context_tokens=32000)
         node = EventLoopNode.__new__(EventLoopNode)
         node._config = config
         node._event_bus = None

core/tests/test_subagent.py

@@ -970,13 +970,13 @@ class TestEscalationFlow:
         )
 
     @pytest.mark.asyncio
-    async def test_wait_for_response_emits_client_events(
+    async def test_wait_for_response_emits_escalation_event(
         self,
         runtime,
         parent_node_spec,
         subagent_node_spec,
     ):
-        """Escalation should emit CLIENT_OUTPUT_DELTA and CLIENT_INPUT_REQUESTED events."""
+        """Escalation should emit ESCALATION_REQUESTED to the queen."""
         from framework.graph.event_loop_node import _EscalationReceiver
 
         bus = EventBus()
@@ -986,7 +986,7 @@ class TestEscalationFlow:
             bus_events.append(event)
 
         bus.subscribe(
-            event_types=[EventType.CLIENT_OUTPUT_DELTA, EventType.CLIENT_INPUT_REQUESTED],
+            event_types=[EventType.ESCALATION_REQUESTED],
             handler=handler,
         )
 
@@ -1034,16 +1034,12 @@ class TestEscalationFlow:
         await node._execute_subagent(ctx, "researcher", "Navigate page with CAPTCHA")
         await injector
 
-        # Should have emitted both events
-        output_deltas = [e for e in bus_events if e.type == EventType.CLIENT_OUTPUT_DELTA]
-        input_requests = [e for e in bus_events if e.type == EventType.CLIENT_INPUT_REQUESTED]
+        # Should have emitted ESCALATION_REQUESTED
+        escalation_events = [e for e in bus_events if e.type == EventType.ESCALATION_REQUESTED]
 
-        assert len(output_deltas) >= 1, "Should emit CLIENT_OUTPUT_DELTA with the message"
-        assert output_deltas[0].data["content"] == "CAPTCHA detected on page"
-        assert output_deltas[0].node_id == "parent"  # Shows as parent talking
-
-        assert len(input_requests) >= 1, "Should emit CLIENT_INPUT_REQUESTED for routing"
-        assert ":escalation:" in input_requests[0].node_id  # Escalation ID for routing
+        assert len(escalation_events) >= 1, "Should emit ESCALATION_REQUESTED"
+        assert escalation_events[0].data["context"] == "CAPTCHA detected on page"
+        assert ":escalation:" in escalation_events[0].node_id
 
     @pytest.mark.asyncio
     async def test_non_blocking_report_still_works(

core/tests/test_subagent_escalation_e2e.py

@@ -3,9 +3,8 @@
 Tests the FULL routing chain:
   ExecutionStream → GraphExecutor → EventLoopNode → _execute_subagent
   → _report_callback registers _EscalationReceiver in executor.node_registry
-  → emit CLIENT_INPUT_REQUESTED with escalation_id
-  → subscriber calls stream.inject_input(escalation_id, "done")
-  → ExecutionStream finds _EscalationReceiver in executor.node_registry
+  → emit ESCALATION_REQUESTED (queen handles the escalation)
+  → queen inject_worker_message() finds _EscalationReceiver via get_waiting_nodes()
   → receiver.inject_event("done") unblocks the subagent
   → subagent continues and completes
 """
@@ -227,26 +226,30 @@ async def test_escalation_e2e_through_execution_stream(tmp_path):
     stream_holder: list[ExecutionStream] = []
 
     async def escalation_handler(event: AgentEvent):
-        """Simulate a TUI/runner: when CLIENT_INPUT_REQUESTED arrives with
-        an escalation node_id, inject the user's response via the stream."""
+        """Simulate the queen: when ESCALATION_REQUESTED arrives,
+        find the waiting receiver and inject the response via the stream."""
         all_events.append(event)
-        if event.type == EventType.CLIENT_INPUT_REQUESTED:
-            node_id = event.node_id
-            if ":escalation:" in node_id:
-                escalation_events.append(event)
-                # Small delay to simulate user typing
-                await asyncio.sleep(0.05)
-                # Route through the REAL inject_input chain
-                stream = stream_holder[0]
-                success = await stream.inject_input(node_id, "done logging in")
-                assert success, (
-                    f"inject_input({node_id!r}) returned False — "
-                    "escalation receiver not found in executor.node_registry"
-                )
-                inject_called.set()
+        if event.type == EventType.ESCALATION_REQUESTED:
+            escalation_events.append(event)
+            # Small delay to simulate queen processing
+            await asyncio.sleep(0.05)
+            # Route through the REAL inject_input chain — find the waiting
+            # escalation receiver via get_waiting_nodes() (mirrors what
+            # inject_worker_message does in the queen lifecycle tools).
+            stream = stream_holder[0]
+            waiting = stream.get_waiting_nodes()
+            assert waiting, "Should have a waiting escalation receiver"
+            target_node_id = waiting[0]["node_id"]
+            assert ":escalation:" in target_node_id
+            success = await stream.inject_input(target_node_id, "done logging in")
+            assert success, (
+                f"inject_input({target_node_id!r}) returned False — "
+                "escalation receiver not found in executor.node_registry"
+            )
+            inject_called.set()
 
     bus.subscribe(
-        event_types=[EventType.CLIENT_INPUT_REQUESTED, EventType.CLIENT_OUTPUT_DELTA],
+        event_types=[EventType.ESCALATION_REQUESTED],
         handler=escalation_handler,
     )
 
@@ -297,17 +300,7 @@ async def test_escalation_e2e_through_execution_stream(tmp_path):
     # 3. Escalation event has correct structure
     esc_event = escalation_events[0]
     assert ":escalation:" in esc_event.node_id
-    assert esc_event.data["prompt"] == "Login required for LinkedIn. Please log in manually."
-
-    # 4. CLIENT_OUTPUT_DELTA was emitted for the escalation message
-    output_deltas = [
-        e
-        for e in all_events
-        if e.type == EventType.CLIENT_OUTPUT_DELTA and "Login required" in e.data.get("content", "")
-    ]
-    assert len(output_deltas) >= 1, (
-        "Should have emitted CLIENT_OUTPUT_DELTA with escalation message"
-    )
+    assert esc_event.data["context"] == "Login required for LinkedIn. Please log in manually."
 
     # 5. The parent node got the subagent's result
     assert "result" in result.output
@@ -444,7 +437,7 @@ async def test_escalation_cleanup_after_completion(tmp_path):
     stream_holder: list[ExecutionStream] = []
 
     async def auto_respond(event: AgentEvent):
-        if event.type == EventType.CLIENT_INPUT_REQUESTED and ":escalation:" in event.node_id:
+        if event.type == EventType.ESCALATION_REQUESTED:
             stream = stream_holder[0]
 
             # Snapshot the active executor's node_registry BEFORE responding
@@ -462,10 +455,13 @@ async def test_escalation_cleanup_after_completion(tmp_path):
                 )
 
             await asyncio.sleep(0.02)
-            await stream.inject_input(event.node_id, "ok")
+            # Find the waiting escalation receiver and inject response
+            waiting = stream.get_waiting_nodes()
+            if waiting:
+                await stream.inject_input(waiting[0]["node_id"], "ok")
 
     bus.subscribe(
-        event_types=[EventType.CLIENT_INPUT_REQUESTED],
+        event_types=[EventType.ESCALATION_REQUESTED],
         handler=auto_respond,
     )
 

docs/configuration.md

@@ -172,7 +172,7 @@ Add to `.vscode/settings.json`:
 ## Security Best Practices
 
 1. **Never commit API keys** - Use environment variables or `.env` files
-2. **`.env` is git-ignored** - Copy `.env.example` to `.env` at the project root and fill in your values
+2. **If you use a local `.env` file, keep it private** - This repository does not include a root `.env.example`; use your own local `.env` file or shell environment variables for secrets
 3. **Use real provider keys in non-production environments** - validate configuration with low-risk inputs before production rollout
 4. **Credential isolation** - Each tool validates its own credentials at runtime
 

docs/draft-flowchart-schema.md

@@ -0,0 +1,597 @@
+# Draft Flowchart System — Complete Reference
+
+The draft flowchart system bridges user-facing workflow design (planning phase) and the runtime agent graph (execution phase). During planning, the queen agent creates an ISO 5807 flowchart that the user reviews. On approval, decision nodes are dissolved into runtime-compatible structures, and the original flowchart is preserved for live status overlay during execution.
+
+---
+
+## Architecture Overview
+
+```
+Planning Phase                    Build Gate                     Runtime Phase
+─────────────────────────────────────────────────────────────────────────────
+
+Queen LLM                      confirm_and_build()              Graph Executor
+    │                                │                               │
+    ▼                                ▼                               ▼
+save_agent_draft()        ┌──────────────────────┐          Node execution
+    │                     │ dissolve_decision_nodes│          with status
+    ▼                     │                        │               │
+DraftGraph (SSE) ────►    │  Decision diamonds     │               ▼
+    │                     │  merged into           │          Flowchart Map
+    ▼                     │  predecessor criteria   │          inverts to
+Frontend renders          │                        │          overlay status
+ISO 5807 flowchart        │  Original draft        │          on original
+with diamond              │  preserved             │          flowchart
+decisions                 │                        │
+                          └──────────────────────┘
+```
+
+**Key files:**
+- Backend: `core/framework/tools/queen_lifecycle_tools.py` — draft creation, classification, dissolution
+- Backend: `core/framework/server/routes_graphs.py` — REST endpoints
+- Frontend: `core/frontend/src/components/DraftGraph.tsx` — SVG flowchart renderer
+- Frontend: `core/frontend/src/api/types.ts` — TypeScript interfaces
+- Frontend: `core/frontend/src/pages/workspace.tsx` — state management and conditional rendering
+
+---
+
+## 1. JSON Schemas
+
+### Tool: `save_agent_draft` — Input Schema
+
+```json
+{
+  "type": "object",
+  "required": ["agent_name", "goal", "nodes"],
+  "properties": {
+    "agent_name": {
+      "type": "string",
+      "description": "Snake_case name for the agent (e.g. 'lead_router_agent')"
+    },
+    "goal": {
+      "type": "string",
+      "description": "High-level goal description for the agent"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of what the agent does"
+    },
+    "nodes": {
+      "type": "array",
+      "description": "Graph nodes. Only 'id' is required; all other fields are optional hints.",
+      "items": { "$ref": "#/$defs/DraftNode" }
+    },
+    "edges": {
+      "type": "array",
+      "description": "Connections between nodes. Auto-generated as linear if omitted.",
+      "items": { "$ref": "#/$defs/DraftEdge" }
+    },
+    "terminal_nodes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Node IDs that are terminal (end) nodes. Auto-detected from edges if omitted."
+    },
+    "success_criteria": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Agent-level success criteria"
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Agent-level constraints"
+    }
+  }
+}
+```
+
+### Node Schema (`DraftNode`)
+
+```json
+{
+  "type": "object",
+  "required": ["id"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Kebab-case node identifier (e.g. 'enrich-lead')"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable display name. Defaults to id if omitted."
+    },
+    "description": {
+      "type": "string",
+      "description": "What this node does (business logic). Used for auto-classification."
+    },
+    "node_type": {
+      "type": "string",
+      "enum": ["event_loop", "gcu"],
+      "default": "event_loop",
+      "description": "Runtime node type. 'gcu' maps to browser automation."
+    },
+    "flowchart_type": {
+      "type": "string",
+      "enum": [
+        "start", "terminal", "process", "decision",
+        "io", "document", "multi_document",
+        "subprocess", "preparation",
+        "manual_input", "manual_operation",
+        "delay", "display",
+        "database", "stored_data", "internal_storage",
+        "connector", "offpage_connector",
+        "merge", "extract", "sort", "collate",
+        "summing_junction", "or",
+        "browser", "comment", "alternate_process"
+      ],
+      "description": "ISO 5807 flowchart symbol. Auto-detected if omitted."
+    },
+    "tools": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Planned tool names (hints for scaffolder, not validated)"
+    },
+    "input_keys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Expected input memory keys"
+    },
+    "output_keys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Expected output memory keys"
+    },
+    "success_criteria": {
+      "type": "string",
+      "description": "What success looks like for this node"
+    },
+    "decision_clause": {
+      "type": "string",
+      "description": "For decision nodes only: the yes/no question to evaluate (e.g. 'Is amount > $100?'). During dissolution, this becomes the predecessor node's success_criteria."
+    }
+  }
+}
+```
+
+### Edge Schema (`DraftEdge`)
+
+```json
+{
+  "type": "object",
+  "required": ["source", "target"],
+  "properties": {
+    "source": {
+      "type": "string",
+      "description": "Source node ID"
+    },
+    "target": {
+      "type": "string",
+      "description": "Target node ID"
+    },
+    "condition": {
+      "type": "string",
+      "enum": ["always", "on_success", "on_failure", "conditional", "llm_decide"],
+      "default": "on_success",
+      "description": "Edge traversal condition"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of when this edge is taken"
+    },
+    "label": {
+      "type": "string",
+      "description": "Short label shown on the flowchart edge (e.g. 'Yes', 'No', 'Retry')"
+    }
+  }
+}
+```
+
+### Output: Enriched Draft Graph Object
+
+After `save_agent_draft` processes the input, it stores and emits an enriched draft with auto-classified flowchart metadata. This is the structure sent via the `draft_graph_updated` SSE event and returned by `GET /api/sessions/{id}/draft-graph`.
+
+```json
+{
+  "agent_name": "lead_router_agent",
+  "goal": "Enrich and route incoming leads",
+  "description": "Automated lead enrichment and routing agent",
+  "success_criteria": ["Lead score calculated", "Correct tier assigned"],
+  "constraints": ["Apollo enrichment required before routing"],
+  "entry_node": "intake",
+  "terminal_nodes": ["route"],
+  "nodes": [
+    {
+      "id": "intake",
+      "name": "Intake",
+      "description": "Fetch contact from HubSpot",
+      "node_type": "event_loop",
+      "tools": ["hubspot_get_contact"],
+      "input_keys": ["contact_id"],
+      "output_keys": ["contact_data", "domain"],
+      "success_criteria": "Contact data retrieved",
+      "decision_clause": "",
+      "sub_agents": [],
+      "flowchart_type": "start",
+      "flowchart_shape": "stadium",
+      "flowchart_color": "#4CAF50"
+    },
+    {
+      "id": "check-tier",
+      "name": "Check Tier",
+      "description": "",
+      "node_type": "event_loop",
+      "decision_clause": "Is lead score > 80?",
+      "flowchart_type": "decision",
+      "flowchart_shape": "diamond",
+      "flowchart_color": "#FF9800"
+    }
+  ],
+  "edges": [
+    {
+      "id": "edge-0",
+      "source": "intake",
+      "target": "check-tier",
+      "condition": "on_success",
+      "description": "",
+      "label": ""
+    },
+    {
+      "id": "edge-1",
+      "source": "check-tier",
+      "target": "enrich",
+      "condition": "on_success",
+      "description": "",
+      "label": "Yes"
+    },
+    {
+      "id": "edge-2",
+      "source": "check-tier",
+      "target": "route",
+      "condition": "on_failure",
+      "description": "",
+      "label": "No"
+    }
+  ],
+  "flowchart_legend": {
+    "start":    { "shape": "stadium",    "color": "#4CAF50" },
+    "terminal": { "shape": "stadium",    "color": "#F44336" },
+    "process":  { "shape": "rectangle",  "color": "#2196F3" },
+    "decision": { "shape": "diamond",    "color": "#FF9800" }
+  }
+}
+```
+
+**Enriched fields** (added by backend to every node during classification):
+
+| Field | Type | Description |
+|---|---|---|
+| `flowchart_type` | `string` | The resolved ISO 5807 symbol type |
+| `flowchart_shape` | `string` | SVG shape identifier for the frontend renderer |
+| `flowchart_color` | `string` | Hex color code for the symbol |
+
+### Flowchart Map Object
+
+Returned by `GET /api/sessions/{id}/flowchart-map` after `confirm_and_build()` dissolves decision nodes:
+
+```json
+{
+  "map": {
+    "intake": ["intake", "check-tier"],
+    "enrich": ["enrich"],
+    "route": ["route"]
+  },
+  "original_draft": { "...original draft graph before dissolution..." }
+}
+```
+
+- `map`: Keys are runtime node IDs, values are lists of original draft node IDs that the runtime node absorbed.
+- `original_draft`: The complete draft graph as it existed before dissolution, preserved for flowchart display.
+- Both fields are `null` if no dissolution has occurred yet.
+
+---
+
+## 2. ISO 5807 Flowchart Types
+
+### Core Symbols
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `start` | stadium | `#4CAF50` green | `<rect rx={h/2}>` | Entry point / start terminator |
+| `terminal` | stadium | `#F44336` red | `<rect rx={h/2}>` | End point / stop terminator |
+| `process` | rectangle | `#2196F3` blue | `<rect rx={4}>` | General processing step |
+| `decision` | diamond | `#FF9800` amber | `<polygon>` 4-point | Branching / conditional logic |
+| `io` | parallelogram | `#9C27B0` purple | `<polygon>` skewed | Data input or output |
+| `document` | document | `#607D8B` blue-grey | `<path>` wavy bottom | Single document output |
+| `multi_document` | multi_document | `#78909C` blue-grey | stacked `<rect>` + `<path>` | Multiple documents |
+| `subprocess` | subroutine | `#009688` teal | `<rect>` + inner `<line>` | Predefined process / sub-agent |
+| `preparation` | hexagon | `#795548` brown | `<polygon>` 6-point | Setup / initialization step |
+| `manual_input` | manual_input | `#E91E63` pink | `<polygon>` sloped top | Manual data entry |
+| `manual_operation` | trapezoid | `#AD1457` dark pink | `<polygon>` tapered bottom | Human-in-the-loop / approval |
+| `delay` | delay | `#FF5722` deep orange | `<path>` D-shape | Wait / pause / cooldown |
+| `display` | display | `#00BCD4` cyan | `<path>` pointed left | Display / render output |
+
+### Data Storage Symbols
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `database` | cylinder | `#8BC34A` light green | `<path>` + `<ellipse>` top/bottom | Database / direct access storage |
+| `stored_data` | stored_data | `#CDDC39` lime | `<path>` curved left | Generic data store |
+| `internal_storage` | internal_storage | `#FFC107` amber | `<rect>` + internal `<line>` grid | Internal memory / cache |
+
+### Connectors
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `connector` | circle | `#9E9E9E` grey | `<circle>` | On-page connector |
+| `offpage_connector` | pentagon | `#757575` dark grey | `<polygon>` 5-point | Off-page connector |
+
+### Flow Operations
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `merge` | triangle_inv | `#3F51B5` indigo | `<polygon>` inverted | Merge multiple flows |
+| `extract` | triangle | `#5C6BC0` indigo light | `<polygon>` upward | Extract / split flow |
+| `sort` | hourglass | `#7986CB` indigo lighter | `<polygon>` X-shape | Sort operation |
+| `collate` | hourglass_inv | `#9FA8DA` indigo lightest | `<polygon>` X-shape inv | Collate operation |
+| `summing_junction` | circle_cross | `#F06292` pink light | `<circle>` + cross `<line>` | Summing junction |
+| `or` | circle_bar | `#CE93D8` purple light | `<circle>` + plus `<line>` | Logical OR |
+
+### Domain-Specific (Hive)
+
+| Type | Shape | Color | SVG Primitive | Description |
+|---|---|---|---|---|
+| `browser` | hexagon | `#1A237E` dark indigo | `<polygon>` 6-point | Browser automation (GCU node) |
+| `comment` | flag | `#BDBDBD` light grey | `<path>` notched right | Annotation / comment |
+| `alternate_process` | rounded_rect | `#42A5F5` light blue | `<rect rx={12}>` | Alternate process variant |
+
+---
+
+## 3. Auto-Classification Priority
+
+When `flowchart_type` is omitted from a node, the backend classifies it automatically using this priority (function `_classify_flowchart_node` in `queen_lifecycle_tools.py`):
+
+1. **Explicit override** — if `flowchart_type` is set and valid, use it
+2. **Node type** — `gcu` nodes become `browser`
+3. **Position** — first node becomes `start`
+4. **Terminal detection** — nodes in `terminal_nodes` (or with no outgoing edges) become `terminal`
+5. **Branching structure** — nodes with 2+ outgoing edges with different conditions become `decision`
+6. **Sub-agents** — nodes with `sub_agents` become `subprocess`
+7. **Tool heuristics** — tool names match known patterns:
+   - DB tools (`query_database`, `sql_query`, `read_table`, etc.) → `database`
+   - Doc tools (`generate_report`, `create_document`, etc.) → `document`
+   - I/O tools (`send_email`, `post_to_slack`, `fetch_url`, etc.) → `io`
+   - Display tools (`serve_file_to_user`, `display_results`) → `display`
+8. **Description keyword heuristics**:
+   - `"manual"`, `"approval"`, `"human review"` → `manual_operation`
+   - `"setup"`, `"prepare"`, `"configure"` → `preparation`
+   - `"wait"`, `"delay"`, `"pause"` → `delay`
+   - `"merge"`, `"combine"`, `"aggregate"` → `merge`
+   - `"display"`, `"show"`, `"render"` → `display`
+   - `"database"`, `"data store"`, `"persist"` → `database`
+   - `"report"`, `"document"`, `"summary"` → `document`
+   - `"deliver"`, `"send"`, `"notify"` → `io`
+9. **Default** — `process` (blue rectangle)
+
+---
+
+## 4. Decision Node Dissolution
+
+When `confirm_and_build()` is called, decision nodes (flowchart diamonds) are dissolved into runtime-compatible structures by `_dissolve_decision_nodes()`. Decision nodes are a **planning-only** concept — they don't exist in the runtime graph.
+
+### Algorithm
+
+```
+For each decision node D (in topological order):
+  1. Find predecessors P via incoming edges
+  2. Find yes-target and no-target via outgoing edges
+     - Yes: edge with label "Yes"/"True"/"Pass" or condition "on_success"
+     - No:  edge with label "No"/"False"/"Fail" or condition "on_failure"
+     - Fallback: first outgoing = yes, second = no
+  3. Get decision clause: D.decision_clause || D.description || D.name
+  4. For each predecessor P:
+     - Append clause to P.success_criteria
+     - Remove edge P → D
+     - Add edge P → yes_target (on_success)
+     - Add edge P → no_target (on_failure)
+  5. Remove D and all its edges from the graph
+  6. Record absorption: flowchart_map[P.id] = [P.id, D.id]
+```
+
+### Edge Cases
+
+| Case | Behavior |
+|---|---|
+| **Decision at start** (no predecessor) | Converted to a process node with `success_criteria` = clause; outgoing edges rewired to `on_success`/`on_failure` |
+| **Chained decisions** (A → D1 → D2 → B) | Processed in order. D1 dissolves into A. D2's predecessor is now A, so D2 also dissolves into A. Map: `A → [A, D1, D2]` |
+| **Multiple predecessors** | Each predecessor gets its own copy of the yes/no edges |
+| **Existing success_criteria on predecessor** | Appended with `"; then evaluate: <clause>"` |
+| **Decision with >2 outgoing edges** | First classified yes/no pair is used; remaining edges are preserved |
+
+### Example
+
+**Input (planning flowchart):**
+```
+[Fetch Billing Data] → <Amount > $100?> → Yes → [Generate PDF Receipt]
+                                         → No  → [Draft Email Receipt]
+```
+
+**Output (runtime graph):**
+```
+[Fetch Billing Data] → on_success → [Generate PDF Receipt]
+                     → on_failure → [Draft Email Receipt]
+  success_criteria: "Amount > $100?"
+```
+
+**Flowchart map:**
+```json
+{
+  "fetch-billing-data": ["fetch-billing-data", "amount-gt-100"],
+  "generate-pdf-receipt": ["generate-pdf-receipt"],
+  "draft-email-receipt": ["draft-email-receipt"]
+}
+```
+
+The runtime Level 2 judge evaluates the decision clause against the node's conversation. `NodeResult.success = true` routes via `on_success` (yes), `false` routes via `on_failure` (no).
+
+---
+
+## 5. Frontend Rendering
+
+### Component: `DraftGraph.tsx`
+
+An SVG-based flowchart renderer that operates in two modes:
+
+1. **Planning mode** — renders the draft graph with ISO 5807 shapes during the planning phase
+2. **Runtime overlay mode** — renders the original (pre-dissolution) draft with live execution status when `flowchartMap` and `runtimeNodes` props are provided
+
+#### Props
+
+```typescript
+interface DraftGraphProps {
+  draft: DraftGraphData;                          // The draft graph to render
+  onNodeClick?: (node: DraftNode) => void;        // Node click handler
+  flowchartMap?: Record<string, string[]>;         // Runtime → draft node mapping
+  runtimeNodes?: GraphNode[];                      // Live runtime graph nodes with status
+}
+```
+
+#### Layout Engine
+
+The layout algorithm arranges nodes in layers based on graph topology:
+
+1. **Layer assignment**: Each node's layer = max(parent layers) + 1. Root nodes are layer 0.
+2. **Column assignment**: Within each layer, nodes are sorted by parent column average and centered.
+3. **Node sizing**: `nodeW = min(360, availableWidth / maxColumns)` — nodes fill available space up to 360px.
+4. **Container measurement**: A `ResizeObserver` measures the actual container width so SVG viewBox coordinates match CSS pixels 1:1.
+
+```
+Constants:
+  NODE_H   = 52px    (node height)
+  GAP_Y    = 48px    (vertical gap between layers)
+  GAP_X    = 16px    (horizontal gap between columns)
+  MARGIN_X = 16px    (left/right margin)
+  TOP_Y    = 28px    (top padding)
+```
+
+#### Shape Rendering
+
+The `FlowchartShape` component renders each ISO 5807 shape as SVG primitives. Each shape receives:
+- `x, y, w, h` — bounding box in SVG units
+- `color` — the hex color from the flowchart type
+- `selected` — hover state (increases fill opacity from 18% to 28%, brightens stroke)
+
+All shapes use `strokeWidth={1.2}` to prevent overflow on hover.
+
+#### Edge Rendering
+
+**Forward edges** (source layer < target layer):
+- Rendered as cubic bezier curves from source bottom-center to target top-center
+- Fan-out: when a node has multiple outgoing edges, start points spread across 40% of node width
+- Labels shown at the midpoint (from `edge.label`, or condition/description fallback)
+
+**Back edges** (source layer >= target layer):
+- Rendered as dashed arcs that loop right of the graph
+- Each back edge gets a unique offset to prevent overlap
+
+#### Node Labels
+
+Each node displays two lines of text:
+- **Primary**: Node name (font size 13, truncated to fit `nodeW - 28px`)
+- **Secondary**: Node description or flowchart type (font size 9.5, truncated to fit `nodeW - 24px`)
+
+Truncation uses `avgCharWidth = fontSize * 0.58` to estimate available characters.
+
+#### Tooltip
+
+An HTML overlay (not SVG) positioned below hovered nodes, showing:
+- Node description
+- Tools list (`Tools: tool_a, tool_b`)
+- Success criteria (`Criteria: ...`)
+
+#### Legend
+
+A dynamic legend at the bottom of the SVG listing all flowchart types used in the current draft, with their shape and color.
+
+### Runtime Status Overlay
+
+When `flowchartMap` and `runtimeNodes` are provided, the component computes per-node statuses:
+
+1. **Invert the map**: `flowchartMap` maps `runtime_id → [draft_ids]`; inversion gives `draft_id → runtime_id`
+2. **Map runtime status**: For each runtime node, classify status as `running` (amber), `complete` (green), `error` (red), or `pending` (no overlay)
+3. **Render overlays**:
+   - **Glow ring**: A pulsing amber `<rect>` around running nodes, solid green/red for complete/error
+   - **Status dot**: A small `<circle>` in the top-right corner with animated radius for running nodes
+4. **Header**: Changes from "Draft / planning" to "Flowchart / live"
+
+```typescript
+// Status color mapping
+const STATUS_COLORS = {
+  running:  "#F59E0B",  // amber — pulsing glow
+  complete: "#22C55E",  // green — solid ring
+  error:    "#EF4444",  // red   — solid ring
+  pending:  "",         // no overlay
+};
+```
+
+### Workspace Integration (`workspace.tsx`)
+
+The workspace conditionally renders `DraftGraph` in three scenarios:
+
+| Condition | Renders | Panel Width |
+|---|---|---|
+| `queenPhase === "planning"` and `draftGraph` exists | `<DraftGraph draft={draftGraph} />` | 500px |
+| `originalDraft` exists (post-planning) | `<DraftGraph draft={originalDraft} flowchartMap={...} runtimeNodes={...} />` | 500px |
+| Neither | `<AgentGraph ... />` (runtime pipeline view) | 300px |
+
+**State management:**
+- `draftGraph`: Set by `draft_graph_updated` SSE event during planning; cleared on phase change
+- `originalDraft` + `flowchartMap`: Fetched from `GET /api/sessions/{id}/flowchart-map` when phase transitions away from planning
+
+---
+
+## 6. Events & API
+
+### SSE Event: `draft_graph_updated`
+
+Emitted when `save_agent_draft` completes. The full draft graph object is the event `data` payload.
+
+```
+event: message
+data: {"type": "draft_graph_updated", "stream_id": "queen", "data": { ...draft graph object... }, ...}
+```
+
+### REST Endpoints
+
+**`GET /api/sessions/{session_id}/draft-graph`**
+
+Returns the current draft graph from planning phase.
+```json
+{"draft": <DraftGraph object>}
+// or
+{"draft": null}
+```
+
+**`GET /api/sessions/{session_id}/flowchart-map`**
+
+Returns the flowchart-to-runtime mapping and original draft (available after `confirm_and_build()`).
+```json
+{
+  "map": { "runtime-node-id": ["draft-node-a", "draft-node-b"], ... },
+  "original_draft": { ...original DraftGraph before dissolution... }
+}
+// or
+{"map": null, "original_draft": null}
+```
+
+---
+
+## 7. Phase Gate
+
+The draft graph is part of a two-step gate controlling the planning → building transition:
+
+1. **`save_agent_draft()`** — creates the draft, classifies nodes, emits `draft_graph_updated`
+2. User reviews the rendered flowchart (with decision diamonds, edge labels, color-coded shapes)
+3. **`confirm_and_build()`** — dissolves decision nodes, preserves original draft, builds flowchart map, sets `build_confirmed = true`
+4. **`initialize_and_build_agent()`** — checks `build_confirmed` before proceeding; passes the dissolved (decision-free) draft to the scaffolder for pre-population
+
+The scaffolder never sees decision nodes — it receives a clean graph with only runtime-compatible node types where branching is expressed through `success_criteria` + `on_success`/`on_failure` edges.

docs/roadmap.md

@@ -312,11 +312,11 @@ Ship essential framework utilities: Node validation, HITL (Human-in-the-loop pau
     - [x] Pause/approve workflow
     - [x] State saved to checkpoint
     - [x] Resume with HITLResponse merged into context
-- [x] **TUI Integration**
-    - [x] Chat REPL with streaming support (tui/app.py)
-    - [x] Multi-graph session management
-    - [x] User presence detection
-    - [x] Real-time log viewing
+- [x] ~~**TUI Integration**~~ *(deprecated — see AGENTS.md; use `hive open` browser UI instead)*
+    - [x] ~~Chat REPL with streaming support (tui/app.py)~~
+    - [x] ~~Multi-graph session management~~
+    - [x] ~~User presence detection~~
+    - [x] ~~Real-time log viewing~~
 - [x] **Node Lifecycle Management**
     - [x] Start/stop/pause/resume in execution stream
     - [x] State persistence via checkpoint store
@@ -538,11 +538,11 @@ Release CLI tools specifically for rapid memory management and credential store
     - [x] test-run, test-debug, test-list, test-stats (testing/cli.py)
     - [x] Pytest integration
     - [x] Test categorization
-- [x] **TUI (Terminal UI)**
-    - [x] Interactive chat with streaming (tui/app.py)
-    - [x] Multi-graph management UI
-    - [x] Log pane for real-time output
-    - [x] Keyboard shortcuts (Ctrl+C, Ctrl+D, etc.)
+- [x] ~~**TUI (Terminal UI)**~~ *(deprecated — see AGENTS.md; use `hive open` browser UI instead)*
+    - [x] ~~Interactive chat with streaming (tui/app.py)~~
+    - [x] ~~Multi-graph management UI~~
+    - [x] ~~Log pane for real-time output~~
+    - [x] ~~Keyboard shortcuts (Ctrl+C, Ctrl+D, etc.)~~
 - [ ] **Memory Management CLI**
     - [ ] Memory inspection commands
     - [ ] Memory cleanup utilities
@@ -776,12 +776,14 @@ Implement an interactive, drag-and-drop canvas (using libraries like React Flow)
 ### TUI to GUI Upgrade
 Port the existing Terminal User Interface (TUI) into a rich web application, allowing users to interact directly with the Queen Bee / Coding Agent via a browser chat interface.
 
-- [x] **TUI Foundation**
-    - [x] Terminal chat interface (tui/app.py)
-    - [x] Streaming support
-    - [x] Multi-graph management
-    - [x] Log pane display
-    - [x] Keyboard shortcuts
+> **Note:** The TUI (`hive tui` / `tui/app.py`) is deprecated and no longer maintained (see AGENTS.md). The items below reflect legacy work completed before deprecation. New development should target the browser-based GUI (`hive open`).
+
+- [x] ~~**TUI Foundation**~~ *(deprecated)*
+    - [x] ~~Terminal chat interface (tui/app.py)~~
+    - [x] ~~Streaming support~~
+    - [x] ~~Multi-graph management~~
+    - [x] ~~Log pane display~~
+    - [x] ~~Keyboard shortcuts~~
 - [ ] **Web Application**
     - [ ] Modern web UI framework setup (React/Vue/Svelte)
     - [ ] Responsive design implementation

examples/recipes/README.md

@@ -1,54 +0,0 @@
-# Recipes
-
-A recipe describes an agent's design — the goal, nodes, prompts, edge logic, and tools — without providing runnable code. Think of it as a blueprint: it tells you *how* to build the agent, but you do the building.
-
-## What's in a recipe
-
-Each recipe is a markdown file (or folder with a markdown file) containing:
-
-- **Goal**: What the agent accomplishes, including success criteria and constraints
-- **Nodes**: Each step in the workflow, with the system prompt, node type, and input/output keys
-- **Edges**: How nodes connect, including conditions and routing logic
-- **Tools**: What external tools or MCP servers the agent needs
-- **Usage notes**: Tips, gotchas, and suggested variations
-
-## How to use a recipe
-
-1. Read through the recipe to understand the design
-2. Create a new agent using the standard export structure (see [templates/](../templates/) for a scaffold)
-3. Translate the recipe's goal, nodes, and edges into code
-4. Wire in the tools described
-5. Test and iterate
-
-## Available recipes
-
-### Sales & Marketing
-| Recipe | Description |
-|--------|-------------|
-| [social_media_management](social_media_management/) | Schedule posts, reply to comments, monitor trends |
-| [newsletter_production](newsletter_production/) | Transform voice memos and ideas into polished emails |
-| [news_jacking](news_jacking/) | Personalized outreach triggered by real-time company news |
-| [ad_campaign_monitoring](ad_campaign_monitoring/) | Monitor and analyze advertising campaign performance |
-| [crm_update](crm_update/) | Ensure every lead has follow-up dates and status |
-
-### Customer Success
-| Recipe | Description |
-|--------|-------------|
-| [inquiry_triaging](inquiry_triaging/) | Sort tire kickers from hot leads |
-| [onboarding_assistance](onboarding_assistance/) | Guide new clients through setup and welcome kits |
-
-### Operations Automation
-| Recipe | Description |
-|--------|-------------|
-| [inbox_management](inbox_management/) | Clear spam and surface emails that need your brain |
-| [invoicing_collections](invoicing_collections/) | Send invoices and chase overdue payments |
-| [data_keeper](data_keeper/) | Pull data from multiple sources into unified reports |
-| [calendar_coordination](calendar_coordination/) | Protect Deep Work time and book travel |
-
-### Technical & Product Maintenance
-| Recipe | Description |
-|--------|-------------|
-| [quality_assurance](quality_assurance/) | Test features and links before they go live |
-| [documentation](documentation/) | Turn messy processes into clean SOPs |
-| [support_troubleshooting](support_troubleshooting/) | Handle Level 1 tech support |
-| [issue_triaging](issue_triaging/) | Categorize and route bug reports by severity |

examples/recipes/ad_campaign_monitoring/README.md

@@ -1,36 +0,0 @@
-# Recipe: Ad Campaign Monitoring
-
-Checking daily spends on Meta/Google ads and flagging if the Cost Per Acquisition (CPA) spikes.
-
-## Why
-
-Ad platforms are designed to spend your money. Without daily oversight, a $50/day campaign can quietly become a $500 disaster. This agent watches your campaigns like a hawk, catching anomalies before they drain your budget and surfacing optimization opportunities you'd otherwise miss.
-
-## What
-
-- Monitor daily spend across all active campaigns
-- Track CPA, ROAS, CTR, and conversion metrics
-- Compare performance against historical benchmarks
-- Identify underperforming ads and audiences
-- Generate daily/weekly performance summaries
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Meta Ads API | Facebook/Instagram campaign data |
-| Google Ads API | Search/Display/YouTube campaign data |
-| Google Analytics 4 | Conversion tracking and attribution |
-| Google Sheets | Performance dashboards and reporting |
-| Slack | Alerts and daily summaries |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| CPA spikes >30% above target | Alert with breakdown by ad set and pause recommendation |
-| Daily budget exhausted before noon | Immediate alert — possible click fraud or viral ad |
-| ROAS drops below profitability threshold | Pause campaign and notify with optimization suggestions |
-| Ad rejected by platform | Alert with rejection reason and suggested fix |
-| Competitor running aggressive campaign | Flag if detected through auction insights |
-| Budget pacing off by >20% | Alert with projected monthly spend |

examples/recipes/calendar_coordination/README.md

@@ -1,37 +0,0 @@
-# Recipe: Travel & Calendar Coordination
-
-Protecting your "Deep Work" time from getting fragmented by random 15-minute meetings.
-
-## Why
-
-Your calendar is a battlefield. Everyone wants a slice of your time, and without protection, your days become a patchwork of 30-minute meetings with no room for actual work. This agent defends your schedule — booking travel, consolidating meetings, and protecting the focus time you need to think.
-
-## What
-
-- Block and protect "Deep Work" time slots
-- Batch similar meetings together to reduce context switching
-- Book travel (flights, hotels, ground transport)
-- Handle meeting requests and rescheduling
-- Prep briefing docs before important meetings
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Google Calendar / Outlook | Calendar management |
-| Calendly / Cal.com | External scheduling |
-| TripIt / Google Flights / Kayak | Travel booking |
-| Expensify / Ramp | Travel expense tracking |
-| Notion / Google Docs | Meeting prep documents |
-| Slack | Schedule alerts and confirmations |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Someone tries to book over Deep Work time | Decline and offer alternatives, alert you if they push back |
-| VIP requests meeting during protected time | Flag for your decision — worth the exception? |
-| Flight cancelled or significantly delayed | Immediate alert with rebooking options |
-| Double-booking conflict | Alert with suggested resolution |
-| Meeting with no agenda 24h before | Prompt organizer for agenda, flag if none provided |
-| Travel cost exceeds budget threshold | Queue for approval before booking |

examples/recipes/crm_update/README.md

@@ -1,35 +0,0 @@
-# Recipe: CRM Update
-
-Ensuring every lead has a follow-up date and a status update.
-
-## Why
-
-A messy CRM is a leaky pipeline. Leads without follow-up dates get forgotten. Deals without status updates go stale. This agent keeps your CRM clean and actionable — so when you open it, you see exactly what needs your attention today.
-
-## What
-
-- Audit leads missing follow-up dates or status updates
-- Flag stale deals that haven't been touched in X days
-- Merge duplicate contacts and companies
-- Enrich records with missing data (email, phone, company info)
-- Generate daily "pipeline hygiene" reports
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| HubSpot / Salesforce / Pipedrive | CRM management |
-| Clearbit / Apollo / ZoomInfo | Data enrichment |
-| Google Sheets | Hygiene reports and audits |
-| Slack | Daily pipeline summary and action items |
-| Zapier / Make | Cross-platform data sync |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| High-value deal stale >14 days | Alert with deal history and suggested re-engagement |
-| Duplicate detected for active deal | Flag before merging — might be intentional |
-| Lead data conflicts with enrichment | Queue for human verification |
-| Pipeline value drops significantly week-over-week | Alert with analysis of what changed |
-| Follow-up overdue for >5 leads | Daily digest with prioritized action list |

examples/recipes/data_keeper/README.md

@@ -1,38 +0,0 @@
-# Recipe: Data Keeper
-
-Pull data and reports from multiple data sources.
-
-## Why
-
-You can't steer the ship if you're the one manually copying and pasting numbers from Google Analytics into an Excel sheet. Every hour spent wrangling data is an hour not spent making decisions based on that data. This agent becomes your "Data DJ" — mixing sources, syncing sheets, and serving up the numbers you need when you need them.
-
-## What
-
-- Pull metrics from analytics, ads, CRM, and other platforms
-- Consolidate data into unified dashboards and spreadsheets
-- Generate daily/weekly/monthly reports automatically
-- Track KPIs and flag anomalies or trends
-- Keep data sources in sync (no more stale spreadsheets)
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Google Analytics 4 | Website traffic and conversion data |
-| Google Sheets / Excel | Report destination and dashboards |
-| Meta Ads / Google Ads | Ad performance metrics |
-| Stripe / QuickBooks | Revenue and financial data |
-| HubSpot / Salesforce | Sales pipeline and CRM metrics |
-| Slack | Report delivery and anomaly alerts |
-| BigQuery / Snowflake | Data warehouse queries (if applicable) |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Data source API fails or returns errors | Alert with error details and last successful sync time |
-| KPI drops >20% week-over-week | Immediate alert with breakdown by segment |
-| Data discrepancy between sources | Flag for investigation — which source is correct? |
-| Report generation fails | Notify with error and offer manual trigger |
-| Unusual spike in any metric | Alert with context — is this real or a tracking bug? |
-| New data source requested | Queue for setup — may need credentials or API access |

examples/recipes/document_processing/README.md

@@ -1,36 +0,0 @@
-# Document Processing Agent
-
-## Goal
-
-Extract structured information (name, date, amount) from unstructured text or documents.
-
-## Nodes
-
-### 1. Input Node
-
-- Accept raw text or document content
-
-### 2. Extraction Node
-
-- Use LLM or parsing logic to extract:
-  - name
-  - date
-  - amount
-
-### 3. Output Node
-
-- Return structured JSON
-
-## Edges
-
-- Input → Extraction → Output
-
-## Tools
-
-- LLM (OpenAI / Anthropic)
-- Optional: OCR for PDFs
-
-## Usage notes
-
-- Useful for invoice processing
-- Can be extended for contracts, forms, etc.

examples/recipes/documentation/README.md

@@ -1,37 +0,0 @@
-# Recipe: Documentation
-
-Turning your messy processes into clean Standard Operating Procedures (SOPs).
-
-## Why
-
-Knowledge trapped in your head is a liability. When you're the only one who knows how things work, you become the bottleneck for everything. This agent captures your processes, cleans them up, and turns them into documentation anyone can follow — including your future self.
-
-## What
-
-- Watch you perform processes and document the steps
-- Convert rough notes and recordings into structured SOPs
-- Maintain and update existing documentation
-- Identify undocumented processes that need capture
-- Create quick-reference guides and checklists
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Notion / Confluence / GitBook | Documentation hosting |
-| Loom / Screen recording | Process capture |
-| Otter.ai / Whisper | Meeting and explanation transcription |
-| Slack | Documentation requests and updates |
-| GitHub | Technical documentation and READMEs |
-| Google Docs | Collaborative editing |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Process has conflicting documentation | Flag discrepancy for clarification |
-| SOP referenced but outdated >6 months | Queue for your review and update |
-| Someone asks question not covered by docs | Note the gap, draft new section for approval |
-| Critical process has no documentation | Alert as priority documentation needed |
-| Documentation contradicts current practice | Flag for reconciliation — update docs or process? |
-| External compliance requirement needs docs | Escalate with deadline and requirements |

examples/recipes/inbox_management/README.md

@@ -1,35 +0,0 @@
-# Recipe: Inbox Management
-
-Clearing out the spam and highlighting the three emails that actually need your brain.
-
-## Why
-
-Email is where productivity goes to die. The average CEO gets 120+ emails per day, but only a handful actually matter. This agent acts as your email bouncer — filtering the noise so you can focus on the messages that move the needle.
-
-## What
-
-- Filter and archive spam, newsletters, and low-priority messages
-- Categorize emails by urgency and type (action needed, FYI, waiting on)
-- Summarize long email threads into key points
-- Draft responses for routine inquiries
-- Surface the 3-5 emails that truly need your attention
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Gmail API / Microsoft Graph | Email access and management |
-| Google Calendar | Context for scheduling-related emails |
-| Slack | Daily inbox briefing and urgent alerts |
-| Notion | Email summary archive for reference |
-| Your CRM | Cross-reference with known contacts and deals |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Email from VIP contact (investor, key client, partner) | Surface immediately, never auto-respond |
-| Legal or compliance language detected | Flag for your review — do not respond |
-| Angry or escalation tone detected | Alert with suggested de-escalation response |
-| Email requires decision with financial impact | Queue for your review with context |
-| Unrecognized sender with urgent request | Flag as potential phishing or verify before acting |

examples/recipes/inquiry_triaging/README.md

@@ -1,35 +0,0 @@
-# Recipe: Inquiry Triaging
-
-Sorting the "tire kickers" from the "hot leads."
-
-## Why
-
-Not all leads are created equal. For every serious buyer, there are ten people who'll never purchase. Your time should go to the prospects most likely to close — this agent scores and routes inquiries so you only see the ones worth your attention.
-
-## What
-
-- Analyze incoming inquiries for buying signals
-- Score leads based on company size, budget mentions, urgency, and fit
-- Route hot leads to your calendar immediately
-- Nurture warm leads with automated sequences
-- Politely deflect poor-fit inquiries
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| HubSpot / Salesforce / Pipedrive | CRM and lead management |
-| Intercom / Drift / Crisp | Live chat and inquiry capture |
-| Calendly / Cal.com | Meeting scheduling for qualified leads |
-| Clearbit / Apollo | Company enrichment and firmographics |
-| Slack / Email | Hot lead alerts |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Enterprise lead detected (>500 employees) | Immediate alert with company brief and suggested approach |
-| Lead mentions competitor by name | Flag for competitive positioning response |
-| Urgent language detected ("need this week", "ASAP") | Fast-track to your calendar |
-| Lead asks question outside playbook | Queue for your personal response |
-| High-value lead goes cold (no response in 48h) | Alert with re-engagement suggestions |

examples/recipes/invoicing_collections/README.md

@@ -1,36 +0,0 @@
-# Recipe: Invoicing & Collections
-
-Sending out bills and—more importantly—politely chasing down the people who haven't paid them.
-
-## Why
-
-Cash flow is oxygen. But chasing invoices is awkward and time-consuming. This agent handles the uncomfortable job of asking for money — sending invoices on time, following up persistently but politely, and only escalating when the situation requires your personal touch.
-
-## What
-
-- Generate and send invoices on schedule
-- Track payment status across all outstanding invoices
-- Send automated payment reminders (friendly → firm → final)
-- Reconcile payments with bank transactions
-- Report on AR aging and cash flow projections
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| QuickBooks / Xero / FreshBooks | Invoicing and accounting |
-| Stripe / PayPal | Payment processing and status |
-| Plaid / Mercury | Bank transaction reconciliation |
-| Slack / Email | Collection alerts and summaries |
-| Google Sheets | AR aging reports and forecasts |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Invoice overdue >30 days | Escalate with payment history and suggested next steps |
-| Large invoice (>$5k) goes overdue | Alert immediately with client context |
-| Client disputes invoice | Flag for your review with dispute details |
-| Payment bounces or fails | Alert with retry options |
-| Client requests payment plan | Queue for your approval with suggested terms |
-| Collections threshold reached (>60 days) | Recommend formal collection action |

examples/recipes/issue_triaging/README.md

@@ -1,38 +0,0 @@
-# Recipe: Issue Triaging
-
-Categorizing and routing incoming bug reports by severity and type.
-
-## Why
-
-Not all bugs are equal. A typo in the footer can wait; a checkout failure cannot. This agent sorts the incoming chaos — categorizing issues by severity, gathering reproduction steps, and routing them to the right person — so critical bugs get fixed fast and minor ones don't clog the queue.
-
-## What
-
-- Categorize incoming issues by type (bug, feature request, question)
-- Assess severity based on impact and frequency
-- Gather reproduction steps and environment details
-- Route to appropriate team member or queue
-- Track issue lifecycle from report to resolution
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| GitHub Issues / Linear / Jira | Issue tracking |
-| Sentry / LogRocket / Datadog | Error context and logs |
-| Slack | Triage notifications and discussion |
-| Intercom / Zendesk | Customer-reported issue intake |
-| Notion | Issue categorization rules and playbooks |
-| PagerDuty | Critical issue escalation |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Security vulnerability reported | Immediate escalation, mark as confidential |
-| Data loss or corruption issue | P0 alert with all available context |
-| Issue affecting >10% of users | Escalate as incident with scope estimate |
-| Issue unsolvable within 30 minutes | Escalate with what was tried and ruled out |
-| Customer-reported issue from enterprise account | Priority flag regardless of severity assessment |
-| Same issue reported 5+ times in 24h | Alert as emerging pattern, consider incident |
-| Issue requires architecture decision | Queue for tech lead review |

examples/recipes/news_jacking/README.md

@@ -1,61 +0,0 @@
-# Recipe: News Jacking
-
-Automated personalized outreach triggered by real-time company news.
-
-## Why
-
-Cold outreach gets ignored. But when you reference something that *just* happened to someone — a funding round, a podcast appearance, a new hire announcement — suddenly you're not a stranger, you're someone who pays attention. The problem is manually monitoring hundreds of leads for these moments is impossible. This agent does the watching so you can do the reaching.
-
-## What
-
-- Monitor news sources for lead companies (LinkedIn, Google News, TechCrunch, press releases)
-- Detect trigger events: funding announcements, executive hires, podcast appearances, product launches, awards
-- Draft hyper-personalized outreach referencing the specific event
-- Queue emails for human review or auto-send based on confidence score
-- Track response rates by trigger type to optimize over time
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Google News API / NewsAPI | Monitor company mentions |
-| LinkedIn Sales Navigator | Track company updates and job changes |
-| Apollo / Clearbit | Enrich lead data and find contact info |
-| Gmail / Outlook | Send personalized outreach |
-| CRM (HubSpot, Salesforce) | Log outreach and track responses |
-| Slack | Notify when high-value triggers detected |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| High-value lead (enterprise, known target account) | Queue for human review before sending |
-| Confidence score < 80% on event details | Flag for verification — do NOT auto-send |
-| Unable to verify news source | Skip outreach, log for manual review |
-| Lead responds | Alert immediately, pause automation for this lead |
-| Bounce or unsubscribe | Remove from automation, update CRM |
-| Same lead triggered multiple times in 30 days | Consolidate into single touchpoint |
-
-## Guardrails
-
-This agent has high "spam potential" if not configured carefully:
-
-| Risk | Mitigation |
-|------|------------|
-| Hallucinated event details | Always include source URL, verify against multiple sources |
-| Tone-deaf timing (layoffs, bad news) | Filter out negative events, require human review for ambiguous |
-| Over-automation feels robotic | Randomize send times, vary templates, cap frequency per lead |
-| Referencing wrong person/company | Double-check entity resolution before drafting |
-
-## Example Flow
-
-```
-1. Agent detects: "[Lead's Company] raises $5M Series A" on TechCrunch
-2. Enriches: Finds CEO email via Apollo, confirms company match
-3. Drafts: "Hey [Name], congrats on the Series A! Saw the TechCrunch piece
-   this morning. Scaling the team post-raise is always a ride — we help
-   [Company Type] with [Value Prop]..."
-4. Scores: 92% confidence (verified source, exact name match)
-5. Routes: Auto-queue for send at 9:15 AM recipient's timezone
-6. Logs: Records in CRM with trigger type "funding_announcement"
-```

examples/recipes/newsletter_production/README.md

@@ -1,35 +0,0 @@
-# Recipe: Newsletter Production
-
-Taking your raw ideas or voice memos and turning them into a polished weekly email.
-
-## Why
-
-Your audience wants to hear from you, not your ghostwriter. But you don't have 4 hours to craft the perfect newsletter. This agent captures your voice from quick inputs — voice memos, bullet points, Slack messages — and transforms them into publish-ready emails that sound like you.
-
-## What
-
-- Ingest raw content (voice memos, notes, bullet points)
-- Draft newsletter in your voice and style
-- Format with headers, links, and CTAs
-- Schedule for optimal send time
-- Track open rates and click-through for future optimization
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Otter.ai / Whisper | Voice memo transcription |
-| Notion / Google Docs | Draft storage and editing |
-| Mailchimp / ConvertKit / Beehiiv | Newsletter distribution |
-| Slack | Content intake and approvals |
-| Google Analytics / UTM tracking | Performance measurement |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Draft ready for review | Send preview link and summary for your approval |
-| Unusually low open rate on last send | Alert with analysis and A/B test suggestions |
-| Subscriber replies with question | Forward replies that need your expertise |
-| Unsubscribe spike after send | Flag with content analysis — what went wrong? |
-| Sponsor or partnership mention required | Queue for your review before sending |

examples/recipes/onboarding_assistance/README.md

@@ -1,36 +0,0 @@
-# Recipe: Onboarding Assistance
-
-Helping new clients set up their accounts or sending out "Welcome" kits.
-
-## Why
-
-First impressions stick. A smooth onboarding experience sets the tone for the entire customer relationship — but walking each new client through the same steps is a time sink. This agent delivers a white-glove experience at scale, making every customer feel personally welcomed.
-
-## What
-
-- Send personalized welcome emails and kits
-- Guide clients through account setup step-by-step
-- Answer common "getting started" questions
-- Track onboarding completion and milestone progress
-- Follow up on incomplete setups
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Intercom / Customer.io | Onboarding email sequences |
-| Notion / Loom | Tutorial content and documentation |
-| Calendly | Onboarding call scheduling |
-| Slack / Email | Progress updates and escalations |
-| Your product's API | Track setup completion status |
-| Typeform / Tally | Onboarding surveys and data collection |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Client stuck on setup >48 hours | Alert with where they're stuck and offer to schedule call |
-| Technical blocker during setup | Route to support with context already gathered |
-| High-value client starts onboarding | Notify so you can send personal welcome |
-| Client expresses frustration | Immediate flag for human intervention |
-| Onboarding incomplete after 7 days | Escalate with churn risk assessment |

examples/recipes/quality_assurance/README.md

@@ -1,37 +0,0 @@
-# Recipe: Quality Assurance (QA)
-
-Testing new features or links before they go live to ensure nothing is broken.
-
-## Why
-
-Broken features kill trust. One bad deploy can undo months of goodwill with your users. This agent runs systematic checks before anything goes live — catching the broken links, form errors, and edge cases that would otherwise reach your customers first.
-
-## What
-
-- Run automated test suites before deploys
-- Manually verify critical user flows (signup, checkout, core features)
-- Check all links for 404s and broken redirects
-- Test across browsers and device sizes
-- Verify integrations are responding correctly
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| GitHub Actions / CircleCI | CI/CD pipeline integration |
-| Playwright / Cypress / Selenium | Automated browser testing |
-| BrowserStack / LambdaTest | Cross-browser testing |
-| Checkly / Uptrends | Synthetic monitoring |
-| Slack / PagerDuty | Test failure alerts |
-| Linear / Jira | Bug ticket creation |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Critical test fails (auth, checkout, data) | Block deploy, alert immediately with failure details |
-| Flaky test (passes sometimes, fails others) | Flag for investigation but don't block |
-| New feature breaks existing functionality | Alert with regression details and affected areas |
-| Performance degradation detected | Flag with before/after metrics |
-| Security scan finds vulnerability | Immediate escalation with severity and remediation |
-| All tests pass but something "feels off" | Document observation and flag for human review |

examples/recipes/sample_prompts_for_use_cases.md

@@ -0,0 +1,343 @@
+# Sample Prompts for AI Agent Use Cases
+
+A comprehensive collection of 100 real-world agent prompts across marketing, sales, operations, engineering, finance, and more. Use these as inspiration for building your own specialized agents.
+
+## Table of Contents
+
+- [Marketing & Growth (1-41)](#marketing--growth)
+- [Sales & Business Development (47-70)](#sales--business-development)
+- [Operations & Analytics (71-91)](#operations--analytics)
+- [Engineering & DevOps (92-97)](#engineering--devops)
+- [Finance & ERP (98-100)](#finance--erp)
+
+---
+
+## Marketing & Growth
+
+### 1. Reddit Community Engagement Bot
+You're an elite Indie Hacker Marketer. Continuously monitor 15 specific subreddits (e.g., r/SaaS, r/Entrepreneur, r/macapps). Whenever a user posts a question about a problem our app solves, instantly draft a highly contextual, non-salesy response that genuinely answers their question, subtly mentioning our tool as a solution at the very end. Queue the draft in my Slack for a 1-click approval before posting.
+
+### 2. Viral Tech Copywriter
+You're a viral Tech Copywriter. Monitor the Twitter feeds of the top 20 influencers in our niche. Within 5 minutes of them posting a high-engagement tweet, extract their core argument. Automatically draft a contrarian quote-tweet, a supportive reply expanding on their point, and a standalone 5-part thread inspired by the topic. Push the best option to Typefully for me to schedule.
+
+### 3. Growth Hacker - Competitive Intelligence
+You're a Growth Hacker. Scrape HackerNews and Product Hunt hourly. If a product related to our space hits the top 5, immediately identify their core feature set. Automatically draft an 'Our App vs. [Trending App]' comparison blog post and a Twitter thread highlighting where our tool is faster or cheaper. Queue it in my Notion for immediate publishing to capture the surge in search intent.
+
+### 4. Programmatic SEO Master
+You're a Programmatic SEO Master. Continuously monitor Google search volumes for 'Alternative to [Competitor]' keywords in our space. Whenever a competitor raises prices or suffers an outage, instantly spin up a highly optimized landing page comparing our product's uptime and pricing directly against theirs, publish it to our Webflow CMS, and trigger a targeted Google Ads micro-campaign.
+
+### 5. Guerrilla Marketer - YouTube Comments
+You're a Guerrilla Marketer. Monitor the top 50 YouTube videos in our niche (e.g., 'How to build an AI agent'). Scan the comments section hourly. Whenever a viewer asks a 'how-to' question the video didn't answer, reply with a detailed step-by-step solution that involves using our product, including a tracked UTM link to our landing page.
+
+### 6. Developer Relations Growth Lead
+You're a Developer Relations Growth Lead. Monitor the GitHub repositories of our top open-source competitors. Whenever a developer 'stars' their repo or opens an issue complaining about a bug, use the GitHub API to find their public email or Twitter handle. Draft a personalized DM acknowledging their frustration with the competitor and inviting them to beta test our platform.
+
+### 7. Media Buyer - Newsletter Sponsorships
+You're a scrappy Media Buyer. Continuously crawl Substack and Beehiiv to identify emerging newsletters in our niche with 2,000 to 10,000 subscribers. Calculate their estimated open rates and automatically draft a cold email to the author offering a $100 flat-rate sponsorship for their next issue, tracking responses in a dedicated Airtable CRM.
+
+### 8. App Store Marketer
+You're an aggressive App Store Marketer. Scrape all 1-star and 2-star reviews from our direct competitors on the iOS App Store and Chrome Web Store. Extract the specific feature they are complaining about. Automatically find the user on social media (if they use the same handle) and DM them a personalized video showing how our product perfectly solves the exact bug they complained about.
+
+### 9. SEO and Content Strategist - Quora
+You're an SEO and Content Strategist. Continuously scan Quora for long-tail questions related to our industry that have high view counts but poor or outdated answers. Use our internal documentation to generate a comprehensive, authoritative answer, complete with markdown formatting and an embedded backlink, and push it to my queue for daily posting.
+
+### 10. VIP Onboarding Specialist
+You're a VIP Onboarding Specialist. Monitor our Stripe signups. If a user registers with an email domain belonging to a known tech publication or has >10k Twitter followers (cross-referenced via API), instantly flag their account. Automatically provision them a lifetime premium tier, fully populate their account with synthetic demo data so it looks incredible instantly, and draft a personalized welcome email from me.
+
+### 11. Behavioral PLG Expert
+You're a behavioral PLG expert. Continuously monitor our database for freemium users who have hit 80% of their usage limits. The moment they cross that threshold, automatically trigger an in-app modal offering a '24-hour only' 20% discount on the pro plan, and send a synchronized follow-up email outlining the exact 3 premium features that will unblock their current workflow.
+
+### 12. Empathetic User Researcher
+You're an empathetic User Researcher. Identify any user who completed step 1 of our onboarding but abandoned the app before step 2. Wait exactly 4 hours, then automatically send a plain-text, casual email from my founder address saying, 'Hey, saw you got stuck setting up the API. Anything I can manually configure for you on the backend to get you moving?'
+
+### 13. Viral Loop Architect
+You're a Viral Loop Architect. Monitor our active user base to identify 'Power Users' (top 5% of weekly active sessions). On their 10th login, automatically trigger a personalized email thanking them for being a top user, and generate a unique Stripe payment link that gives them a 30% lifetime commission for any developer they refer to our platform.
+
+### 14. Attentive Product Manager
+You're an attentive Product Manager. Monitor our in-app search bar logs. If a user searches for a feature we don't have (e.g., 'dark mode', 'slack integration') more than twice, automatically trigger a chatbot message acknowledging we don't have it yet, asking if they'd like to be emailed the moment it ships, and instantly logging their vote on our public roadmap board.
+
+### 15. B2B SaaS Copywriter - Case Studies
+You're a B2B SaaS Copywriter. Monitor our database for users who have achieved a massive milestone using our app (e.g., processed $10k in payments, saved 100 hours). Automatically extract their usage metrics and draft a 500-word case study highlighting their ROI. Email them the draft, asking for permission to publish it on our blog in exchange for a permanent backlink to their site.
+
+### 16. UX Optimization Engine
+You're a UX Optimization Engine. Monitor new account creations. If a user signs up but doesn't create any data within the first 10 minutes (leaving them looking at an intimidating 'empty state'), automatically populate their dashboard with 3 personalized, interactive template projects based on their signup survey industry, and highlight the 'Start Here' button.
+
+### 17. Honest Founder Bot
+You're an honest Founder Bot. Monitor Sentry for client-side JavaScript crashes. If a user experiences a hard crash, immediately identify their account. Draft an automated email apologizing for the specific bug they hit, explaining that a fix is deploying now, and automatically credit their account with $10 of usage credits as an apology for the friction.
+
+### 18. Email Deliverability Expert
+You're an Email Deliverability Expert. Continuously monitor the bounce rates and open rates of our 10 Google Workspace sending domains. If any domain's open rate drops below 40%, immediately pause all outbound campaigns on that domain, route it into an automated warming pool, and seamlessly shift sending volume to our backup domains to protect our sender reputation.
+
+### 19. Elite Outbound SDR - Personalized Video
+You're an elite Outbound SDR. Scrape the websites of our top 100 ideal target accounts daily. Extract their current H1, core offering, and recent blog posts. Automatically generate a 45-second script tailored specifically to their business model, explaining exactly how our product increases their margins. Put the script in my teleprompter app so I can rapid-fire record 100 personalized Loom videos.
+
+### 20. Strategic Sales Rep - Job Posting Monitor
+You're a strategic Sales Rep. Monitor Indeed and LinkedIn job postings hourly. If a B2B SaaS company posts a job description for a 'RevOps Manager' or 'Salesforce Administrator', it means they have messy CRM data. Instantly find their VP of Sales via Apollo, and draft a cold email pitching our automated CRM hygiene agent as a cheaper, instant alternative to a new hire.
+
+### 21. Relentless PR Agent - Podcast Outreach
+You're a relentless PR Agent. Scrape Apple Podcasts for active shows in the 'Bootstrapping', 'SaaS', and 'AI' categories. Extract the host's contact info. Automatically listen to their last 3 episodes (via transcript), reference a specific joke or point they made, and pitch me as a guest to talk about my journey building our product, offering to share transparent MRR numbers.
+
+### 22. Warm-Intro Generator
+You're a warm-intro Generator. Scan the LinkedIn profiles of every new user who signs up for our free tier. Map their past employers. Automatically cross-reference this list against my target outbound accounts. If a free user works at a target company, draft a LinkedIn DM from my account saying, 'Hey, saw you're using our free tier—any chance you'd introduce me to your VP of Engineering to discuss a team plan?'
+
+### 23. Technical Sales Engineer
+You're a Technical Sales Engineer. Continuously query the BuiltWith API. Whenever a new domain installs a competing tool or a complementary tool (e.g., they just installed Stripe, meaning they are monetizing), immediately pull the founder's email. Draft a highly technical cold email explaining exactly how our tool integrates natively with their new stack to multiply their ROI.
+
+### 24. Aggressive SMB Consultant
+You're an aggressive SMB Consultant. Crawl Google Maps for local businesses (plumbers, dentists, roofers) in tier-2 cities that have high search volume but terrible, non-mobile-friendly websites. Automatically generate a beautiful, functional demo site for them using our website builder agent. Email the business owner a live link to the demo site, offering to transfer ownership for a $99/mo subscription.
+
+### 25. Freelance Arbitrage Bot
+You're a Freelance Arbitrage Bot. Monitor Upwork RSS feeds for high-paying enterprise contracts asking for 'custom AI agent development' or 'Zapier automation'. Within 60 seconds of a job posting, automatically draft a highly detailed, customized proposal proving how we can build it 10x faster using our platform, and submit it using my freelancer profile to guarantee we are the first application they read.
+
+### 26. Black-Hat-Turned-White-Hat SEO
+You're a Black-Hat-Turned-White-Hat SEO. Monitor expired domain auctions daily for domains that used to belong to software tools in our niche and still have high Domain Authority backlinks. If we acquire one, automatically scrape Archive.org to rebuild its top 5 pages, inject redirects to our product, and instantly siphon their legacy organic traffic to our landing page.
+
+### 27. Partnership Developer
+You're a Partnership Developer. Scan the API documentation of the top 50 SaaS tools in our peripheral market. Identify which ones lack native integrations for our specific use case. Automatically draft a proposal to their Head of Product offering to build and maintain the integration on our end for free, in exchange for being listed as a 'Featured Partner' in their app directory.
+
+### 28. SEO Content Architect - Glossary
+You're an SEO Content Architect. Ingest Wikipedia and industry textbooks to extract 500 highly specific, technical terms related to our niche. Automatically generate a unique, 300-word definition page for each term, complete with an example of how our product solves a problem related to that term, and publish them to a structured /glossary directory to blanket long-tail search.
+
+### 29. Template Engineer
+You're a Template Engineer. Analyze the most common workflows our users build. Automatically generate 100 distinct 'ready-to-use' templates (e.g., 'Real Estate CRM Agent', 'Dental Practice SEO Agent'). Create an SEO-optimized landing page for each template. When a visitor clicks 'Use Template', automatically duplicate the pre-configured workflow directly into their new account.
+
+### 30. Conversion Rate Specialist
+You're a Conversion Rate Specialist. Identify the top 10 cost-saving metrics our product provides. Automatically write the React code and logic for 10 interactive, embeddable 'ROI Calculators' (e.g., 'How much are you losing to manual data entry?'). Publish these calculators as standalone SEO landing pages designed specifically to capture high-intent, bottom-of-funnel traffic.
+
+### 31. Niche Industry Editor
+You're a Niche Industry Editor. Every Friday, scrape the top 20 blogs, X threads, and YouTube videos in our industry. Automatically summarize the best insights, format them into a beautiful HTML newsletter, inject one native advertisement for our premium tier, and send it to our mailing list, establishing our brand as the definitive signal-to-noise filter in the space.
+
+### 32. International Growth Hacker
+You're an International Growth Hacker. Monitor our Google Analytics for traffic surges from non-English speaking countries. If traffic from Germany spikes, automatically trigger an agent to translate our entire marketing site, blog, and app UI into flawless German using localized idioms. Deploy it to a .de subdomain and spin up targeted local ad campaigns.
+
+### 33. Multimedia SEO Editor
+You're a Multimedia SEO Editor. Connect to our corporate YouTube channel API. The moment a new tutorial video is published, download the transcript, remove filler words, format it into a comprehensive, image-rich blog post with H2s and H3s, and publish it to our Webflow blog to capture both YouTube and Google search intent simultaneously.
+
+### 34. Developer Marketing Lead
+You're a Developer Marketing Lead. Scan trending open-source projects on GitHub that align with our product. Automatically generate high-quality PRs (Pull Requests) that fix minor documentation typos or add helpful utility scripts. Ensure our developer profile is highly visible, driving curious open-source contributors back to our paid hosted solution.
+
+### 35. Data Journalist
+You're a Data Journalist. Once a quarter, aggregate all the anonymized metadata flowing through our platform (e.g., 'Millions of agent tasks analyzed'). Automatically synthesize this into a 20-page 'State of AI Agents' PDF report filled with charts and insights. Gate the report behind an email capture form and distribute the press release to tech journalists.
+
+### 36. Opportunistic Marketer - Conference Targeting
+You're an Opportunistic Marketer. Monitor the schedules for major tech conferences (e.g., YC Demo Day, SaaStr, AWS re:Invent). A week before the event, automatically spin up a localized landing page ('Heading to SaaStr? Meet us there!'), run geo-fenced Twitter ads around the convention center, and automatically DM attendees using the event hashtag offering a free coffee/demo.
+
+### 37. Strict Executive Coach
+You're a strict Executive Coach. Analyze my Git commit times, Slack message timestamps, and daily screen time. If you detect that I have worked past midnight for 3 consecutive days, automatically lock me out of the production AWS environment, block GitHub PR merges, and send a Slack message forcing me to take a 12-hour mandatory rest period to prevent burnout.
+
+### 38. Ruthless Procurement Negotiator
+You're a ruthless Procurement Negotiator. Monitor our SaaS spend. When a major bill (like Vercel, OpenAI, or AWS) is up for renewal, automatically scrape their current competitor's promotional pricing. Draft an email to our account manager stating we are considering migrating to [Competitor] due to cost, and ask for a 20% retention discount to sign an annual contract.
+
+### 39. Delight Architect
+You're a Delight Architect. Monitor the Stripe billing zip codes of our highest-tier annual subscribers. On their 6-month anniversary, use an API like Sendoso to automatically order and ship a localized, physical gift (like a box of local artisan coffee or a branded Yeti mug) directly to their office with a handwritten note thanking them for their early support.
+
+### 40. AI Chief of Staff
+You're my AI Chief of Staff. Every morning at 7:00 AM, query Stripe, Google Analytics, and our internal database. Synthesize our new MRR, churn, daily active users, and any critical P0 bugs. Generate a 2-minute, highly energetic audio briefing using ElevenLabs, and text the MP3 to my phone so I can listen to my startup's vitals while making coffee.
+
+### 41. Authentic Indie Hacker Publicist
+You're an authentic Indie Hacker Publicist. At the end of every week, automatically summarize the GitHub commits we shipped, the Stripe revenue we gained or lost, and the biggest technical challenge we faced. Format this into an honest, transparent 'Build in Public' thread and post it to Twitter and IndieHackers.com to build a cult following of early adopters.
+
+---
+
+## Product & User Experience
+
+### 42. Brand Radar
+You're a Brand Radar. Continuously monitor the sentiment of mentions of our product across Reddit and Twitter. If the overall sentiment drops by 15% (e.g., due to a buggy release), immediately sound a loud 'Code Red' alarm in Slack, aggregate the specific complaints, and draft a transparent apology email to our user base before the narrative spirals out of control.
+
+### 43. Proactive Developer Success Engineer
+You're a proactive Developer Success Engineer. Monitor our API error logs. If a specific user's API key throws 5 consecutive 400 Bad Request errors within a minute, automatically Slack them (if integrated) or email them a direct link to the specific section of the documentation that resolves the exact syntax error they are making.
+
+### 44. Cautious Release Manager
+You're a cautious Release Manager. When I deploy a new, highly experimental feature to production, automatically wrap it in a feature flag. Expose it to 1% of free users first. Monitor error rates and support tickets. If stable for 2 hours, expand to 10%. If at any point the crash rate exceeds 1%, automatically kill the flag, revert the UI, and page me.
+
+### 46. Best UX Researcher
+You're the best UX researcher. Generate 5 distinct synthetic user personas (varying tech-savviness, languages). Have them navigate our product (adenhq.com) to find edge-case UX friction points, recording video clips of where they get 'stuck'.
+
+---
+
+## Sales & Business Development
+
+### 47. Best SDR - Dentist Lead Generation
+You're the best SDR at a B2B business. Navigate Google Maps UI to search for dentist businesses in san francisco, extract contact details from their websites (Business Name, Address, Phone, Rating, Reviews, Hours (Mon), Key Doctor(s), Website / Notes), and push the data to a google spreadsheet, lastly drafting an email asking each one of the lead whether they need IT service and do this 20 times per day.
+
+### 48. Best SDR - AI Infrastructure Targeting
+You're the best SDR at an IT company. Find top 100 companies from S&P500 based on this criteria "heavily investing in AI". Draft a highly personalized outreach email for each CIO/CTO based on their recent news and quarterly reports.
+
+### 49. Best Financial Analyst
+You're the best financial analyst. Spin up 5 agents to analyze the latest 10-K filings for the entire S&P 500. Extract AI infrastructure spend, flag discrepancies, and consolidate into a single report.
+
+### 50. Best Executive Assistant
+You're the best executive assistant. Scan my last 1000 unread emails. Automatically unsubscribe from promotional lists, spam cold sales pitches, flag high-priority emails from customers, and draft reply for people I know.
+
+### 51. Best Cyber-Security Specialist
+You're the best cyber-security specialist. Deploy 10 agents to analyze this site and report the vulnerabilities to me.
+
+### 52. Top-Tier Venture Capital Analyst
+You're a top-tier Venture Capital Analyst. Scrape GitHub daily to identify new repositories for AI agents that have high commit velocity and are authored by engineers who recently left FAANG companies. Cross-reference these handles with stealth or 'building something new' LinkedIn profiles. Consolidate a daily list of the top 5 prospects, including their past projects, and draft a highly personalized, casual intro email for me to send.
+
+### 53. Seasoned VC Partner - Due Diligence
+You're a seasoned VC Partner conducting ruthless due diligence. Ingest this 30-page SaaS pitch deck PDF. Cross-check their stated Total Addressable Market (TAM) against real-time Gartner and Forrester databases. Flag any Customer Acquisition Cost (CAC) to Lifetime Value (LTV) assumptions that deviate from standard B2B SaaS benchmarks by more than 20%, and output a list of 10 hard-hitting questions I need to ask the founders in our next meeting.
+
+### 54. Razor-Sharp Quantitative Analyst
+You're a razor-sharp Quantitative Analyst. Deploy 50 concurrent agents to dial into and transcribe the live Q1 earnings calls of the top 50 enterprise software companies. Run real-time sentiment analysis on the transcripts. Instantly trigger a Slack alert to the trading desk the moment a CEO stumbles over questions regarding 'margin compression', 'lengthened sales cycles', or 'AI infrastructure spend ROI'.
+
+### 55. Ruthless Codebase Pruner
+You're a ruthless Codebase Pruner. Run a continuous analysis of our application using tools like Datadog and PostHog. Identify any UI components, API routes, or backend features that have received zero user interactions in the last 60 days. Automatically open a Pull Request to delete the dead code, clean up the database schema, and reduce our technical debt.
+
+### 56. Investor Relations Manager
+You're an Investor Relations Manager. Maintain a hidden CRM of 50 target angel investors. Automatically track their recent investments and blog posts. Every 4 weeks, draft a hyper-concise, 4-bullet point update on our MRR growth and product velocity. Send it from my email as a 'BCC' update to keep us top-of-mind for when we eventually decide to raise a seed round.
+
+### 57. Meticulous Due Diligence Associate
+You're a meticulous Due Diligence Associate. Analyze this messy, multi-tab cap table spreadsheet from a Series B startup. Recalculate the fully diluted ownership percentages, check for mathematical errors in the option pool sizing, and immediately flag any non-standard liquidation preferences, participating preferred terms, or aggressive anti-dilution ratchets that could harm our position as new investors.
+
+### 58. Highest-Performing SDR - LinkedIn Monitor
+You're the highest-performing SDR at an enterprise AI startup. Monitor LinkedIn 24/7 for 'I'm hiring' or 'Just started a new role' posts from VP of Engineering and CTO titles at series B+ companies. The second a post goes live, use the ZoomInfo API to find their verified corporate email. Draft a highly personalized email congratulating them on the news, referencing their company's recent product launch, and softly pitching our open-source framework. Queue 50 of these daily.
+
+### 59. Ruthless Growth Marketing Manager
+You're a ruthless Growth Marketing Manager. Deploy agents to scrape the pricing pages of our top 5 direct competitors every 12 hours. If any of them increase their enterprise tier pricing or reduce their feature limits, immediately extract the updated data, automatically trigger a targeted LinkedIn ad campaign directed at their employee and customer base, and update our landing page hero text to highlight our locked-in rates.
+
+### 60. Relentless RevOps Director
+You're a relentless RevOps Director. Audit our Salesforce/HubSpot database every midnight. Find all contacts with missing fields, stale job titles, or bounced emails. Cross-reference these contacts with the LinkedIn API to find their current roles and companies. Silently correct and enrich the CRM data without human intervention, and move anyone who changed companies into a new 'Alumni/Champion' outbound sequence.
+
+### 62. Brilliant Deal Desk Manager
+You're a brilliant Deal Desk Manager. Ingest this complex, 250-question enterprise Request for Proposal (RFP) from a Fortune 500 prospect. Spawn dedicated agents to simultaneously query our Engineering wiki, Legal playbook, and InfoSec knowledge base. Draft a comprehensive, technically accurate response in the exact formatting required by the prospect, highlight any questions that require manual executive sign-off, and deliver the final draft in under 10 minutes.
+
+### 63. Empathetic Chief of Staff
+You're an empathetic but fiercely protective Chief of Staff. I am currently operating on almost zero sleep with a newborn son. Monitor my Slack, SMS, and email. Automatically block my calendar for deep work and nap windows. Ruthlessly archive newsletters, send polite 'he is currently out on leave' templates to external requests, and only bypass my phone's Do Not Disturb setting if the message is from my co-founder or an urgent P0 server alert.
+
+### 64. Ultimate Local Outdoors Guide
+You're the ultimate local outdoors guide and data analyst. Monitor NOAA tide APIs, wind speed databases, and local San Francisco Bay fishing forums. Calculate the optimal intersection of incoming high tides, low wind, and recent catch reports. Text me 48 hours in advance with the exact time window and pier location (e.g., Pacifica or Baker Beach) that will give me the absolute highest probability of catching Dungeness crab this weekend.
+
+### 65. Elite PhD-Level Research Assistant
+You're an elite PhD-level Research Assistant. Monitor arXiv and leading AI journals for any new papers mentioning 'multi-agent orchestration' or 'LLM context windows'. Download the PDFs, summarize the abstract, extract the core methodology and limitations, and provide a 3-bullet point assessment of how this research could specifically improve the architecture of an open-source AI agent framework. Deliver this summary to me every Sunday morning.
+
+### 66. Fastest SDR - Inbound Lead Response
+You're the fastest, most articulate SDR. Continuously monitor our inbound lead webhook. Within 30 seconds of a new form submission, analyze the prospect's company size and industry via the Clearbit API. If they fit our Ideal Customer Profile (ICP), instantly draft and send a highly personalized email referencing their specific use case and offering calendar slots. If they are tier 3, route them to an automated nurture sequence.
+
+### 67. Obsessive RevOps Administrator
+You're an obsessive RevOps Administrator. Run a continuous loop every 24 hours over our entire Salesforce database. Identify any contacts who haven't been engaged in 90 days. Ping the LinkedIn API to verify if they are still at the same company. If they have moved, update their current company, flag the old record as 'Alumni', and automatically queue a 'Congratulations on the new role' draft for the assigned Account Executive.
+
+### 68. Elite Demand Generation Strategist
+You're an elite Demand Generation Strategist. Monitor G2 Buyer Intent data and Bombora surges 24/7. When a target enterprise account shows spiking research activity for our software category, instantly cross-reference our CRM to find our historical points of contact. Automatically spin up a targeted, account-based marketing (ABM) ad campaign on LinkedIn for that specific company, and alert the territory owner via Slack.
+
+### 69. Data-Driven Sales Enablement Lead
+You're a data-driven Sales Enablement Lead. Continuously analyze the reply rates and open rates of our active Outreach.io sequences across all 50 sales reps. Once a specific subject line or email template drops below a 2% conversion rate, automatically pause it. Generate 3 new variations based on the current highest-performing templates, deploy them as an A/B test, and report the winner after 500 sends.
+
+### 70. Proactive Customer Success Director
+You're a proactive Customer Success Director. Run continuously to monitor daily product telemetry. If an enterprise account's core feature usage drops by more than 15% week-over-week, or if their key champion stops logging in entirely, instantly change their CRM health score to 'Red'. Automatically draft an urgent check-in email for the Account Manager, prepopulated with their latest usage charts.
+
+---
+
+## Operations & Analytics
+
+### 71. Ruthless Competitive Intelligence Analyst
+You're a ruthless Competitive Intelligence Analyst. Every morning at 6 AM, crawl the pricing pages and feature matrices of our top 5 direct competitors. If any competitor introduces a price hike or moves a premium feature behind a higher paywall, immediately extract the changes. Draft a competitive battlecard for the sales team and queue an email campaign to our lost-deal pipeline highlighting our price stability.
+
+### 72. Objective Sales Strategy Ops Manager
+You're an objective Sales Strategy Ops Manager. On the 1st of every month, analyze the pipeline generated, win rates, and total addressable market (TAM) exhaustion across all sales territories. If any rep's territory falls below 20% untouched ICP accounts, automatically pull from unassigned geographical pools to rebalance their book of business, ensuring equitable quota attainment opportunities, and log the changes in Salesforce.
+
+### 73. Organized Account Manager
+You're an organized Account Manager. Continuously monitor the CRM for enterprise contracts expiring in exactly 90 days. Automatically generate a personalized 'Year in Review' slide deck utilizing their specific usage metrics and ROI calculations. Draft an email to the economic buyer proposing a renewal with a 5% price increase, and attach the presentation for the assigned rep to review and send.
+
+### 74. Highly Connected Channel Sales Manager
+You're a highly connected Channel Sales Manager. Monitor new signups in our partner portal 24/7. When a new system integrator registers, scan their website for their certified tech stacks. Automatically match them with our mutual overlapping prospects in the CRM, draft a joint go-to-market proposal, and email it to the partner to accelerate co-selling.
+
+### 75. Brilliant Deal Desk Engineer
+You're a brilliant Deal Desk Engineer. Whenever an RFP or Security Questionnaire is uploaded to our shared drive, instantly ingest the document. Spawn a swarm of agents to query our internal engineering, legal, and security knowledge bases. Automatically fill out 80% of the standard questions, highlight any non-standard compliance requirements in red for human review, and format the output to match the prospect's exact template.
+
+### 76. Polite Accounts Receivable Clerk
+You're a polite but persistent Accounts Receivable Clerk. Monitor the ERP billing module continuously. For any invoice that hits 3 days past due, automatically send a gentle reminder email with a direct payment link. At 15 days past due, escalate the tone and CC the assigned Account Executive. At 30 days past due, automatically restrict the client's software access via API and notify the CFO.
+
+### 77. Elite Performance Marketer
+You're an elite Performance Marketer. Continuously monitor our Google Ads and LinkedIn Ads accounts. If the Cost Per Acquisition (CPA) on a specific campaign exceeds our $150 threshold for more than 4 hours, automatically pause the ad. Reallocate that daily budget to the top 3 highest-performing campaigns currently operating below target CPA, maximizing our daily ad ROI.
+
+### 78. Technical SEO Master
+You're a technical SEO Master. Run a continuous loop across our corporate blog and documentation sites. Whenever a new piece of content is published, automatically scan our existing database of 2,000 articles. Find the 5 most contextually relevant older posts and automatically inject natural anchor-text links pointing to the new article to instantly boost its search engine indexing.
+
+### 79. Attentive Brand Manager
+You're an attentive Brand Manager. Monitor G2, Capterra, and Twitter 24/7 for positive mentions or 5-star reviews of our product. Whenever one is posted, automatically extract the quote, format it into an approved branded graphic using a Figma API integration, and schedule it to be posted across our corporate social media channels within 48 hours.
+
+### 80. Prolific Content Marketer
+You're a prolific Content Marketer. Whenever our CEO publishes a new long-form thought leadership article on the blog, instantly ingest it. Automatically slice the core arguments into a 5-part LinkedIn text post series, a Twitter thread consisting of 8 tweets, and a script for a 60-second YouTube Short, scheduling them in Buffer for drip release over the next two weeks.
+
+### 81. Tactical Search Engine Marketer
+You're a tactical Search Engine Marketer. Continuously monitor the Google search results for our top 20 most valuable non-branded keywords. If a competitor suddenly outranks us or launches a new aggressive paid ad campaign on those terms, instantly alert the marketing team and automatically increase our exact-match bidding strategy by 15% to maintain the top position.
+
+### 82. Analytical Email Marketing Ops Lead
+You're an analytical Email Marketing Ops Lead. Continuously monitor our Marketo database. Identify any subscribers who have not opened our weekly newsletter in 6 months. Automatically add them to a 3-part 'breakup' re-engagement campaign. If they still do not engage, automatically scrub them from our database to protect our domain sending reputation and reduce our SaaS contact limits.
+
+### 83. Proactive Event Marketer
+You're a proactive Event Marketer. Following the conclusion of our weekly live product demo, immediately ingest the attendee list and chat logs. Automatically sort attendees into tiers: those who asked pricing questions get immediately routed to an AE; those who stayed the whole time get a 'next steps' email; those who left early get a link to the recording.
+
+### 84. Precise Partner Marketing Manager
+You're a precise Partner Marketing Manager. Continuously monitor tracking links from our affiliate network. Cross-reference the referred signups with our Stripe billing system to ensure the referred customer actually paid and didn't immediately churn or request a refund. Automatically calculate and approve valid monthly commission payouts, blocking fraudulent click-farm traffic.
+
+### 85. Hyper-Vigilant Customer Support Dispatcher
+You're a hyper-vigilant Customer Support Dispatcher. Continuously monitor the Zendesk inbound queue. Cross-reference every incoming ticket email against our Salesforce CRM. If the ticket is from an account paying over $100k ARR, or an account currently in the 'Renewal' stage, automatically tag it 'Priority 1', bypass the standard queue, and text the dedicated Customer Success Manager directly.
+
+### 86. Analytical Product Operations Manager
+You're an analytical Product Operations Manager. Ingest all closed support tickets, sales loss reasons, and user feedback forms continuously. Use natural language processing to cluster similar feature requests. Update a live dashboard showing the engineering team exactly which missing features are causing the most churn, quantified by the actual ARR tied to those requests.
+
+### 87. Diligent Technical Support Writer
+You're a diligent Technical Support Writer. Continuously monitor the resolutions of closed Tier 3 technical support tickets. When a support engineer writes a detailed workaround for a novel bug or configuration issue, automatically extract the steps, format it into a standardized Help Center article, and submit it to the documentation repository for approval.
+
+### 88. Data-Obsessed Product Manager
+You're a data-obsessed Product Manager. Continuously monitor product telemetry for newly signed-up cohorts. Track their progression through our 5-step onboarding funnel. If a statistically significant percentage of users get stuck at step 3 (e.g., database integration), automatically alert the UX team and trigger an automated in-app chat prompt offering a live setup session for users stalled at that step.
+
+### 89. Zero-Trust IT Administrator
+You're a zero-trust IT Administrator. Run a continuous loop hooked into the HRIS (Workday/Gusto). The precise second an employee's termination status is logged by HR, automatically trigger a script to instantly revoke their Okta SSO access, wipe their mobile device via MDM, transfer their Google Drive files to their manager, and lock their physical keycard access.
+
+### 90. Polyglot Support Specialist
+You're a polyglot Support Specialist. Continuously intercept inbound support chats originating from non-English speaking regions. Instantly translate the user's query into English for our tier-1 support staff. When the staff member replies in English, instantly translate it back into the user's native language using localized idioms and a polite tone, ensuring zero friction in global support.
+
+### 91. Ultra-Responsive Public Relations Bot
+You're an ultra-responsive Public Relations Bot. Monitor Reddit, HackerNews, and Quora 24/7 for discussions containing our brand name or our core value proposition. If a user asks a technical question or complains about a bug, instantly draft a helpful, non-salesy response with links to our documentation, placing it in a Slack channel for the community manager to approve and post.
+
+---
+
+## Engineering & DevOps
+
+### 92. Best Site Reliability Engineer (SRE)
+You're the best Site Reliability Engineer (SRE). Deploy a swarm of 5 agents to our staging Kubernetes cluster to conduct chaos testing. Randomly terminate non-critical pods, throttle network latency by 200ms on the API gateway, and monitor the system's auto-recovery over 30 minutes. Aggregate the Datadog logs, identify the single points of failure, and draft a resilient infrastructure Terraform PR to patch the discovered weaknesses.
+
+### 93. Elite Staff Software Engineer
+You're an elite Staff Software Engineer specializing in system modernization. Ingest this monolithic legacy COBOL codebase. Translate the core billing logic into modular Go microservices. You must retain all edge-case business logic, enforce strict typing, generate a complete suite of unit tests with at least 90% coverage, and output a Docker-compose file so I can spin up the new architecture locally.
+
+### 94. Strictest Tech Lead
+You're the strictest, most helpful Tech Lead. Monitor the Aden Hive main repository. For every incoming Pull Request, read the diff and analyze it for security vulnerabilities, cyclomatic complexity, and adherence to our style guide. Automatically reject any PR that drops overall test coverage below 85%, and leave inline comments with exact refactoring suggestions for any function longer than 40 lines.
+
+### 95. Paranoid DevSecOps Specialist
+You're a paranoid DevSecOps specialist. Continuously monitor the National Vulnerability Database (NVD) and GitHub security advisories for zero-day exploits related to our package.json dependencies. The moment a critical vulnerability is published, automatically spin up an agent to bump the package version, run the full integration test suite, and if it passes, deploy the hotfix directly to production while alerting the engineering channel.
+
+### 96. Expert Developer Advocate
+You're an expert Developer Advocate and Technical Writer. Read our newly committed Python repository. Generate comprehensive API documentation, extract inline code comments to build a clean MkDocs site, and create Mermaid.js sequence diagrams for the core authentication and payment flows. Finally, write a 'Quick Start' README that a junior developer could follow in under 5 minutes.
+
+### 97. Meticulous Enterprise IT Auditor
+You're a meticulous Enterprise IT Auditor. Scan our enterprise network logs and ping the Expensify API to extract all employee software subscription reimbursements over the last 90 days. Cross-reference these against our officially sanctioned ERP software directory to identify 'Shadow IT'. Output a consolidated spreadsheet of unauthorized tools, their monthly spend, and draft a polite email to each employee suggesting the equivalent internal ERP module they should use instead.
+
+---
+
+## Finance & ERP
+
+### 98. Eagle-Eyed Financial Controller
+You're an eagle-eyed Financial Controller. Monitor the invoices@ inbox. Extract line-item data from incoming unstructured PDF invoices using OCR. Cross-reference the extracted data (vendor, amounts, SKUs) against the approved Purchase Orders in our ERP system. Automatically approve and route exact matches for payment. For any invoice with a price discrepancy greater than 5%, flag it, highlight the specific mismatched row, and route it to the respective department head for review.
+
+### 99. Proactive Supply Chain Manager
+You're a proactive Supply Chain Manager. Analyze our historical ERP seasonal sales data, current warehouse inventory levels, and real-time supplier lead times via their APIs. If our projected 'safety stock' for any top-20 SKU drops below 15 days of runway, automatically draft a new Purchase Order in the ERP system, calculate the optimal freight route based on current spot rates, and queue it for my final approval.
+
+### 100. Meticulous Payroll Compliance Manager
+You're a meticulous Payroll Compliance Manager. Monitor daily state and federal tax law changes. Automatically audit our ERP's payroll settings and employee location data for our remote workforce across all 50 states. Flag any non-compliance risks regarding state income tax withholdings or localized labor laws, and generate a step-by-step remediation checklist for the HR team.
+
+---
+
+## Usage Notes
+
+These prompts are designed as starting points for building specialized AI agents. When implementing:
+
+1. **Adapt to your specific context**: Replace placeholder tools, APIs, and systems with your actual stack
+2. **Set appropriate boundaries**: Add rate limits, approval workflows, and human-in-the-loop checkpoints
+3. **Ensure compliance**: Review all prompts for legal, ethical, and platform ToS compliance
+4. **Test incrementally**: Start with read-only monitoring before enabling write operations
+5. **Monitor continuously**: Track agent performance, error rates, and user feedback
+
+For implementation guidance, refer to the [templates](../templates/) directory for code scaffolds.

examples/recipes/social_media_management/README.md

@@ -1,34 +0,0 @@
-# Recipe: Social Media Management
-
-Scheduling posts, replying to comments, and monitoring trends.
-
-## Why
-
-Consistency kills on social media — but it also kills your time. One "quick post" turns into an hour of tweaking copy, finding hashtags, and responding to comments. This agent maintains your social presence so you stay visible without staying glued to your phone.
-
-## What
-
-- Schedule posts across platforms (Twitter/X, LinkedIn, Instagram, Facebook)
-- Reply to comments and DMs with on-brand responses
-- Monitor trending topics and hashtags in your niche
-- Track engagement metrics and surface what's working
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Buffer / Hootsuite / Later | Post scheduling and publishing |
-| Twitter/X API | Direct posting and engagement |
-| LinkedIn API | Professional network management |
-| Meta Graph API | Facebook/Instagram management |
-| Slack | Notifications and escalations |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Post goes viral (>10x normal engagement) | Alert with engagement stats and suggested follow-up content |
-| Negative viral moment | Immediate alert — do NOT auto-respond, queue for human review |
-| Influencer or press mentions you | Flag for personal response opportunity |
-| Controversial topic trending in your space | Alert before posting scheduled content that might be tone-deaf |
-| DM from verified account or known lead | Route directly to you |

examples/recipes/support_troubleshooting/README.md

@@ -1,37 +0,0 @@
-# Recipe: Support Troubleshooting
-
-Handling "Level 1" tech support for your platform or website.
-
-## Why
-
-Most support tickets are the same 20 questions over and over: password resets, access issues, "how do I..." questions. You don't need to answer these — but someone does. This agent handles the repetitive tier-1 support so your users get fast answers and you get your time back.
-
-## What
-
-- Handle password resets and account access issues
-- Answer common "how do I" questions from the knowledge base
-- Walk users through basic setup and configuration
-- Collect diagnostic information for complex issues
-- Log all support interactions for pattern analysis
-
-## Integrations
-
-| Platform | Purpose |
-|----------|---------|
-| Intercom / Zendesk / Freshdesk | Support ticket management |
-| Notion / Confluence | Knowledge base for answers |
-| Slack | Internal escalation channel |
-| Your product's API | Account status, password reset triggers |
-| LogRocket / FullStory | Session replay for debugging |
-| PagerDuty | Urgent escalation routing |
-
-## Escalation Path
-
-| Trigger | Action |
-|---------|--------|
-| Issue not resolved within 30 minutes | Escalate with full context gathered |
-| User expresses frustration or anger | Immediate handoff to human with de-escalation note |
-| Security-related issue (account compromise, data concern) | Escalate immediately, do not attempt to resolve |
-| Bug discovered during troubleshooting | Create ticket and escalate to engineering |
-| VIP or enterprise customer | Flag for priority handling regardless of issue |
-| Same issue reported by 3+ users | Alert as potential systemic problem |

quickstart.ps1

@@ -911,6 +911,13 @@ $zaiKey = [System.Environment]::GetEnvironmentVariable("ZAI_API_KEY", "User")
 if (-not $zaiKey) { $zaiKey = $env:ZAI_API_KEY }
 if ($zaiKey) { $ZaiCredDetected = $true }
 
+$KimiCredDetected = $false
+$kimiConfigPath = Join-Path $env:USERPROFILE ".kimi\config.toml"
+if (Test-Path $kimiConfigPath) { $KimiCredDetected = $true }
+$kimiKey = [System.Environment]::GetEnvironmentVariable("KIMI_API_KEY", "User")
+if (-not $kimiKey) { $kimiKey = $env:KIMI_API_KEY }
+if ($kimiKey) { $KimiCredDetected = $true }
+
 # Detect API key providers
 $ProviderMenuEnvVars  = @("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GROQ_API_KEY", "CEREBRAS_API_KEY")
 $ProviderMenuNames    = @("Anthropic (Claude) - Recommended", "OpenAI (GPT)", "Google Gemini - Free tier available", "Groq - Fast, free tier", "Cerebras - Fast, free tier")
@@ -938,7 +945,9 @@ if (Test-Path $HiveConfigFile) {
             $PrevEnvVar = if ($prevLlm.api_key_env_var) { $prevLlm.api_key_env_var } else { "" }
             if ($prevLlm.use_claude_code_subscription) { $PrevSubMode = "claude_code" }
             elseif ($prevLlm.use_codex_subscription) { $PrevSubMode = "codex" }
+            elseif ($prevLlm.use_kimi_code_subscription) { $PrevSubMode = "kimi_code" }
             elseif ($prevLlm.api_base -and $prevLlm.api_base -like "*api.z.ai*") { $PrevSubMode = "zai_code" }
+            elseif ($prevLlm.api_base -and $prevLlm.api_base -like "*api.kimi.com*") { $PrevSubMode = "kimi_code" }
         }
     } catch { }
 }
@@ -951,6 +960,7 @@ if ($PrevSubMode -or $PrevProvider) {
         "claude_code" { if ($ClaudeCredDetected) { $prevCredValid = $true } }
         "zai_code"    { if ($ZaiCredDetected)    { $prevCredValid = $true } }
         "codex"       { if ($CodexCredDetected)  { $prevCredValid = $true } }
+        "kimi_code"   { if ($KimiCredDetected)   { $prevCredValid = $true } }
         default {
             if ($PrevEnvVar) {
                 $envVal = [System.Environment]::GetEnvironmentVariable($PrevEnvVar, "Process")
@@ -964,14 +974,16 @@ if ($PrevSubMode -or $PrevProvider) {
             "claude_code" { $DefaultChoice = "1" }
             "zai_code"    { $DefaultChoice = "2" }
             "codex"       { $DefaultChoice = "3" }
+            "kimi_code"   { $DefaultChoice = "4" }
         }
         if (-not $DefaultChoice) {
             switch ($PrevProvider) {
-                "anthropic" { $DefaultChoice = "4" }
-                "openai"    { $DefaultChoice = "5" }
-                "gemini"    { $DefaultChoice = "6" }
-                "groq"      { $DefaultChoice = "7" }
-                "cerebras"  { $DefaultChoice = "8" }
+                "anthropic" { $DefaultChoice = "5" }
+                "openai"    { $DefaultChoice = "6" }
+                "gemini"    { $DefaultChoice = "7" }
+                "groq"      { $DefaultChoice = "8" }
+                "cerebras"  { $DefaultChoice = "9" }
+                "kimi"      { $DefaultChoice = "4" }
             }
         }
     }
@@ -1003,12 +1015,19 @@ Write-Host ") OpenAI Codex Subscription  " -NoNewline
 Write-Color -Text "(use your Codex/ChatGPT Plus plan)" -Color DarkGray -NoNewline
 if ($CodexCredDetected) { Write-Color -Text "  (credential detected)" -Color Green } else { Write-Host "" }
 
+# 4) Kimi Code
+Write-Host "  " -NoNewline
+Write-Color -Text "4" -Color Cyan -NoNewline
+Write-Host ") Kimi Code Subscription     " -NoNewline
+Write-Color -Text "(use your Kimi Code plan)" -Color DarkGray -NoNewline
+if ($KimiCredDetected) { Write-Color -Text "  (credential detected)" -Color Green } else { Write-Host "" }
+
 Write-Host ""
 Write-Color -Text "  API key providers:" -Color Cyan
 
-# 4-8) API key providers
+# 5-9) API key providers
 for ($idx = 0; $idx -lt $ProviderMenuEnvVars.Count; $idx++) {
-    $num = $idx + 4
+    $num = $idx + 5
     $envVal = [System.Environment]::GetEnvironmentVariable($ProviderMenuEnvVars[$idx], "Process")
     if (-not $envVal) { $envVal = [System.Environment]::GetEnvironmentVariable($ProviderMenuEnvVars[$idx], "User") }
     Write-Host "  " -NoNewline
@@ -1018,7 +1037,7 @@ for ($idx = 0; $idx -lt $ProviderMenuEnvVars.Count; $idx++) {
 }
 
 Write-Host "  " -NoNewline
-Write-Color -Text "9" -Color Cyan -NoNewline
+Write-Color -Text "10" -Color Cyan -NoNewline
 Write-Host ") Skip for now"
 Write-Host ""
 
@@ -1029,16 +1048,16 @@ if ($DefaultChoice) {
 
 while ($true) {
     if ($DefaultChoice) {
-        $raw = Read-Host "Enter choice (1-9) [$DefaultChoice]"
+        $raw = Read-Host "Enter choice (1-10) [$DefaultChoice]"
         if ([string]::IsNullOrWhiteSpace($raw)) { $raw = $DefaultChoice }
     } else {
-        $raw = Read-Host "Enter choice (1-9)"
+        $raw = Read-Host "Enter choice (1-10)"
     }
     if ($raw -match '^\d+$') {
         $num = [int]$raw
-        if ($num -ge 1 -and $num -le 9) { break }
+        if ($num -ge 1 -and $num -le 10) { break }
     }
-    Write-Color -Text "Invalid choice. Please enter 1-9" -Color Red
+    Write-Color -Text "Invalid choice. Please enter 1-10" -Color Red
 }
 
 switch ($num) {
@@ -1102,9 +1121,20 @@ switch ($num) {
             Write-Ok "Using OpenAI Codex subscription"
         }
     }
-    { $_ -ge 4 -and $_ -le 8 } {
+    4 {
+        # Kimi Code Subscription
+        $SubscriptionMode   = "kimi_code"
+        $SelectedProviderId = "kimi"
+        $SelectedEnvVar     = "KIMI_API_KEY"
+        $SelectedModel      = "kimi-k2.5"
+        $SelectedMaxTokens  = 32768
+        Write-Host ""
+        Write-Ok "Using Kimi Code subscription"
+        Write-Color -Text "  Model: kimi-k2.5 | API: api.kimi.com/coding" -Color DarkGray
+    }
+    { $_ -ge 5 -and $_ -le 9 } {
         # API key providers
-        $provIdx = $num - 4
+        $provIdx = $num - 5
         $SelectedEnvVar     = $ProviderMenuEnvVars[$provIdx]
         $SelectedProviderId = $ProviderMenuIds[$provIdx]
         $providerName       = $ProviderMenuNames[$provIdx] -replace ' - .*', ''  # strip description
@@ -1175,7 +1205,7 @@ switch ($num) {
             }
         }
     }
-    9 {
+    10 {
         Write-Host ""
         Write-Warn "Skipped. An LLM API key is required to test and use worker agents."
         Write-Host "  Add your API key later by running:"
@@ -1252,6 +1282,70 @@ if ($SubscriptionMode -eq "zai_code") {
     }
 }
 
+# For Kimi Code subscription: prompt for API key with verification + retry
+if ($SubscriptionMode -eq "kimi_code") {
+    while ($true) {
+        $existingKimi = [System.Environment]::GetEnvironmentVariable("KIMI_API_KEY", "User")
+        if (-not $existingKimi) { $existingKimi = $env:KIMI_API_KEY }
+
+        if ($existingKimi) {
+            $masked = $existingKimi.Substring(0, [Math]::Min(4, $existingKimi.Length)) + "..." + $existingKimi.Substring([Math]::Max(0, $existingKimi.Length - 4))
+            Write-Host ""
+            Write-Color -Text "  $([char]0x2B22) Current Kimi key: $masked" -Color Green
+            $apiKey = Read-Host "  Press Enter to keep, or paste a new key to replace"
+        } else {
+            Write-Host ""
+            Write-Host "Get your API key from: " -NoNewline
+            Write-Color -Text "https://www.kimi.com/code" -Color Cyan
+            Write-Host ""
+            $apiKey = Read-Host "Paste your Kimi API key (or press Enter to skip)"
+        }
+
+        if ($apiKey) {
+            [System.Environment]::SetEnvironmentVariable("KIMI_API_KEY", $apiKey, "User")
+            $env:KIMI_API_KEY = $apiKey
+            Write-Host ""
+            Write-Ok "Kimi API key saved as User environment variable"
+
+            # Health check the new key
+            Write-Host "  Verifying Kimi API key... " -NoNewline
+            try {
+                $hcResult = & uv run python (Join-Path $ScriptDir "scripts/check_llm_key.py") "kimi" $apiKey "https://api.kimi.com/coding" 2>$null
+                $hcJson = $hcResult | ConvertFrom-Json
+                if ($hcJson.valid -eq $true) {
+                    Write-Color -Text "ok" -Color Green
+                    break
+                } elseif ($hcJson.valid -eq $false) {
+                    Write-Color -Text "failed" -Color Red
+                    Write-Warn $hcJson.message
+                    [System.Environment]::SetEnvironmentVariable("KIMI_API_KEY", $null, "User")
+                    Remove-Item -Path "Env:\KIMI_API_KEY" -ErrorAction SilentlyContinue
+                    Write-Host ""
+                    Read-Host "  Press Enter to try again"
+                } else {
+                    Write-Color -Text "--" -Color Yellow
+                    Write-Color -Text "  Could not verify key (network issue). The key has been saved." -Color DarkGray
+                    break
+                }
+            } catch {
+                Write-Color -Text "--" -Color Yellow
+                Write-Color -Text "  Could not verify key (network issue). The key has been saved." -Color DarkGray
+                break
+            }
+        } elseif (-not $existingKimi) {
+            Write-Host ""
+            Write-Warn "Skipped. Add your Kimi API key later:"
+            Write-Color -Text "  [System.Environment]::SetEnvironmentVariable('KIMI_API_KEY', 'your-key', 'User')" -Color Cyan
+            $SelectedEnvVar     = ""
+            $SelectedProviderId = ""
+            $SubscriptionMode   = ""
+            break
+        } else {
+            break
+        }
+    }
+}
+
 # Prompt for model if not already selected (manual provider path)
 if ($SelectedProviderId -and -not $SelectedModel) {
     $modelSel = Get-ModelSelection $SelectedProviderId
@@ -1287,6 +1381,9 @@ if ($SelectedProviderId) {
     } elseif ($SubscriptionMode -eq "zai_code") {
         $config.llm["api_base"] = "https://api.z.ai/api/coding/paas/v4"
         $config.llm["api_key_env_var"] = $SelectedEnvVar
+    } elseif ($SubscriptionMode -eq "kimi_code") {
+        $config.llm["api_base"] = "https://api.kimi.com/coding"
+        $config.llm["api_key_env_var"] = $SelectedEnvVar
     } else {
         $config.llm["api_key_env_var"] = $SelectedEnvVar
     }

quickstart.sh

@@ -410,7 +410,7 @@ if [ "$USE_ASSOC_ARRAYS" = true ]; then
     declare -A DEFAULT_MODELS=(
         ["anthropic"]="claude-haiku-4-5-20251001"
         ["openai"]="gpt-5-mini"
-        ["minimax"]="MiniMax-M2.1"
+        ["minimax"]="MiniMax-M2.5"
         ["gemini"]="gemini-3-flash-preview"
         ["groq"]="moonshotai/kimi-k2-instruct-0905"
         ["cerebras"]="zai-glm-4.7"
@@ -466,6 +466,23 @@ if [ "$USE_ASSOC_ARRAYS" = true ]; then
         ["cerebras:1"]=8192
     )
 
+    # Max context tokens (input history budget) per model, based on actual context windows.
+    # Leave ~10% headroom for system prompt and output tokens.
+    declare -A MODEL_CHOICES_MAXCONTEXTTOKENS=(
+        ["anthropic:0"]=180000   # Claude Haiku 4.5 — 200k context window
+        ["anthropic:1"]=180000   # Claude Sonnet 4 — 200k context window
+        ["anthropic:2"]=180000   # Claude Sonnet 4.5 — 200k context window
+        ["anthropic:3"]=180000   # Claude Opus 4.6 — 200k context window
+        ["openai:0"]=120000      # GPT-5 Mini — 128k context window
+        ["openai:1"]=120000      # GPT-5.2 — 128k context window
+        ["gemini:0"]=900000      # Gemini 3 Flash — 1M context window
+        ["gemini:1"]=900000      # Gemini 3.1 Pro — 1M context window
+        ["groq:0"]=120000        # Kimi K2 — 128k context window
+        ["groq:1"]=120000        # GPT-OSS 120B — 128k context window
+        ["cerebras:0"]=120000    # ZAI-GLM 4.7 — 128k context window
+        ["cerebras:1"]=120000    # Qwen3 235B — 128k context window
+    )
+
     declare -A MODEL_CHOICES_COUNT=(
         ["anthropic"]=4
         ["openai"]=2
@@ -502,6 +519,10 @@ if [ "$USE_ASSOC_ARRAYS" = true ]; then
     get_model_choice_maxtokens() {
         echo "${MODEL_CHOICES_MAXTOKENS[$1:$2]}"
     }
+
+    get_model_choice_maxcontexttokens() {
+        echo "${MODEL_CHOICES_MAXCONTEXTTOKENS[$1:$2]}"
+    }
 else
     # Bash 3.2 - use parallel indexed arrays
     PROVIDER_ENV_VARS=(ANTHROPIC_API_KEY OPENAI_API_KEY MINIMAX_API_KEY GEMINI_API_KEY GOOGLE_API_KEY GROQ_API_KEY CEREBRAS_API_KEY MISTRAL_API_KEY TOGETHER_API_KEY DEEPSEEK_API_KEY)
@@ -510,7 +531,7 @@ else
 
     # Default models by provider id (parallel arrays)
     MODEL_PROVIDER_IDS=(anthropic openai minimax gemini groq cerebras mistral together_ai deepseek)
-    MODEL_DEFAULTS=("claude-haiku-4-5-20251001" "gpt-5-mini" "MiniMax-M2.1" "gemini-3-flash-preview" "moonshotai/kimi-k2-instruct-0905" "zai-glm-4.7" "mistral-large-latest" "meta-llama/Llama-3.3-70B-Instruct-Turbo" "deepseek-chat")
+    MODEL_DEFAULTS=("claude-haiku-4-5-20251001" "gpt-5-mini" "MiniMax-M2.5" "gemini-3-flash-preview" "moonshotai/kimi-k2-instruct-0905" "zai-glm-4.7" "mistral-large-latest" "meta-llama/Llama-3.3-70B-Instruct-Turbo" "deepseek-chat")
 
     # Helper: get provider display name for an env var
     get_provider_name() {
@@ -557,6 +578,9 @@ else
     MC_IDS=("claude-haiku-4-5-20251001" "claude-sonnet-4-20250514" "claude-sonnet-4-5-20250929" "claude-opus-4-6" "gpt-5-mini" "gpt-5.2" "gemini-3-flash-preview" "gemini-3.1-pro-preview" "moonshotai/kimi-k2-instruct-0905" "openai/gpt-oss-120b" "zai-glm-4.7" "qwen3-235b-a22b-instruct-2507")
     MC_LABELS=("Haiku 4.5 - Fast + cheap (recommended)" "Sonnet 4 - Fast + capable" "Sonnet 4.5 - Best balance" "Opus 4.6 - Most capable" "GPT-5 Mini - Fast + cheap (recommended)" "GPT-5.2 - Most capable" "Gemini 3 Flash - Fast (recommended)" "Gemini 3.1 Pro - Best quality" "Kimi K2 - Best quality (recommended)" "GPT-OSS 120B - Fast reasoning" "ZAI-GLM 4.7 - Best quality (recommended)" "Qwen3 235B - Frontier reasoning")
     MC_MAXTOKENS=(8192 8192 16384 32768 16384 16384 8192 8192 8192 8192 8192 8192)
+    # Max context tokens per model (same order as MC_PROVIDERS/MC_IDS above)
+    # Based on actual context windows with ~10% headroom for system prompt + output.
+    MC_MAXCONTEXTTOKENS=(180000 180000 180000 180000 120000 120000 900000 900000 120000 120000 120000 120000)
 
     # Helper: get number of model choices for a provider
     get_model_choice_count() {
@@ -625,6 +649,24 @@ else
             i=$((i + 1))
         done
     }
+
+    # Helper: get model choice max_context_tokens by provider and index
+    get_model_choice_maxcontexttokens() {
+        local provider_id="$1"
+        local idx="$2"
+        local count=0
+        local i=0
+        while [ $i -lt ${#MC_PROVIDERS[@]} ]; do
+            if [ "${MC_PROVIDERS[$i]}" = "$provider_id" ]; then
+                if [ $count -eq "$idx" ]; then
+                    echo "${MC_MAXCONTEXTTOKENS[$i]}"
+                    return
+                fi
+                count=$((count + 1))
+            fi
+            i=$((i + 1))
+        done
+    }
 fi
 
 # Configuration directory
@@ -664,7 +706,7 @@ SHELL_RC_FILE=$(detect_shell_rc)
 SHELL_NAME=$(basename "$SHELL")
 
 # Prompt the user to choose a model for their selected provider.
-# Sets SELECTED_MODEL and SELECTED_MAX_TOKENS.
+# Sets SELECTED_MODEL, SELECTED_MAX_TOKENS, and SELECTED_MAX_CONTEXT_TOKENS.
 prompt_model_selection() {
     local provider_id="$1"
     local count
@@ -674,6 +716,7 @@ prompt_model_selection() {
         # No curated choices for this provider (e.g. Mistral, DeepSeek)
         SELECTED_MODEL="$(get_default_model "$provider_id")"
         SELECTED_MAX_TOKENS=8192
+        SELECTED_MAX_CONTEXT_TOKENS=120000  # 128k context window (Mistral, DeepSeek, etc.)
         return
     fi
 
@@ -681,6 +724,7 @@ prompt_model_selection() {
         # Only one choice — auto-select
         SELECTED_MODEL="$(get_model_choice_id "$provider_id" 0)"
         SELECTED_MAX_TOKENS="$(get_model_choice_maxtokens "$provider_id" 0)"
+        SELECTED_MAX_CONTEXT_TOKENS="$(get_model_choice_maxcontexttokens "$provider_id" 0)"
         return
     fi
 
@@ -726,6 +770,7 @@ prompt_model_selection() {
             local idx=$((choice - 1))
             SELECTED_MODEL="$(get_model_choice_id "$provider_id" "$idx")"
             SELECTED_MAX_TOKENS="$(get_model_choice_maxtokens "$provider_id" "$idx")"
+            SELECTED_MAX_CONTEXT_TOKENS="$(get_model_choice_maxcontexttokens "$provider_id" "$idx")"
             echo ""
             echo -e "${GREEN}⬢${NC} Model: ${DIM}$SELECTED_MODEL${NC}"
             return
@@ -735,15 +780,16 @@ prompt_model_selection() {
 }
 
 # Function to save configuration
-# Args: provider_id env_var model max_tokens [use_claude_code_sub] [api_base] [use_codex_sub]
+# Args: provider_id env_var model max_tokens max_context_tokens [use_claude_code_sub] [api_base] [use_codex_sub]
 save_configuration() {
     local provider_id="$1"
     local env_var="$2"
     local model="$3"
     local max_tokens="$4"
-    local use_claude_code_sub="${5:-}"
-    local api_base="${6:-}"
-    local use_codex_sub="${7:-}"
+    local max_context_tokens="$5"
+    local use_claude_code_sub="${6:-}"
+    local api_base="${7:-}"
+    local use_codex_sub="${8:-}"
 
     # Fallbacks if not provided
     if [ -z "$model" ]; then
@@ -752,6 +798,9 @@ save_configuration() {
     if [ -z "$max_tokens" ]; then
         max_tokens=8192
     fi
+    if [ -z "$max_context_tokens" ]; then
+        max_context_tokens=120000
+    fi
 
     mkdir -p "$HIVE_CONFIG_DIR"
 
@@ -762,6 +811,7 @@ config = {
         'provider': '$provider_id',
         'model': '$model',
         'max_tokens': $max_tokens,
+        'max_context_tokens': $max_context_tokens,
         'api_key_env_var': '$env_var'
     },
     'created_at': '$(date -u +"%Y-%m-%dT%H:%M:%S+00:00")'
@@ -796,7 +846,8 @@ FOUND_ENV_VARS=()       # Corresponding env var names
 SELECTED_PROVIDER_ID="" # Will hold the chosen provider ID
 SELECTED_ENV_VAR=""     # Will hold the chosen env var
 SELECTED_MODEL=""       # Will hold the chosen model ID
-SELECTED_MAX_TOKENS=8192 # Will hold the chosen max_tokens
+SELECTED_MAX_TOKENS=8192 # Will hold the chosen max_tokens (output limit)
+SELECTED_MAX_CONTEXT_TOKENS=120000 # Will hold the chosen max_context_tokens (input history budget)
 SUBSCRIPTION_MODE=""    # "claude_code" | "codex" | "zai_code" | ""
 
 # ── Credential detection (silent — just set flags) ───────────
@@ -824,6 +875,13 @@ if [ -n "${MINIMAX_API_KEY:-}" ]; then
     MINIMAX_CRED_DETECTED=true
 fi
 
+KIMI_CRED_DETECTED=false
+if [ -f "$HOME/.kimi/config.toml" ]; then
+    KIMI_CRED_DETECTED=true
+elif [ -n "${KIMI_API_KEY:-}" ]; then
+    KIMI_CRED_DETECTED=true
+fi
+
 # Detect API key providers
 if [ "$USE_ASSOC_ARRAYS" = true ]; then
     for env_var in "${!PROVIDER_NAMES[@]}"; do
@@ -859,6 +917,7 @@ try:
     sub = ''
     if llm.get('use_claude_code_subscription'): sub = 'claude_code'
     elif llm.get('use_codex_subscription'): sub = 'codex'
+    elif llm.get('use_kimi_code_subscription'): sub = 'kimi_code'
     elif llm.get('provider', '') == 'minimax' or 'api.minimax.io' in llm.get('api_base', ''): sub = 'minimax_code'
     elif 'api.z.ai' in llm.get('api_base', ''): sub = 'zai_code'
     print(f'PREV_SUB_MODE={sub}')
@@ -875,6 +934,7 @@ if [ -n "$PREV_SUB_MODE" ] || [ -n "$PREV_PROVIDER" ]; then
         claude_code) [ "$CLAUDE_CRED_DETECTED" = true ] && PREV_CRED_VALID=true ;;
         zai_code)    [ "$ZAI_CRED_DETECTED" = true ] && PREV_CRED_VALID=true ;;
         codex)       [ "$CODEX_CRED_DETECTED" = true ] && PREV_CRED_VALID=true ;;
+        kimi_code)   [ "$KIMI_CRED_DETECTED" = true ] && PREV_CRED_VALID=true ;;
         *)
             # API key provider — check if the env var is set
             if [ -n "$PREV_ENV_VAR" ] && [ -n "${!PREV_ENV_VAR}" ]; then
@@ -889,15 +949,17 @@ if [ -n "$PREV_SUB_MODE" ] || [ -n "$PREV_PROVIDER" ]; then
             zai_code)    DEFAULT_CHOICE=2 ;;
             codex)       DEFAULT_CHOICE=3 ;;
             minimax_code) DEFAULT_CHOICE=4 ;;
+            kimi_code)   DEFAULT_CHOICE=5 ;;
         esac
         if [ -z "$DEFAULT_CHOICE" ]; then
             case "$PREV_PROVIDER" in
-                anthropic) DEFAULT_CHOICE=5 ;;
-                openai)    DEFAULT_CHOICE=6 ;;
-                gemini)    DEFAULT_CHOICE=7 ;;
-                groq)      DEFAULT_CHOICE=8 ;;
-                cerebras)  DEFAULT_CHOICE=9 ;;
+                anthropic) DEFAULT_CHOICE=6 ;;
+                openai)    DEFAULT_CHOICE=7 ;;
+                gemini)    DEFAULT_CHOICE=8 ;;
+                groq)      DEFAULT_CHOICE=9 ;;
+                cerebras)  DEFAULT_CHOICE=10 ;;
                 minimax)   DEFAULT_CHOICE=4 ;;
+                kimi)      DEFAULT_CHOICE=5 ;;
             esac
         fi
     fi
@@ -936,14 +998,21 @@ else
     echo -e "  ${CYAN}4)${NC} MiniMax Coding Key         ${DIM}(use your MiniMax coding key)${NC}"
 fi
 
+# 5) Kimi Code
+if [ "$KIMI_CRED_DETECTED" = true ]; then
+    echo -e "  ${CYAN}5)${NC} Kimi Code Subscription     ${DIM}(use your Kimi Code plan)${NC}  ${GREEN}(credential detected)${NC}"
+else
+    echo -e "  ${CYAN}5)${NC} Kimi Code Subscription     ${DIM}(use your Kimi Code plan)${NC}"
+fi
+
 echo ""
 echo -e "  ${CYAN}${BOLD}API key providers:${NC}"
 
-# 5-9) API key providers — show (credential detected) if key already set
+# 6-10) API key providers — show (credential detected) if key already set
 PROVIDER_MENU_ENVS=(ANTHROPIC_API_KEY OPENAI_API_KEY GEMINI_API_KEY GROQ_API_KEY CEREBRAS_API_KEY)
 PROVIDER_MENU_NAMES=("Anthropic (Claude) - Recommended" "OpenAI (GPT)" "Google Gemini - Free tier available" "Groq - Fast, free tier" "Cerebras - Fast, free tier")
 for idx in 0 1 2 3 4; do
-    num=$((idx + 5))
+    num=$((idx + 6))
     env_var="${PROVIDER_MENU_ENVS[$idx]}"
     if [ -n "${!env_var}" ]; then
         echo -e "  ${CYAN}$num)${NC} ${PROVIDER_MENU_NAMES[$idx]}  ${GREEN}(credential detected)${NC}"
@@ -952,7 +1021,7 @@ for idx in 0 1 2 3 4; do
     fi
 done
 
-echo -e "  ${CYAN}10)${NC} Skip for now"
+echo -e "  ${CYAN}11)${NC} Skip for now"
 echo ""
 
 if [ -n "$DEFAULT_CHOICE" ]; then
@@ -962,15 +1031,15 @@ fi
 
 while true; do
     if [ -n "$DEFAULT_CHOICE" ]; then
-        read -r -p "Enter choice (1-10) [$DEFAULT_CHOICE]: " choice || true
+        read -r -p "Enter choice (1-11) [$DEFAULT_CHOICE]: " choice || true
         choice="${choice:-$DEFAULT_CHOICE}"
     else
-        read -r -p "Enter choice (1-10): " choice || true
+        read -r -p "Enter choice (1-11): " choice || true
     fi
-    if [[ "$choice" =~ ^[0-9]+$ ]] && [ "$choice" -ge 1 ] && [ "$choice" -le 10 ]; then
+    if [[ "$choice" =~ ^[0-9]+$ ]] && [ "$choice" -ge 1 ] && [ "$choice" -le 11 ]; then
         break
     fi
-    echo -e "${RED}Invalid choice. Please enter 1-10${NC}"
+    echo -e "${RED}Invalid choice. Please enter 1-11${NC}"
 done
 
 case $choice in
@@ -988,6 +1057,7 @@ case $choice in
             SELECTED_PROVIDER_ID="anthropic"
             SELECTED_MODEL="claude-opus-4-6"
             SELECTED_MAX_TOKENS=32768
+            SELECTED_MAX_CONTEXT_TOKENS=180000  # Claude — 200k context window
             echo ""
             echo -e "${GREEN}⬢${NC} Using Claude Code subscription"
         fi
@@ -999,6 +1069,7 @@ case $choice in
         SELECTED_ENV_VAR="ZAI_API_KEY"
         SELECTED_MODEL="glm-5"
         SELECTED_MAX_TOKENS=32768
+        SELECTED_MAX_CONTEXT_TOKENS=120000  # GLM-5 — 128k context window
         PROVIDER_NAME="ZAI"
         echo ""
         echo -e "${GREEN}⬢${NC} Using ZAI Code subscription"
@@ -1029,6 +1100,7 @@ case $choice in
             SELECTED_PROVIDER_ID="openai"
             SELECTED_MODEL="gpt-5.3-codex"
             SELECTED_MAX_TOKENS=16384
+            SELECTED_MAX_CONTEXT_TOKENS=120000  # GPT Codex — 128k context window
             echo ""
             echo -e "${GREEN}⬢${NC} Using OpenAI Codex subscription"
         fi
@@ -1038,46 +1110,62 @@ case $choice in
         SUBSCRIPTION_MODE="minimax_code"
         SELECTED_ENV_VAR="MINIMAX_API_KEY"
         SELECTED_PROVIDER_ID="minimax"
-        SELECTED_MODEL="MiniMax-M2.1"
-        SELECTED_MAX_TOKENS=8192
+        SELECTED_MODEL="MiniMax-M2.5"
+        SELECTED_MAX_TOKENS=32768
+        SELECTED_MAX_CONTEXT_TOKENS=900000  # MiniMax M2.5 — 1M context window
         SELECTED_API_BASE="https://api.minimax.io/v1"
         PROVIDER_NAME="MiniMax"
         SIGNUP_URL="https://platform.minimax.io/user-center/basic-information/interface-key"
         echo ""
         echo -e "${GREEN}⬢${NC} Using MiniMax coding key"
-        echo -e "  ${DIM}Model: MiniMax-M2.1 | API: api.minimax.io${NC}"
+        echo -e "  ${DIM}Model: MiniMax-M2.5 | API: api.minimax.io${NC}"
         ;;
     5)
+        # Kimi Code Subscription
+        SUBSCRIPTION_MODE="kimi_code"
+        SELECTED_PROVIDER_ID="kimi"
+        SELECTED_ENV_VAR="KIMI_API_KEY"
+        SELECTED_MODEL="kimi-k2.5"
+        SELECTED_MAX_TOKENS=32768
+        SELECTED_MAX_CONTEXT_TOKENS=120000  # Kimi K2.5 — 128k context window
+        SELECTED_API_BASE="https://api.kimi.com/coding"
+        PROVIDER_NAME="Kimi"
+        SIGNUP_URL="https://www.kimi.com/code"
+        echo ""
+        echo -e "${GREEN}⬢${NC} Using Kimi Code subscription"
+        echo -e "  ${DIM}Model: kimi-k2.5 | API: api.kimi.com/coding${NC}"
+        ;;
+    6)
         SELECTED_ENV_VAR="ANTHROPIC_API_KEY"
         SELECTED_PROVIDER_ID="anthropic"
         PROVIDER_NAME="Anthropic"
         SIGNUP_URL="https://console.anthropic.com/settings/keys"
         ;;
-    6)
+    7)
         SELECTED_ENV_VAR="OPENAI_API_KEY"
         SELECTED_PROVIDER_ID="openai"
         PROVIDER_NAME="OpenAI"
         SIGNUP_URL="https://platform.openai.com/api-keys"
         ;;
-    7)
+    8)
         SELECTED_ENV_VAR="GEMINI_API_KEY"
         SELECTED_PROVIDER_ID="gemini"
         PROVIDER_NAME="Google Gemini"
         SIGNUP_URL="https://aistudio.google.com/apikey"
         ;;
-    8)
+    9)
         SELECTED_ENV_VAR="GROQ_API_KEY"
         SELECTED_PROVIDER_ID="groq"
         PROVIDER_NAME="Groq"
         SIGNUP_URL="https://console.groq.com/keys"
         ;;
-    9)
+    10)
         SELECTED_ENV_VAR="CEREBRAS_API_KEY"
         SELECTED_PROVIDER_ID="cerebras"
         PROVIDER_NAME="Cerebras"
         SIGNUP_URL="https://cloud.cerebras.ai/"
         ;;
-    10)
+    11)
         echo ""
         echo -e "${YELLOW}Skipped.${NC} An LLM API key is required to test and use worker agents."
         echo -e "Add your API key later by running:"
@@ -1090,7 +1178,7 @@ case $choice in
 esac
 
 # For API-key providers: prompt for key (allow replacement if already set)
-if { [ -z "$SUBSCRIPTION_MODE" ] || [ "$SUBSCRIPTION_MODE" = "minimax_code" ]; } && [ -n "$SELECTED_ENV_VAR" ]; then
+if { [ -z "$SUBSCRIPTION_MODE" ] || [ "$SUBSCRIPTION_MODE" = "minimax_code" ] || [ "$SUBSCRIPTION_MODE" = "kimi_code" ]; } && [ -n "$SELECTED_ENV_VAR" ]; then
     while true; do
         CURRENT_KEY="${!SELECTED_ENV_VAR}"
         if [ -n "$CURRENT_KEY" ]; then
@@ -1118,7 +1206,7 @@ if { [ -z "$SUBSCRIPTION_MODE" ] || [ "$SUBSCRIPTION_MODE" = "minimax_code" ]; }
             echo -e "${GREEN}⬢${NC} API key saved to $SHELL_RC_FILE"
             # Health check the new key
             echo -n "  Verifying API key... "
-            if [ "$SUBSCRIPTION_MODE" = "minimax_code" ] && [ -n "${SELECTED_API_BASE:-}" ]; then
+            if { [ "$SUBSCRIPTION_MODE" = "minimax_code" ] || [ "$SUBSCRIPTION_MODE" = "kimi_code" ]; } && [ -n "${SELECTED_API_BASE:-}" ]; then
                 HC_RESULT=$(uv run python "$SCRIPT_DIR/scripts/check_llm_key.py" "$SELECTED_PROVIDER_ID" "$API_KEY" "$SELECTED_API_BASE" 2>/dev/null) || true
             else
                 HC_RESULT=$(uv run python "$SCRIPT_DIR/scripts/check_llm_key.py" "$SELECTED_PROVIDER_ID" "$API_KEY" 2>/dev/null) || true
@@ -1231,15 +1319,17 @@ if [ -n "$SELECTED_PROVIDER_ID" ]; then
     echo ""
     echo -n "  Saving configuration... "
     if [ "$SUBSCRIPTION_MODE" = "claude_code" ]; then
-        save_configuration "$SELECTED_PROVIDER_ID" "" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "true" "" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "true" "" > /dev/null
     elif [ "$SUBSCRIPTION_MODE" = "codex" ]; then
-        save_configuration "$SELECTED_PROVIDER_ID" "" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "" "" "true" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "" "" "true" > /dev/null
     elif [ "$SUBSCRIPTION_MODE" = "zai_code" ]; then
-        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "" "https://api.z.ai/api/coding/paas/v4" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "" "https://api.z.ai/api/coding/paas/v4" > /dev/null
     elif [ "$SUBSCRIPTION_MODE" = "minimax_code" ]; then
-        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "" "$SELECTED_API_BASE" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "" "$SELECTED_API_BASE" > /dev/null
+    elif [ "$SUBSCRIPTION_MODE" = "kimi_code" ]; then
+        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" "" "$SELECTED_API_BASE" > /dev/null
     else
-        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" > /dev/null
+        save_configuration "$SELECTED_PROVIDER_ID" "$SELECTED_ENV_VAR" "$SELECTED_MODEL" "$SELECTED_MAX_TOKENS" "$SELECTED_MAX_CONTEXT_TOKENS" > /dev/null
     fi
     echo -e "${GREEN}⬢${NC}"
     echo -e "  ${DIM}~/.hive/configuration.json${NC}"

scripts/check_llm_key.py

@@ -56,6 +56,53 @@ def check_openai_compatible(api_key: str, endpoint: str, name: str) -> dict:
     return {"valid": False, "message": f"{name} API returned status {r.status_code}"}
 
 
+def check_minimax(
+    api_key: str, api_base: str = "https://api.minimax.io/v1", **_: str
+) -> dict:
+    """Validate via chatcompletion_v2 endpoint with empty messages.
+
+    MiniMax doesn't support GET /models; their native endpoint is
+    /v1/text/chatcompletion_v2.
+    """
+    with httpx.Client(timeout=TIMEOUT) as client:
+        r = client.post(
+            f"{api_base.rstrip('/')}/text/chatcompletion_v2",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            json={"model": "MiniMax-M2.5", "messages": []},
+        )
+    if r.status_code in (200, 400, 422, 429):
+        return {"valid": True, "message": "MiniMax API key valid"}
+    if r.status_code == 401:
+        return {"valid": False, "message": "Invalid MiniMax API key"}
+    if r.status_code == 403:
+        return {"valid": False, "message": "MiniMax API key lacks permissions"}
+    return {"valid": False, "message": f"MiniMax API returned status {r.status_code}"}
+
+
+def check_anthropic_compatible(api_key: str, endpoint: str, name: str) -> dict:
+    """POST empty messages to an Anthropic-compatible endpoint to validate key."""
+    with httpx.Client(timeout=TIMEOUT) as client:
+        r = client.post(
+            endpoint,
+            headers={
+                "x-api-key": api_key,
+                "anthropic-version": "2023-06-01",
+                "Content-Type": "application/json",
+            },
+            json={"model": "kimi-k2.5", "max_tokens": 1, "messages": []},
+        )
+    if r.status_code in (200, 400, 429):
+        return {"valid": True, "message": f"{name} API key valid"}
+    if r.status_code == 401:
+        return {"valid": False, "message": f"Invalid {name} API key"}
+    if r.status_code == 403:
+        return {"valid": False, "message": f"{name} API key lacks permissions"}
+    return {"valid": False, "message": f"{name} API returned status {r.status_code}"}
+
+
 def check_gemini(api_key: str, **_: str) -> dict:
     """List models with query param auth."""
     with httpx.Client(timeout=TIMEOUT) as client:
@@ -82,8 +129,11 @@ PROVIDERS = {
     "cerebras": lambda key, **kw: check_openai_compatible(
         key, "https://api.cerebras.ai/v1/models", "Cerebras"
     ),
-    "minimax": lambda key, **kw: check_openai_compatible(
-        key, "https://api.minimax.io/v1/models", "MiniMax"
+    "minimax": lambda key, **kw: check_minimax(key),
+    # Kimi For Coding uses an Anthropic-compatible endpoint; check via /v1/messages
+    # with empty messages (same as check_anthropic, triggers 400 not 401).
+    "kimi": lambda key, **kw: check_anthropic_compatible(
+        key, "https://api.kimi.com/coding/v1/messages", "Kimi"
     ),
 }
 
@@ -105,12 +155,17 @@ def main() -> None:
     api_base = sys.argv[3] if len(sys.argv) > 3 else ""
 
     try:
-        if api_base:
+        if api_base and provider_id == "minimax":
+            result = check_minimax(api_key, api_base)
+        elif api_base and provider_id == "kimi":
+            # Kimi uses an Anthropic-compatible endpoint; check via /v1/messages
+            result = check_anthropic_compatible(
+                api_key, api_base.rstrip("/") + "/v1/messages", "Kimi"
+            )
+        elif api_base:
             # Custom API base (ZAI or other OpenAI-compatible)
             endpoint = api_base.rstrip("/") + "/models"
-            name = {"zai": "ZAI", "minimax": "MiniMax"}.get(
-                provider_id, "Custom provider"
-            )
+            name = {"zai": "ZAI"}.get(provider_id, "Custom provider")
             result = check_openai_compatible(api_key, endpoint, name)
         elif provider_id in PROVIDERS:
             result = PROVIDERS[provider_id](api_key)

tools/coder_tools_server.py

@@ -334,8 +334,10 @@ def undo_changes(path: str = "") -> str:
 @mcp.tool()
 def list_agent_tools(
     server_config_path: str = "",
-    output_schema: str = "simple",
+    output_schema: str = "summary",
     group: str = "all",
+    credentials: str = "all",
+    service: str = "",
 ) -> str:
     """Discover tools available for agent building, grouped by provider.
 
@@ -343,22 +345,52 @@ def list_agent_tools(
     BEFORE designing an agent to know exactly which tools exist. Only use
     tools from this list in node definitions — never guess or fabricate.
 
+    Progressive disclosure workflow (start narrow, drill in):
+        list_agent_tools()                                           # provider summary: counts + credential status
+        list_agent_tools(group="google", output_schema="summary")   # service breakdown within google
+        list_agent_tools(group="google", service="gmail")           # tool names for just gmail
+        list_agent_tools(group="google", service="gmail", output_schema="full")  # full detail
+
     Args:
         server_config_path: Path to mcp_servers.json. Default: tools/mcp_servers.json
             (the standard hive-tools server). Can also point to an agent's config
             to see what tools that specific agent has access to.
-        output_schema: "simple" (default) returns name and description per tool.
-            "full" also includes server and input_schema.
+        output_schema: Controls verbosity of the response.
+            "summary" (default) — provider list with tool counts + credential status. Very compact.
+                When group is specified, shows service-level breakdown within that provider.
+            "names" — tool names only (no descriptions), grouped by provider.
+            "simple" — names + truncated descriptions.
+            "full" — names + descriptions + server + input_schema.
         group: "all" (default) returns all providers. A provider like "google"
             returns only that provider's tools. Legacy prefix filters (e.g. "gmail")
             are still supported.
+        credentials: Filter by credential availability.
+            "all" (default) — show every tool regardless of credential status.
+            "available" — only tools whose credentials are already configured.
+            "unavailable" — only tools that still need credential setup.
+        service: Filter to a specific service within a provider (e.g. service="gmail"
+            when group="google"). Matches tools whose name starts with "<service>_".
 
     Returns:
         JSON with tools grouped by provider.
     """
-    if output_schema not in ("simple", "full"):
+    if output_schema not in ("summary", "names", "simple", "full"):
         return json.dumps(
-            {"error": f"Invalid output_schema: {output_schema!r}. Use 'simple' or 'full'."}
+            {
+                "error": (
+                    f"Invalid output_schema: {output_schema!r}. "
+                    "Use 'summary', 'names', 'simple', or 'full'."
+                )
+            }
+        )
+    if credentials not in ("all", "available", "unavailable"):
+        return json.dumps(
+            {
+                "error": (
+                    f"Invalid credentials: {credentials!r}. "
+                    "Use 'all', 'available', or 'unavailable'."
+                )
+            }
         )
 
     # Resolve config path
@@ -472,6 +504,33 @@ def list_agent_tools(
 
     tool_provider_auth, tool_providers = _build_provider_metadata()
 
+    def _get_available_credential_names() -> set[str]:
+        """Return set of credential spec keys whose env_var is set in the environment."""
+        try:
+            from framework.credentials.validation import ensure_credential_key_env
+
+            ensure_credential_key_env()
+        except Exception:
+            pass
+        try:
+            from aden_tools.credentials import CREDENTIAL_SPECS
+        except ImportError:
+            return set()
+        return {
+            cred_name
+            for cred_name, spec in CREDENTIAL_SPECS.items()
+            if spec.env_var and os.environ.get(spec.env_var)
+        }
+
+    def _tool_credentials_available(tool_name: str, available_creds: set[str]) -> bool:
+        """True if all credentials required by tool_name are available (or tool needs none)."""
+        required = set()
+        for provider_creds in tool_provider_auth.get(tool_name, {}).values():
+            required.update(provider_creds.keys())
+        if not required:
+            return True  # no credentials needed
+        return required.issubset(available_creds)
+
     def _group_by_provider(tools: list[dict]) -> dict[str, dict]:
         """Group tools by provider, including auth metadata and providerless tools."""
         groups: dict[str, dict] = {}
@@ -481,16 +540,20 @@ def list_agent_tools(
             if not providers:
                 providers = ["no_provider"]
 
-            desc = t["description"]
-            if output_schema == "simple" and desc and len(desc) > 200:
-                desc = desc[:200].rsplit(" ", 1)[0] + "..."
-            tool_payload = {
-                "name": t["name"],
-                "description": desc,
-            }
-            if output_schema == "full":
-                tool_payload["server"] = t["server"]
-                tool_payload["input_schema"] = t["input_schema"]
+            if output_schema == "names":
+                # Store just the name string — will be collapsed to flat list below
+                tool_payload: dict | str = t["name"]
+            else:
+                desc = t["description"]
+                if output_schema == "simple" and desc and len(desc) > 200:
+                    desc = desc[:200].rsplit(" ", 1)[0] + "..."
+                tool_payload = {
+                    "name": t["name"],
+                    "description": desc,
+                }
+                if output_schema == "full":
+                    tool_payload["server"] = t["server"]
+                    tool_payload["input_schema"] = t["input_schema"]
 
             for provider in providers:
                 bucket = groups.setdefault(
@@ -502,17 +565,48 @@ def list_agent_tools(
                 )
                 bucket["tools"].append(tool_payload)
 
-                provider_auth = tool_provider_auth.get(t["name"], {}).get(provider, {})
-                for cred_name, auth in provider_auth.items():
-                    bucket["authorization"][cred_name] = auth
+                # Only accumulate full auth metadata for simple/full schemas.
+                # summary/names use compact representations.
+                if output_schema not in ("summary", "names"):
+                    provider_auth = tool_provider_auth.get(t["name"], {}).get(provider, {})
+                    for cred_name, auth in provider_auth.items():
+                        bucket["authorization"][cred_name] = auth
 
-        for _provider, bucket in groups.items():
-            bucket["tools"] = sorted(bucket["tools"], key=lambda x: x["name"])
-            bucket["authorization"] = dict(sorted(bucket["authorization"].items()))
+        for provider, bucket in groups.items():
+            if output_schema == "names":
+                # Collapse to compact structure: flat sorted name list + credential keys only
+                tool_names = sorted(set(bucket["tools"]))
+                cred_keys: set[str] = set()
+                for tn in tool_names:
+                    for prov_creds in tool_provider_auth.get(tn, {}).values():
+                        cred_keys.update(prov_creds.keys())
+                groups[provider] = {
+                    "tool_count": len(tool_names),
+                    "credentials_required": sorted(cred_keys),
+                    "tool_names": tool_names,
+                }
+            else:
+                bucket["tools"] = sorted(bucket["tools"], key=lambda x: x["name"])
+                bucket["authorization"] = dict(sorted(bucket["authorization"].items()))
 
         return dict(sorted(groups.items()))
 
-    provider_groups = _group_by_provider(all_tools)
+    # Compute credential availability once (used for filtering and summary)
+    available_creds: set[str] = (
+        _get_available_credential_names() if credentials != "all" or output_schema == "summary"
+        else set()
+    )
+
+    # Apply credentials filter before grouping (filter tool list)
+    filtered_tools = all_tools
+    if credentials != "all":
+        filtered_tools = [
+            t
+            for t in all_tools
+            if (credentials == "available") == _tool_credentials_available(t["name"], available_creds)
+        ]
+
+    provider_groups = _group_by_provider(filtered_tools)
 
     # Filter to a specific provider (preferred) or legacy prefix (fallback)
     if group != "all":
@@ -520,20 +614,104 @@ def list_agent_tools(
             provider_groups = {group: provider_groups[group]}
         else:
             prefixed_tools = []
-            for t in all_tools:
+            for t in filtered_tools:
                 parts = t["name"].split("_", 1)
                 prefix = parts[0] if len(parts) > 1 else "general"
                 if prefix == group:
                     prefixed_tools.append(t)
             provider_groups = _group_by_provider(prefixed_tools)
 
-    all_names = sorted({t["name"] for p in provider_groups.values() for t in p["tools"]})
-    result: dict = {
-        "total": len(all_names),
-        "tools_by_provider": provider_groups,
-        "tools_by_category": provider_groups,  # backward-compat alias
-        "all_tool_names": all_names,
-    }
+    # Apply service filter (tool name prefix within a provider, e.g. service="gmail")
+    if service:
+        service_prefix = service.rstrip("_") + "_"
+        service_filtered: list[dict] = []
+        for t in filtered_tools:
+            # Only include tools from the already-filtered provider set
+            tool_name = t["name"]
+            in_provider = any(tool_name in p.get("tool_names", [tool_entry.get("name") for tool_entry in p.get("tools", [])]) for p in provider_groups.values())
+            if in_provider and tool_name.startswith(service_prefix):
+                service_filtered.append(t)
+        provider_groups = _group_by_provider(service_filtered)
+
+    def _infer_service(tool_name: str) -> str:
+        """Infer service name from tool name prefix (e.g. 'gmail' from 'gmail_send_message')."""
+        return tool_name.split("_", 1)[0]
+
+    # Summary mode: compact overview with counts + credential status
+    if output_schema == "summary":
+        if group == "all":
+            # Provider-level summary (default first call)
+            full_groups = _group_by_provider(all_tools) if credentials != "all" else provider_groups
+            summary_providers: dict = {}
+            for prov, bucket in full_groups.items():
+                cred_names = bucket.get("credentials_required", sorted(bucket.get("authorization", {}).keys()))
+                creds_ok = all(c in available_creds for c in cred_names) if cred_names else True
+                summary_providers[prov] = {
+                    "tool_count": len(bucket.get("tool_names", bucket.get("tools", []))),
+                    "credentials_required": cred_names,
+                    "credentials_available": creds_ok,
+                }
+            result: dict = {
+                "total_tools": sum(v["tool_count"] for v in summary_providers.values()),
+                "providers": summary_providers,
+                "hint": (
+                    "Use list_agent_tools(group='<provider>', output_schema='summary') for service breakdown, "
+                    "list_agent_tools(group='<provider>', service='<service>') for tool names. "
+                    "Filter by credentials='available' to see only ready-to-use tools."
+                ),
+            }
+        else:
+            # Service-level breakdown within a specific provider
+            # Re-build from all filtered tools for this provider (ignore service filter for summary)
+            provider_tool_names: list[str] = []
+            for bucket in provider_groups.values():
+                provider_tool_names.extend(
+                    bucket.get("tool_names", [e.get("name") for e in bucket.get("tools", [])])
+                )
+
+            services: dict = {}
+            for tn in sorted(set(provider_tool_names)):
+                svc = _infer_service(tn)
+                if svc not in services:
+                    svc_creds: set[str] = set()
+                    for prov_creds in tool_provider_auth.get(tn, {}).values():
+                        svc_creds.update(prov_creds.keys())
+                    services[svc] = {"tool_count": 0, "credentials_required": sorted(svc_creds)}
+                services[svc]["tool_count"] += 1
+                # Accumulate credentials for other tools in this service
+                for prov_creds in tool_provider_auth.get(tn, {}).values():
+                    existing = set(services[svc]["credentials_required"])
+                    existing.update(prov_creds.keys())
+                    services[svc]["credentials_required"] = sorted(existing)
+
+            result = {
+                "provider": group,
+                "total_tools": len(provider_tool_names),
+                "services": services,
+                "hint": (
+                    f"Use list_agent_tools(group='{group}', service='<service>') "
+                    "for tool names within a service."
+                ),
+            }
+        if errors:
+            result["errors"] = errors
+        return json.dumps(result, indent=2, default=str)
+
+    if output_schema == "names":
+        # Compact result: no duplication, no all_tool_names list
+        total = sum(p["tool_count"] for p in provider_groups.values())
+        result = {
+            "total": total,
+            "tools_by_provider": provider_groups,
+        }
+    else:
+        all_names = sorted({t["name"] for p in provider_groups.values() for t in p["tools"]})
+        result = {
+            "total": len(all_names),
+            "tools_by_provider": provider_groups,
+            "tools_by_category": provider_groups,  # backward-compat alias
+            "all_tool_names": all_names,
+        }
     if errors:
         result["errors"] = errors
 
@@ -1483,7 +1661,11 @@ def _node_var_name(node_id: str) -> str:
 
 
 @mcp.tool()
-def initialize_and_build_agent(agent_name: str, nodes: str | None = None) -> str:
+def initialize_and_build_agent(
+    agent_name: str,
+    nodes: str | None = None,
+    _draft: dict | None = None,
+) -> str:
     """Scaffold a new agent package with placeholder files.
 
     Creates exports/{agent_name}/ with all files needed for a runnable agent:
@@ -1500,6 +1682,8 @@ def initialize_and_build_agent(agent_name: str, nodes: str | None = None) -> str
         nodes: Comma-separated node names (snake_case or kebab-case).
                If omitted, a single 'start' node is created.
                Example: 'intake,process,review'
+        _draft: Internal. Draft graph metadata from planning phase, used to
+                pre-populate descriptions, goals, and node metadata.
 
     Returns:
         JSON with files written and next steps.
@@ -1519,6 +1703,15 @@ def initialize_and_build_agent(agent_name: str, nodes: str | None = None) -> str
 
     node_list = [n.strip() for n in nodes.split(",") if n.strip()] if nodes else ["start"]
 
+    # Build draft node lookup for pre-populating metadata from planning phase
+    _draft_nodes: dict[str, dict] = {}
+    if _draft and _draft.get("nodes"):
+        for dn in _draft["nodes"]:
+            _draft_nodes[dn.get("id", "")] = dn
+
+    # Extract top-level draft metadata early so it's available for all templates
+    _draft_desc = (_draft.get("description") or "") if _draft else ""
+
     class_name = _snake_to_camel(agent_name)
     human_name = agent_name.replace("_", " ").title()
     entry_node = node_list[0]
@@ -1583,7 +1776,7 @@ default_config = RuntimeConfig()
 class AgentMetadata:
     name: str = "{human_name}"
     version: str = "1.0.0"
-    description: str = "TODO: Add agent description."
+    description: str = "{_draft_desc or 'TODO: Add agent description.'}"
     intro_message: str = "TODO: Add intro message."
 
 
@@ -1598,22 +1791,33 @@ metadata = AgentMetadata()
         var = _node_var_name(node_id)
         node_var_names.append(var)
         is_first = node_id == entry_node
+
+        # Use draft metadata to pre-populate if available
+        dn = _draft_nodes.get(node_id, {})
+        node_name = dn.get("name") or node_id.replace("_", " ").replace("-", " ").title()
+        node_desc = dn.get("description") or "TODO: Describe what this node does."
+        node_type = dn.get("node_type") or "event_loop"
+        node_tools = dn.get("tools") or []
+        node_input_keys = dn.get("input_keys") or []
+        node_output_keys = dn.get("output_keys") or []
+        node_sc = dn.get("success_criteria") or "TODO: Define success criteria."
+
         node_specs.append(f'''\
 {var} = NodeSpec(
     id="{node_id}",
-    name="{node_id.replace("_", " ").replace("-", " ").title()}",
-    description="TODO: Describe what this node does.",
-    node_type="event_loop",
+    name="{node_name}",
+    description="{node_desc}",
+    node_type="{node_type}",
     client_facing={is_first},
     max_node_visits=0,
-    input_keys=[],
-    output_keys=[],
+    input_keys={node_input_keys!r},
+    output_keys={node_output_keys!r},
     nullable_output_keys=[],
-    success_criteria="TODO: Define success criteria.",
+    success_criteria="{node_sc}",
     system_prompt="""\\
 TODO: Add system prompt for this node.
 """,
-    tools=[],
+    tools={node_tools!r},
 )''')
 
     nodes_init = f'''\
@@ -1631,10 +1835,29 @@ __all__ = {node_var_names!r}
     node_imports = ", ".join(node_var_names)
     nodes_list = ", ".join(node_var_names)
 
+    # Use draft edges if available, otherwise generate linear edges
+    _draft_edges = _draft.get("edges", []) if _draft else []
     edge_defs = []
-    for i in range(len(node_list) - 1):
-        src, tgt = node_list[i], node_list[i + 1]
-        edge_defs.append(f"""\
+    if _draft_edges:
+        for de in _draft_edges:
+            eid = de.get("id", f"{de.get('source', '')}-to-{de.get('target', '')}")
+            src = de.get("source", "")
+            tgt = de.get("target", "")
+            cond = de.get("condition", "on_success").upper()
+            desc = de.get("description", "")
+            desc_line = f'\n        description="{desc}",' if desc else ""
+            edge_defs.append(f"""\
+    EdgeSpec(
+        id="{eid}",
+        source="{src}",
+        target="{tgt}",
+        condition=EdgeCondition.{cond},{desc_line}
+        priority=1,
+    ),""")
+    else:
+        for i in range(len(node_list) - 1):
+            src, tgt = node_list[i], node_list[i + 1]
+            edge_defs.append(f"""\
     EdgeSpec(
         id="{src}-to-{tgt}",
         source="{src}",
@@ -1644,6 +1867,55 @@ __all__ = {node_var_names!r}
     ),""")
     edges_str = "\n".join(edge_defs) if edge_defs else "    # TODO: Add edges"
 
+    # Pre-populate goal from draft metadata
+    _draft_goal = (_draft.get("goal") or "TODO: Describe the agent's goal.") if _draft else "TODO: Describe the agent's goal."
+    _draft_sc = (_draft.get("success_criteria") or []) if _draft else []
+    _draft_constraints = (_draft.get("constraints") or []) if _draft else []
+
+    # Build success criteria entries
+    if _draft_sc:
+        sc_entries = "\n".join(
+            f'''\
+        SuccessCriterion(
+            id="sc-{i+1}",
+            description="{sc}",
+            metric="TODO",
+            target="TODO",
+            weight=1.0,
+        ),'''
+            for i, sc in enumerate(_draft_sc)
+        )
+    else:
+        sc_entries = '''\
+        SuccessCriterion(
+            id="sc-1",
+            description="TODO: Define success criterion.",
+            metric="TODO",
+            target="TODO",
+            weight=1.0,
+        ),'''
+
+    # Build constraint entries
+    if _draft_constraints:
+        constraint_entries = "\n".join(
+            f'''\
+        Constraint(
+            id="c-{i+1}",
+            description="{c}",
+            constraint_type="hard",
+            category="functional",
+        ),'''
+            for i, c in enumerate(_draft_constraints)
+        )
+    else:
+        constraint_entries = '''\
+        Constraint(
+            id="c-1",
+            description="TODO: Define constraint.",
+            constraint_type="hard",
+            category="functional",
+        ),'''
+
     _write(
         "agent.py",
         f'''\
@@ -1667,23 +1939,12 @@ from .nodes import {node_imports}
 goal = Goal(
     id="{agent_name}-goal",
     name="{human_name}",
-    description="TODO: Describe the agent's goal.",
+    description="{_draft_goal}",
     success_criteria=[
-        SuccessCriterion(
-            id="sc-1",
-            description="TODO: Define success criterion.",
-            metric="TODO",
-            target="TODO",
-            weight=1.0,
-        ),
+{sc_entries}
     ],
     constraints=[
-        Constraint(
-            id="c-1",
-            description="TODO: Define constraint.",
-            constraint_type="hard",
-            category="functional",
-        ),
+{constraint_entries}
     ],
 )
 

tools/src/aden_tools/_win32_atomic.py

@@ -0,0 +1,108 @@
+"""Windows atomic file replacement with DACL preservation.
+
+Uses ReplaceFileW for atomic replacement, then SetFileSecurityW to
+restore the exact original DACL.  ReplaceFileW merges ACEs from the
+temp file, which can duplicate inherited entries.  SetFileSecurityW
+restores the security descriptor as-is without re-evaluating
+inheritance (unlike SetNamedSecurityInfoW).
+
+On non-NTFS volumes (e.g. FAT32), DACL snapshot/restore is skipped
+gracefully and only the atomic replacement is performed.
+"""
+
+import ctypes
+import ctypes.wintypes
+
+_DACL_SECURITY_INFORMATION = 0x00000004
+_REPLACEFILE_IGNORE_MERGE_ERRORS = 0x00000002
+
+_advapi32 = None
+_kernel32 = None
+
+if hasattr(ctypes, "windll"):
+    _advapi32 = ctypes.windll.advapi32
+    _kernel32 = ctypes.windll.kernel32
+
+    _advapi32.GetFileSecurityW.argtypes = [
+        ctypes.wintypes.LPCWSTR,  # lpFileName
+        ctypes.wintypes.DWORD,  # RequestedInformation
+        ctypes.c_void_p,  # pSecurityDescriptor
+        ctypes.wintypes.DWORD,  # nLength
+        ctypes.POINTER(ctypes.wintypes.DWORD),  # lpnLengthNeeded
+    ]
+    _advapi32.GetFileSecurityW.restype = ctypes.wintypes.BOOL
+
+    _advapi32.SetFileSecurityW.argtypes = [
+        ctypes.wintypes.LPCWSTR,  # lpFileName
+        ctypes.wintypes.DWORD,  # SecurityInformation
+        ctypes.c_void_p,  # pSecurityDescriptor
+    ]
+    _advapi32.SetFileSecurityW.restype = ctypes.wintypes.BOOL
+
+    _kernel32.ReplaceFileW.argtypes = [
+        ctypes.wintypes.LPCWSTR,  # lpReplacedFileName
+        ctypes.wintypes.LPCWSTR,  # lpReplacementFileName
+        ctypes.wintypes.LPCWSTR,  # lpBackupFileName
+        ctypes.wintypes.DWORD,  # dwReplaceFlags
+        ctypes.c_void_p,  # lpExclude (reserved)
+        ctypes.c_void_p,  # lpReserved
+    ]
+    _kernel32.ReplaceFileW.restype = ctypes.wintypes.BOOL
+
+
+def snapshot_dacl(path: str) -> ctypes.Array | None:
+    """Save a file's DACL as raw bytes.  Returns None on non-NTFS."""
+    if _advapi32 is None:
+        return None
+
+    needed = ctypes.wintypes.DWORD()
+    _advapi32.GetFileSecurityW(
+        path,
+        _DACL_SECURITY_INFORMATION,
+        None,
+        0,
+        ctypes.byref(needed),
+    )
+    if needed.value == 0:
+        return None
+    sd_buf = ctypes.create_string_buffer(needed.value)
+    if not _advapi32.GetFileSecurityW(
+        path,
+        _DACL_SECURITY_INFORMATION,
+        sd_buf,
+        needed.value,
+        ctypes.byref(needed),
+    ):
+        return None
+    return sd_buf
+
+
+def atomic_replace(target: str, replacement: str) -> None:
+    """Atomically replace *target* with *replacement*, preserving the DACL.
+
+    Uses ReplaceFileW for the atomic swap, then restores the original
+    DACL via SetFileSecurityW (best-effort).
+    """
+    if _kernel32 is None or _advapi32 is None:
+        raise OSError("atomic_replace is only available on Windows")
+
+    sd_buf = snapshot_dacl(target)
+
+    if not _kernel32.ReplaceFileW(
+        target,
+        replacement,
+        None,
+        _REPLACEFILE_IGNORE_MERGE_ERRORS,
+        None,
+        None,
+    ):
+        raise ctypes.WinError()
+
+    # Best-effort: content is already saved, don't fail the whole edit
+    # over a DACL restore failure.
+    if sd_buf is not None:
+        _advapi32.SetFileSecurityW(
+            target,
+            _DACL_SECURITY_INFORMATION,
+            sd_buf,
+        )

tools/src/aden_tools/credentials/__init__.py

@@ -40,7 +40,6 @@ Credential categories:
 - discord.py: Discord bot credentials
 - github.py: GitHub API credentials
 - google_analytics.py: Google Analytics 4 Data API credentials
-- google_docs.py: Google Docs API credentials
 - google_maps.py: Google Maps Platform credentials
 - hubspot.py: HubSpot CRM credentials
 - intercom.py: Intercom customer messaging credentials
@@ -81,7 +80,6 @@ from .gcp_vision import GCP_VISION_CREDENTIALS
 from .github import GITHUB_CREDENTIALS
 from .gitlab import GITLAB_CREDENTIALS
 from .google_analytics import GOOGLE_ANALYTICS_CREDENTIALS
-from .google_docs import GOOGLE_DOCS_CREDENTIALS
 from .google_maps import GOOGLE_MAPS_CREDENTIALS
 from .google_search_console import GOOGLE_SEARCH_CONSOLE_CREDENTIALS
 from .greenhouse import GREENHOUSE_CREDENTIALS
@@ -171,7 +169,6 @@ CREDENTIAL_SPECS = {
     **GREENHOUSE_CREDENTIALS,
     **GITLAB_CREDENTIALS,
     **GOOGLE_ANALYTICS_CREDENTIALS,
-    **GOOGLE_DOCS_CREDENTIALS,
     **GOOGLE_MAPS_CREDENTIALS,
     **GOOGLE_SEARCH_CONSOLE_CREDENTIALS,
     **HUBSPOT_CREDENTIALS,
@@ -264,7 +261,6 @@ __all__ = [
     "GREENHOUSE_CREDENTIALS",
     "GITLAB_CREDENTIALS",
     "GOOGLE_ANALYTICS_CREDENTIALS",
-    "GOOGLE_DOCS_CREDENTIALS",
     "GOOGLE_MAPS_CREDENTIALS",
     "GOOGLE_SEARCH_CONSOLE_CREDENTIALS",
     "HUBSPOT_CREDENTIALS",