refactor: clean dead codes

micro-fix: readme & 500 use cases

.claude/settings.json

@@ -1,4 +1,58 @@
 {
+  "permissions": {
+    "allow": [
+      "Bash(grep -n \"_is_context_too_large_error\" core/framework/agent_loop/agent_loop.py core/framework/agent_loop/internals/*.py)",
+      "Read(//^class/ {cls=$3} /def test_/**)",
+      "Read(//^    @pytest.mark.asyncio/{getline n; print NR\": \"n} /^    def test_/**)",
+      "Bash(python3)",
+      "Bash(grep -nE 'Tool\\\\\\(\\\\s*$|name=\"[a-z_]+\",' core/framework/tools/queen_lifecycle_tools.py)",
+      "Bash(awk -F'\"' '{print $2}')",
+      "Bash(grep -n \"create_colony\\\\|colony-spawn\\\\|colony_spawn\" /home/timothy/aden/hive/core/framework/agents/queen/nodes/__init__.py /home/timothy/aden/hive/core/framework/tools/*.py)",
+      "Bash(git stash:*)",
+      "Bash(python3 -c \"import sys,json; d=json.loads\\(sys.stdin.read\\(\\)\\); print\\('keys:', list\\(d.keys\\(\\)\\)[:10]\\)\")",
+      "Bash(python3 -c ':*)",
+      "Bash(uv run:*)",
+      "Read(//tmp/**)",
+      "Bash(grep -n \"useColony\\\\|const { queens, queenProfiles\" /home/timothy/aden/hive/core/frontend/src/pages/queen-dm.tsx)",
+      "Bash(awk 'NR==385,/\\\\}, \\\\[/' /home/timothy/aden/hive/core/frontend/src/pages/queen-dm.tsx)",
+      "Bash(xargs -I{} sh -c 'if ! grep -q \"^import base64\\\\|^from base64\" \"{}\"; then echo \"MISSING: {}\"; fi')",
+      "Bash(find /home/timothy/aden/hive/core/framework -name \"*.py\" -type f -exec grep -l \"FileConversationStore\\\\|class.*ConversationStore\" {} \\\\;)",
+      "Bash(find /home/timothy/aden/hive/core/framework -name \"*.py\" -exec grep -l \"run_parallel_workers\\\\|create_colony\" {} \\\\;)",
+      "Bash(awk '/^    async def execute\\\\\\(self, ctx: AgentContext\\\\\\)/,/^    async def [a-z_]+/ {print NR\": \"$0}' /home/timothy/aden/hive/core/framework/agent_loop/agent_loop.py)",
+      "Bash(grep -r \"max_concurrent_workers\\\\|max_depth\\\\|recursion\\\\|spawn.*bomb\" /home/timothy/aden/hive/core/framework/host/*.py)",
+      "Bash(wc -l /home/timothy/aden/hive/tools/src/gcu/browser/*.py /home/timothy/aden/hive/tools/src/gcu/browser/tools/*.py)",
+      "Bash(file /tmp/gcu_verify/*.png)",
+      "Bash(ps -eo pid,cmd)",
+      "Bash(ps -o pid,lstart,cmd -p 746640)",
+      "Bash(kill 746636)",
+      "Bash(ps -eo pid,lstart,cmd)",
+      "Bash(grep -E \"^d|\\\\.py$\")",
+      "Bash(grep -E \"\\\\.\\(ts|tsx\\)$\")",
+      "Bash(xargs cat:*)",
+      "Bash(find /home/timothy/aden/hive -path \"*/.venv\" -prune -o -name \"*.py\" -type f -exec grep -l \"frontend\\\\|UI\\\\|terminal\\\\|interactive\\\\|TUI\" {} \\\\;)",
+      "Bash(wc -l /home/timothy/.hive/backup/*/SKILL.md)",
+      "Bash(awk -F'::' '{print $1}')",
+      "Bash(wait)",
+      "Bash(pkill -f \"pytest.*test_event_loop_node\")",
+      "Bash(pkill -f \"pytest.*TestToolConcurrency\")",
+      "Bash(grep -n \"def.*discover\\\\|/api/agents\\\\|agents_discover\" /home/timothy/aden/hive/core/framework/server/*.py)",
+      "Bash(bun run:*)",
+      "Bash(npx eslint:*)",
+      "Bash(npm run:*)",
+      "Bash(npm test:*)",
+      "Bash(grep -E \"\\\\.tsx$|^d\")",
+      "Bash(grep -E \"test_.*\\\\.py$\")",
+      "Bash(grep \"\\\\.py$\")",
+      "Bash(grep -l \"save_agent_draft\\\\|confirm_and_build\\\\|replan_agent\\\\|load_built_agent\\\\|planning\\\\|building\\\\|staging\" /home/timothy/aden/hive/core/framework/agents/queen/reference/*.md)",
+      "Bash(grep -E \"\\\\.tsx$|\\\\.ts$\")",
+      "Bash(find /home/timothy/aden/hive/core/framework/tools -name \"*.py\" -exec grep -l \"switch_to_\" {} \\\\;)"
+    ],
+    "additionalDirectories": [
+      "/home/timothy/.hive/skills/writing-hive-skills",
+      "/tmp",
+      "/home/timothy/.hive/skills"
+    ]
+  },
   "hooks": {
     "PostToolUse": [
       {

.claude/skills/browser-edge-cases/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: browser-edge-cases
+description: SOP for debugging browser automation failures on complex websites. Use when browser tools fail on specific sites like LinkedIn, Twitter/X, SPAs, or sites with Shadow DOM.
+license: MIT
+---
+
+# Browser Tool Edge Cases
+
+Standard Operating Procedure for debugging and fixing browser automation failures on complex websites.
+
+## When to Use This Skill
+
+- `browser_scroll` succeeds but page doesn't move
+- `browser_click` succeeds but no action triggered
+- `browser_type` text disappears or doesn't work
+- `browser_snapshot` hangs or returns stale content
+- `browser_navigate` loads wrong content
+
+## SOP: Debugging Browser Tool Failures
+
+### Phase 1: Reproduce & Isolate
+
+```
+1. Create minimal test case demonstrating failure
+2. Test against simple site (example.com) to verify tool works
+3. Test against problematic site to confirm issue
+```
+
+**Quick isolation test:**
+```python
+# Test 1: Does the tool work at all?
+await browser_navigate(tab_id, "https://example.com")
+result = await browser_scroll(tab_id, "down", 100)
+# Should work on simple sites
+
+# Test 2: Does it fail on the problematic site?
+await browser_navigate(tab_id, "https://linkedin.com/feed")
+result = await browser_scroll(tab_id, "down", 100)
+# If this fails but example.com works → site-specific edge case
+```
+
+### Phase 2: Analyze Root Cause
+
+**Step 2a: Check console for errors**
+```python
+console = await browser_console(tab_id)
+# Look for: CSP violations, React errors, JavaScript exceptions
+```
+
+**Step 2b: Inspect DOM structure**
+```python
+html = await browser_html(tab_id)
+snapshot = await browser_snapshot(tab_id)
+# Look for:
+# - Nested scrollable divs (overflow: scroll/auto)
+# - Shadow DOM roots
+# - iframes
+# - Custom widgets
+```
+
+**Step 2c: Identify the pattern**
+
+| Symptom | Likely Cause | Check |
+|---------|--------------|-------|
+| Scroll doesn't move | Nested scroll container | Look for `overflow: scroll` divs |
+| Click no effect | Element covered | Check `getBoundingClientRect` vs viewport |
+| Type clears | Autocomplete/React | Check for event listeners on input |
+| Snapshot hangs | Huge DOM | Check node count in snapshot |
+| Snapshot stale | SPA hydration | Wait after navigation |
+
+### Phase 3: Implement Multi-Layer Fix
+
+**Pattern: Always have fallbacks**
+
+```python
+async def robust_operation(tab_id):
+    # Method 1: Primary approach
+    try:
+        result = await primary_method(tab_id)
+        if verify_success(result):
+            return result
+    except Exception:
+        pass
+
+    # Method 2: CDP fallback
+    try:
+        result = await cdp_fallback(tab_id)
+        if verify_success(result):
+            return result
+    except Exception:
+        pass
+
+    # Method 3: JavaScript fallback
+    return await javascript_fallback(tab_id)
+```
+
+**Pattern: Always add timeouts**
+
+```python
+# Bad - can hang forever
+result = await browser_snapshot(tab_id)
+
+# Good - fails fast with useful error
+try:
+    result = await browser_snapshot(tab_id, timeout_s=10.0)
+except asyncio.TimeoutError:
+    # Handle timeout gracefully
+    result = await fallback_snapshot(tab_id)
+```
+
+### Phase 4: Verify Fix
+
+```
+1. Run against problematic site → should work
+2. Run against simple site → should still work (regression check)
+3. Document in registry.md
+```
+
+## Pattern Library
+
+### P1: Nested Scrollable Containers
+
+**Sites:** LinkedIn, Twitter/X, any SPA with scrollable feeds
+
+**Detection:**
+```javascript
+// Find largest scrollable container
+const candidates = [];
+document.querySelectorAll('*').forEach(el => {
+    const style = getComputedStyle(el);
+    if (style.overflow.includes('scroll') || style.overflow.includes('auto')) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width > 100 && rect.height > 100) {
+            candidates.push({el, area: rect.width * rect.height});
+        }
+    }
+});
+candidates.sort((a, b) => b.area - a.area);
+return candidates[0]?.el;
+```
+
+**Fix:** Dispatch scroll events at container's center, not viewport center.
+
+### P2: Element Covered by Overlay
+
+**Sites:** Modals, tooltips, SPAs with loading overlays
+
+**Detection:**
+```javascript
+const rect = element.getBoundingClientRect();
+const centerX = rect.left + rect.width / 2;
+const centerY = rect.top + rect.height / 2;
+const topElement = document.elementFromPoint(centerX, centerY);
+return topElement === element || element.contains(topElement);
+```
+
+**Fix:** Wait for overlay to disappear, or use JavaScript click.
+
+### P3: React Synthetic Events
+
+**Sites:** React SPAs, modern web apps
+
+**Detection:** If CDP click doesn't trigger handler but manual click works.
+
+**Fix:** Use JavaScript click as primary:
+```javascript
+element.click();
+```
+
+### P4: Huge DOM / Accessibility Tree
+
+**Sites:** LinkedIn, Facebook, Twitter (feeds with 1000s of nodes)
+
+**Detection:**
+```javascript
+document.querySelectorAll('*').length > 5000
+```
+
+**Fix:**
+1. Add timeout to snapshot operation
+2. Truncate tree at 2000 nodes
+3. Fall back to DOM-based snapshot if accessibility tree too large
+
+### P5: SPA Hydration Delay
+
+**Sites:** React, Vue, Angular SPAs after navigation
+
+**Detection:**
+```javascript
+// Check if React app has hydrated
+document.querySelector('[data-reactroot]') ||
+document.querySelector('[data-reactid]')
+```
+
+**Fix:** Wait for specific selector after navigation:
+```python
+await browser_navigate(tab_id, url, wait_until="load")
+await browser_wait(tab_id, selector='[data-testid="content"]', timeout_ms=5000)
+```
+
+### P6: Shadow DOM
+
+**Sites:** Components using Shadow DOM, Lit elements
+
+**Detection:**
+```javascript
+document.querySelectorAll('*').some(el => el.shadowRoot)
+```
+
+**Fix:** Pierce shadow root:
+```javascript
+function queryShadow(selector) {
+    const parts = selector.split('>>>');
+    let node = document;
+    for (const part of parts) {
+        if (node.shadowRoot) {
+            node = node.shadowRoot.querySelector(part.trim());
+        } else {
+            node = node.querySelector(part.trim());
+        }
+    }
+    return node;
+}
+```
+
+## Quick Reference
+
+| Issue | Primary Fix | Fallback |
+|-------|-------------|----------|
+| Scroll not working | Find scrollable container | Mouse wheel at container center |
+| Click no effect | JavaScript click() | CDP mouse events |
+| Type clears | Add delay_ms | Use execCommand |
+| Snapshot hangs | Add timeout_s | DOM snapshot fallback |
+| Stale content | Wait for selector | Increase wait_until timeout |
+| Shadow DOM | Pierce selector | JavaScript traversal |
+
+## References
+
+- [registry.md](registry.md) - Full list of known edge cases
+- [scripts/test_case.py](scripts/test_case.py) - Template for testing new cases
+- [BROWSER_USE_PATTERNS.md](../../tools/BROWSER_USE_PATTERNS.md) - Implementation patterns from browser-use

.claude/skills/browser-edge-cases/registry.md

@@ -0,0 +1,261 @@
+# Browser Edge Case Registry
+
+Curated list of known browser automation edge cases with symptoms, causes, and fixes.
+
+---
+
+## Scroll Issues
+
+### #1: LinkedIn Nested Scroll Container
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | LinkedIn (linkedin.com/feed) |
+| **Symptom** | `browser_scroll()` returns `{ok: true}` but page doesn't move |
+| **Root Cause** | Content is in a nested scrollable div (`overflow: scroll`), not the main window |
+| **Detection** | `document.querySelectorAll('*')` with `overflow: scroll/auto` has large candidates |
+| **Fix** | JavaScript finds largest scrollable container, uses `container.scrollBy()` |
+| **Code** | `bridge.py:808-891` - smart scroll with container detection |
+| **Verified** | 2026-04-03 ✓ |
+
+### #2: Twitter/X Lazy Loading
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | Twitter/X (x.com) |
+| **Symptom** | Infinite scroll doesn't load new content |
+| **Root Cause** | Lazy loading requires content to be visible before loading more |
+| **Detection** | Scroll position at bottom but no new `[data-testid="tweet"]` elements |
+| **Fix** | Add `wait_for_selector` between scroll calls with 1s delay |
+| **Code** | Test file: `tests/test_x_page_load_repro.py` |
+| **Verified** | - |
+
+### #3: Modal/Dialog Scroll Container
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | Any site with modal dialogs |
+| **Symptom** | Scroll scrolls background page, not modal content |
+| **Root Cause** | Modal has its own scroll container with `overflow: scroll` |
+| **Detection** | Visible element with `position: fixed` and scrollable content |
+| **Fix** | Find visible modal container (highest z-index scrollable), scroll that |
+| **Code** | - |
+| **Verified** | - |
+
+---
+
+## Click Issues
+
+### #4: Element Covered by Overlay
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | SPAs, sites with loading overlays |
+| **Symptom** | Click succeeds but no action triggered |
+| **Root Cause** | Element is covered by transparent overlay, tooltip, or iframe |
+| **Detection** | `document.elementFromPoint(x, y) !== target` |
+| **Fix** | Wait for overlay to disappear, or use JavaScript `element.click()` |
+| **Code** | `bridge.py:394-591` - JavaScript click as primary |
+| **Verified** | - |
+
+### #5: React Synthetic Events
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | React applications |
+| **Symptom** | CDP click doesn't trigger React handler |
+| **Root Cause** | React uses synthetic events that don't respond to CDP events |
+| **Detection** | Site uses React (check for `__reactFiber$` or `data-reactroot`) |
+| **Fix** | Use JavaScript `element.click()` as primary method |
+| **Code** | `bridge.py:394-591` - JavaScript-first click |
+| **Verified** | - |
+
+### #6: Shadow DOM Elements
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | Components using Shadow DOM, Lit elements |
+| **Symptom** | `querySelector` can't find element |
+| **Root Cause** | Element is inside a shadow root, not main DOM tree |
+| **Detection** | `element.shadowRoot !== null` on parent elements |
+| **Fix** | Use piercing selector (`host >>> target`) or traverse shadow roots |
+| **Code** | See SKILL.md P6 pattern |
+| **Verified** | 2026-04-03 ✓ |
+
+---
+
+## Input Issues
+
+### #7: ContentEditable / Rich Text Editors
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | Rich text editors (Notion, Slack web, etc.) |
+| **Symptom** | `browser_type()` doesn't insert text |
+| **Root Cause** | Element is `contenteditable`, not an `<input>` or `<textarea>` |
+| **Detection** | `element.contentEditable === 'true'` |
+| **Fix** | Focus via JavaScript, use `execCommand('insertText')` or `Input.dispatchKeyEvent` |
+| **Code** | `bridge.py:616-694` - contentEditable handling |
+| **Verified** | 2026-04-03 ✓ |
+
+### #8: Autocomplete Field Clearing
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | Search fields with autocomplete, address forms |
+| **Symptom** | Typed text gets cleared immediately |
+| **Root Cause** | Field expects realistic keystroke timing for autocomplete |
+| **Detection** | Field has autocomplete listeners or dropdown appears |
+| **Fix** | Add `delay_ms=50` between keystrokes |
+| **Code** | `bridge.py:type()` - delay_ms parameter |
+| **Verified** | 2026-04-03 ✓ |
+
+### #9: Custom Date Pickers
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | Forms with custom date widgets |
+| **Symptom** | Can't type date into date field |
+| **Root Cause** | Custom widget intercepts and blocks keyboard input |
+| **Detection** | Typing doesn't change field value |
+| **Fix** | Click calendar widget icon, select date from dropdown |
+| **Code** | - |
+| **Verified** | - |
+
+---
+
+## Snapshot Issues
+
+### #10: LinkedIn Huge DOM Tree
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | LinkedIn, Facebook, Twitter feeds |
+| **Symptom** | `browser_snapshot()` hangs forever |
+| **Root Cause** | 10k+ DOM nodes, accessibility tree has 50k+ nodes |
+| **Detection** | `document.querySelectorAll('*').length > 5000` |
+| **Fix** | Add `timeout_s` param with `asyncio.timeout()`, proper error handling |
+| **Code** | `bridge.py:1041-1028` - snapshot with timeout protection |
+| **Verified** | 2026-04-03 ✓ (0.08s on LinkedIn) |
+
+### #11: SPA Hydration Delay
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | React/Vue/Angular SPAs |
+| **Symptom** | Snapshot shows old content after navigation |
+| **Root Cause** | Client-side hydration hasn't completed when snapshot runs |
+| **Detection** | `document.readyState === 'complete'` but content missing |
+| **Fix** | Wait for specific selector after navigation |
+| **Code** | Test file: `tests/test_x_page_load_repro.py` |
+| **Verified** | - |
+
+### #12: iframe Content Missing
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | Sites with embedded content |
+| **Symptom** | Snapshot missing iframe content |
+| **Root Cause** | Accessibility tree doesn't include iframe content |
+| **Detection** | `document.querySelectorAll('iframe')` has results |
+| **Fix** | Use `DOM.getFrameOwner` + separate snapshot for each iframe |
+| **Code** | - |
+| **Verified** | - |
+
+---
+
+## Navigation Issues
+
+### #13: SPA Navigation Events
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | React Router, Vue Router SPAs |
+| **Symptom** | `wait_until="load"` fires before content ready |
+| **Root Cause** | SPA uses client-side routing, no full page load |
+| **Detection** | URL changes but `load` event already fired |
+| **Fix** | Use `wait_until="networkidle"` or `wait_for_selector` |
+| **Code** | `bridge.py:navigate()` - wait_until options |
+| **Verified** | - |
+
+### #14: Cross-Origin Redirects
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | OAuth flows, SSO logins |
+| **Symptom** | Navigation fails during redirect |
+| **Root Cause** | Cross-origin security prevents CDP tracking |
+| **Detection** | URL changes to different domain |
+| **Fix** | Use `wait_for_url` with pattern matching instead of exact URL |
+| **Code** | - |
+| **Verified** | - |
+
+---
+
+## Screenshot Issues
+
+### #15: Selector Screenshot Not Implemented
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | Any site |
+| **Symptom** | `browser_screenshot(selector="h1")` takes full viewport instead of element |
+| **Root Cause** | `selector` param existed in signature but was silently ignored in both `bridge.py` and `inspection.py` |
+| **Detection** | Screenshot with selector same byte size as screenshot without selector |
+| **Fix** | Use CDP `Runtime.evaluate` to call `getBoundingClientRect()` on the element, pass result as `clip` to `Page.captureScreenshot` |
+| **Code** | `bridge.py:1315-1344` - selector clip logic; `inspection.py:94-96` - pass selector to bridge |
+| **Verified** | 2026-04-03 ✓ (JS rect query returns correct viewport coords; requires server restart) |
+
+### #16: Stale Browser Context (Group ID Mismatch)
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | Any |
+| **Symptom** | `browser_open()` returns `"No group with id: XXXXXXX"` even though `browser_status` shows `running: true` |
+| **Root Cause** | In-memory `_contexts` dict has a stale `groupId` from a Chrome tab group that was closed outside the tool (e.g. user closed the tab group) |
+| **Detection** | `browser_status` returns `running: true` but `browser_open` fails with "No group with id" |
+| **Fix** | Call `browser_stop()` to clear stale context from `_contexts`, then `browser_start()` again |
+| **Code** | `tools/lifecycle.py:144-160` - `already_running` check uses cached dict without validating against Chrome |
+| **Verified** | 2026-04-03 ✓ |
+
+---
+
+## How to Add New Edge Cases
+
+1. **Reproduce** the issue with minimal test case
+2. **Document** using the template below
+3. **Implement** fix with multi-layer fallback
+4. **Verify** against both problematic and simple sites
+5. **Submit** by appending to this file
+
+### Template
+
+```markdown
+### #N: [Short Title]
+
+| Attribute | Value |
+|-----------|-------|
+| **Site** | [URL or site type] |
+| **Symptom** | [What the user observes] |
+| **Root Cause** | [Technical explanation] |
+| **Detection** | [JavaScript to detect this case] |
+| **Fix** | [Solution approach] |
+| **Code** | [File:line reference if implemented] |
+| **Verified** | [Date or "pending"] |
+```
+
+---
+
+## Statistics
+
+| Category | Count |
+|----------|-------|
+| Scroll Issues | 3 |
+| Click Issues | 3 |
+| Input Issues | 3 |
+| Snapshot Issues | 3 |
+| Navigation Issues | 2 |
+| Screenshot Issues | 2 |
+| **Total** | **16** |
+
+Last updated: 2026-04-03

.claude/skills/browser-edge-cases/scripts/test_02_twitter_scroll.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python
+"""
+Test #2: Twitter/X Lazy Loading Scroll
+
+Symptom: Infinite scroll doesn't load new content
+Root Cause: Lazy loading requires content to be visible before loading more
+Fix: Add wait_for_selector between scroll calls
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+BRIDGE_PORT = 9229
+CONTEXT_NAME = "twitter-scroll-test"
+
+
+async def test_twitter_lazy_scroll():
+    """Test that repeated scrolls with waits load new content."""
+    print("=" * 70)
+    print("TEST #2: Twitter/X Lazy Loading Scroll")
+    print("=" * 70)
+
+    bridge = BeelineBridge()
+
+    try:
+        await bridge.start()
+
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+            print(f"Waiting for extension... ({i + 1}/10)")
+        else:
+            print("✗ Extension not connected")
+            return
+
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        # Navigate to Twitter/X
+        print("\n--- Navigating to X.com ---")
+        await bridge.navigate(tab_id, "https://x.com", wait_until="networkidle", timeout_ms=30000)
+        print("✓ Page loaded")
+
+        # Wait for tweets to appear
+        print("\n--- Waiting for tweets ---")
+        await bridge.wait_for_selector(tab_id, '[data-testid="tweet"]', timeout_ms=10000)
+
+        # Count initial tweets
+        initial_count = await bridge.evaluate(
+            tab_id,
+            "(function() { return document.querySelectorAll("
+            "'[data-testid=\"tweet\"]').length; })()",
+        )
+        print(f"Initial tweet count: {initial_count.get('result', 0)}")
+
+        # Take screenshot of initial state
+        screenshot = await bridge.screenshot(tab_id)
+        print(f"Screenshot: {len(screenshot.get('data', ''))} bytes")
+
+        # Scroll multiple times with waits
+        print("\n--- Scrolling with waits ---")
+        for i in range(3):
+            result = await bridge.scroll(tab_id, "down", 500)
+            print(f"  Scroll {i + 1}: {result.get('method', 'unknown')} method")
+
+            # Wait for new content to load
+            await asyncio.sleep(2)
+
+            # Count tweets after scroll
+            count_result = await bridge.evaluate(
+                tab_id,
+                "(function() { return document.querySelectorAll("
+                "'[data-testid=\"tweet\"]').length; })()",
+            )
+            count = count_result.get("result", 0)
+            print(f"  Tweet count after scroll: {count}")
+
+        # Final count
+        final_count = await bridge.evaluate(
+            tab_id,
+            "(function() { return document.querySelectorAll("
+            "'[data-testid=\"tweet\"]').length; })()",
+        )
+        final = final_count.get("result", 0)
+        initial = initial_count.get("result", 0)
+
+        print("\n--- Results ---")
+        print(f"Initial tweets: {initial}")
+        print(f"Final tweets: {final}")
+
+        if final > initial:
+            print(f"✓ PASS: Loaded {final - initial} new tweets")
+        else:
+            print("✗ FAIL: No new tweets loaded (may need login)")
+
+        await bridge.destroy_context(group_id)
+        print("\n✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(test_twitter_lazy_scroll())

.claude/skills/browser-edge-cases/scripts/test_03_modal_scroll.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python
+"""
+Test #3: Modal/Dialog Scroll Container
+
+Symptom: Scroll scrolls background page, not modal content
+Root Cause: Modal has its own scroll container with overflow: scroll
+Fix: Find visible modal container (highest z-index scrollable), scroll that
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+BRIDGE_PORT = 9229
+CONTEXT_NAME = "modal-scroll-test"
+
+# Test site with modal - using a demo site
+MODAL_DEMO_URL = "https://www.w3schools.com/howto/howto_css_modals.asp"
+
+
+async def test_modal_scroll():
+    """Test that scroll targets modal content, not background."""
+    print("=" * 70)
+    print("TEST #3: Modal/Dialog Scroll Container")
+    print("=" * 70)
+
+    bridge = BeelineBridge()
+
+    try:
+        await bridge.start()
+
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+        else:
+            print("✗ Extension not connected")
+            return
+
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        # Navigate to modal demo
+        print("\n--- Navigating to modal demo ---")
+        await bridge.navigate(tab_id, MODAL_DEMO_URL, wait_until="load")
+        print("✓ Page loaded")
+
+        # Take screenshot before
+        screenshot_before = await bridge.screenshot(tab_id)
+        print(f"Screenshot before: {len(screenshot_before.get('data', ''))} bytes")
+
+        # Click button to open modal
+        print("\n--- Opening modal ---")
+        # Find and click the "Open Modal" button
+        result = await bridge.click(tab_id, ".ws-btn", timeout_ms=5000)
+        print(f"Click result: {result}")
+
+        await asyncio.sleep(1)
+
+        # Take screenshot with modal open
+        screenshot_modal = await bridge.screenshot(tab_id)
+        print(f"Screenshot modal open: {len(screenshot_modal.get('data', ''))} bytes")
+
+        # Try to scroll within modal
+        print("\n--- Scrolling modal content ---")
+        result = await bridge.scroll(tab_id, "down", 100)
+        print(f"Scroll result: {result}")
+
+        await asyncio.sleep(0.5)
+
+        # Take screenshot after scroll
+        screenshot_after = await bridge.screenshot(tab_id)
+        print(f"Screenshot after scroll: {len(screenshot_after.get('data', ''))} bytes")
+
+        # Check if modal content scrolled (not background)
+        # This is a visual check - we can verify by comparing screenshots
+        print("\n--- Results ---")
+        print(f"Modal scroll test completed. Method used: {result.get('method', 'unknown')}")
+        print("Visual verification needed: Check if modal content scrolled vs background")
+
+        await bridge.destroy_context(group_id)
+        print("\n✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(test_modal_scroll())

.claude/skills/browser-edge-cases/scripts/test_04_element_covered.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python
+"""
+Test #4: Element Covered by Overlay
+
+Symptom: Click succeeds but no action triggered
+Root Cause: Element is covered by transparent overlay, tooltip, or iframe
+Detection: document.elementFromPoint(x, y) !== target
+Fix: Wait for overlay to disappear, or use JavaScript element.click()
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+CONTEXT_NAME = "overlay-click-test"
+
+
+async def test_overlay_click():
+    """Test clicking elements that are covered by overlays."""
+    print("=" * 70)
+    print("TEST #4: Element Covered by Overlay")
+    print("=" * 70)
+
+    bridge = BeelineBridge()
+
+    try:
+        await bridge.start()
+
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+        else:
+            print("✗ Extension not connected")
+            return
+
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        # Create a test page with overlay
+        print("\n--- Creating test page with overlay ---")
+        test_html = """
+        <!DOCTYPE html>
+        <html>
+        <head><title>Overlay Test</title></head>
+        <body>
+            <button id="target-btn" onclick="alert('Clicked!')">Click Me</button>
+            <div id="overlay" style="position:fixed;top:0;left:0;
+            width:100%;height:100%;
+            background:rgba(0,0,0,0.3);z-index:1000;"></div>
+            <script>
+                window.clickCount = 0;
+                document.getElementById('target-btn').addEventListener('click', () => {
+                    window.clickCount++;
+                });
+            </script>
+        </body>
+        </html>
+        """
+
+        # Navigate to data URL
+        import base64
+
+        data_url = f"data:text/html;base64,{base64.b64encode(test_html.encode()).decode()}"
+        await bridge.navigate(tab_id, data_url, wait_until="load")
+
+        # Screenshot before
+        screenshot = await bridge.screenshot(tab_id)
+        print(f"Screenshot: {len(screenshot.get('data', ''))} bytes")
+
+        # Try to click the covered button
+        print("\n--- Attempting to click covered button ---")
+
+        # First, check if element is covered
+        coverage_check = await bridge.evaluate(
+            tab_id,
+            """
+            (function() {
+                const btn = document.getElementById('target-btn');
+                const rect = btn.getBoundingClientRect();
+                const centerX = rect.left + rect.width / 2;
+                const centerY = rect.top + rect.height / 2;
+                const topElement = document.elementFromPoint(centerX, centerY);
+                return {
+                    isCovered: topElement !== btn && !btn.contains(topElement),
+                    topElement: topElement?.tagName,
+                    targetElement: btn.tagName
+                };
+            })();
+        """,
+        )
+        print(f"Coverage check: {coverage_check.get('result', {})}")
+
+        # Try CDP click (may fail due to overlay)
+        click_result = await bridge.click(tab_id, "#target-btn", timeout_ms=5000)
+        print(f"Click result: {click_result}")
+
+        # Check if click registered
+        count_result = await bridge.evaluate(tab_id, "(function() { return window.clickCount; })()")
+        count = count_result.get("result", 0)
+        print(f"Click count after CDP click: {count}")
+
+        if count > 0:
+            print("✓ PASS: JavaScript click penetrated overlay")
+        else:
+            print("✗ FAIL: Click did not reach button (overlay blocked it)")
+
+        await bridge.destroy_context(group_id)
+        print("\n✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(test_overlay_click())

.claude/skills/browser-edge-cases/scripts/test_06_shadow_dom.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python
+"""
+Test #6: Shadow DOM Elements
+
+Symptom: querySelector can't find element
+Root Cause: Element is inside a shadow root, not main DOM tree
+Detection: element.shadowRoot !== null on parent elements
+Fix: Use piercing selector (host >>> target) or traverse shadow roots
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+CONTEXT_NAME = "shadow-dom-test"
+
+
+async def test_shadow_dom():
+    """Test clicking elements inside Shadow DOM."""
+    print("=" * 70)
+    print("TEST #6: Shadow DOM Elements")
+    print("=" * 70)
+
+    bridge = BeelineBridge()
+
+    try:
+        await bridge.start()
+
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+        else:
+            print("✗ Extension not connected")
+            return
+
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        # Create test page with Shadow DOM
+        print("\n--- Creating test page with Shadow DOM ---")
+        test_html = """
+        <!DOCTYPE html>
+        <html>
+        <head><title>Shadow DOM Test</title></head>
+        <body>
+            <div id="shadow-host"></div>
+            <script>
+                const host = document.getElementById('shadow-host');
+                const shadow = host.attachShadow({ mode: 'open' });
+                shadow.innerHTML = `
+                    <style>
+                        button { padding: 10px 20px; font-size: 16px; }
+                    </style>
+                    <button id="shadow-btn">Shadow Button</button>
+                `;
+                shadow.getElementById('shadow-btn').addEventListener('click', () => {
+                    window.shadowClickCount = (window.shadowClickCount || 0) + 1;
+                    console.log('Shadow button clicked:', window.shadowClickCount);
+                });
+            </script>
+        </body>
+        </html>
+        """
+
+        # Write to file and use file:// URL (data: URLs don't work well with extension)
+        test_file = Path("/tmp/shadow_dom_test.html")
+        test_file.write_text(test_html.strip())
+        file_url = f"file://{test_file}"
+        await bridge.navigate(tab_id, file_url, wait_until="load")
+        print("✓ Page loaded")
+
+        # Screenshot
+        screenshot = await bridge.screenshot(tab_id)
+        print(f"Screenshot: {len(screenshot.get('data', ''))} bytes")
+
+        # Detect Shadow DOM
+        print("\n--- Detecting Shadow DOM ---")
+        detection = await bridge.evaluate(
+            tab_id,
+            """
+            (function() {
+                const hosts = [];
+                document.querySelectorAll('*').forEach(el => {
+                    if (el.shadowRoot) {
+                        hosts.push({
+                            tag: el.tagName,
+                            id: el.id,
+                            hasButton: el.shadowRoot.querySelector('button') !== null
+                        });
+                    }
+                });
+                return { count: hosts.length, hosts };
+            })();
+        """,
+        )
+        print(f"Shadow DOM detection: {detection.get('result', {})}")
+
+        # Try to click shadow button using regular selector (should fail)
+        print("\n--- Attempting click with regular selector ---")
+        try:
+            result = await bridge.click(tab_id, "#shadow-btn", timeout_ms=3000)
+            print(f"Result: {result}")
+        except Exception as e:
+            print(f"Expected failure: {e}")
+
+        # Try to click using JavaScript that pierces shadow DOM
+        print("\n--- Clicking via JavaScript shadow piercing ---")
+        click_result = await bridge.evaluate(
+            tab_id,
+            """
+            (function() {
+                const host = document.getElementById('shadow-host');
+                const btn = host.shadowRoot.getElementById('shadow-btn');
+                if (btn) {
+                    btn.click();
+                    return { success: true, clicked: 'shadow-btn' };
+                }
+                return { success: false, error: 'Button not found' };
+            })();
+        """,
+        )
+        print(f"JS click result: {click_result.get('result', {})}")
+
+        # Verify click was registered
+        count_result = await bridge.evaluate(
+            tab_id, "(function() { return window.shadowClickCount || 0; })()"
+        )
+        count = count_result.get("result") or 0
+        print(f"Shadow click count: {count}")
+
+        if count and count > 0:
+            print("✓ PASS: Shadow DOM element clicked successfully")
+        else:
+            print("✗ FAIL: Could not click Shadow DOM element")
+
+        await bridge.destroy_context(group_id)
+        print("\n✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(test_shadow_dom())

.claude/skills/browser-edge-cases/scripts/test_07_contenteditable.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python
+"""
+Test #7: ContentEditable / Rich Text Editors
+
+Symptom: browser_type() doesn't insert text
+Root Cause: Element is contenteditable, not an <input> or <textarea>
+Detection: element.contentEditable === 'true'
+Fix: Focus via JavaScript, use execCommand('insertText') or Input.dispatchKeyEvent
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+CONTEXT_NAME = "contenteditable-test"
+
+
+async def test_contenteditable():
+    """Test typing into contenteditable elements."""
+    print("=" * 70)
+    print("TEST #7: ContentEditable / Rich Text Editors")
+    print("=" * 70)
+
+    bridge = BeelineBridge()
+
+    try:
+        await bridge.start()
+
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+        else:
+            print("✗ Extension not connected")
+            return
+
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        # Create test page with contenteditable
+        test_html = """
+        <!DOCTYPE html>
+        <html>
+        <head><title>ContentEditable Test</title></head>
+        <body>
+            <h2>ContentEditable Test</h2>
+
+            <h3>1. Simple contenteditable div</h3>
+            <div id="editor1" contenteditable="true"
+            style="border:1px solid #ccc;padding:10px;
+            min-height:50px;">Start text</div>
+
+            <h3>2. Rich text editor (like Notion)</h3>
+            <div id="editor2" contenteditable="true"
+            style="border:1px solid #ccc;padding:10px;
+            min-height:50px;">
+                <p>Type here...</p>
+            </div>
+
+            <h3>3. Regular input (for comparison)</h3>
+            <input id="input1" type="text" placeholder="Regular input" />
+
+            <script>
+                // Track content changes
+                window.editor1Content = '';
+                window.editor2Content = '';
+
+                document.getElementById('editor1').addEventListener('input', (e) => {
+                    window.editor1Content = e.target.innerText;
+                });
+                document.getElementById('editor2').addEventListener('input', (e) => {
+                    window.editor2Content = e.target.innerText;
+                });
+            </script>
+        </body>
+        </html>
+        """
+
+        # Write to file and use file:// URL (data: URLs don't work well with extension)
+        test_file = Path("/tmp/contenteditable_test.html")
+        test_file.write_text(test_html.strip())
+        file_url = f"file://{test_file}"
+        await bridge.navigate(tab_id, file_url, wait_until="load")
+        print("✓ Page loaded")
+
+        # Screenshot with timeout protection
+        try:
+            screenshot = await asyncio.wait_for(bridge.screenshot(tab_id), timeout=10.0)
+            print(f"Screenshot: {len(screenshot.get('data', ''))} bytes")
+        except asyncio.TimeoutError:
+            print("Screenshot timed out (skipping)")
+
+        # Detect contenteditable
+        print("\n--- Detecting contenteditable elements ---")
+        detection = await bridge.evaluate(
+            tab_id,
+            """
+            (function() {
+                const editables = document.querySelectorAll('[contenteditable="true"]');
+                return {
+                    count: editables.length,
+                    ids: Array.from(editables).map(el => el.id)
+                };
+            })();
+        """,
+        )
+        print(f"Contenteditable detection: {detection.get('result', {})}")
+
+        # Test 1: Type into regular input (baseline)
+        print("\n--- Test 1: Regular input ---")
+        await bridge.click(tab_id, "#input1")
+        await bridge.type_text(tab_id, "#input1", "Hello input")
+        input_result = await bridge.evaluate(
+            tab_id, "(function() { return document.getElementById('input1').value; })()"
+        )
+        print(f"Input value: {input_result.get('result', '')}")
+
+        # Test 2: Type into contenteditable div
+        print("\n--- Test 2: Contenteditable div ---")
+        await bridge.click(tab_id, "#editor1")
+        await bridge.type_text(tab_id, "#editor1", "Hello contenteditable", clear_first=True)
+        editor_result = await bridge.evaluate(
+            tab_id,
+            "(function() { return document.getElementById('editor1').innerText; })()",
+        )
+        print(f"Editor1 innerText: {editor_result.get('result', '')}")
+
+        # Test 3: Use JavaScript insertText for rich editor
+        print("\n--- Test 3: JavaScript insertText for rich editor ---")
+        insert_result = await bridge.evaluate(
+            tab_id,
+            """
+            (function() {
+                const editor = document.getElementById('editor2');
+                editor.focus();
+                document.execCommand('selectAll', false, null);
+                document.execCommand('insertText', false, 'Hello from execCommand');
+                return editor.innerText;
+            })();
+        """,
+        )
+        print(f"Editor2 after execCommand: {insert_result.get('result', '')}")
+
+        # Screenshot after with timeout protection
+        try:
+            screenshot_after = await asyncio.wait_for(bridge.screenshot(tab_id), timeout=10.0)
+            print(f"Screenshot after: {len(screenshot_after.get('data', ''))} bytes")
+        except asyncio.TimeoutError:
+            print("Screenshot after timed out (skipping)")
+
+        # Results
+        print("\n--- Results ---")
+        input_val = input_result.get("result", "")
+        editor1_val = editor_result.get("result", "")
+        editor2_val = insert_result.get("result", "")
+
+        input_pass = "Hello input" in input_val
+        editor1_pass = "Hello contenteditable" in editor1_val
+        editor2_pass = "execCommand" in editor2_val
+
+        print(f"Input: {'✓ PASS' if input_pass else '✗ FAIL'} - {input_val}")
+        print(f"Editor1: {'✓ PASS' if editor1_pass else '✗ FAIL'} - {editor1_val}")
+        print(f"Editor2: {'✓ PASS' if editor2_pass else '✗ FAIL'} - {editor2_val}")
+
+        await bridge.destroy_context(group_id)
+        print("\n✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(test_contenteditable())

.claude/skills/browser-edge-cases/scripts/test_08_autocomplete.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python
+"""
+Test #8: Autocomplete Field Clearing
+
+Symptom: Typed text gets cleared immediately
+Root Cause: Field expects realistic keystroke timing for autocomplete
+Detection: Field has autocomplete listeners or dropdown appears
+Fix: Add delay_ms between keystrokes
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+CONTEXT_NAME = "autocomplete-test"
+
+
+async def test_autocomplete():
+    """Test typing into fields with autocomplete behavior."""
+    print("=" * 70)
+    print("TEST #8: Autocomplete Field Clearing")
+    print("=" * 70)
+
+    bridge = BeelineBridge()
+
+    try:
+        await bridge.start()
+
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+        else:
+            print("✗ Extension not connected")
+            return
+
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        # Create test page with autocomplete behavior
+        test_html = """
+        <!DOCTYPE html>
+        <html>
+        <head><title>Autocomplete Test</title>
+        <style>
+            .autocomplete-items {
+                position: absolute;
+                border: 1px solid #d4d4d4;
+                border-top: none;
+                z-index: 99;
+                top: 100%;
+                left: 0;
+                right: 0;
+                max-height: 200px;
+                overflow-y: auto;
+                background: white;
+            }
+            .autocomplete-items div {
+                padding: 10px;
+                cursor: pointer;
+            }
+            .autocomplete-items div:hover {
+                background-color: #e9e9e9;
+            }
+            .autocomplete-active {
+                background-color: DodgerBlue !important;
+                color: white;
+            }
+            .autocomplete { position: relative; display: inline-block; }
+            input { width: 300px; padding: 10px; font-size: 16px; }
+        </style></head>
+        <body>
+            <h2>Autocomplete Test</h2>
+
+            <div class="autocomplete">
+                <input id="search" type="text" placeholder="Search countries..." autocomplete="off">
+            </div>
+
+            <div id="log" style="margin-top:20px;font-family:monospace;"></div>
+
+            <script>
+                const countries = [
+                    "Afghanistan","Albania","Algeria",
+                    "Andorra","Angola","Argentina",
+                    "Armenia","Australia","Austria",
+                    "Azerbaijan","Bahamas","Bahrain",
+                    "Bangladesh","Belarus","Belgium",
+                    "Belize","Benin","Bhutan",
+                    "Bolivia","Brazil","Canada",
+                    "China","Colombia","Denmark",
+                    "Egypt","France","Germany",
+                    "India","Indonesia","Italy",
+                    "Japan","Mexico","Netherlands",
+                    "Nigeria","Norway","Pakistan",
+                    "Peru","Philippines","Poland",
+                    "Portugal","Russia","Spain",
+                    "Sweden","Switzerland","Thailand",
+                    "Turkey","Ukraine",
+                    "United Kingdom","United States",
+                    "Vietnam"
+                ];
+
+                const input = document.getElementById('search');
+                const log = document.getElementById('log');
+                let currentFocus = -1;
+                let typingTimeout = null;
+
+                // Track events for testing
+                window.inputEvents = [];
+                window.inputValue = '';
+
+                function logEvent(type, value) {
+                    window.inputEvents.push({ type, value, time: Date.now() });
+                    const entry = document.createElement('div');
+                    entry.textContent = type + ': ' + value;
+                    log.insertBefore(entry, log.firstChild);
+                }
+
+                // Simulate autocomplete that clears fast typing
+                input.addEventListener('input', function(e) {
+                    const val = this.value;
+
+                    // Clear previous dropdown
+                    closeAllLists();
+
+                    if (!val) return;
+
+                    // If typing too fast (autocomplete-style), clear and restart
+                    clearTimeout(typingTimeout);
+                    typingTimeout = setTimeout(() => {
+                        logEvent('input', val);
+                        window.inputValue = val;
+
+                        // Create dropdown
+                        const div = document.createElement('div');
+                        div.setAttribute('id', this.id + 'autocomplete-list');
+                        div.setAttribute('class', 'autocomplete-items');
+                        this.parentNode.appendChild(div);
+
+                        countries.filter(
+                            c => c.substr(0, val.length).toUpperCase()
+                                === val.toUpperCase()
+                        ).slice(0, 5).forEach(country => {
+                                const item = document.createElement('div');
+                                item.innerHTML = '<strong>'
+                                    + country.substr(0, val.length)
+                                    + '</strong>'
+                                    + country.substr(val.length);
+                                item.addEventListener('click', function() {
+                                    input.value = country;
+                                    closeAllLists();
+                                    logEvent('select', country);
+                                    window.inputValue = country;
+                                });
+                                div.appendChild(item);
+                            });
+                    }, 100); // 100ms debounce
+                });
+
+                function closeAllLists() {
+                    document.querySelectorAll('.autocomplete-items').forEach(el => el.remove());
+                }
+
+                document.addEventListener('click', function() {
+                    closeAllLists();
+                });
+            </script>
+        </body>
+        </html>
+        """
+
+        # Write to file and use file:// URL (data: URLs don't work well with extension)
+        test_file = Path("/tmp/autocomplete_test.html")
+        test_file.write_text(test_html.strip())
+        file_url = f"file://{test_file}"
+        await bridge.navigate(tab_id, file_url, wait_until="load")
+        print("✓ Page loaded")
+
+        # Screenshot
+        screenshot = await bridge.screenshot(tab_id)
+        print(f"Screenshot: {len(screenshot.get('data', ''))} bytes")
+
+        # Test 1: Fast typing (no delay) - may fail
+        print("\n--- Test 1: Fast typing (delay_ms=0) ---")
+        await bridge.click(tab_id, "#search")
+        await bridge.type_text(tab_id, "#search", "Ger", clear_first=True, delay_ms=0)
+        await asyncio.sleep(0.5)
+
+        fast_result = await bridge.evaluate(
+            tab_id, "(function() { return document.getElementById('search').value; })()"
+        )
+        fast_value = fast_result.get("result", "")
+        print(f"Value after fast typing: '{fast_value}'")
+
+        # Check events
+        events_result = await bridge.evaluate(
+            tab_id, "(function() { return window.inputEvents; })()"
+        )
+        print(f"Events logged: {events_result.get('result', [])}")
+
+        # Test 2: Slow typing (with delay) - should work
+        print("\n--- Test 2: Slow typing (delay_ms=100) ---")
+        await bridge.click(tab_id, "#search")
+        await bridge.type_text(tab_id, "#search", "United", clear_first=True, delay_ms=100)
+        await asyncio.sleep(0.5)
+
+        slow_result = await bridge.evaluate(
+            tab_id, "(function() { return document.getElementById('search').value; })()"
+        )
+        slow_value = slow_result.get("result", "")
+        print(f"Value after slow typing: '{slow_value}'")
+
+        # Check if dropdown appeared
+        dropdown_result = await bridge.evaluate(
+            tab_id,
+            "(function() { return document.querySelectorAll("
+            "'.autocomplete-items div').length; })()",
+        )
+        dropdown_count = dropdown_result.get("result", 0)
+        print(f"Dropdown items: {dropdown_count}")
+
+        # Screenshot with dropdown
+        screenshot_dropdown = await bridge.screenshot(tab_id)
+        print(f"Screenshot with dropdown: {len(screenshot_dropdown.get('data', ''))} bytes")
+
+        # Results
+        print("\n--- Results ---")
+        if "United" in slow_value:
+            print("✓ PASS: Slow typing with delay_ms worked")
+        else:
+            print("✗ FAIL: Slow typing still didn't work")
+
+        if dropdown_count > 0:
+            print("✓ PASS: Autocomplete dropdown appeared")
+        else:
+            print("⚠ WARNING: No autocomplete dropdown")
+
+        await bridge.destroy_context(group_id)
+        print("\n✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(test_autocomplete())

.claude/skills/browser-edge-cases/scripts/test_10_huge_dom.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python
+"""
+Test #10: LinkedIn Huge DOM Tree
+
+Symptom: browser_snapshot() hangs forever
+Root Cause: 10k+ DOM nodes, accessibility tree has 50k+ nodes
+Detection: document.querySelectorAll('*').length > 5000
+Fix: Add timeout (10s default), truncate tree at 2000 nodes
+"""
+
+import asyncio
+import sys
+import time
+import base64
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+CONTEXT_NAME = "huge-dom-test"
+
+
+async def test_huge_dom():
+    """Test snapshot performance on huge DOM trees."""
+    print("=" * 70)
+    print("TEST #10: Huge DOM Tree (LinkedIn-style)")
+    print("=" * 70)
+
+    bridge = BeelineBridge()
+
+    try:
+        await bridge.start()
+
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+        else:
+            print("✗ Extension not connected")
+            return
+
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        # Test 1: Small DOM (baseline)
+        print("\n--- Test 1: Small DOM (baseline) ---")
+        small_html = """
+        <!DOCTYPE html>
+        <html><body>
+            <h1>Small Page</h1>
+            <p>A few elements</p>
+            <button>Click me</button>
+        </body></html>
+        """
+        data_url = f"data:text/html;base64,{base64.b64encode(small_html.encode()).decode()}"
+        await bridge.navigate(tab_id, data_url, wait_until="load")
+
+        start = time.perf_counter()
+        snapshot = await bridge.snapshot(tab_id, timeout_s=5.0)
+        elapsed = time.perf_counter() - start
+        tree_len = len(snapshot.get("tree", ""))
+        print(f"Small DOM snapshot: {elapsed:.3f}s, {tree_len} chars")
+
+        # Test 2: Generate huge DOM
+        print("\n--- Test 2: Huge DOM (5000+ elements) ---")
+        huge_html = """
+        <!DOCTYPE html>
+        <html><body>
+        <h1>Huge DOM Test</h1>
+        <div id="container"></div>
+        <script>
+            const container = document.getElementById('container');
+            for (let i = 0; i < 5000; i++) {
+                const div = document.createElement('div');
+                div.className = 'item-' + i;
+                div.innerHTML = '<span>Item ' + i + '</span><button>Action</button>';
+                container.appendChild(div);
+            }
+        </script>
+        </body></html>
+        """
+        data_url = f"data:text/html;base64,{base64.b64encode(huge_html.encode()).decode()}"
+        await bridge.navigate(tab_id, data_url, wait_until="load")
+
+        # Count elements
+        count_result = await bridge.evaluate(
+            tab_id, "(function() { return document.querySelectorAll('*').length; })()"
+        )
+        elem_count = count_result.get("result", 0)
+        print(f"DOM elements: {elem_count}")
+
+        # Skip screenshot on huge DOM - it can timeout
+        # Instead verify page loaded by checking DOM
+        print("✓ Page verified (skipping screenshot on huge DOM)")
+
+        # Test snapshot with timeout
+        print("\n--- Testing snapshot with 10s timeout ---")
+        start = time.perf_counter()
+        try:
+            snapshot = await bridge.snapshot(tab_id, timeout_s=10.0)
+            elapsed = time.perf_counter() - start
+            tree_len = len(snapshot.get("tree", ""))
+            truncated = "(truncated)" in snapshot.get("tree", "")
+            print(f"✓ Huge DOM snapshot: {elapsed:.3f}s, {tree_len} chars, truncated={truncated}")
+
+            if elapsed < 5.0:
+                print("✓ PASS: Snapshot completed quickly")
+            else:
+                print(f"⚠ WARNING: Snapshot took {elapsed:.1f}s")
+
+            if truncated:
+                print("✓ PASS: Tree was truncated to prevent hang")
+            else:
+                print("⚠ WARNING: Tree not truncated (may need adjustment)")
+
+        except asyncio.TimeoutError:
+            print("✗ FAIL: Snapshot timed out (this shouldn't happen)")
+
+        # Test 3: Real LinkedIn
+        print("\n--- Test 3: Real LinkedIn Feed ---")
+        await bridge.navigate(
+            tab_id, "https://www.linkedin.com/feed", wait_until="load", timeout_ms=30000
+        )
+        await asyncio.sleep(2)
+
+        count_result = await bridge.evaluate(
+            tab_id, "(function() { return document.querySelectorAll('*').length; })()"
+        )
+        elem_count = count_result.get("result", 0)
+        print(f"LinkedIn DOM elements: {elem_count}")
+
+        start = time.perf_counter()
+        try:
+            snapshot = await bridge.snapshot(tab_id, timeout_s=15.0)
+            elapsed = time.perf_counter() - start
+            tree_len = len(snapshot.get("tree", ""))
+            truncated = "(truncated)" in snapshot.get("tree", "")
+            print(f"LinkedIn snapshot: {elapsed:.3f}s, {tree_len} chars, truncated={truncated}")
+
+            if elapsed < 5.0:
+                print("✓ PASS: LinkedIn snapshot fast enough")
+            elif elapsed < 15.0:
+                print("⚠ WARNING: LinkedIn snapshot slow but within timeout")
+            else:
+                print("✗ FAIL: LinkedIn snapshot too slow")
+
+        except asyncio.TimeoutError:
+            print("✗ FAIL: LinkedIn snapshot timed out")
+
+        await bridge.destroy_context(group_id)
+        print("\n✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(test_huge_dom())

.claude/skills/browser-edge-cases/scripts/test_13_spa_navigation.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python
+"""
+Test #13: SPA Navigation Events
+
+Symptom: wait_until="load" fires before content ready
+Root Cause: SPA uses client-side routing, no full page load
+Detection: URL changes but load event already fired
+Fix: Use wait_until="networkidle" or wait_for_selector
+"""
+
+import asyncio
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+CONTEXT_NAME = "spa-nav-test"
+
+
+async def test_spa_navigation():
+    """Test navigation timing on SPA pages."""
+    print("=" * 70)
+    print("TEST #13: SPA Navigation Events")
+    print("=" * 70)
+
+    bridge = BeelineBridge()
+
+    try:
+        await bridge.start()
+
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+        else:
+            print("✗ Extension not connected")
+            return
+
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        # Create a test SPA
+        spa_html = """
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <title>SPA Test</title>
+            <style>
+                nav a { margin-right: 10px; }
+                .page { padding: 20px; border: 1px solid #ccc; margin-top: 10px; }
+            </style>
+        </head>
+        <body>
+            <nav>
+                <a href="#home" onclick="navigate('home')">Home</a>
+                <a href="#about" onclick="navigate('about')">About</a>
+                <a href="#contact" onclick="navigate('contact')">Contact</a>
+            </nav>
+            <div id="app" class="page">
+                <h1>Loading...</h1>
+            </div>
+            <script>
+                // Simulate SPA routing
+                let currentPage = '';
+
+                async function navigate(page) {
+                    event.preventDefault();
+                    currentPage = page;
+
+                    // Show loading state
+                    document.getElementById('app').innerHTML = '<h1>Loading...</h1>';
+
+                    // Simulate async content loading (like real SPAs)
+                    await new Promise(r => setTimeout(r, 500));
+
+                    // Render content
+                    const content = {
+                        home: '<h1>Home Page</h1><p>Welcome!</p>'
+                            + '<button id="home-btn">Home Action</button>',
+                        about: '<h1>About Page</h1><p>Simulated SPA.</p>'
+                            + '<button id="about-btn">About Action</button>',
+                        contact: '<h1>Contact Page</h1>'
+                            + '<p>Contact us at test@example.com</p>'
+                            + '<button id="contact-btn">Contact Action</button>'
+                    };
+
+                    document.getElementById('app').innerHTML = content[page] || '<h1>404</h1>';
+                    window.location.hash = page;
+                }
+
+                // Initial load with delay (simulates SPA hydration)
+                setTimeout(() => {
+                    navigate('home');
+                }, 1000);
+
+                // Track for testing
+                window.pageLoads = [];
+                window.addEventListener('hashchange', () => {
+                    window.pageLoads.push(window.location.hash);
+                });
+            </script>
+        </body>
+        </html>
+        """
+
+        # Write to file and use file:// URL (data: URLs don't work well with extension)
+        test_file = Path("/tmp/spa_test.html")
+        test_file.write_text(spa_html.strip())
+        file_url = f"file://{test_file}"
+
+        # Test 1: wait_until="load" - may fire before content ready
+        print("\n--- Test 1: wait_until='load' ---")
+        start = time.perf_counter()
+        await bridge.navigate(tab_id, file_url, wait_until="load")
+        elapsed = time.perf_counter() - start
+        print(f"Navigation completed in {elapsed:.3f}s")
+
+        # Check content immediately
+        content = await bridge.evaluate(
+            tab_id,
+            "(function() { return document.getElementById('app').innerText; })()",
+        )
+        print(f"Content immediately after load: '{content.get('result', '')}'")
+
+        # Screenshot
+        screenshot = await bridge.screenshot(tab_id)
+        print(f"Screenshot: {len(screenshot.get('data', ''))} bytes")
+
+        # Wait for content
+        print("\n--- Waiting for content to hydrate ---")
+        await bridge.wait_for_selector(tab_id, "#home-btn", timeout_ms=5000)
+        print("✓ Content loaded")
+
+        # Check content after wait
+        content_after = await bridge.evaluate(
+            tab_id,
+            "(function() { return document.getElementById('app').innerText; })()",
+        )
+        print(f"Content after wait: '{content_after.get('result', '')}'")
+
+        # Test 2: SPA navigation (no full page load)
+        print("\n--- Test 2: SPA client-side navigation ---")
+
+        # Click "About" link
+        await bridge.click(tab_id, 'a[href="#about"]')
+        await asyncio.sleep(1)
+
+        # Check if content changed
+        about_content = await bridge.evaluate(
+            tab_id,
+            "(function() { return document.getElementById('app').innerText; })()",
+        )
+        print(f"Content after SPA nav: '{about_content.get('result', '')}'")
+
+        if "About Page" in about_content.get("result", ""):
+            print("✓ PASS: SPA navigation worked")
+        else:
+            print("✗ FAIL: SPA navigation didn't update content")
+
+        # Test 3: wait_until="networkidle"
+        print("\n--- Test 3: wait_until='networkidle' ---")
+        await bridge.navigate(tab_id, file_url, wait_until="networkidle", timeout_ms=10000)
+
+        # Check content immediately
+        content_networkidle = await bridge.evaluate(
+            tab_id,
+            "(function() { return document.getElementById('app').innerText; })()",
+        )
+        print(f"Content after networkidle: '{content_networkidle.get('result', '')}'")
+
+        if "Home Page" in content_networkidle.get("result", ""):
+            print("✓ PASS: networkidle waited for content")
+        else:
+            print("⚠ WARNING: networkidle didn't wait long enough")
+
+        await bridge.destroy_context(group_id)
+        print("\n✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(test_spa_navigation())

.claude/skills/browser-edge-cases/scripts/test_15_screenshot.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python
+"""
+Test #15: Screenshot Functionality
+
+Tests browser_screenshot across multiple scenarios:
+- Basic viewport screenshot
+- Full-page screenshot
+- Selector-based screenshot
+- Screenshot on complex DOM
+- Timeout handling
+
+Category: screenshot
+"""
+
+import asyncio
+import base64
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+CONTEXT_NAME = "screenshot-test"
+
+SIMPLE_HTML = """<!DOCTYPE html>
+<html>
+<head><style>
+  body { margin: 0; background: #fff; font-family: sans-serif; }
+  h1 { color: #333; padding: 20px; }
+  .box { width: 200px; height: 100px; background: #4a90e2; margin: 20px; }
+  .long-content { height: 2000px; background: linear-gradient(blue, red); }
+</style></head>
+<body>
+  <h1 id="title">Screenshot Test Page</h1>
+  <div class="box" id="target-box">Target Box</div>
+  <div class="long-content"></div>
+</body>
+</html>"""
+
+
+def check_png(data: str) -> bool:
+    """Verify that base64 data decodes to a valid PNG."""
+    try:
+        raw = base64.b64decode(data)
+        return raw[:8] == b"\x89PNG\r\n\x1a\n"
+    except Exception:
+        return False
+
+
+async def test_basic_screenshot(bridge: BeelineBridge, tab_id: int, data_url: str):
+    print("\n--- Test 1: Basic Viewport Screenshot ---")
+    await bridge.navigate(tab_id, data_url, wait_until="load")
+    await asyncio.sleep(0.5)
+
+    start = time.perf_counter()
+    result = await bridge.screenshot(tab_id)
+    elapsed = time.perf_counter() - start
+
+    ok = result.get("ok")
+    data = result.get("data", "")
+    mime = result.get("mimeType", "")
+
+    print(f"  ok={ok}, mimeType={mime}, elapsed={elapsed:.3f}s")
+    print(f"  data length: {len(data)} chars")
+
+    if ok and data:
+        valid_png = check_png(data)
+        print(f"  valid PNG: {valid_png}")
+        if valid_png:
+            raw = base64.b64decode(data)
+            print(f"  PNG size: {len(raw)} bytes")
+            print("  ✓ PASS: Basic screenshot works")
+            return True
+        else:
+            print("  ✗ FAIL: Data is not a valid PNG")
+    else:
+        print(f"  ✗ FAIL: {result.get('error', 'no data')}")
+    return False
+
+
+async def test_full_page_screenshot(bridge: BeelineBridge, tab_id: int, data_url: str):
+    print("\n--- Test 2: Full Page Screenshot ---")
+    await bridge.navigate(tab_id, data_url, wait_until="load")
+    await asyncio.sleep(0.5)
+
+    viewport_result = await bridge.screenshot(tab_id, full_page=False)
+    full_result = await bridge.screenshot(tab_id, full_page=True)
+
+    v_data = viewport_result.get("data", "")
+    f_data = full_result.get("data", "")
+
+    if not v_data or not f_data:
+        print(f"  ✗ FAIL: viewport ok={viewport_result.get('ok')}, full ok={full_result.get('ok')}")
+        return False
+
+    v_size = len(base64.b64decode(v_data))
+    f_size = len(base64.b64decode(f_data))
+    print(f"  Viewport PNG: {v_size} bytes")
+    print(f"  Full page PNG: {f_size} bytes")
+
+    if f_size > v_size:
+        print("  ✓ PASS: Full page larger than viewport")
+        return True
+    else:
+        print("  ✗ FAIL: Full page not larger than viewport (may not capture long pages)")
+        return False
+
+
+async def test_selector_screenshot(bridge: BeelineBridge, tab_id: int, data_url: str):
+    print("\n--- Test 3: Selector Screenshot ---")
+    await bridge.navigate(tab_id, data_url, wait_until="load")
+    await asyncio.sleep(0.5)
+
+    # selector param exists in signature but may not be implemented
+    result = await bridge.screenshot(tab_id, selector="#target-box")
+
+    ok = result.get("ok")
+    data = result.get("data", "")
+
+    if ok and data:
+        # If implemented, the box screenshot should be smaller than a full viewport screenshot
+        full_result = await bridge.screenshot(tab_id)
+        full_data = full_result.get("data", "")
+
+        if full_data:
+            sel_size = len(base64.b64decode(data))
+            full_size = len(base64.b64decode(full_data))
+            print(f"  Selector PNG: {sel_size} bytes")
+            print(f"  Full page PNG: {full_size} bytes")
+            if sel_size < full_size:
+                print("  ✓ PASS: Selector screenshot smaller than full page")
+                return True
+            else:
+                print("  ⚠ WARNING: Selector screenshot not smaller (may be full page)")
+                return False
+    else:
+        print(
+            "  ⚠ NOT IMPLEMENTED: selector param ignored"
+            f" (returns full page) - error={result.get('error')}"
+        )
+        print("  NOTE: selector parameter exists in signature but is not used in implementation")
+        return False
+
+
+async def test_screenshot_url_metadata(bridge: BeelineBridge, tab_id: int):
+    print("\n--- Test 4: Screenshot URL Metadata ---")
+    await bridge.navigate(tab_id, "https://example.com", wait_until="load")
+    await asyncio.sleep(1)
+
+    result = await bridge.screenshot(tab_id)
+    url = result.get("url", "")
+    tab = result.get("tabId")
+
+    print(f"  url={url!r}, tabId={tab}")
+
+    if "example.com" in url:
+        print("  ✓ PASS: URL metadata captured correctly")
+        return True
+    else:
+        print(f"  ✗ FAIL: Expected example.com in URL, got {url!r}")
+        return False
+
+
+async def test_screenshot_timeout(bridge: BeelineBridge, tab_id: int, data_url: str):
+    print("\n--- Test 5: Timeout Handling ---")
+    await bridge.navigate(tab_id, data_url, wait_until="load")
+
+    # Very short timeout - likely still completes since simple page
+    start = time.perf_counter()
+    result = await bridge.screenshot(tab_id, timeout_s=0.001)
+    elapsed = time.perf_counter() - start
+
+    if not result.get("ok"):
+        err = result.get("error", "")
+        if "timed out" in err or "cancelled" in err:
+            print(f"  ✓ PASS: Timeout handled gracefully: {err!r}")
+            return True
+        else:
+            print(f"  ⚠ Fast enough to beat timeout: {err!r} in {elapsed:.3f}s")
+            return True  # Not a failure, just fast
+    else:
+        print(
+            f"  ⚠ Screenshot completed before timeout ({elapsed:.3f}s) - too fast to test timeout"
+        )
+        return True  # Still ok, just very fast
+
+
+async def test_screenshot_complex_site(bridge: BeelineBridge, tab_id: int):
+    print("\n--- Test 6: Complex Site (example.com) ---")
+    await bridge.navigate(tab_id, "https://example.com", wait_until="load")
+    await asyncio.sleep(1)
+
+    start = time.perf_counter()
+    result = await bridge.screenshot(tab_id)
+    elapsed = time.perf_counter() - start
+
+    ok = result.get("ok")
+    data = result.get("data", "")
+
+    print(f"  ok={ok}, elapsed={elapsed:.3f}s, data_len={len(data)}")
+    if ok and check_png(data):
+        print("  ✓ PASS: Screenshot on real site works")
+        return True
+    else:
+        print(f"  ✗ FAIL: {result.get('error', 'bad data')}")
+        return False
+
+
+async def main():
+    print("=" * 70)
+    print("TEST #15: Screenshot Functionality")
+    print("=" * 70)
+
+    bridge = BeelineBridge()
+
+    try:
+        await bridge.start()
+
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+            print(f"Waiting for extension... ({i + 1}/10)")
+        else:
+            print("✗ Extension not connected. Ensure Chrome with Beeline extension is running.")
+            return
+
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        data_url = f"data:text/html;base64,{base64.b64encode(SIMPLE_HTML.encode()).decode()}"
+
+        results = {
+            "basic": await test_basic_screenshot(bridge, tab_id, data_url),
+            "full_page": await test_full_page_screenshot(bridge, tab_id, data_url),
+            "selector": await test_selector_screenshot(bridge, tab_id, data_url),
+            "metadata": await test_screenshot_url_metadata(bridge, tab_id),
+            "timeout": await test_screenshot_timeout(bridge, tab_id, data_url),
+            "complex_site": await test_screenshot_complex_site(bridge, tab_id),
+        }
+
+        print("\n" + "=" * 70)
+        print("SUMMARY")
+        print("=" * 70)
+        for name, passed in results.items():
+            status = "✓ PASS" if passed else "✗ FAIL"
+            print(f"  {status}: {name}")
+
+        passed_count = sum(1 for v in results.values() if v)
+        total = len(results)
+        print(f"\n  {passed_count}/{total} tests passed")
+
+        await bridge.destroy_context(group_id)
+        print("\n✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+        print("✓ Bridge stopped")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

.claude/skills/browser-edge-cases/scripts/test_case.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python
+"""
+Browser Edge Case Test Template
+
+This script provides a template for testing and debugging browser tool failures
+on specific websites. Use this to reproduce, isolate, and verify fixes.
+
+Usage:
+    1. Copy this file: cp test_case.py test_#[number]_[site].py
+    2. Fill in the CONFIG section with your test details
+    3. Run: uv run python test_#[number]_[site].py
+
+Example:
+    uv run python test_01_linkedin_scroll.py
+"""
+
+import asyncio
+import sys
+import time
+from pathlib import Path
+
+# Add tools to path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "tools" / "src"))
+
+from gcu.browser.bridge import BeelineBridge
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# CONFIG: Fill in these values for your test case
+# ═══════════════════════════════════════════════════════════════════════════════
+
+TEST_CASE = {
+    "number": 1,
+    "name": "LinkedIn Nested Scroll Container",
+    "site": "https://www.linkedin.com/feed",
+    "simple_site": "https://example.com",
+    "category": "scroll",  # scroll, click, input, snapshot, navigation
+    "symptom": "scroll() returns success but page doesn't move",
+}
+
+BRIDGE_PORT = 9229
+CONTEXT_NAME = "edge-case-test"
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# TEST FUNCTIONS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+async def test_simple_site(bridge: BeelineBridge, tab_id: int) -> dict:
+    """Test that the tool works on a simple site (baseline)."""
+    print("\n--- Baseline Test (Simple Site) ---")
+
+    await bridge.navigate(tab_id, TEST_CASE["simple_site"], wait_until="load")
+    await asyncio.sleep(1)
+
+    # Adjust this based on category
+    if TEST_CASE["category"] == "scroll":
+        result = await bridge.scroll(tab_id, "down", 100)
+        print(f"  Scroll result: {result}")
+        return result
+    elif TEST_CASE["category"] == "click":
+        # Add click test
+        pass
+    elif TEST_CASE["category"] == "snapshot":
+        result = await bridge.snapshot(tab_id, timeout_s=5.0)
+        print(f"  Snapshot length: {len(result.get('tree', ''))}")
+        return result
+
+    return {"ok": True}
+
+
+async def test_problematic_site(bridge: BeelineBridge, tab_id: int) -> dict:
+    """Test the tool on the problematic site."""
+    print("\n--- Problem Site Test ---")
+
+    await bridge.navigate(tab_id, TEST_CASE["site"], wait_until="load", timeout_ms=30000)
+    await asyncio.sleep(2)
+
+    # Adjust this based on category
+    if TEST_CASE["category"] == "scroll":
+        # Get scroll positions before
+        before = await bridge.evaluate(
+            tab_id,
+            """
+            (function() {
+                const results = { window: { y: window.scrollY } };
+                document.querySelectorAll('*').forEach((el, i) => {
+                    const style = getComputedStyle(el);
+                    if ((style.overflowY === 'scroll' || style.overflowY === 'auto') &&
+                        el.scrollHeight > el.clientHeight) {
+                        results['el_' + i] = {
+                            tag: el.tagName,
+                            scrollTop: el.scrollTop,
+                            class: el.className.substring(0, 30)
+                        };
+                    }
+                });
+                return results;
+            })();
+        """,
+        )
+        print(f"  Before scroll: {before.get('result', {})}")
+
+        # Try to scroll
+        result = await bridge.scroll(tab_id, "down", 500)
+        print(f"  Scroll result: {result}")
+
+        await asyncio.sleep(1)
+
+        # Get scroll positions after
+        after = await bridge.evaluate(
+            tab_id,
+            """
+            (function() {
+                const results = { window: { y: window.scrollY } };
+                document.querySelectorAll('*').forEach((el, i) => {
+                    const style = getComputedStyle(el);
+                    if ((style.overflowY === 'scroll' || style.overflowY === 'auto') &&
+                        el.scrollHeight > el.clientHeight) {
+                        results['el_' + i] = {
+                            tag: el.tagName,
+                            scrollTop: el.scrollTop,
+                            class: el.className.substring(0, 30)
+                        };
+                    }
+                });
+                return results;
+            })();
+        """,
+        )
+        print(f"  After scroll: {after.get('result', {})}")
+
+        # Check if anything changed
+        before_data = before.get("result", {}) or {}
+        after_data = after.get("result", {}) or {}
+
+        changed = False
+        for key in after_data:
+            if key in before_data:
+                b_val = (
+                    before_data[key].get("scrollTop", 0)
+                    if isinstance(before_data[key], dict)
+                    else 0
+                )
+                a_val = (
+                    after_data[key].get("scrollTop", 0) if isinstance(after_data[key], dict) else 0
+                )
+                if a_val != b_val:
+                    print(f"  ✓ CHANGE DETECTED: {key} scrolled from {b_val} to {a_val}")
+                    changed = True
+
+        if not changed:
+            print("  ✗ NO CHANGE: Scroll did not affect any container")
+
+        return {"ok": changed, "scroll_result": result}
+
+    elif TEST_CASE["category"] == "snapshot":
+        start = time.perf_counter()
+        try:
+            result = await bridge.snapshot(tab_id, timeout_s=15.0)
+            elapsed = time.perf_counter() - start
+            tree_len = len(result.get("tree", ""))
+            print(f"  Snapshot completed in {elapsed:.2f}s, {tree_len} chars")
+            return {"ok": True, "elapsed": elapsed, "tree_length": tree_len}
+        except asyncio.TimeoutError:
+            print("  ✗ SNAPSHOT TIMED OUT")
+            return {"ok": False, "error": "timeout"}
+
+    return {"ok": True}
+
+
+async def detect_root_cause(bridge: BeelineBridge, tab_id: int) -> dict:
+    """Run detection scripts to identify the root cause."""
+    print("\n--- Root Cause Detection ---")
+
+    detections = {}
+
+    # Detection 1: Nested scrollable containers
+    scroll_check = await bridge.evaluate(
+        tab_id,
+        """
+        (function() {
+            const candidates = [];
+            document.querySelectorAll('*').forEach(el => {
+                const style = getComputedStyle(el);
+                if (style.overflow.includes('scroll') || style.overflow.includes('auto')) {
+                    const rect = el.getBoundingClientRect();
+                    if (rect.width > 100 && rect.height > 100) {
+                        candidates.push({
+                            tag: el.tagName,
+                            area: rect.width * rect.height,
+                            class: el.className.substring(0, 30)
+                        });
+                    }
+                }
+            });
+            candidates.sort((a, b) => b.area - a.area);
+            return {
+                count: candidates.length,
+                largest: candidates[0]
+            };
+        })();
+    """,
+    )
+    detections["nested_scroll"] = scroll_check.get("result", {})
+    print(f"  Nested scroll containers: {detections['nested_scroll']}")
+
+    # Detection 2: Shadow DOM
+    shadow_check = await bridge.evaluate(
+        tab_id,
+        """
+        (function() {
+            const withShadow = [];
+            document.querySelectorAll('*').forEach(el => {
+                if (el.shadowRoot) {
+                    withShadow.push(el.tagName);
+                }
+            });
+            return { count: withShadow.length, elements: withShadow.slice(0, 5) };
+        })();
+    """,
+    )
+    detections["shadow_dom"] = shadow_check.get("result", {})
+    print(f"  Shadow DOM: {detections['shadow_dom']}")
+
+    # Detection 3: iframes
+    iframe_check = await bridge.evaluate(
+        tab_id,
+        """
+        (function() {
+            const iframes = document.querySelectorAll('iframe');
+            return { count: iframes.length };
+        })();
+    """,
+    )
+    detections["iframes"] = iframe_check.get("result", {})
+    print(f"  iframes: {detections['iframes']}")
+
+    # Detection 4: DOM size
+    dom_check = await bridge.evaluate(
+        tab_id,
+        """
+        (function() {
+            return {
+                elements: document.querySelectorAll('*').length,
+                body_children: document.body.children.length
+            };
+        })();
+    """,
+    )
+    detections["dom_size"] = dom_check.get("result", {})
+    print(f"  DOM size: {detections['dom_size']}")
+
+    # Detection 5: Framework detection
+    framework_check = await bridge.evaluate(
+        tab_id,
+        """
+        (function() {
+            return {
+                react: !!document.querySelector('[data-reactroot], [data-reactid]'),
+                vue: !!document.querySelector('[data-v-]'),
+                angular: !!document.querySelector('[ng-app], [ng-version]')
+            };
+        })();
+    """,
+    )
+    detections["frameworks"] = framework_check.get("result", {})
+    print(f"  Frameworks: {detections['frameworks']}")
+
+    return detections
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MAIN
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+async def main():
+    print("=" * 70)
+    print(f"EDGE CASE TEST #{TEST_CASE['number']}: {TEST_CASE['name']}")
+    print("=" * 70)
+    print(f"Site: {TEST_CASE['site']}")
+    print(f"Category: {TEST_CASE['category']}")
+    print(f"Symptom: {TEST_CASE['symptom']}")
+
+    bridge = BeelineBridge()
+
+    try:
+        print("\n--- Starting Bridge ---")
+        await bridge.start()
+
+        # Wait for extension connection
+        for i in range(10):
+            await asyncio.sleep(1)
+            if bridge.is_connected:
+                print("✓ Extension connected!")
+                break
+            print(f"Waiting for extension... ({i + 1}/10)")
+        else:
+            print("✗ Extension not connected. Ensure Chrome with Beeline extension is running.")
+            return
+
+        # Create browser context
+        context = await bridge.create_context(CONTEXT_NAME)
+        tab_id = context.get("tabId")
+        group_id = context.get("groupId")
+        print(f"✓ Created tab: {tab_id}")
+
+        # Run tests
+        baseline_result = await test_simple_site(bridge, tab_id)
+        problem_result = await test_problematic_site(bridge, tab_id)
+        detections = await detect_root_cause(bridge, tab_id)
+
+        # Summary
+        print("\n" + "=" * 70)
+        print("SUMMARY")
+        print("=" * 70)
+        print(f"Baseline test: {'✓ PASS' if baseline_result.get('ok') else '✗ FAIL'}")
+        print(f"Problem test: {'✓ PASS' if problem_result.get('ok') else '✗ FAIL'}")
+        print(f"Root cause indicators: {list(k for k, v in detections.items() if v)}")
+
+        # Cleanup
+        print("\n--- Cleanup ---")
+        await bridge.destroy_context(group_id)
+        print("✓ Context destroyed")
+
+    finally:
+        await bridge.stop()
+        print("✓ Bridge stopped")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

.claude/skills/test-reporting/SKILL.md

@@ -0,0 +1,225 @@
+# Integration Test Reporting Skill
+
+Run the Level 2 dummy agent integration test suite and produce a detailed HTML report with per-test input → outcome analysis.
+
+## Trigger
+
+User wants to run integration tests and see results:
+- `/test-reporting`
+- `/test-reporting test_component_queen_live.py`
+- `/test-reporting --all`
+
+## SOP: Running Tests
+
+### Step 1: Select Scope
+
+If the user provides a specific test file or pattern, use it. Otherwise run the full suite.
+
+```bash
+# Full suite
+cd core && echo "1" | uv run python tests/dummy_agents/run_all.py --interactive 2>&1
+
+# Specific file (requires manual provider setup)
+cd core && uv run python -c "
+import sys
+sys.path.insert(0, '.')
+from tests.dummy_agents.run_all import detect_available
+from tests.dummy_agents.conftest import set_llm_selection
+
+avail = detect_available()
+claude = [p for p in avail if 'Claude Code' in p['name']]
+if not claude:
+    avail_names = [p['name'] for p in avail]
+    raise RuntimeError(f'No Claude Code subscription. Available: {avail_names}')
+provider = claude[0]
+set_llm_selection(
+    model=provider['model'],
+    api_key=provider['api_key'],
+    extra_headers=provider.get('extra_headers'),
+    api_base=provider.get('api_base'),
+)
+
+import pytest
+sys.exit(pytest.main([
+    'tests/dummy_agents/TEST_FILE_HERE',
+    '-v', '--override-ini=asyncio_mode=auto', '--no-header', '--tb=long',
+    '--log-cli-level=WARNING', '--junitxml=/tmp/hive_test_results.xml',
+]))
+"
+```
+
+### Step 2: Collect Results
+
+After the test run completes, collect:
+1. **JUnit XML** from `--junitxml` output (if available)
+2. **stdout/stderr** from the run
+3. **Summary table** from `run_all.py` output (the Unicode table)
+
+### Step 3: Generate HTML Report
+
+Write the report to `/tmp/hive_integration_test_report.html`.
+
+The report MUST include these sections:
+
+#### Header
+- Run timestamp (ISO 8601)
+- Provider used (model name, source)
+- Total tests / passed / failed / skipped
+- Total wall-clock time
+- Overall verdict: PASS (all green) or FAIL (with count)
+
+#### Per-Test Table
+
+For EVERY test (not just failures), include a row with:
+
+| Column | Description |
+|--------|-------------|
+| Component | Test file grouping (e.g., `component_queen_live`) |
+| Test Name | Function name (e.g., `test_queen_starts_in_planning_without_worker`) |
+| Status | PASS / FAIL / SKIP / ERROR with color badge |
+| Duration | Wall-clock seconds |
+| What | One-line description of what the test verifies |
+| How | How it works (setup → action → assertion) |
+| Why | Why this test matters (what bug/behavior it catches) |
+| Input | The input data or configuration (graph spec, initial prompt, phase, etc.) |
+| Expected Outcome | What the test asserts |
+| Actual Outcome | What actually happened (PASS: matches expected / FAIL: actual vs expected) |
+| Failure Detail | For failures only: full traceback + diagnosis |
+
+#### What / How / Why Descriptions
+
+These MUST be derived from the test function's docstring and code. Read each test file to extract:
+- **What**: From the docstring first line
+- **How**: From the test body (what fixtures, what graph, what assertions)
+- **Why**: From the docstring body or "Why this matters" section in the test module
+
+Use these mappings for the component test files:
+
+```
+test_component_llm.py          → "LLM Provider" — streaming, tool calling, tokens
+test_component_tools.py        → "Tool Registry + MCP" — connection, execution
+test_component_event_loop.py   → "EventLoopNode" — iteration, output, stall
+test_component_edges.py        → "Edge Evaluation" — conditional, priority
+test_component_conversation.py → "Conversation Persistence" — storage, cursor
+test_component_escalation.py   → "Escalation Flow" — worker→queen signaling
+test_component_continuous.py   → "Continuous Mode" — conversation threading
+test_component_queen.py        → "Queen Phase (Unit)" — phase state, tools, events
+test_component_queen_live.py   → "Queen Phase (Live)" — real queen, real LLM
+test_component_queen_state_machine.py → "Queen State Machine" — edge cases, races
+test_component_worker_comms.py → "Worker Communication" — events, data flow
+test_component_strict_outcomes.py → "Strict Outcomes" — exact path, output, quality
+```
+
+#### HTML Template
+
+Use this structure:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Hive Integration Test Report — {timestamp}</title>
+<style>
+  :root { --pass: #22c55e; --fail: #ef4444; --skip: #f59e0b; --bg: #0f172a; --surface: #1e293b; --text: #e2e8f0; --muted: #94a3b8; --border: #334155; }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: 'SF Mono', 'Fira Code', monospace; background: var(--bg); color: var(--text); padding: 2rem; line-height: 1.6; }
+  h1, h2, h3 { font-weight: 600; }
+  h1 { font-size: 1.5rem; margin-bottom: 1rem; }
+  h2 { font-size: 1.2rem; margin: 2rem 0 1rem; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }
+  .summary { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 1rem; margin-bottom: 2rem; }
+  .card { background: var(--surface); padding: 1rem; border-radius: 8px; border: 1px solid var(--border); }
+  .card .label { color: var(--muted); font-size: 0.75rem; text-transform: uppercase; }
+  .card .value { font-size: 1.5rem; font-weight: 700; margin-top: 0.25rem; }
+  .card .value.pass { color: var(--pass); }
+  .card .value.fail { color: var(--fail); }
+  table { width: 100%; border-collapse: collapse; font-size: 0.8rem; }
+  th { background: var(--surface); position: sticky; top: 0; text-align: left; padding: 0.5rem; border-bottom: 2px solid var(--border); color: var(--muted); text-transform: uppercase; font-size: 0.7rem; }
+  td { padding: 0.5rem; border-bottom: 1px solid var(--border); vertical-align: top; }
+  tr:hover { background: rgba(255,255,255,0.03); }
+  .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 0.7rem; font-weight: 700; }
+  .badge.pass { background: rgba(34,197,94,0.2); color: var(--pass); }
+  .badge.fail { background: rgba(239,68,68,0.2); color: var(--fail); }
+  .badge.skip { background: rgba(245,158,11,0.2); color: var(--skip); }
+  .detail { background: #1a1a2e; padding: 0.75rem; border-radius: 4px; margin-top: 0.5rem; font-size: 0.75rem; white-space: pre-wrap; overflow-x: auto; max-height: 200px; overflow-y: auto; }
+  .component-header { background: var(--surface); padding: 0.75rem 0.5rem; font-weight: 600; font-size: 0.85rem; }
+  .meta { color: var(--muted); font-size: 0.75rem; }
+</style>
+</head>
+<body>
+<h1>Hive Integration Test Report</h1>
+<p class="meta">Generated: {timestamp} | Provider: {provider} | Duration: {duration}s</p>
+
+<div class="summary">
+  <div class="card"><div class="label">Total</div><div class="value">{total}</div></div>
+  <div class="card"><div class="label">Passed</div><div class="value pass">{passed}</div></div>
+  <div class="card"><div class="label">Failed</div><div class="value fail">{failed}</div></div>
+  <div class="card"><div class="label">Verdict</div><div class="value {verdict_class}">{verdict}</div></div>
+</div>
+
+<h2>Test Results</h2>
+<table>
+<thead>
+<tr>
+  <th>Component</th>
+  <th>Test</th>
+  <th>Status</th>
+  <th>Time</th>
+  <th>What</th>
+  <th>Input → Expected → Actual</th>
+</tr>
+</thead>
+<tbody>
+<!-- For each test: -->
+<tr>
+  <td>{component}</td>
+  <td>{test_name}</td>
+  <td><span class="badge {status_class}">{status}</span></td>
+  <td>{duration}s</td>
+  <td>{what_description}</td>
+  <td>
+    <strong>Input:</strong> {input_description}<br>
+    <strong>Expected:</strong> {expected_outcome}<br>
+    <strong>Actual:</strong> {actual_outcome}
+    <!-- If failed: -->
+    <div class="detail">{failure_traceback}</div>
+  </td>
+</tr>
+</tbody>
+</table>
+
+<h2>Failure Analysis</h2>
+<!-- Only if there are failures -->
+<p>For each failure, provide:</p>
+<ul>
+  <li><strong>Root cause:</strong> Why it failed</li>
+  <li><strong>Impact:</strong> What this means for the system</li>
+  <li><strong>Suggested fix:</strong> How to address it</li>
+</ul>
+
+</body>
+</html>
+```
+
+### Step 4: Output
+
+1. Write the HTML file to `/tmp/hive_integration_test_report.html`
+2. Print the file path so the user can open it
+3. Print a concise summary to the terminal:
+   ```
+   Test Report: /tmp/hive_integration_test_report.html
+   Result: 74/76 PASSED (2 failures)
+   Failures:
+     - parallel_merge::test_parallel_disjoint_output_keys
+     - worker::test_worker_timestamped_note_artifact
+   ```
+
+## Key Rules
+
+1. ALWAYS use `--junitxml` when running pytest to get structured results
+2. ALWAYS read the test source files to populate What/How/Why columns — do not guess
+3. For Input/Expected/Actual, extract from the test's graph spec, assertions, and result
+4. Color-code everything: green for pass, red for fail, amber for skip
+5. Include the full traceback for failures in a scrollable `<div class="detail">`
+6. Group tests by component (file name) with a visual separator
+7. The report must be self-contained HTML (no external CSS/JS dependencies)

.github/ISSUE_TEMPLATE/link-discord.yml

@@ -1,31 +0,0 @@
-name: Link Discord Account
-description: Connect your GitHub and Discord for the bounty program
-title: "link: @{{ github.actor }}"
-labels: ["link-discord"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Link your Discord account to receive XP and role rewards when your bounty PRs are merged.
-
-        **How to find your Discord ID:**
-        1. Open Discord Settings > Advanced > Enable **Developer Mode**
-        2. Right-click your username > **Copy User ID**
-
-  - type: input
-    id: discord_id
-    attributes:
-      label: Discord User ID
-      description: "Your numeric Discord ID (not your username). Example: 123456789012345678"
-      placeholder: "123456789012345678"
-    validations:
-      required: true
-
-  - type: input
-    id: display_name
-    attributes:
-      label: Display Name (optional)
-      description: How you'd like to be credited
-      placeholder: "Jane Doe"
-    validations:
-      required: false

.github/ISSUE_TEMPLATE/standard-bounty.yml

@@ -0,0 +1,78 @@
+name: Standard Bounty
+description: A bounty task for general framework contributions (not integration-specific)
+title: "[Bounty]: "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Standard Bounty
+
+        This issue is part of the [Bounty Program](../../docs/bounty-program/README.md).
+        **Claim this bounty** by commenting below — a maintainer will assign you within 24 hours.
+
+  - type: dropdown
+    id: bounty-size
+    attributes:
+      label: Bounty Size
+      options:
+        - "Small (10 pts)"
+        - "Medium (30 pts)"
+        - "Large (75 pts)"
+        - "Extreme (150 pts)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: difficulty
+    attributes:
+      label: Difficulty
+      options:
+        - Easy
+        - Medium
+        - Hard
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What needs to be done to complete this bounty.
+      placeholder: |
+        Describe the specific task, including:
+        - What the contributor needs to do
+        - Links to relevant files in the repo
+        - Any context or motivation for the change
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance Criteria
+      description: What "done" looks like. The PR must meet all criteria.
+      placeholder: |
+        - [ ] Criterion 1
+        - [ ] Criterion 2
+        - [ ] CI passes
+    validations:
+      required: true
+
+  - type: textarea
+    id: relevant-files
+    attributes:
+      label: Relevant Files
+      description: Links to files or directories related to this bounty.
+      placeholder: |
+        - `path/to/file.py`
+        - `path/to/directory/`
+
+  - type: textarea
+    id: resources
+    attributes:
+      label: Resources
+      description: Links to docs, issues, or external references that will help.
+      placeholder: |
+        - Related issue: #XXXX
+        - Docs: https://...

.github/workflows/bounty-completed.yml

@@ -2,14 +2,22 @@ name: Bounty completed
 description: Awards points and notifies Discord when a bounty PR is merged
 
 on:
-  pull_request:
+  pull_request_target:
     types: [closed]
 
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "PR number to process (for missed bounties)"
+        required: true
+        type: number
+
 jobs:
   bounty-notify:
     if: >
-      github.event.pull_request.merged == true &&
-      contains(join(github.event.pull_request.labels.*.name, ','), 'bounty:')
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.pull_request.merged == true &&
+       contains(join(github.event.pull_request.labels.*.name, ','), 'bounty:'))
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions:
@@ -32,6 +40,8 @@ jobs:
           GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
           GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
           DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_BOUNTY_WEBHOOK_URL }}
+          BOT_API_URL: ${{ secrets.BOT_API_URL }}
+          BOT_API_KEY: ${{ secrets.BOT_API_KEY }}
           LURKR_API_KEY: ${{ secrets.LURKR_API_KEY }}
           LURKR_GUILD_ID: ${{ secrets.LURKR_GUILD_ID }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_NUMBER: ${{ inputs.pr_number || github.event.pull_request.number }}

.github/workflows/ci.yml

@@ -5,7 +5,7 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
-
+    
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -24,6 +24,8 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
 
       - name: Install dependencies
         run: uv sync --project core --group dev
@@ -54,12 +56,14 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
 
       - name: Install dependencies and run tests
+        working-directory: core
         run: |
-          cd core
           uv sync
-          uv run pytest tests/ -v
+          uv run pytest tests/ -v --ignore=tests/dummy_agents
 
   test-tools:
     name: Test Tools (${{ matrix.os }})
@@ -77,10 +81,12 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
 
       - name: Install dependencies and run tests
+        working-directory: tools
         run: |
-          cd tools
           uv sync --extra dev
           uv run pytest tests/ -v
 
@@ -98,10 +104,12 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
-
+        with:
+          enable-cache: true
+            
       - name: Install dependencies
+        working-directory: core
         run: |
-          cd core
           uv sync
 
       - name: Validate exported agents

.github/workflows/link-discord.yml

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

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

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

.github/workflows/pr-requirements.yml

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

.github/workflows/weekly-leaderboard.yml

@@ -35,6 +35,8 @@ jobs:
           GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
           GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
           DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_BOUNTY_WEBHOOK_URL }}
+          BOT_API_URL: ${{ secrets.BOT_API_URL }}
+          BOT_API_KEY: ${{ secrets.BOT_API_KEY }}
           LURKR_API_KEY: ${{ secrets.LURKR_API_KEY }}
           LURKR_GUILD_ID: ${{ secrets.LURKR_GUILD_ID }}
           SINCE_DATE: ${{ github.event.inputs.since_date || '' }}

.gitignore

@@ -13,6 +13,10 @@ out/
 .env
 .env.local
 .env.*.local
+.venv
+/venv
+tools/src/uv.lock
+
 
 # User configuration (copied from .example)
 config.yaml
@@ -66,11 +70,10 @@ tmp/
 temp/
 
 exports/*
+exports.old*
+artifacts/*
 
 .claude/settings.local.json
-.claude/skills/ship-it/
-
-.venv
 
 docs/github-issues/*
 core/tests/*dumps/*
@@ -78,3 +81,4 @@ core/tests/*dumps/*
 screenshots/*
 
 .gemini/*
+.coverage

.hive/browser-logs/browser-2026-04-04.jsonl

@@ -0,0 +1,9 @@
+{"type": "connection", "event": "connect", "ts": "2026-04-04T01:10:38.245667+00:00", "profile": "default"}
+{"type": "connection", "event": "hello", "details": {"version": "1.0"}, "ts": "2026-04-04T01:10:38.247207+00:00", "profile": "default"}
+{"type": "connection", "event": "disconnect", "ts": "2026-04-04T01:11:57.148273+00:00", "profile": "default"}
+{"type": "connection", "event": "connect", "ts": "2026-04-04T01:12:09.162378+00:00", "profile": "default"}
+{"type": "connection", "event": "hello", "details": {"version": "1.0"}, "ts": "2026-04-04T01:12:09.163899+00:00", "profile": "default"}
+{"type": "connection", "event": "disconnect", "ts": "2026-04-04T01:15:12.826042+00:00", "profile": "default"}
+{"type": "connection", "event": "connect", "ts": "2026-04-04T01:15:30.842533+00:00", "profile": "default"}
+{"type": "connection", "event": "hello", "details": {"version": "1.0"}, "ts": "2026-04-04T01:15:30.845025+00:00", "profile": "default"}
+{"type": "tool_call", "tool": "browser_stop", "params": {"profile": "gcu-browser-worker:3"}, "result": {"ok": true, "status": "not_running", "profile": "gcu-browser-worker:3"}, "ok": true, "duration_ms": 0.01, "ts": "2026-04-04T01:29:04.294954+00:00", "profile": "default"}

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
 
 - 

CHANGELOG.md

@@ -1,17 +1,149 @@
 # Release Notes
 
+## v0.7.1
+
+**Release Date:** March 13, 2026
+**Tag:** v0.7.1
+
+### Chrome-Native Browser Control
+
+v0.7.1 replaces Playwright with direct Chrome DevTools Protocol (CDP) integration. The GCU now launches the user's system Chrome via `open -n` on macOS, connects over CDP, and manages browser lifecycle end-to-end -- no extra browser binary required.
+
+---
+
+### Highlights
+
+#### System Chrome via CDP
+
+The entire GCU browser stack has been rewritten:
+
+- **Chrome finder & launcher** -- New `chrome_finder.py` discovers installed Chrome and `chrome_launcher.py` manages process lifecycle with `--remote-debugging-port`
+- **Coexist with user's browser** -- `open -n` on macOS launches a separate Chrome instance so the user's tabs stay untouched
+- **Dynamic viewport sizing** -- Viewport auto-sizes to the available display area, suppressing Chrome warning bars
+- **Orphan cleanup** -- Chrome processes are killed on GCU server shutdown to prevent leaks
+- **`--no-startup-window`** -- Chrome launches headlessly by default until a page is needed
+
+#### Per-Subagent Browser Isolation
+
+Each GCU subagent gets its own Chrome user-data directory, preventing cookie/session cross-contamination:
+
+- Unique browser profiles injected per subagent
+- Profiles cleaned up after top-level GCU node execution
+- Tab origin and age metadata tracked per subagent
+
+#### Dummy Agent Testing Framework
+
+A comprehensive test suite for validating agent graph patterns without LLM calls:
+
+- 8 test modules covering echo, pipeline, branch, parallel merge, retry, feedback loop, worker, and GCU subagent patterns
+- Shared fixtures and a `run_all.py` runner for CI integration
+- Subagent lifecycle tests
+
+---
+
+### What's New
+
+#### GCU Browser
+
+- **Switch from Playwright to system Chrome via CDP** -- Direct CDP connection replaces Playwright dependency. (@bryanadenhq)
+- **Chrome finder and launcher modules** -- `chrome_finder.py` and `chrome_launcher.py` for cross-platform Chrome discovery and process management. (@bryanadenhq)
+- **Dynamic viewport sizing** -- Auto-size viewport and suppress Chrome warning bar. (@bryanadenhq)
+- **Per-subagent browser profile isolation** -- Unique user-data directories per subagent with cleanup. (@bryanadenhq)
+- **Tab origin/age metadata** -- Track which subagent opened each tab and when. (@bryanadenhq)
+- **`browser_close_all` tool** -- Bulk tab cleanup for agents managing many pages. (@bryanadenhq)
+- **Auto-track popup pages** -- Popups are automatically captured and tracked. (@bryanadenhq)
+- **Auto-snapshot from browser interactions** -- Browser interaction tools return screenshots automatically. (@bryanadenhq)
+- **Kill orphaned Chrome processes** -- GCU server shutdown cleans up lingering Chrome instances. (@bryanadenhq)
+- **`--no-startup-window` Chrome flag** -- Prevent empty window on launch. (@bryanadenhq)
+- **Launch Chrome via `open -n` on macOS** -- Coexist with the user's running browser. (@bryanadenhq)
+
+#### Framework & Runtime
+
+- **Session resume fix for new agents** -- Correctly resume sessions when a new agent is loaded. (@bryanadenhq)
+- **Queen upsert fix** -- Prevent duplicate queen entries on session restore. (@bryanadenhq)
+- **Anchor worker monitoring to queen's session ID on cold-restore** -- Worker monitors reconnect to the correct queen after restart. (@bryanadenhq)
+- **Update meta.json when loading workers** -- Worker metadata stays in sync with runtime state. (@RichardTang-Aden)
+- **Generate worker MCP file correctly** -- Fix MCP config generation for spawned workers. (@RichardTang-Aden)
+- **Share event bus so tool events are visible to parent** -- Tool execution events propagate up to parent graphs. (@bryanadenhq)
+- **Subagent activity tracking in queen status** -- Queen instructions include live subagent status. (@bryanadenhq)
+- **GCU system prompt updates** -- Auto-snapshots, batching, popup tracking, and close_all guidance. (@bryanadenhq)
+
+#### Frontend
+
+- **Loading spinner in draft panel** -- Shows spinner during planning phase instead of blank panel. (@bryanadenhq)
+- **Fix credential modal errors** -- Modal no longer eats errors; banner stays visible. (@bryanadenhq)
+- **Fix credentials_required loop** -- Stop clearing the flag on modal close to prevent infinite re-prompting. (@bryanadenhq)
+- **Fix "Add tab" dropdown overflow** -- Dropdown no longer hidden when many agents are open. (@prasoonmhwr)
+
+#### Testing
+
+- **Dummy agent test framework** -- 8 test modules (echo, pipeline, branch, parallel merge, retry, feedback loop, worker, GCU subagent) with shared fixtures and CI runner. (@bryanadenhq)
+- **Subagent lifecycle tests** -- Validate subagent spawn and completion flows. (@bryanadenhq)
+
+#### Documentation & Infrastructure
+
+- **MCP integration PRD** -- Product requirements for MCP server registry. (@TimothyZhang7)
+- **Skills registry PRD** -- Product requirements for skill registry system. (@bryanadenhq)
+- **Bounty program updates** -- Standard bounty issue template and updated contributor guide. (@bryanadenhq)
+- **Windows quickstart** -- Add default context limit for PowerShell setup. (@bryanadenhq)
+- **Remove deprecated files** -- Clean up `setup_mcp.py`, `verify_mcp.py`, `antigravity-setup.md`, and `setup-antigravity-mcp.sh`. (@bryanadenhq)
+
+---
+
+### Bug Fixes
+
+- Fix credential modal eating errors and banner staying open
+- Stop clearing `credentials_required` on modal close to prevent infinite loop
+- Share event bus so tool events are visible to parent graph
+- Use lazy %-formatting in subagent completion log to avoid f-string in logger
+- Anchor worker monitoring to queen's session ID on cold-restore
+- Update meta.json when loading workers
+- Generate worker MCP file correctly
+- Fix "Add tab" dropdown partially hidden when creating multiple agents
+
+---
+
+### Community Contributors
+
+- **Prasoon Mahawar** (@prasoonmhwr) -- Fix UI overflow on agent tab dropdown
+- **Richard Tang** (@RichardTang-Aden) -- Worker MCP generation and meta.json fixes
+
+---
+
+### Upgrading
+
+```bash
+git pull origin main
+uv sync
+```
+
+The Playwright dependency is no longer required for GCU browser operations. Chrome must be installed on the host system.
+
+---
+
+## v0.7.0
+
+**Release Date:** March 5, 2026
+**Tag:** v0.7.0
+
+Session management refactor release.
+
+---
+
+## v0.5.1
+
 **Release Date:** February 18, 2026
 **Tag:** v0.5.1
 
-## The Hive Gets a Brain
+### The Hive Gets a Brain
 
 v0.5.1 is our most ambitious release yet. Hive agents can now **build other agents** -- the new Hive Coder meta-agent writes, tests, and fixes agent packages from natural language. The runtime grows multi-graph support so one session can orchestrate multiple agents simultaneously. The TUI gets a complete overhaul with an in-app agent picker, live streaming, and seamless escalation to the Coder. And we're now provider-agnostic: Claude Code subscriptions, OpenAI-compatible endpoints, and any LiteLLM-supported model work out of the box.
 
 ---
 
-## Highlights
+### Highlights
 
-### Hive Coder -- The Agent That Builds Agents
+#### Hive Coder -- The Agent That Builds Agents
 
 A native meta-agent that lives inside the framework at `core/framework/agents/hive_coder/`. Give it a natural-language specification and it produces a complete agent package -- goal definition, node prompts, edge routing, MCP tool wiring, tests, and all boilerplate files.
 
@@ -30,7 +162,7 @@ The Coder ships with:
 - **Coder Tools MCP server** -- file I/O, fuzzy-match editing, git snapshots, and sandboxed shell execution (`tools/coder_tools_server.py`)
 - **Test generation** -- structural tests for forever-alive agents that don't hang on `runner.run()`
 
-### Multi-Graph Agent Runtime
+#### Multi-Graph Agent Runtime
 
 `AgentRuntime` now supports loading, managing, and switching between multiple agent graphs within a single session. Six new lifecycle tools give agents (and the TUI) full control:
 
@@ -44,7 +176,7 @@ await runtime.add_graph("exports/deep_research_agent")
 
 The Hive Coder uses multi-graph internally -- when you escalate from a worker agent, the Coder loads as a separate graph while the worker stays alive in the background.
 
-### TUI Revamp
+#### TUI Revamp
 
 The Terminal UI gets a ground-up rebuild with five major additions:
 
@@ -54,7 +186,7 @@ The Terminal UI gets a ground-up rebuild with five major additions:
 - **PDF attachments** -- `/attach` and `/detach` commands with native OS file dialog (macOS, Linux, Windows)
 - **Multi-graph commands** -- `/graphs`, `/graph <id>`, `/load <path>`, `/unload <id>` for managing agent graphs in-session
 
-### Provider-Agnostic LLM Support
+#### Provider-Agnostic LLM Support
 
 Hive is no longer Anthropic-only. v0.5.1 adds first-class support for:
 
@@ -66,9 +198,9 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 
 ---
 
-## What's New
+### What's New
 
-### Architecture & Runtime
+#### Architecture & Runtime
 
 - **Hive Coder meta-agent** -- Natural-language agent builder with reference docs, guardian watchdog, and `hive code` CLI command. (@TimothyZhang7)
 - **Multi-graph agent sessions** -- `add_graph`/`remove_graph` on AgentRuntime with 6 lifecycle tools (`load_agent`, `unload_agent`, `start_agent`, `restart_agent`, `list_agents`, `get_user_presence`). (@TimothyZhang7)
@@ -79,7 +211,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 - **Pre-start confirmation prompt** -- Interactive prompt before agent execution allowing credential updates or abort. (@RichardTang-Aden)
 - **Event bus multi-graph support** -- `graph_id` on events, `filter_graph` on subscriptions, `ESCALATION_REQUESTED` event type, `exclude_own_graph` filter. (@TimothyZhang7)
 
-### TUI Improvements
+#### TUI Improvements
 
 - **In-app agent picker** (Ctrl+A) -- Tabbed modal for browsing agents with metadata badges (nodes, tools, sessions, tags). (@TimothyZhang7)
 - **Runtime-optional TUI startup** -- Launches without a pre-loaded agent, shows agent picker on startup. (@TimothyZhang7)
@@ -89,7 +221,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 - **Multi-graph TUI commands** -- `/graphs`, `/graph <id>`, `/load <path>`, `/unload <id>`. (@TimothyZhang7)
 - **Agent Guardian watchdog** -- Event-driven monitor that catches secondary agent failures and triggers automatic remediation, with `--no-guardian` CLI flag. (@TimothyZhang7)
 
-### New Tool Integrations
+#### New Tool Integrations
 
 | Tool                   | Description                                                                                                                                                            | Contributor        |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
@@ -99,7 +231,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 | **Google Docs**        | Document creation, reading, and editing with OAuth credential support                                                                                                  | @haliaeetusvocifer |
 | **Gmail enhancements** | Expanded mail operations for inbox management                                                                                                                          | @bryanadenhq       |
 
-### Infrastructure
+#### Infrastructure
 
 - **Default node type → `event_loop`** -- `NodeSpec.node_type` defaults to `"event_loop"` instead of `"llm_tool_use"`. (@TimothyZhang7)
 - **Default `max_node_visits` → 0 (unlimited)** -- Nodes default to unlimited visits, reducing friction for feedback loops and forever-alive agents. (@TimothyZhang7)
@@ -112,7 +244,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 
 ---
 
-## Bug Fixes
+### Bug Fixes
 
 - Flush WIP accumulator outputs on cancel/failure so edge conditions see correct values on resume
 - Stall detection state preserved across resume (no more resets on checkpoint restore)
@@ -125,13 +257,13 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 - Fix email agent version conflicts (@RichardTang-Aden)
 - Fix coder tool timeouts (120s for tests, 300s cap for commands)
 
-## Documentation
+### Documentation
 
 - Clarify installation and prevent root pip install misuse (@paarths-collab)
 
 ---
 
-## Agent Updates
+### Agent Updates
 
 - **Email Inbox Management** -- Consolidate `gmail_inbox_guardian` and `inbox_management` into a single unified agent with updated prompts and config. (@RichardTang-Aden, @bryanadenhq)
 - **Job Hunter** -- Updated node prompts, config, and agent metadata; added PDF resume selection. (@bryanadenhq)
@@ -141,7 +273,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 
 ---
 
-## Breaking Changes
+### Breaking Changes
 
 - **Deprecated node types raise `RuntimeError`** -- `llm_tool_use`, `llm_generate`, `function`, `router`, `human_input` now fail instead of warning. Migrate to `event_loop`.
 - **`NodeSpec.node_type` defaults to `"event_loop"`** (was `"llm_tool_use"`)
@@ -150,7 +282,7 @@ The quickstart script auto-detects Claude Code subscriptions and ZAI Code instal
 
 ---
 
-## Community Contributors
+### Community Contributors
 
 A huge thank you to everyone who contributed to this release:
 
@@ -165,14 +297,14 @@ A huge thank you to everyone who contributed to this release:
 
 ---
 
-## Upgrading
+### Upgrading
 
 ```bash
 git pull origin main
 uv sync
 ```
 
-### Migration Guide
+#### Migration Guide
 
 If your agents use deprecated node types, update them:
 
@@ -196,12 +328,3 @@ hive code
 # Or from TUI -- press Ctrl+E to escalate
 hive tui
 ```
-
----
-
-## What's Next
-
-- **Agent-to-agent communication** -- one agent's output triggers another agent's entry point
-- **Cost visibility** -- detailed runtime log of LLM costs per node and per session
-- **Persistent webhook subscriptions** -- survive agent restarts without re-registering
-- **Remote agent deployment** -- run agents as long-lived services with HTTP APIs

Makefile

@@ -1,27 +1,34 @@
-.PHONY: lint format check test install-hooks help frontend-install frontend-dev frontend-build
+.PHONY: lint format check test test-tools test-live test-all install-hooks help frontend-install frontend-dev frontend-build
+
+# ── Ensure uv is findable in Git Bash on Windows ──────────────────────────────
+# uv installs to ~/.local/bin on Windows/Linux/macOS. Git Bash may not include
+# this in PATH by default, so we prepend it here.
+export PATH := $(HOME)/.local/bin:$(PATH)
+
+# ── Targets ───────────────────────────────────────────────────────────────────
 
 help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
 		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
 
 lint: ## Run ruff linter and formatter (with auto-fix)
-	cd core && ruff check --fix .
-	cd tools && ruff check --fix .
-	cd core && ruff format .
-	cd tools && ruff format .
+	cd core && uv run ruff check --fix .
+	cd tools && uv run ruff check --fix .
+	cd core && uv run ruff format .
+	cd tools && uv run ruff format .
 
 format: ## Run ruff formatter
-	cd core && ruff format .
-	cd tools && ruff format .
+	cd core && uv run ruff format .
+	cd tools && uv run ruff format .
 
 check: ## Run all checks without modifying files (CI-safe)
-	cd core && ruff check .
-	cd tools && ruff check .
-	cd core && ruff format --check .
-	cd tools && ruff format --check .
+	cd core && uv run ruff check .
+	cd tools && uv run ruff check .
+	cd core && uv run ruff format --check .
+	cd tools && uv run ruff format --check .
 
 test: ## Run all tests (core + tools, excludes live)
-	cd core && uv run python -m pytest tests/ -v
+	cd core && uv run python -m pytest tests/ -v --ignore=tests/dummy_agents
 	cd tools && uv run python -m pytest -v
 
 test-tools: ## Run tool tests only (mocked, no credentials needed)
@@ -31,7 +38,7 @@ test-live: ## Run live integration tests (requires real API credentials)
 	cd tools && uv run python -m pytest -m live -s -o "addopts=" --log-cli-level=INFO
 
 test-all: ## Run everything including live tests
-	cd core && uv run python -m pytest tests/ -v
+	cd core && uv run python -m pytest tests/ -v --ignore=tests/dummy_agents
 	cd tools && uv run python -m pytest -v
 	cd tools && uv run python -m pytest -m live -s -o "addopts=" --log-cli-level=INFO
 
@@ -46,4 +53,4 @@ frontend-dev: ## Start frontend dev server
 	cd core/frontend && npm run dev
 
 frontend-build: ## Build frontend for production
-	cd core/frontend && npm run build
+	cd core/frontend && npm run build

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img width="100%" alt="Hive Banner" src="https://github.com/user-attachments/assets/a027429b-5d3c-4d34-88e4-0feaeaabbab3" />
+  <img width="100%" alt="Hive Banner" src="https://asset.acho.io/github/img/banner.gif" />
 </p>
 
 <p align="center">
@@ -23,11 +23,12 @@
 </p>
 
 <p align="center">
+  <img src="https://img.shields.io/badge/Agent_Harness-Runtime_Layer-ff6600?style=flat-square" alt="Agent Harness" />
   <img src="https://img.shields.io/badge/AI_Agents-Self--Improving-brightgreen?style=flat-square" alt="AI Agents" />
   <img src="https://img.shields.io/badge/Multi--Agent-Systems-blue?style=flat-square" alt="Multi-Agent" />
   <img src="https://img.shields.io/badge/Headless-Development-purple?style=flat-square" alt="Headless" />
   <img src="https://img.shields.io/badge/Human--in--the--Loop-orange?style=flat-square" alt="HITL" />
-  <img src="https://img.shields.io/badge/Production--Ready-red?style=flat-square" alt="Production" />
+  <img src="https://img.shields.io/badge/Browser-Use-red?style=flat-square" alt="Browser Use" />
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/OpenAI-supported-412991?style=flat-square&logo=openai" alt="OpenAI" />
@@ -35,37 +36,51 @@
   <img src="https://img.shields.io/badge/Google_Gemini-supported-4285F4?style=flat-square&logo=google" alt="Gemini" />
 </p>
 
+<p align="center"><em>The agent harness for production workloads — state management, failure recovery, observability, and human oversight so your agents actually run.</em></p>
+
 ## Overview
 
-Build autonomous, reliable, self-improving AI agents without hardcoding workflows. Define your goal through conversation with hive coding agent(queen), and the framework generates a node graph with dynamically created connection code. When things break, the framework captures failure data, evolves the agent through the coding agent, and redeploys. Built-in human-in-the-loop nodes, credential management, and real-time monitoring give you control without sacrificing adaptability.
+OpenHive is a zero-setup, model-agnostic execution harness that dynamically generates multi-agent topologies to tackle complex, long-running business workflows without requiring any orchestration boilerplate. By simply defining your objective, the runtime compiles a strict, graph-based execution DAG that safely coordinates specialized agents to execute concurrent tasks in parallel. Backed by persistent, role-based memory that intelligently evolves with your project's context, OpenHive ensures deterministic fault tolerance, deep state observability, and seamless asynchronous execution across whichever underlying LLMs you choose to plug in.
+
+## Features
+
+- ✅ Multi-Agent Coordination for parallel task execution 
+- ✅ Graph-based execution for recurring and complex processes 
+- ✅ Role-based memory that evolves with your projects 
+- ✅ Zero Setup - No technical configuration required
+- ✅ General Compute Use and Browser Use with Native Extension 
+- ✅ Custom Model Support
 
 Visit [adenhq.com](https://adenhq.com) for complete documentation, examples, and guides.
 
-[![Hive Demo](https://img.youtube.com/vi/XDOG9fOaLjU/maxresdefault.jpg)](https://www.youtube.com/watch?v=XDOG9fOaLjU)
+Visit [HoneyComb](http://honeycomb.open-hive.com/) to see what jobs are being automated by AI. It’s a stock market for jobs, driven by our community’s AI agent progress. You can long and short jobs (with no real money but compute token)based on how much you think a job is going to be replaced by AI.
+
+https://github.com/user-attachments/assets/bf10edc3-06ba-48b6-98ba-d069b15fb69d
+
 
 ## Who Is Hive For?
 
-Hive is designed for developers and teams who want to build **production-grade AI agents** without manually wiring complex workflows.
+Hive is the multi-agent harness layer for teams moving AI agents from prototype to production. Single agents like Openclaw and Cowork can finish personal jobs pretty well but lack the rigor to fulfil business processes. 
 
 Hive is a good fit if you:
 
 - Want AI agents that **execute real business processes**, not demos
-- Need **fast or high volume agent execution** over open workflow
+- Need a **runtime that handles state, recovery, and parallel execution** at scale
 - Need **self-healing and adaptive agents** that improve over time
 - Require **human-in-the-loop control**, observability, and cost limits
-- Plan to run agents in **production environments**
+- Plan to run agents in **production** where uptime, cost, and auditability matter
 
 Hive may not be the best fit if you’re only experimenting with simple agent chains or one-off scripts.
 
 ## When Should You Use Hive?
 
-Use Hive when you need:
+Use Hive when the bottleneck is no longer the model but the harness around it:
 
-- Long-running, autonomous agents
-- Strong guardrails, process, and controls
-- Continuous improvement based on failures
-- Multi-agent coordination
-- A framework that evolves with your goals
+- Long-running agents that need **state persistence and crash recovery**
+- Production workloads requiring **cost enforcement, observability, and audit trails**
+- Agents that **self-heal** through failure capture and graph evolution
+- Multi-agent coordination with **session isolation and shared buffers**
+- A framework that **scales with model improvements** rather than fighting them
 
 ## Quick Links
 
@@ -73,7 +88,7 @@ Use Hive when you need:
 - **[Self-Hosting Guide](https://docs.adenhq.com/getting-started/quickstart)** - Deploy Hive on your infrastructure
 - **[Changelog](https://github.com/aden-hive/hive/releases)** - Latest updates and releases
 - **[Roadmap](docs/roadmap.md)** - Upcoming features and plans
-- **[Report Issues](https://github.com/adenhq/hive/issues)** - Bug reports and feature requests
+- **[Report Issues](https://github.com/aden-hive/hive/issues)** - Bug reports and feature requests
 - **[Contributing](CONTRIBUTING.md)** - How to contribute and submit PRs
 
 ## Quick Start
@@ -84,7 +99,7 @@ Use Hive when you need:
 - An LLM provider that powers the agents
 - **ripgrep (optional, recommended on Windows):** The `search_files` tool uses ripgrep for faster file search. If not installed, a Python fallback is used. On Windows: `winget install BurntSushi.ripgrep` or `scoop install ripgrep`
 
-> **Note for Windows Users:** It is strongly recommended to use **WSL (Windows Subsystem for Linux)** or **Git Bash** to run this framework. Some core automation scripts may not execute correctly in standard Command Prompt or PowerShell.
+> **Windows Users:** Native Windows is supported via `quickstart.ps1` and `hive.ps1`. Run these in PowerShell 5.1+. WSL is also an option but not required.
 
 ### Installation
 
@@ -98,9 +113,11 @@ Use Hive when you need:
 git clone https://github.com/aden-hive/hive.git
 cd hive
 
-
-# Run quickstart setup
+# Run quickstart setup (macOS/Linux)
 ./quickstart.sh
+
+# Windows (PowerShell)
+.\quickstart.ps1
 ```
 
 This sets up:
@@ -108,54 +125,40 @@ This sets up:
 - **framework** - Core agent runtime and graph executor (in `core/.venv`)
 - **aden_tools** - MCP tools for agent capabilities (in `tools/.venv`)
 - **credential store** - Encrypted API key storage (`~/.hive/credentials`)
-- **LLM provider** - Interactive default model configuration
+- **LLM provider** - Interactive default model configuration, including Hive LLM and OpenRouter
 - 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.
 
-<img width="2500" height="1214" alt="home-screen" src="https://github.com/user-attachments/assets/134d897f-5e75-4874-b00b-e0505f6b45c4" />
-
 ### Build Your First Agent
 
-Type the agent you want to build in the home input box
+Type the agent you want to build in the home input box. The queen is going to ask you questions and work out a solution with you.
 
 <img width="2500" height="1214" alt="Image" src="https://github.com/user-attachments/assets/1ce19141-a78b-46f5-8d64-dbf987e048f4" />
 
 ### 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
-- **[Goal-Driven Generation](docs/key_concepts/goals_outcome.md)** - Define objectives in natural language; the coding agent generates the agent graph and connection code to achieve them
-- **[Adaptiveness](docs/key_concepts/evolution.md)** - Framework captures failures, calibrates according to the objectives, and evolves the agent graph
-- **[Dynamic Node Connections](docs/key_concepts/graph.md)** - No predefined edges; connection code is generated by any capable LLM based on your goals
-- **SDK-Wrapped Nodes** - Every node gets shared memory, local RLM memory, monitoring, tools, and LLM access out of the box
-- **[Human-in-the-Loop](docs/key_concepts/graph.md#human-in-the-loop)** - Intervention nodes that pause execution for human input with configurable timeouts and escalation
-- **Real-time Observability** - WebSocket streaming for live monitoring of agent execution, decisions, and node-to-node communication
-- **Production-Ready** - Self-hostable, built for scale and reliability
+<img width="2549" height="1174" alt="Screenshot 2026-03-12 at 9 27 36 PM" src="https://github.com/user-attachments/assets/7c7d30fa-9ceb-4c23-95af-b1caa405547d" />
 
 ## Integration
 
 <a href="https://github.com/aden-hive/hive/tree/main/tools/src/aden_tools/tools"><img width="100%" alt="Integration" src="https://github.com/user-attachments/assets/a1573f93-cf02-4bb8-b3d5-b305b05b1e51" /></a>
 Hive is built to be model-agnostic and system-agnostic.
 
-- **LLM flexibility** - Hive Framework is designed to support various types of LLMs, including hosted and local models through LiteLLM-compatible providers.
+- **LLM flexibility** - Hive Framework supports Anthropic, OpenAI, OpenRouter, Hive LLM, and other hosted or local models through LiteLLM-compatible providers.
 - **Business system connectivity** - Hive Framework is designed to connect to all kinds of business systems as tools, such as CRM, support, messaging, data, file, and internal APIs via MCP.
 
-## Why Aden
+## Why Hive
 
-Hive focuses on generating agents that run real business processes rather than generic agents. Instead of requiring you to manually design workflows, define agent interactions, and handle failures reactively, Hive flips the paradigm: **you describe outcomes, and the system builds itself**—delivering an outcome-driven, adaptive experience with an easy-to-use set of tools and integrations.
+As models improve, the upper bound of what agents can do rises — but their reliability and production value are determined by the harness. Hive focuses on generating agents that run real business processes rather than generic agents. Instead of requiring you to manually design workflows, define agent interactions, and handle failures reactively, Hive flips the paradigm: **you describe outcomes, and the system builds itself**—delivering an outcome-driven, adaptive experience with an easy-to-use set of tools and integrations.
 
 ```mermaid
 flowchart LR
@@ -189,17 +192,6 @@ flowchart LR
     style V6 fill:#fff,stroke:#ed8c00,stroke-width:1px,color:#cc5d00
 ```
 
-### The Hive Advantage
-
-| Traditional Frameworks     | Hive                                   |
-| -------------------------- | -------------------------------------- |
-| Hardcode agent workflows   | Describe goals in natural language     |
-| Manual graph definition    | Auto-generated agent graphs            |
-| Reactive error handling    | Outcome-evaluation and adaptiveness    |
-| Static tool configurations | Dynamic SDK-wrapped nodes              |
-| Separate monitoring setup  | Built-in real-time observability       |
-| DIY budget management      | Integrated cost controls & degradation |
-
 ### How It Works
 
 1. **[Define Your Goal](docs/key_concepts/goals_outcome.md)** → Describe what you want to achieve in plain English
@@ -215,131 +207,6 @@ flowchart LR
 - [Configuration Guide](docs/configuration.md) - All configuration options
 - [Architecture Overview](docs/architecture/README.md) - System design and structure
 
-## Roadmap
-
-Aden Hive Agent Framework aims to help developers build outcome-oriented, self-adaptive agents. See [roadmap.md](docs/roadmap.md) for details.
-
-```mermaid
-flowchart TB
-    %% Main Entity
-    User([User])
-
-    %% =========================================
-    %% EXTERNAL EVENT SOURCES
-    %% =========================================
-    subgraph ExtEventSource [External Event Source]
-        E_Sch["Schedulers"]
-        E_WH["Webhook"]
-        E_SSE["SSE"]
-    end
-
-    %% =========================================
-    %% SYSTEM NODES
-    %% =========================================
-    subgraph WorkerBees [Worker Bees]
-        WB_C["Conversation"]
-        WB_SP["System prompt"]
-
-        subgraph Graph [Graph]
-            direction TB
-            N1["Node"] --> N2["Node"] --> N3["Node"]
-            N1 -.-> AN["Active Node"]
-            N2 -.-> AN
-            N3 -.-> AN
-
-            %% Nested Event Loop Node
-            subgraph EventLoopNode [Event Loop Node]
-                ELN_L["listener"]
-                ELN_SP["System Prompt<br/>(Task)"]
-                ELN_EL["Event loop"]
-                ELN_C["Conversation"]
-            end
-        end
-    end
-
-    subgraph JudgeNode [Judge]
-        J_C["Criteria"]
-        J_P["Principles"]
-        J_EL["Event loop"] <--> J_S["Scheduler"]
-    end
-
-    subgraph QueenBee [Queen Bee]
-        QB_SP["System prompt"]
-        QB_EL["Event loop"]
-        QB_C["Conversation"]
-    end
-
-    subgraph Infra [Infra]
-        SA["Sub Agent"]
-        TR["Tool Registry"]
-        WTM["Write through Conversation Memory<br/>(Logs/RAM/Harddrive)"]
-        SM["Shared Memory<br/>(State/Harddrive)"]
-        EB["Event Bus<br/>(RAM)"]
-        CS["Credential Store<br/>(Harddrive/Cloud)"]
-    end
-
-    subgraph PC [PC]
-        B["Browser"]
-        CB["Codebase<br/>v 0.0.x ... v n.n.n"]
-    end
-
-    %% =========================================
-    %% CONNECTIONS & DATA FLOW
-    %% =========================================
-
-    %% External Event Routing
-    E_Sch --> ELN_L
-    E_WH --> ELN_L
-    E_SSE --> ELN_L
-    ELN_L -->|"triggers"| ELN_EL
-
-    %% User Interactions
-    User -->|"Talk"| WB_C
-    User -->|"Talk"| QB_C
-    User -->|"Read/Write Access"| CS
-
-    %% Inter-System Logic
-    ELN_C <-->|"Mirror"| WB_C
-    WB_C -->|"Focus"| AN
-
-    WorkerBees -->|"Inquire"| JudgeNode
-    JudgeNode -->|"Approve"| WorkerBees
-
-    %% Judge Alignments
-    J_C <-.->|"aligns"| WB_SP
-    J_P <-.->|"aligns"| QB_SP
-
-    %% Escalate path
-    J_EL -->|"Report (Escalate)"| QB_EL
-
-    %% Pub/Sub Logic
-    AN -->|"publish"| EB
-    EB -->|"subscribe"| QB_C
-
-    %% Infra and Process Spawning
-    ELN_EL -->|"Spawn"| SA
-    SA -->|"Inform"| ELN_EL
-    SA -->|"Starts"| B
-    B -->|"Report"| ELN_EL
-    TR -->|"Assigned"| ELN_EL
-    CB -->|"Modify Worker Bee"| WB_C
-
-    %% =========================================
-    %% SHARED MEMORY & LOGS ACCESS
-    %% =========================================
-
-    %% Worker Bees Access (link to node inside Graph subgraph)
-    AN <-->|"Read/Write"| WTM
-    AN <-->|"Read/Write"| SM
-
-    %% Queen Bee Access
-    QB_C <-->|"Read/Write"| WTM
-    QB_EL <-->|"Read/Write"| SM
-
-    %% Credentials Access
-    CS -->|"Read Access"| QB_C
-```
-
 ## Contributing
 We welcome contributions from the community! We’re especially looking for help building tools, integrations, and example agents for the framework ([check #2805](https://github.com/aden-hive/hive/issues/2805)). If you’re interested in extending its functionality, this is the perfect place to start. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
@@ -378,7 +245,7 @@ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENS
 
 **Q: What LLM providers does Hive support?**
 
-Hive supports 100+ LLM providers through LiteLLM integration, including OpenAI (GPT-4, GPT-4o), Anthropic (Claude models), Google Gemini, DeepSeek, Mistral, Groq, and many more. Simply set the appropriate API key environment variable and specify the model name. We recommend using Claude, GLM and Gemini as they have the best performance.
+Hive supports 100+ LLM providers through LiteLLM integration, including OpenAI (GPT-4, GPT-4o), Anthropic (Claude models), Google Gemini, DeepSeek, Mistral, Groq, OpenRouter, and Hive LLM. Simply set the appropriate API key environment variable and specify the model name. See [docs/configuration.md](docs/configuration.md) for provider-specific configuration examples.
 
 **Q: Can I use Hive with local AI models like Ollama?**
 
@@ -386,16 +253,12 @@ Yes! Hive supports local models through LiteLLM. Simply use the model name forma
 
 **Q: What makes Hive different from other agent frameworks?**
 
-Hive generates your entire agent system from natural language goals using a coding agent—you don't hardcode workflows or manually define graphs. When agents fail, the framework automatically captures failure data, [evolves the agent graph](docs/key_concepts/evolution.md), and redeploys. This self-improving loop is unique to Aden.
+Hive is an agent harness, not just an orchestration framework. It provides the production runtime layer — session isolation, checkpoint-based crash recovery, cost enforcement, real-time observability, and human-in-the-loop controls — that makes agents reliable enough to run real workloads. On top of that, Hive generates your entire agent system from natural language goals and automatically [evolves the graph](docs/key_concepts/evolution.md) when agents fail. The combination of a robust harness with self-improving generation is what sets Hive apart.
 
 **Q: Is Hive open-source?**
 
 Yes, Hive is fully open-source under the Apache License 2.0. We actively encourage community contributions and collaboration.
 
-**Q: Can Hive handle complex, production-scale use cases?**
-
-Yes. Hive is explicitly designed for production environments with features like automatic failure recovery, real-time observability, cost controls, and horizontal scaling support. The framework handles both simple automations and complex multi-agent workflows.
-
 **Q: Does Hive support human-in-the-loop workflows?**
 
 Yes, Hive fully supports [human-in-the-loop](docs/key_concepts/graph.md#human-in-the-loop) workflows through intervention nodes that pause execution for human input. These include configurable timeouts and escalation policies, allowing seamless collaboration between human experts and AI agents.
@@ -420,6 +283,16 @@ Visit [docs.adenhq.com](https://docs.adenhq.com/) for complete guides, API refer
 
 Contributions are welcome! Fork the repository, create your feature branch, implement your changes, and submit a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 
+## Star History
+
+<a href="https://star-history.com/#aden-hive/hive&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=aden-hive/hive&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=aden-hive/hive&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=aden-hive/hive&type=Date" />
+ </picture>
+</a>
+
 ---
 
 <p align="center">

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
 

commit_message.txt

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

contributors.yml

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

core/MCP_INTEGRATION_GUIDE.md

@@ -6,7 +6,7 @@ This guide explains how to integrate Model Context Protocol (MCP) servers with t
 
 The framework provides built-in support for MCP servers, allowing you to:
 
-- **Register MCP servers** via STDIO or HTTP transport
+- **Register MCP servers** via STDIO, HTTP, Unix socket, or SSE transport
 - **Auto-discover tools** from registered servers
 - **Use MCP tools** seamlessly in your agents
 - **Manage multiple MCP servers** simultaneously
@@ -104,6 +104,48 @@ runner.register_mcp_server(
 - `url`: Base URL of the MCP server
 - `headers`: HTTP headers to include (optional)
 
+### Unix Socket Transport
+
+Best for same-host inter-process communication with lower overhead than TCP:
+
+```python
+runner.register_mcp_server(
+    name="local-ipc-tools",
+    transport="unix",
+    url="http://localhost",
+    socket_path="/tmp/mcp_server.sock",
+    headers={
+        "Authorization": "Bearer token"
+    }
+)
+```
+
+**Configuration:**
+
+- `url`: Base URL for HTTP requests over the socket (required, e.g., `"http://localhost"`)
+- `socket_path`: Absolute path to the Unix socket file (required, e.g., `"/tmp/mcp_server.sock"`)
+- `headers`: HTTP headers to include (optional)
+
+### SSE Transport
+
+Best for real-time, event-driven connections using the MCP SDK's SSE client:
+
+```python
+runner.register_mcp_server(
+    name="streaming-tools",
+    transport="sse",
+    url="http://localhost:8000/sse",
+    headers={
+        "Authorization": "Bearer token"
+    }
+)
+```
+
+**Configuration:**
+
+- `url`: SSE endpoint URL (required, e.g., `"http://localhost:8000/sse"`)
+- `headers`: HTTP headers for the SSE connection (optional)
+
 ## Using MCP Tools in Agents
 
 Once registered, MCP tools are available just like any other tool:
@@ -258,7 +300,32 @@ runner.register_mcp_server(
 )
 ```
 
-### 3. Handle Cleanup
+### 3. Use Unix Socket for Same-Host IPC
+
+When both the agent and MCP server run on the same machine, Unix sockets avoid TCP overhead:
+
+```python
+runner.register_mcp_server(
+    name="fast-local-tools",
+    transport="unix",
+    url="http://localhost",
+    socket_path="/tmp/mcp_server.sock"
+)
+```
+
+### 4. Use SSE for Streaming and Real-Time Tools
+
+SSE transport maintains a persistent connection, ideal for event-driven servers:
+
+```python
+runner.register_mcp_server(
+    name="realtime-tools",
+    transport="sse",
+    url="http://realtime-server:8000/sse"
+)
+```
+
+### 5. Handle Cleanup
 
 Always clean up MCP connections when done:
 
@@ -280,7 +347,7 @@ async with AgentRunner.load("exports/my-agent") as runner:
     # Automatic cleanup
 ```
 
-### 4. Tool Name Conflicts
+### 6. Tool Name Conflicts
 
 If multiple MCP servers provide tools with the same name, the last registered server wins. To avoid conflicts:
 
@@ -315,6 +382,24 @@ If HTTP transport fails:
 2. Check firewall settings
 3. Verify the URL and port are correct
 
+### Unix Socket Not Connecting
+
+If Unix socket transport fails:
+
+1. Verify the socket file exists: `ls -la /tmp/mcp_server.sock`
+2. Check file permissions on the socket
+3. Ensure no other process has locked the socket
+4. Verify the `url` field is set (e.g., `"http://localhost"`)
+
+### SSE Connection Issues
+
+If SSE transport fails:
+
+1. Verify the server supports SSE at the given URL
+2. Check that the `mcp` Python package is installed (`pip install mcp`)
+3. Ensure the SSE endpoint is accessible: `curl http://localhost:8000/sse`
+4. Check for firewall or proxy issues blocking long-lived connections
+
 ## Example: Full Agent with MCP Tools
 
 Here's a complete example of an agent that uses MCP tools:

core/MCP_SERVER_GUIDE.md

@@ -1,6 +1,6 @@
 # MCP Server Guide - Agent Building Tools
 
-> **Note:** The standalone `agent-builder` MCP server (`framework.mcp.agent_builder_server`) has been replaced. Agent building is now done via the `coder-tools` server's `initialize_agent_package` tool, with underlying logic in `framework.builder.package_generator`.
+> **Note:** The standalone `agent-builder` MCP server (`framework.mcp.agent_builder_server`) has been replaced. Agent building is now done via the `coder-tools` server's `initialize_and_build_agent` tool, with underlying logic in `tools/coder_tools_server.py`.
 
 This guide covers the MCP tools available for building goal-driven agents.
 

core/README.md

@@ -19,7 +19,7 @@ uv pip install -e .
 
 ## Agent Building
 
-Agent scaffolding is handled by the `coder-tools` MCP server (in `tools/coder_tools_server.py`), which provides the `initialize_agent_package` tool and related utilities. The underlying package generation logic lives in `framework.builder.package_generator`.
+Agent scaffolding is handled by the `coder-tools` MCP server (in `tools/coder_tools_server.py`), which provides the `initialize_and_build_agent` tool and related utilities. The package generation logic lives directly in `tools/coder_tools_server.py`.
 
 See the [Getting Started Guide](../docs/getting-started.md) for building agents.
 

core/antigravity_auth.py

@@ -0,0 +1,583 @@
+#!/usr/bin/env python3
+"""Antigravity authentication CLI.
+
+Implements OAuth2 flow for Google's Antigravity Code Assist gateway.
+Credentials are stored in ~/.hive/antigravity-accounts.json.
+
+Usage:
+    python -m antigravity_auth auth account add
+    python -m antigravity_auth auth account list
+    python -m antigravity_auth auth account remove <email>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import secrets
+import socket
+import sys
+import time
+import urllib.parse
+import urllib.request
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger(__name__)
+
+# OAuth endpoints
+_OAUTH_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth"
+_OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token"
+
+# Scopes for Antigravity/Cloud Code Assist
+_OAUTH_SCOPES = [
+    "https://www.googleapis.com/auth/cloud-platform",
+    "https://www.googleapis.com/auth/userinfo.email",
+    "https://www.googleapis.com/auth/userinfo.profile",
+]
+
+# Credentials file path in ~/.hive/
+_ACCOUNTS_FILE = Path.home() / ".hive" / "antigravity-accounts.json"
+
+# Default project ID
+_DEFAULT_PROJECT_ID = "rising-fact-p41fc"
+_DEFAULT_REDIRECT_PORT = 51121
+
+# OAuth credentials fetched from the opencode-antigravity-auth project.
+# This project reverse-engineered and published the public OAuth credentials
+# for Google's Antigravity/Cloud Code Assist API.
+# Source: https://github.com/NoeFabris/opencode-antigravity-auth
+_CREDENTIALS_URL = (
+    "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/dev/src/constants.ts"
+)
+
+# Cached credentials fetched from public source
+_cached_client_id: str | None = None
+_cached_client_secret: str | None = None
+
+
+def _fetch_credentials_from_public_source() -> tuple[str | None, str | None]:
+    """Fetch OAuth client ID and secret from the public npm package source on GitHub."""
+    global _cached_client_id, _cached_client_secret
+    if _cached_client_id and _cached_client_secret:
+        return _cached_client_id, _cached_client_secret
+
+    try:
+        req = urllib.request.Request(
+            _CREDENTIALS_URL, headers={"User-Agent": "Hive-Antigravity-Auth/1.0"}
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            content = resp.read().decode("utf-8")
+            import re
+
+            id_match = re.search(r'ANTIGRAVITY_CLIENT_ID\s*=\s*"([^"]+)"', content)
+            secret_match = re.search(r'ANTIGRAVITY_CLIENT_SECRET\s*=\s*"([^"]+)"', content)
+            if id_match:
+                _cached_client_id = id_match.group(1)
+            if secret_match:
+                _cached_client_secret = secret_match.group(1)
+            return _cached_client_id, _cached_client_secret
+    except Exception as e:
+        logger.debug(f"Failed to fetch credentials from public source: {e}")
+    return None, None
+
+
+def get_client_id() -> str:
+    """Get OAuth client ID from env, config, or public source."""
+    env_id = os.environ.get("ANTIGRAVITY_CLIENT_ID")
+    if env_id:
+        return env_id
+
+    # Try hive config
+    hive_cfg = Path.home() / ".hive" / "configuration.json"
+    if hive_cfg.exists():
+        try:
+            with open(hive_cfg) as f:
+                cfg = json.load(f)
+                cfg_id = cfg.get("llm", {}).get("antigravity_client_id")
+                if cfg_id:
+                    return cfg_id
+        except Exception:
+            pass
+
+    # Fetch from public source
+    client_id, _ = _fetch_credentials_from_public_source()
+    if client_id:
+        return client_id
+
+    raise RuntimeError("Could not obtain Antigravity OAuth client ID")
+
+
+def get_client_secret() -> str | None:
+    """Get OAuth client secret from env, config, or public source."""
+    secret = os.environ.get("ANTIGRAVITY_CLIENT_SECRET")
+    if secret:
+        return secret
+
+    # Try to read from hive config
+    hive_cfg = Path.home() / ".hive" / "configuration.json"
+    if hive_cfg.exists():
+        try:
+            with open(hive_cfg) as f:
+                cfg = json.load(f)
+                secret = cfg.get("llm", {}).get("antigravity_client_secret")
+                if secret:
+                    return secret
+        except Exception:
+            pass
+
+    # Fetch from public source (npm package on GitHub)
+    _, secret = _fetch_credentials_from_public_source()
+    return secret
+
+
+def find_free_port() -> int:
+    """Find an available local port."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        s.listen(1)
+        return s.getsockname()[1]
+
+
+class OAuthCallbackHandler(BaseHTTPRequestHandler):
+    """Handle OAuth callback from browser."""
+
+    auth_code: str | None = None
+    state: str | None = None
+    error: str | None = None
+
+    def log_message(self, format: str, *args: Any) -> None:
+        pass  # Suppress default logging
+
+    def do_GET(self) -> None:
+        parsed = urllib.parse.urlparse(self.path)
+
+        if parsed.path == "/oauth-callback":
+            query = urllib.parse.parse_qs(parsed.query)
+
+            if "error" in query:
+                self.error = query["error"][0]
+                self._send_response("Authentication failed. You can close this window.")
+                return
+
+            if "code" in query and "state" in query:
+                OAuthCallbackHandler.auth_code = query["code"][0]
+                OAuthCallbackHandler.state = query["state"][0]
+                self._send_response(
+                    "Authentication successful! You can close this window "
+                    "and return to the terminal."
+                )
+                return
+
+        self._send_response("Waiting for authentication...")
+
+    def _send_response(self, message: str) -> None:
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        html = f"""<!DOCTYPE html>
+<html>
+<head><title>Antigravity Auth</title></head>
+<body style="font-family: system-ui; display: flex; align-items: center;
+      justify-content: center; height: 100vh; margin: 0; background: #1a1a2e;
+      color: #eee;">
+    <div style="text-align: center;">
+        <h2>{message}</h2>
+    </div>
+</body>
+</html>"""
+        self.wfile.write(html.encode())
+
+
+def wait_for_callback(port: int, timeout: int = 300) -> tuple[str | None, str | None, str | None]:
+    """Start local server and wait for OAuth callback."""
+    server = HTTPServer(("localhost", port), OAuthCallbackHandler)
+    server.timeout = 1
+
+    start = time.time()
+    while time.time() - start < timeout:
+        if OAuthCallbackHandler.auth_code:
+            return (
+                OAuthCallbackHandler.auth_code,
+                OAuthCallbackHandler.state,
+                OAuthCallbackHandler.error,
+            )
+        server.handle_request()
+
+    return None, None, "timeout"
+
+
+def exchange_code_for_tokens(
+    code: str, redirect_uri: str, client_id: str, client_secret: str | None
+) -> dict[str, Any] | None:
+    """Exchange authorization code for tokens."""
+    data = {
+        "code": code,
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "grant_type": "authorization_code",
+    }
+    if client_secret:
+        data["client_secret"] = client_secret
+
+    body = urllib.parse.urlencode(data).encode()
+
+    req = urllib.request.Request(
+        _OAUTH_TOKEN_URL,
+        data=body,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read())
+    except Exception as e:
+        logger.error(f"Token exchange failed: {e}")
+        return None
+
+
+def get_user_email(access_token: str) -> str | None:
+    """Get user email from Google API."""
+    req = urllib.request.Request(
+        "https://www.googleapis.com/oauth2/v2/userinfo",
+        headers={"Authorization": f"Bearer {access_token}"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+            return data.get("email")
+    except Exception:
+        return None
+
+
+def load_accounts() -> dict[str, Any]:
+    """Load existing accounts from file."""
+    if not _ACCOUNTS_FILE.exists():
+        return {"schemaVersion": 4, "accounts": []}
+    try:
+        with open(_ACCOUNTS_FILE) as f:
+            return json.load(f)
+    except Exception:
+        return {"schemaVersion": 4, "accounts": []}
+
+
+def save_accounts(data: dict[str, Any]) -> None:
+    """Save accounts to file."""
+    _ACCOUNTS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(_ACCOUNTS_FILE, "w") as f:
+        json.dump(data, f, indent=2)
+    logger.info(f"Saved credentials to {_ACCOUNTS_FILE}")
+
+
+def validate_credentials(access_token: str, project_id: str = _DEFAULT_PROJECT_ID) -> bool:
+    """Test if credentials work by making a simple API call to Antigravity.
+
+    Returns True if credentials are valid, False otherwise.
+    """
+    endpoint = "https://daily-cloudcode-pa.sandbox.googleapis.com"
+    body = {
+        "project": project_id,
+        "model": "gemini-3-flash",
+        "request": {
+            "contents": [{"role": "user", "parts": [{"text": "hi"}]}],
+            "generationConfig": {"maxOutputTokens": 10},
+        },
+        "requestType": "agent",
+        "userAgent": "antigravity",
+        "requestId": "validation-test",
+    }
+    headers = {
+        "Authorization": f"Bearer {access_token}",
+        "Content-Type": "application/json",
+        "User-Agent": (
+            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) Antigravity/1.18.3"
+        ),
+        "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    }
+
+    try:
+        req = urllib.request.Request(
+            f"{endpoint}/v1internal:generateContent",
+            data=json.dumps(body).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            json.loads(resp.read())
+            return True
+    except Exception:
+        return False
+
+
+def refresh_access_token(
+    refresh_token: str, client_id: str, client_secret: str | None
+) -> dict | None:
+    """Refresh the access token using the refresh token."""
+    data = {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": client_id,
+    }
+    if client_secret:
+        data["client_secret"] = client_secret
+
+    body = urllib.parse.urlencode(data).encode()
+    req = urllib.request.Request(
+        _OAUTH_TOKEN_URL,
+        data=body,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read())
+    except Exception as e:
+        logger.debug(f"Token refresh failed: {e}")
+        return None
+
+
+def cmd_account_add(args: argparse.Namespace) -> int:
+    """Add a new Antigravity account via OAuth2.
+
+    First checks if valid credentials already exist. If so, validates them
+    and skips OAuth if they work. Otherwise, proceeds with OAuth flow.
+    """
+    client_id = get_client_id()
+    client_secret = get_client_secret()
+
+    # Check if credentials already exist
+    accounts_data = load_accounts()
+    accounts = accounts_data.get("accounts", [])
+
+    if accounts:
+        account = next((a for a in accounts if a.get("enabled", True) is not False), accounts[0])
+        access_token = account.get("access")
+        refresh_token_str = account.get("refresh", "")
+        refresh_token = refresh_token_str.split("|")[0] if refresh_token_str else None
+        project_id = (
+            refresh_token_str.split("|")[1] if "|" in refresh_token_str else _DEFAULT_PROJECT_ID
+        )
+        email = account.get("email", "unknown")
+        expires_ms = account.get("expires", 0)
+        expires_at = expires_ms / 1000.0 if expires_ms else 0.0
+
+        # Check if token is expired or near expiry
+        if access_token and expires_at and time.time() < expires_at - 60:
+            # Token still valid, test it
+            logger.info(f"Found existing credentials for: {email}")
+            logger.info("Validating existing credentials...")
+            if validate_credentials(access_token, project_id):
+                logger.info("✓ Credentials valid! Skipping OAuth.")
+                return 0
+            else:
+                logger.info("Credentials failed validation, refreshing...")
+        elif refresh_token:
+            logger.info(f"Found expired credentials for: {email}")
+            logger.info("Attempting token refresh...")
+
+            tokens = refresh_access_token(refresh_token, client_id, client_secret)
+            if tokens:
+                new_access = tokens.get("access_token")
+                expires_in = tokens.get("expires_in", 3600)
+                if new_access:
+                    # Update the account
+                    account["access"] = new_access
+                    account["expires"] = int((time.time() + expires_in) * 1000)
+                    accounts_data["last_refresh"] = time.strftime(
+                        "%Y-%m-%dT%H:%M:%SZ", time.gmtime()
+                    )
+                    save_accounts(accounts_data)
+
+                    # Validate the refreshed token
+                    logger.info("Validating refreshed credentials...")
+                    if validate_credentials(new_access, project_id):
+                        logger.info("✓ Credentials refreshed and validated!")
+                        return 0
+                    else:
+                        logger.info("Refreshed token failed validation, proceeding with OAuth...")
+            else:
+                logger.info("Token refresh failed, proceeding with OAuth...")
+
+    # No valid credentials, proceed with OAuth
+    if not client_secret:
+        logger.warning(
+            "No client secret configured. Token refresh may fail.\n"
+            "Set ANTIGRAVITY_CLIENT_SECRET env var or add "
+            "'antigravity_client_secret' to ~/.hive/configuration.json"
+        )
+
+    # Use fixed port and path matching Google's expected OAuth redirect URI
+    port = _DEFAULT_REDIRECT_PORT
+    redirect_uri = f"http://localhost:{port}/oauth-callback"
+
+    # Generate state for CSRF protection
+    state = secrets.token_urlsafe(16)
+
+    # Build authorization URL
+    params = {
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "response_type": "code",
+        "scope": " ".join(_OAUTH_SCOPES),
+        "state": state,
+        "access_type": "offline",
+        "prompt": "consent",
+    }
+    auth_url = f"{_OAUTH_AUTH_URL}?{urllib.parse.urlencode(params)}"
+
+    logger.info("Opening browser for authentication...")
+    logger.info(f"If the browser doesn't open, visit: {auth_url}\n")
+
+    # Open browser
+    webbrowser.open(auth_url)
+
+    # Wait for callback
+    logger.info(f"Listening for callback on port {port}...")
+    code, received_state, error = wait_for_callback(port)
+
+    if error:
+        logger.error(f"Authentication failed: {error}")
+        return 1
+
+    if not code:
+        logger.error("No authorization code received")
+        return 1
+
+    if received_state != state:
+        logger.error("State mismatch - possible CSRF attack")
+        return 1
+
+    # Exchange code for tokens
+    logger.info("Exchanging authorization code for tokens...")
+    tokens = exchange_code_for_tokens(code, redirect_uri, client_id, client_secret)
+
+    if not tokens:
+        return 1
+
+    access_token = tokens.get("access_token")
+    refresh_token = tokens.get("refresh_token")
+    expires_in = tokens.get("expires_in", 3600)
+
+    if not access_token:
+        logger.error("No access token in response")
+        return 1
+
+    # Get user email
+    email = get_user_email(access_token)
+    if email:
+        logger.info(f"Authenticated as: {email}")
+
+    # Load existing accounts and add/update
+    accounts_data = load_accounts()
+    accounts = accounts_data.get("accounts", [])
+
+    # Build new account entry (V4 schema)
+    expires_ms = int((time.time() + expires_in) * 1000)
+    refresh_entry = f"{refresh_token}|{_DEFAULT_PROJECT_ID}"
+
+    new_account = {
+        "access": access_token,
+        "refresh": refresh_entry,
+        "expires": expires_ms,
+        "email": email,
+        "enabled": True,
+    }
+
+    # Update existing account or add new one
+    existing_idx = next((i for i, a in enumerate(accounts) if a.get("email") == email), None)
+    if existing_idx is not None:
+        accounts[existing_idx] = new_account
+        logger.info(f"Updated existing account: {email}")
+    else:
+        accounts.append(new_account)
+        logger.info(f"Added new account: {email}")
+
+    accounts_data["accounts"] = accounts
+    accounts_data["schemaVersion"] = 4
+    accounts_data["last_refresh"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+    save_accounts(accounts_data)
+    logger.info("\n✓ Authentication complete!")
+    return 0
+
+
+def cmd_account_list(args: argparse.Namespace) -> int:
+    """List all stored accounts."""
+    data = load_accounts()
+    accounts = data.get("accounts", [])
+
+    if not accounts:
+        logger.info("No accounts configured.")
+        logger.info("Run 'antigravity auth account add' to add one.")
+        return 0
+
+    logger.info("Configured accounts:\n")
+    for i, account in enumerate(accounts, 1):
+        email = account.get("email", "unknown")
+        enabled = "enabled" if account.get("enabled", True) else "disabled"
+        logger.info(f"  {i}. {email} ({enabled})")
+
+    return 0
+
+
+def cmd_account_remove(args: argparse.Namespace) -> int:
+    """Remove an account by email."""
+    email = args.email
+    data = load_accounts()
+    accounts = data.get("accounts", [])
+
+    original_len = len(accounts)
+    accounts = [a for a in accounts if a.get("email") != email]
+
+    if len(accounts) == original_len:
+        logger.error(f"No account found with email: {email}")
+        return 1
+
+    data["accounts"] = accounts
+    save_accounts(data)
+    logger.info(f"Removed account: {email}")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Antigravity authentication CLI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # auth account add
+    auth_parser = subparsers.add_parser("auth", help="Authentication commands")
+    auth_subparsers = auth_parser.add_subparsers(dest="auth_command")
+
+    account_parser = auth_subparsers.add_parser("account", help="Account management")
+    account_subparsers = account_parser.add_subparsers(dest="account_command")
+
+    add_parser = account_subparsers.add_parser("add", help="Add a new account via OAuth2")
+    add_parser.set_defaults(func=cmd_account_add)
+
+    list_parser = account_subparsers.add_parser("list", help="List configured accounts")
+    list_parser.set_defaults(func=cmd_account_list)
+
+    remove_parser = account_subparsers.add_parser("remove", help="Remove an account")
+    remove_parser.add_argument("email", help="Email of account to remove")
+    remove_parser.set_defaults(func=cmd_account_remove)
+
+    args = parser.parse_args()
+
+    if hasattr(args, "func"):
+        return args.func(args)
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

core/codex_oauth.py

@@ -17,6 +17,7 @@ import http.server
 import json
 import os
 import platform
+import queue
 import secrets
 import subprocess
 import sys
@@ -27,6 +28,7 @@ import urllib.parse
 import urllib.request
 from datetime import UTC, datetime
 from pathlib import Path
+from typing import TextIO
 
 # OAuth constants (from the Codex CLI binary)
 CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
@@ -165,11 +167,11 @@ def open_browser(url: str) -> bool:
         if system == "Darwin":
             subprocess.Popen(["open", url], stdout=devnull, stderr=devnull)
         elif system == "Windows":
-            subprocess.Popen(["cmd", "/c", "start", url], stdout=devnull, stderr=devnull)
+            os.startfile(url)  # type: ignore[attr-defined]
         else:
             subprocess.Popen(["xdg-open", url], stdout=devnull, stderr=devnull)
         return True
-    except OSError:
+    except (AttributeError, OSError):
         return False
 
 
@@ -266,6 +268,71 @@ def parse_manual_input(value: str, expected_state: str) -> str | None:
     return None
 
 
+def _read_manual_input_lines(
+    manual_inputs: queue.Queue[str],
+    stop_event: threading.Event,
+    stdin: TextIO | None = None,
+) -> None:
+    stream = sys.stdin if stdin is None else stdin
+
+    while not stop_event.is_set():
+        try:
+            manual = stream.readline()
+        except (EOFError, OSError):
+            return
+
+        if not manual:
+            return
+
+        if manual.strip():
+            manual_inputs.put(manual)
+
+
+def wait_for_code_from_callback_or_stdin(
+    expected_state: str,
+    callback_result: list[str | None],
+    callback_done: threading.Event,
+    timeout_secs: float = 120,
+    poll_interval: float = 0.1,
+    stdin: TextIO | None = None,
+) -> str | None:
+    manual_inputs: queue.Queue[str] = queue.Queue()
+    stop_event = threading.Event()
+
+    # Read stdin on a daemon thread so manual paste works on platforms where
+    # select() cannot poll console handles, including Windows terminals.
+    threading.Thread(
+        target=_read_manual_input_lines,
+        args=(manual_inputs, stop_event, stdin),
+        daemon=True,
+    ).start()
+
+    deadline = time.time() + timeout_secs
+    try:
+        while time.time() < deadline:
+            if callback_result[0]:
+                return callback_result[0]
+
+            while True:
+                try:
+                    manual = manual_inputs.get_nowait()
+                except queue.Empty:
+                    break
+
+                code = parse_manual_input(manual, expected_state)
+                if code:
+                    return code
+
+            if callback_done.is_set():
+                return callback_result[0]
+
+            time.sleep(poll_interval)
+
+        return callback_result[0]
+    finally:
+        stop_event.set()
+
+
 def main() -> int:
     # Generate PKCE and state
     verifier, challenge = generate_pkce()
@@ -315,41 +382,28 @@ def main() -> int:
 
         # Start callback server in background
         callback_result: list[str | None] = [None]
+        callback_done = threading.Event()
 
         def run_server() -> None:
-            callback_result[0] = wait_for_callback(state, timeout_secs=120)
+            try:
+                callback_result[0] = wait_for_callback(state, timeout_secs=120)
+            finally:
+                callback_done.set()
 
         server_thread = threading.Thread(target=run_server)
         server_thread.daemon = True
         server_thread.start()
 
-        # Also accept manual input in parallel
-        # We poll for both the server result and stdin
         try:
-            import select
-
-            while server_thread.is_alive():
-                # Check if stdin has data (non-blocking on unix)
-                if hasattr(select, "select"):
-                    ready, _, _ = select.select([sys.stdin], [], [], 0.5)
-                    if ready:
-                        manual = sys.stdin.readline()
-                        if manual.strip():
-                            code = parse_manual_input(manual, state)
-                            if code:
-                                break
-                else:
-                    time.sleep(0.5)
-
-                if callback_result[0]:
-                    code = callback_result[0]
-                    break
-        except (KeyboardInterrupt, EOFError):
+            code = wait_for_code_from_callback_or_stdin(
+                state,
+                callback_result,
+                callback_done,
+                timeout_secs=120,
+            )
+        except KeyboardInterrupt:
             print("\n\033[0;31mCancelled.\033[0m")
             return 1
-
-        if not code:
-            code = callback_result[0]
     else:
         # Manual paste mode
         try:

core/demos/event_loop_wss_demo.py

@@ -1,740 +0,0 @@
-#!/usr/bin/env python3
-"""
-EventLoopNode WebSocket Demo
-
-Real LLM, real FileConversationStore, real EventBus.
-Streams EventLoopNode execution to a browser via WebSocket.
-
-Usage:
-    cd /home/timothy/oss/hive/core
-    python demos/event_loop_wss_demo.py
-
-    Then open http://localhost:8765 in your browser.
-"""
-
-import asyncio
-import json
-import logging
-import sys
-import tempfile
-from http import HTTPStatus
-from pathlib import Path
-
-import httpx
-import websockets
-from bs4 import BeautifulSoup
-from websockets.http11 import Request, Response
-
-# Add core, tools, and hive root to path
-_CORE_DIR = Path(__file__).resolve().parent.parent
-_HIVE_DIR = _CORE_DIR.parent
-sys.path.insert(0, str(_CORE_DIR))  # framework.*
-sys.path.insert(0, str(_HIVE_DIR / "tools" / "src"))  # aden_tools.*
-sys.path.insert(0, str(_HIVE_DIR))  # core.framework.* (for aden_tools imports)
-
-import os  # noqa: E402
-
-from aden_tools.credentials import CREDENTIAL_SPECS, CredentialStoreAdapter  # noqa: E402
-from core.framework.credentials import CredentialStore  # noqa: E402
-
-from framework.credentials.storage import (  # noqa: E402
-    CompositeStorage,
-    EncryptedFileStorage,
-    EnvVarStorage,
-)
-from framework.graph.event_loop_node import EventLoopNode, LoopConfig  # noqa: E402
-from framework.graph.node import NodeContext, NodeSpec, SharedMemory  # noqa: E402
-from framework.llm.litellm import LiteLLMProvider  # noqa: E402
-from framework.llm.provider import Tool  # noqa: E402
-from framework.runner.tool_registry import ToolRegistry  # noqa: E402
-from framework.runtime.core import Runtime  # noqa: E402
-from framework.runtime.event_bus import EventBus, EventType  # noqa: E402
-from framework.storage.conversation_store import FileConversationStore  # noqa: E402
-
-logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
-logger = logging.getLogger("demo")
-
-# -------------------------------------------------------------------------
-# Persistent state (shared across WebSocket connections)
-# -------------------------------------------------------------------------
-
-STORE_DIR = Path(tempfile.mkdtemp(prefix="hive_demo_"))
-STORE = FileConversationStore(STORE_DIR / "conversation")
-RUNTIME = Runtime(STORE_DIR / "runtime")
-LLM = LiteLLMProvider(model="claude-sonnet-4-5-20250929")
-
-# -------------------------------------------------------------------------
-# Tool Registry — real tools via ToolRegistry (same pattern as GraphExecutor)
-# -------------------------------------------------------------------------
-
-TOOL_REGISTRY = ToolRegistry()
-
-# Credential store: Aden sync (OAuth2 tokens) + encrypted files + env var fallback
-_env_mapping = {name: spec.env_var for name, spec in CREDENTIAL_SPECS.items()}
-_local_storage = CompositeStorage(
-    primary=EncryptedFileStorage(),
-    fallbacks=[EnvVarStorage(env_mapping=_env_mapping)],
-)
-
-if os.environ.get("ADEN_API_KEY"):
-    try:
-        from framework.credentials.aden import (  # noqa: E402
-            AdenCachedStorage,
-            AdenClientConfig,
-            AdenCredentialClient,
-            AdenSyncProvider,
-        )
-
-        _client = AdenCredentialClient(AdenClientConfig(base_url="https://api.adenhq.com"))
-        _provider = AdenSyncProvider(client=_client)
-        _storage = AdenCachedStorage(
-            local_storage=_local_storage,
-            aden_provider=_provider,
-        )
-        _cred_store = CredentialStore(storage=_storage, providers=[_provider], auto_refresh=True)
-        _synced = _provider.sync_all(_cred_store)
-        logger.info("Synced %d credentials from Aden", _synced)
-    except Exception as e:
-        logger.warning("Aden sync unavailable: %s", e)
-        _cred_store = CredentialStore(storage=_local_storage)
-else:
-    logger.info("ADEN_API_KEY not set, using local credential storage")
-    _cred_store = CredentialStore(storage=_local_storage)
-
-CREDENTIALS = CredentialStoreAdapter(_cred_store)
-
-# Debug: log which credentials resolved
-for _name in ["brave_search", "hubspot", "anthropic"]:
-    _val = CREDENTIALS.get(_name)
-    if _val:
-        logger.debug("credential %s: OK (len=%d)", _name, len(_val))
-    else:
-        logger.debug("credential %s: not found", _name)
-
-# --- web_search (Brave Search API) ---
-
-TOOL_REGISTRY.register(
-    name="web_search",
-    tool=Tool(
-        name="web_search",
-        description=(
-            "Search the web for current information. "
-            "Returns titles, URLs, and snippets from search results."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "query": {
-                    "type": "string",
-                    "description": "The search query (1-500 characters)",
-                },
-                "num_results": {
-                    "type": "integer",
-                    "description": "Number of results to return (1-20, default 10)",
-                },
-            },
-            "required": ["query"],
-        },
-    ),
-    executor=lambda inputs: _exec_web_search(inputs),
-)
-
-
-def _exec_web_search(inputs: dict) -> dict:
-    api_key = CREDENTIALS.get("brave_search")
-    if not api_key:
-        return {"error": "brave_search credential not configured"}
-    query = inputs.get("query", "")
-    num_results = min(inputs.get("num_results", 10), 20)
-    resp = httpx.get(
-        "https://api.search.brave.com/res/v1/web/search",
-        params={"q": query, "count": num_results},
-        headers={"X-Subscription-Token": api_key, "Accept": "application/json"},
-        timeout=30.0,
-    )
-    if resp.status_code != 200:
-        return {"error": f"Brave API HTTP {resp.status_code}"}
-    data = resp.json()
-    results = [
-        {
-            "title": item.get("title", ""),
-            "url": item.get("url", ""),
-            "snippet": item.get("description", ""),
-        }
-        for item in data.get("web", {}).get("results", [])[:num_results]
-    ]
-    return {"query": query, "results": results, "total": len(results)}
-
-
-# --- web_scrape (httpx + BeautifulSoup, no playwright for sync compat) ---
-
-TOOL_REGISTRY.register(
-    name="web_scrape",
-    tool=Tool(
-        name="web_scrape",
-        description=(
-            "Scrape and extract text content from a webpage URL. "
-            "Returns the page title and main text content."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "url": {
-                    "type": "string",
-                    "description": "URL of the webpage to scrape",
-                },
-                "max_length": {
-                    "type": "integer",
-                    "description": "Maximum text length (default 50000)",
-                },
-            },
-            "required": ["url"],
-        },
-    ),
-    executor=lambda inputs: _exec_web_scrape(inputs),
-)
-
-_SCRAPE_HEADERS = {
-    "User-Agent": (
-        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
-        "AppleWebKit/537.36 (KHTML, like Gecko) "
-        "Chrome/131.0.0.0 Safari/537.36"
-    ),
-    "Accept": "text/html,application/xhtml+xml",
-}
-
-
-def _exec_web_scrape(inputs: dict) -> dict:
-    url = inputs.get("url", "")
-    max_length = max(1000, min(inputs.get("max_length", 50000), 500000))
-    if not url.startswith(("http://", "https://")):
-        url = "https://" + url
-    try:
-        resp = httpx.get(url, timeout=30.0, follow_redirects=True, headers=_SCRAPE_HEADERS)
-        if resp.status_code != 200:
-            return {"error": f"HTTP {resp.status_code}"}
-        soup = BeautifulSoup(resp.text, "html.parser")
-        for tag in soup(["script", "style", "nav", "footer", "header", "aside", "noscript"]):
-            tag.decompose()
-        title = soup.title.get_text(strip=True) if soup.title else ""
-        main = (
-            soup.find("article")
-            or soup.find("main")
-            or soup.find(attrs={"role": "main"})
-            or soup.find("body")
-        )
-        text = main.get_text(separator=" ", strip=True) if main else ""
-        text = " ".join(text.split())
-        if len(text) > max_length:
-            text = text[:max_length] + "..."
-        return {"url": url, "title": title, "content": text, "length": len(text)}
-    except httpx.TimeoutException:
-        return {"error": "Request timed out"}
-    except Exception as e:
-        return {"error": f"Scrape failed: {e}"}
-
-
-# --- HubSpot CRM tools (optional, requires HUBSPOT_ACCESS_TOKEN) ---
-
-_HUBSPOT_API = "https://api.hubapi.com"
-
-
-def _hubspot_headers() -> dict | None:
-    token = CREDENTIALS.get("hubspot")
-    if token:
-        logger.debug("HubSpot token: %s...%s (len=%d)", token[:8], token[-4:], len(token))
-    else:
-        logger.debug("HubSpot token: not found")
-    if not token:
-        return None
-    return {
-        "Authorization": f"Bearer {token}",
-        "Content-Type": "application/json",
-        "Accept": "application/json",
-    }
-
-
-def _exec_hubspot_search(inputs: dict) -> dict:
-    headers = _hubspot_headers()
-    if not headers:
-        return {"error": "HUBSPOT_ACCESS_TOKEN not set"}
-    object_type = inputs.get("object_type", "contacts")
-    query = inputs.get("query", "")
-    limit = min(inputs.get("limit", 10), 100)
-    body: dict = {"limit": limit}
-    if query:
-        body["query"] = query
-    try:
-        resp = httpx.post(
-            f"{_HUBSPOT_API}/crm/v3/objects/{object_type}/search",
-            headers=headers,
-            json=body,
-            timeout=30.0,
-        )
-        if resp.status_code != 200:
-            return {"error": f"HubSpot API HTTP {resp.status_code}: {resp.text[:200]}"}
-        return resp.json()
-    except httpx.TimeoutException:
-        return {"error": "Request timed out"}
-    except Exception as e:
-        return {"error": f"HubSpot error: {e}"}
-
-
-TOOL_REGISTRY.register(
-    name="hubspot_search",
-    tool=Tool(
-        name="hubspot_search",
-        description=(
-            "Search HubSpot CRM objects (contacts, companies, or deals). "
-            "Returns matching records with their properties."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "object_type": {
-                    "type": "string",
-                    "description": "CRM object type: 'contacts', 'companies', or 'deals'",
-                },
-                "query": {
-                    "type": "string",
-                    "description": "Search query (name, email, domain, etc.)",
-                },
-                "limit": {
-                    "type": "integer",
-                    "description": "Max results (1-100, default 10)",
-                },
-            },
-            "required": ["object_type"],
-        },
-    ),
-    executor=lambda inputs: _exec_hubspot_search(inputs),
-)
-
-logger.info(
-    "ToolRegistry loaded: %s",
-    ", ".join(TOOL_REGISTRY.get_registered_names()),
-)
-
-
-# -------------------------------------------------------------------------
-# HTML page (embedded)
-# -------------------------------------------------------------------------
-
-HTML_PAGE = (  # noqa: E501
-    """<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>EventLoopNode Live Demo</title>
-<style>
-  * { box-sizing: border-box; margin: 0; padding: 0; }
-  body {
-    font-family: 'SF Mono', 'Fira Code', monospace;
-    background: #0d1117; color: #c9d1d9;
-    height: 100vh; display: flex; flex-direction: column;
-  }
-  header {
-    background: #161b22; padding: 12px 20px;
-    border-bottom: 1px solid #30363d;
-    display: flex; align-items: center; gap: 16px;
-  }
-  header h1 { font-size: 16px; color: #58a6ff; font-weight: 600; }
-  .status {
-    font-size: 12px; padding: 3px 10px; border-radius: 12px;
-    background: #21262d; color: #8b949e;
-  }
-  .status.running { background: #1a4b2e; color: #3fb950; }
-  .status.done { background: #1a3a5c; color: #58a6ff; }
-  .status.error { background: #4b1a1a; color: #f85149; }
-  .chat { flex: 1; overflow-y: auto; padding: 16px; }
-  .msg {
-    margin: 8px 0; padding: 10px 14px; border-radius: 8px;
-    line-height: 1.6; white-space: pre-wrap; word-wrap: break-word;
-  }
-  .msg.user { background: #1a3a5c; color: #58a6ff; }
-  .msg.assistant { background: #161b22; color: #c9d1d9; }
-  .msg.event {
-    background: transparent; color: #8b949e; font-size: 11px;
-    padding: 4px 14px; border-left: 3px solid #30363d;
-  }
-  .msg.event.loop { border-left-color: #58a6ff; }
-  .msg.event.tool { border-left-color: #d29922; }
-  .msg.event.stall { border-left-color: #f85149; }
-  .input-bar {
-    padding: 12px 16px; background: #161b22;
-    border-top: 1px solid #30363d; display: flex; gap: 8px;
-  }
-  .input-bar input {
-    flex: 1; background: #0d1117; border: 1px solid #30363d;
-    color: #c9d1d9; padding: 8px 12px; border-radius: 6px;
-    font-family: inherit; font-size: 14px; outline: none;
-  }
-  .input-bar input:focus { border-color: #58a6ff; }
-  .input-bar button {
-    background: #238636; color: #fff; border: none;
-    padding: 8px 20px; border-radius: 6px; cursor: pointer;
-    font-family: inherit; font-weight: 600;
-  }
-  .input-bar button:hover { background: #2ea043; }
-  .input-bar button:disabled {
-    background: #21262d; color: #484f58; cursor: not-allowed;
-  }
-  .input-bar button.clear { background: #da3633; }
-  .input-bar button.clear:hover { background: #f85149; }
-</style>
-</head>
-<body>
-  <header>
-    <h1>EventLoopNode Live</h1>
-    <span id="status" class="status">Idle</span>
-    <span id="iter" class="status" style="display:none">Step 0</span>
-  </header>
-  <div id="chat" class="chat"></div>
-  <div class="input-bar">
-    <input id="input" type="text"
-           placeholder="Ask anything..." autofocus />
-    <button id="go" onclick="run()">Send</button>
-    <button class="clear"
-            onclick="clearConversation()">Clear</button>
-  </div>
-
-<script>
-let ws = null;
-let currentAssistantEl = null;
-let iterCount = 0;
-const chat = document.getElementById('chat');
-const status = document.getElementById('status');
-const iterEl = document.getElementById('iter');
-const goBtn = document.getElementById('go');
-const inputEl = document.getElementById('input');
-
-inputEl.addEventListener('keydown', e => {
-  if (e.key === 'Enter') run();
-});
-
-function setStatus(text, cls) {
-  status.textContent = text;
-  status.className = 'status ' + cls;
-}
-
-function addMsg(text, cls) {
-  const el = document.createElement('div');
-  el.className = 'msg ' + cls;
-  el.textContent = text;
-  chat.appendChild(el);
-  chat.scrollTop = chat.scrollHeight;
-  return el;
-}
-
-function connect() {
-  ws = new WebSocket('ws://' + location.host + '/ws');
-  ws.onopen = () => {
-    setStatus('Ready', 'done');
-    goBtn.disabled = false;
-  };
-  ws.onmessage = handleEvent;
-  ws.onerror = () => { setStatus('Error', 'error'); };
-  ws.onclose = () => {
-    setStatus('Reconnecting...', '');
-    goBtn.disabled = true;
-    setTimeout(connect, 2000);
-  };
-}
-
-function handleEvent(msg) {
-  const evt = JSON.parse(msg.data);
-
-  if (evt.type === 'llm_text_delta') {
-    if (currentAssistantEl) {
-      currentAssistantEl.textContent += evt.content;
-      chat.scrollTop = chat.scrollHeight;
-    }
-  }
-  else if (evt.type === 'ready') {
-    setStatus('Ready', 'done');
-    if (currentAssistantEl && !currentAssistantEl.textContent)
-      currentAssistantEl.remove();
-    goBtn.disabled = false;
-  }
-  else if (evt.type === 'node_loop_iteration') {
-    iterCount = evt.iteration || (iterCount + 1);
-    iterEl.textContent = 'Step ' + iterCount;
-    iterEl.style.display = '';
-  }
-  else if (evt.type === 'tool_call_started') {
-    var info = evt.tool_name + '('
-      + JSON.stringify(evt.tool_input).slice(0, 120) + ')';
-    addMsg('TOOL  ' + info, 'event tool');
-  }
-  else if (evt.type === 'tool_call_completed') {
-    var preview = (evt.result || '').slice(0, 200);
-    var cls = evt.is_error ? 'stall' : 'tool';
-    addMsg('RESULT  ' + evt.tool_name + ': ' + preview,
-           'event ' + cls);
-    currentAssistantEl = addMsg('', 'assistant');
-  }
-  else if (evt.type === 'result') {
-    setStatus('Session ended', evt.success ? 'done' : 'error');
-    if (evt.error) addMsg('ERROR  ' + evt.error, 'event stall');
-    if (currentAssistantEl && !currentAssistantEl.textContent)
-      currentAssistantEl.remove();
-    goBtn.disabled = false;
-  }
-  else if (evt.type === 'node_stalled') {
-    addMsg('STALLED  ' + evt.reason, 'event stall');
-  }
-  else if (evt.type === 'cleared') {
-    chat.innerHTML = '';
-    iterCount = 0;
-    iterEl.textContent = 'Step 0';
-    iterEl.style.display = 'none';
-    setStatus('Ready', 'done');
-    goBtn.disabled = false;
-  }
-}
-
-function run() {
-  const text = inputEl.value.trim();
-  if (!text || !ws || ws.readyState !== 1) return;
-  addMsg(text, 'user');
-  currentAssistantEl = addMsg('', 'assistant');
-  inputEl.value = '';
-  setStatus('Running', 'running');
-  goBtn.disabled = true;
-  ws.send(JSON.stringify({ topic: text }));
-}
-
-function clearConversation() {
-  if (ws && ws.readyState === 1) {
-    ws.send(JSON.stringify({ command: 'clear' }));
-  }
-}
-
-connect();
-</script>
-</body>
-</html>"""
-)
-
-
-# -------------------------------------------------------------------------
-# WebSocket handler
-# -------------------------------------------------------------------------
-
-
-async def handle_ws(websocket):
-    """Persistent WebSocket: long-lived EventLoopNode with client_facing blocking."""
-    global STORE
-
-    # -- Event forwarding (WebSocket ← EventBus) ----------------------------
-    bus = EventBus()
-
-    async def forward_event(event):
-        try:
-            payload = {"type": event.type.value, **event.data}
-            if event.node_id:
-                payload["node_id"] = event.node_id
-            await websocket.send(json.dumps(payload))
-        except Exception:
-            pass
-
-    bus.subscribe(
-        event_types=[
-            EventType.NODE_LOOP_STARTED,
-            EventType.NODE_LOOP_ITERATION,
-            EventType.NODE_LOOP_COMPLETED,
-            EventType.LLM_TEXT_DELTA,
-            EventType.TOOL_CALL_STARTED,
-            EventType.TOOL_CALL_COMPLETED,
-            EventType.NODE_STALLED,
-        ],
-        handler=forward_event,
-    )
-
-    # -- Per-connection state -----------------------------------------------
-    node = None
-    loop_task = None
-
-    tools = list(TOOL_REGISTRY.get_tools().values())
-    tool_executor = TOOL_REGISTRY.get_executor()
-
-    node_spec = NodeSpec(
-        id="assistant",
-        name="Chat Assistant",
-        description="A conversational assistant that remembers context across messages",
-        node_type="event_loop",
-        client_facing=True,
-        system_prompt=(
-            "You are a helpful assistant with access to tools. "
-            "You can search the web, scrape webpages, and query HubSpot CRM. "
-            "Use tools when the user asks for current information or external data. "
-            "You have full conversation history, so you can reference previous messages."
-        ),
-    )
-
-    # -- Ready callback: subscribe to CLIENT_INPUT_REQUESTED on the bus ---
-    async def on_input_requested(event):
-        try:
-            await websocket.send(json.dumps({"type": "ready"}))
-        except Exception:
-            pass
-
-    bus.subscribe(
-        event_types=[EventType.CLIENT_INPUT_REQUESTED],
-        handler=on_input_requested,
-    )
-
-    async def start_loop(first_message: str):
-        """Create an EventLoopNode and run it as a background task."""
-        nonlocal node, loop_task
-
-        memory = SharedMemory()
-        ctx = NodeContext(
-            runtime=RUNTIME,
-            node_id="assistant",
-            node_spec=node_spec,
-            memory=memory,
-            input_data={},
-            llm=LLM,
-            available_tools=tools,
-        )
-        node = EventLoopNode(
-            event_bus=bus,
-            config=LoopConfig(max_iterations=10_000, max_history_tokens=32_000),
-            conversation_store=STORE,
-            tool_executor=tool_executor,
-        )
-        await node.inject_event(first_message)
-
-        async def _run():
-            try:
-                result = await node.execute(ctx)
-                try:
-                    await websocket.send(
-                        json.dumps(
-                            {
-                                "type": "result",
-                                "success": result.success,
-                                "output": result.output,
-                                "error": result.error,
-                                "tokens": result.tokens_used,
-                            }
-                        )
-                    )
-                except Exception:
-                    pass
-                logger.info(f"Loop ended: success={result.success}, tokens={result.tokens_used}")
-            except websockets.exceptions.ConnectionClosed:
-                logger.info("Loop stopped: WebSocket closed")
-            except Exception as e:
-                logger.exception("Loop error")
-                try:
-                    await websocket.send(
-                        json.dumps(
-                            {
-                                "type": "result",
-                                "success": False,
-                                "error": str(e),
-                                "output": {},
-                            }
-                        )
-                    )
-                except Exception:
-                    pass
-
-        loop_task = asyncio.create_task(_run())
-
-    async def stop_loop():
-        """Signal the node and wait for the loop task to finish."""
-        nonlocal node, loop_task
-        if loop_task and not loop_task.done():
-            if node:
-                node.signal_shutdown()
-            try:
-                await asyncio.wait_for(loop_task, timeout=5.0)
-            except (TimeoutError, asyncio.CancelledError):
-                loop_task.cancel()
-        node = None
-        loop_task = None
-
-    # -- Message loop (runs for the lifetime of this WebSocket) -------------
-    try:
-        async for raw in websocket:
-            try:
-                msg = json.loads(raw)
-            except Exception:
-                continue
-
-            # Clear command
-            if msg.get("command") == "clear":
-                import shutil
-
-                await stop_loop()
-                await STORE.close()
-                conv_dir = STORE_DIR / "conversation"
-                if conv_dir.exists():
-                    shutil.rmtree(conv_dir)
-                STORE = FileConversationStore(conv_dir)
-                await websocket.send(json.dumps({"type": "cleared"}))
-                logger.info("Conversation cleared")
-                continue
-
-            topic = msg.get("topic", "")
-            if not topic:
-                continue
-
-            if node is None:
-                # First message — spin up the loop
-                logger.info(f"Starting persistent loop: {topic}")
-                await start_loop(topic)
-            else:
-                # Subsequent message — inject into the running loop
-                logger.info(f"Injecting message: {topic}")
-                await node.inject_event(topic)
-
-    except websockets.exceptions.ConnectionClosed:
-        pass
-    finally:
-        await stop_loop()
-        logger.info("WebSocket closed, loop stopped")
-
-
-# -------------------------------------------------------------------------
-# HTTP handler for serving the HTML page
-# -------------------------------------------------------------------------
-
-
-async def process_request(connection, request: Request):
-    """Serve HTML on GET /, upgrade to WebSocket on /ws."""
-    if request.path == "/ws":
-        return None  # let websockets handle the upgrade
-    # Serve the HTML page for any other path
-    return Response(
-        HTTPStatus.OK,
-        "OK",
-        websockets.Headers({"Content-Type": "text/html; charset=utf-8"}),
-        HTML_PAGE.encode(),
-    )
-
-
-# -------------------------------------------------------------------------
-# Main
-# -------------------------------------------------------------------------
-
-
-async def main():
-    port = 8765
-    async with websockets.serve(
-        handle_ws,
-        "0.0.0.0",
-        port,
-        process_request=process_request,
-    ):
-        logger.info(f"Demo running at http://localhost:{port}")
-        logger.info("Open in your browser and enter a topic to research.")
-        await asyncio.Future()  # run forever
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

core/demos/handoff_demo.py

@@ -1,930 +0,0 @@
-#!/usr/bin/env python3
-"""
-Two-Node ContextHandoff Demo
-
-Demonstrates ContextHandoff between two EventLoopNode instances:
-  Node A (Researcher) → ContextHandoff → Node B (Analyst)
-
-Real LLM, real FileConversationStore, real EventBus.
-Streams both nodes to a browser via WebSocket.
-
-Usage:
-    cd /home/timothy/oss/hive/core
-    python demos/handoff_demo.py
-
-    Then open http://localhost:8766 in your browser.
-"""
-
-import asyncio
-import json
-import logging
-import sys
-import tempfile
-from http import HTTPStatus
-from pathlib import Path
-
-import httpx
-import websockets
-from bs4 import BeautifulSoup
-from websockets.http11 import Request, Response
-
-# Add core, tools, and hive root to path
-_CORE_DIR = Path(__file__).resolve().parent.parent
-_HIVE_DIR = _CORE_DIR.parent
-sys.path.insert(0, str(_CORE_DIR))  # framework.*
-sys.path.insert(0, str(_HIVE_DIR / "tools" / "src"))  # aden_tools.*
-sys.path.insert(0, str(_HIVE_DIR))  # core.framework.* (for aden_tools imports)
-
-from aden_tools.credentials import CREDENTIAL_SPECS, CredentialStoreAdapter  # noqa: E402
-from core.framework.credentials import CredentialStore  # noqa: E402
-
-from framework.credentials.storage import (  # noqa: E402
-    CompositeStorage,
-    EncryptedFileStorage,
-    EnvVarStorage,
-)
-from framework.graph.context_handoff import ContextHandoff  # noqa: E402
-from framework.graph.conversation import NodeConversation  # noqa: E402
-from framework.graph.event_loop_node import EventLoopNode, LoopConfig  # noqa: E402
-from framework.graph.node import NodeContext, NodeSpec, SharedMemory  # noqa: E402
-from framework.llm.litellm import LiteLLMProvider  # noqa: E402
-from framework.llm.provider import Tool  # noqa: E402
-from framework.runner.tool_registry import ToolRegistry  # noqa: E402
-from framework.runtime.core import Runtime  # noqa: E402
-from framework.runtime.event_bus import EventBus, EventType  # noqa: E402
-from framework.storage.conversation_store import FileConversationStore  # noqa: E402
-
-logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(message)s")
-logger = logging.getLogger("handoff_demo")
-
-# -------------------------------------------------------------------------
-# Persistent state
-# -------------------------------------------------------------------------
-
-STORE_DIR = Path(tempfile.mkdtemp(prefix="hive_handoff_"))
-RUNTIME = Runtime(STORE_DIR / "runtime")
-LLM = LiteLLMProvider(model="claude-sonnet-4-5-20250929")
-
-# -------------------------------------------------------------------------
-# Credentials
-# -------------------------------------------------------------------------
-
-# Composite credential store: encrypted files (primary) + env vars (fallback)
-_env_mapping = {name: spec.env_var for name, spec in CREDENTIAL_SPECS.items()}
-_composite = CompositeStorage(
-    primary=EncryptedFileStorage(),
-    fallbacks=[EnvVarStorage(env_mapping=_env_mapping)],
-)
-CREDENTIALS = CredentialStoreAdapter(CredentialStore(storage=_composite))
-
-for _name in ["brave_search", "hubspot"]:
-    _val = CREDENTIALS.get(_name)
-    if _val:
-        logger.debug("credential %s: OK (len=%d)", _name, len(_val))
-    else:
-        logger.debug("credential %s: not found", _name)
-
-# -------------------------------------------------------------------------
-# Tool Registry — web_search + web_scrape for Node A (Researcher)
-# -------------------------------------------------------------------------
-
-TOOL_REGISTRY = ToolRegistry()
-
-
-def _exec_web_search(inputs: dict) -> dict:
-    api_key = CREDENTIALS.get("brave_search")
-    if not api_key:
-        return {"error": "brave_search credential not configured"}
-    query = inputs.get("query", "")
-    num_results = min(inputs.get("num_results", 10), 20)
-    resp = httpx.get(
-        "https://api.search.brave.com/res/v1/web/search",
-        params={"q": query, "count": num_results},
-        headers={
-            "X-Subscription-Token": api_key,
-            "Accept": "application/json",
-        },
-        timeout=30.0,
-    )
-    if resp.status_code != 200:
-        return {"error": f"Brave API HTTP {resp.status_code}"}
-    data = resp.json()
-    results = [
-        {
-            "title": item.get("title", ""),
-            "url": item.get("url", ""),
-            "snippet": item.get("description", ""),
-        }
-        for item in data.get("web", {}).get("results", [])[:num_results]
-    ]
-    return {"query": query, "results": results, "total": len(results)}
-
-
-TOOL_REGISTRY.register(
-    name="web_search",
-    tool=Tool(
-        name="web_search",
-        description=(
-            "Search the web for current information. "
-            "Returns titles, URLs, and snippets from search results."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "query": {
-                    "type": "string",
-                    "description": "The search query (1-500 characters)",
-                },
-                "num_results": {
-                    "type": "integer",
-                    "description": "Number of results (1-20, default 10)",
-                },
-            },
-            "required": ["query"],
-        },
-    ),
-    executor=lambda inputs: _exec_web_search(inputs),
-)
-
-_SCRAPE_HEADERS = {
-    "User-Agent": (
-        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
-        "AppleWebKit/537.36 (KHTML, like Gecko) "
-        "Chrome/131.0.0.0 Safari/537.36"
-    ),
-    "Accept": "text/html,application/xhtml+xml",
-}
-
-
-def _exec_web_scrape(inputs: dict) -> dict:
-    url = inputs.get("url", "")
-    max_length = max(1000, min(inputs.get("max_length", 50000), 500000))
-    if not url.startswith(("http://", "https://")):
-        url = "https://" + url
-    try:
-        resp = httpx.get(
-            url,
-            timeout=30.0,
-            follow_redirects=True,
-            headers=_SCRAPE_HEADERS,
-        )
-        if resp.status_code != 200:
-            return {"error": f"HTTP {resp.status_code}"}
-        soup = BeautifulSoup(resp.text, "html.parser")
-        for tag in soup(["script", "style", "nav", "footer", "header", "aside", "noscript"]):
-            tag.decompose()
-        title = soup.title.get_text(strip=True) if soup.title else ""
-        main = (
-            soup.find("article")
-            or soup.find("main")
-            or soup.find(attrs={"role": "main"})
-            or soup.find("body")
-        )
-        text = main.get_text(separator=" ", strip=True) if main else ""
-        text = " ".join(text.split())
-        if len(text) > max_length:
-            text = text[:max_length] + "..."
-        return {
-            "url": url,
-            "title": title,
-            "content": text,
-            "length": len(text),
-        }
-    except httpx.TimeoutException:
-        return {"error": "Request timed out"}
-    except Exception as e:
-        return {"error": f"Scrape failed: {e}"}
-
-
-TOOL_REGISTRY.register(
-    name="web_scrape",
-    tool=Tool(
-        name="web_scrape",
-        description=(
-            "Scrape and extract text content from a webpage URL. "
-            "Returns the page title and main text content."
-        ),
-        parameters={
-            "type": "object",
-            "properties": {
-                "url": {
-                    "type": "string",
-                    "description": "URL of the webpage to scrape",
-                },
-                "max_length": {
-                    "type": "integer",
-                    "description": "Maximum text length (default 50000)",
-                },
-            },
-            "required": ["url"],
-        },
-    ),
-    executor=lambda inputs: _exec_web_scrape(inputs),
-)
-
-logger.info(
-    "ToolRegistry loaded: %s",
-    ", ".join(TOOL_REGISTRY.get_registered_names()),
-)
-
-# -------------------------------------------------------------------------
-# Node Specs
-# -------------------------------------------------------------------------
-
-RESEARCHER_SPEC = NodeSpec(
-    id="researcher",
-    name="Researcher",
-    description="Researches a topic using web search and scraping tools",
-    node_type="event_loop",
-    input_keys=["topic"],
-    output_keys=["research_summary"],
-    system_prompt=(
-        "You are a thorough research assistant. Your job is to research "
-        "the given topic using the web_search and web_scrape tools.\n\n"
-        "1. Search for relevant information on the topic\n"
-        "2. Scrape 1-2 of the most promising URLs for details\n"
-        "3. Synthesize your findings into a comprehensive summary\n"
-        "4. Use set_output with key='research_summary' to save your "
-        "findings\n\n"
-        "Be thorough but efficient. Aim for 2-4 search/scrape calls, "
-        "then summarize and set_output."
-    ),
-)
-
-ANALYST_SPEC = NodeSpec(
-    id="analyst",
-    name="Analyst",
-    description="Analyzes research findings and provides insights",
-    node_type="event_loop",
-    input_keys=["context"],
-    output_keys=["analysis"],
-    system_prompt=(
-        "You are a strategic analyst. You receive research findings from "
-        "a previous researcher and must:\n\n"
-        "1. Identify key themes and patterns\n"
-        "2. Assess the reliability and significance of the findings\n"
-        "3. Provide actionable insights and recommendations\n"
-        "4. Use set_output with key='analysis' to save your analysis\n\n"
-        "Be concise but insightful. Focus on what matters most."
-    ),
-)
-
-
-# -------------------------------------------------------------------------
-# HTML page
-# -------------------------------------------------------------------------
-
-HTML_PAGE = (  # noqa: E501
-    """<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>ContextHandoff Demo</title>
-<style>
-  * {
-    box-sizing: border-box;
-    margin: 0;
-    padding: 0;
-  }
-  body {
-    font-family: 'SF Mono', 'Fira Code', monospace;
-    background: #0d1117;
-    color: #c9d1d9;
-    height: 100vh;
-    display: flex;
-    flex-direction: column;
-  }
-  header {
-    background: #161b22;
-    padding: 12px 20px;
-    border-bottom: 1px solid #30363d;
-    display: flex;
-    align-items: center;
-    gap: 16px;
-  }
-  header h1 {
-    font-size: 16px;
-    color: #58a6ff;
-    font-weight: 600;
-  }
-  .badge {
-    font-size: 12px;
-    padding: 3px 10px;
-    border-radius: 12px;
-    background: #21262d;
-    color: #8b949e;
-  }
-  .badge.researcher {
-    background: #1a3a5c;
-    color: #58a6ff;
-  }
-  .badge.analyst {
-    background: #1a4b2e;
-    color: #3fb950;
-  }
-  .badge.handoff {
-    background: #3d1f00;
-    color: #d29922;
-  }
-  .badge.done {
-    background: #21262d;
-    color: #8b949e;
-  }
-  .badge.error {
-    background: #4b1a1a;
-    color: #f85149;
-  }
-  .chat {
-    flex: 1;
-    overflow-y: auto;
-    padding: 16px;
-  }
-  .msg {
-    margin: 8px 0;
-    padding: 10px 14px;
-    border-radius: 8px;
-    line-height: 1.6;
-    white-space: pre-wrap;
-    word-wrap: break-word;
-  }
-  .msg.user {
-    background: #1a3a5c;
-    color: #58a6ff;
-  }
-  .msg.assistant {
-    background: #161b22;
-    color: #c9d1d9;
-  }
-  .msg.assistant.analyst-msg {
-    border-left: 3px solid #3fb950;
-  }
-  .msg.event {
-    background: transparent;
-    color: #8b949e;
-    font-size: 11px;
-    padding: 4px 14px;
-    border-left: 3px solid #30363d;
-  }
-  .msg.event.loop {
-    border-left-color: #58a6ff;
-  }
-  .msg.event.tool {
-    border-left-color: #d29922;
-  }
-  .msg.event.stall {
-    border-left-color: #f85149;
-  }
-  .handoff-banner {
-    margin: 16px 0;
-    padding: 16px;
-    background: #1c1200;
-    border: 1px solid #d29922;
-    border-radius: 8px;
-    text-align: center;
-  }
-  .handoff-banner h3 {
-    color: #d29922;
-    font-size: 14px;
-    margin-bottom: 8px;
-  }
-  .handoff-banner p, .result-banner p {
-    color: #8b949e;
-    font-size: 12px;
-    line-height: 1.5;
-    max-height: 200px;
-    overflow-y: auto;
-    white-space: pre-wrap;
-    text-align: left;
-  }
-  .result-banner {
-    margin: 16px 0;
-    padding: 16px;
-    background: #0a2614;
-    border: 1px solid #3fb950;
-    border-radius: 8px;
-  }
-  .result-banner h3 {
-    color: #3fb950;
-    font-size: 14px;
-    margin-bottom: 8px;
-    text-align: center;
-  }
-  .result-banner .label {
-    color: #58a6ff;
-    font-size: 11px;
-    font-weight: 600;
-    margin-top: 10px;
-    margin-bottom: 2px;
-  }
-  .result-banner .tokens {
-    color: #484f58;
-    font-size: 11px;
-    text-align: center;
-    margin-top: 10px;
-  }
-  .input-bar {
-    padding: 12px 16px;
-    background: #161b22;
-    border-top: 1px solid #30363d;
-    display: flex;
-    gap: 8px;
-  }
-  .input-bar input {
-    flex: 1;
-    background: #0d1117;
-    border: 1px solid #30363d;
-    color: #c9d1d9;
-    padding: 8px 12px;
-    border-radius: 6px;
-    font-family: inherit;
-    font-size: 14px;
-    outline: none;
-  }
-  .input-bar input:focus {
-    border-color: #58a6ff;
-  }
-  .input-bar button {
-    background: #238636;
-    color: #fff;
-    border: none;
-    padding: 8px 20px;
-    border-radius: 6px;
-    cursor: pointer;
-    font-family: inherit;
-    font-weight: 600;
-  }
-  .input-bar button:hover {
-    background: #2ea043;
-  }
-  .input-bar button:disabled {
-    background: #21262d;
-    color: #484f58;
-    cursor: not-allowed;
-  }
-</style>
-</head>
-<body>
-  <header>
-    <h1>ContextHandoff Demo</h1>
-    <span id="phase" class="badge">Idle</span>
-    <span id="iter" class="badge" style="display:none">Step 0</span>
-  </header>
-  <div id="chat" class="chat"></div>
-  <div class="input-bar">
-    <input id="input" type="text"
-           placeholder="Enter a research topic..." autofocus />
-    <button id="go" onclick="run()">Research</button>
-  </div>
-
-<script>
-let ws = null;
-let currentAssistantEl = null;
-let iterCount = 0;
-let currentPhase = 'idle';
-const chat = document.getElementById('chat');
-const phase = document.getElementById('phase');
-const iterEl = document.getElementById('iter');
-const goBtn = document.getElementById('go');
-const inputEl = document.getElementById('input');
-
-inputEl.addEventListener('keydown', e => {
-  if (e.key === 'Enter') run();
-});
-
-function setPhase(text, cls) {
-  phase.textContent = text;
-  phase.className = 'badge ' + cls;
-  currentPhase = cls;
-}
-
-function addMsg(text, cls) {
-  const el = document.createElement('div');
-  el.className = 'msg ' + cls;
-  el.textContent = text;
-  chat.appendChild(el);
-  chat.scrollTop = chat.scrollHeight;
-  return el;
-}
-
-function addHandoffBanner(summary) {
-  const banner = document.createElement('div');
-  banner.className = 'handoff-banner';
-  const h3 = document.createElement('h3');
-  h3.textContent = 'Context Handoff: Researcher -> Analyst';
-  const p = document.createElement('p');
-  p.textContent = summary || 'Passing research context...';
-  banner.appendChild(h3);
-  banner.appendChild(p);
-  chat.appendChild(banner);
-  chat.scrollTop = chat.scrollHeight;
-}
-
-function addResultBanner(researcher, analyst, tokens) {
-  const banner = document.createElement('div');
-  banner.className = 'result-banner';
-  const h3 = document.createElement('h3');
-  h3.textContent = 'Pipeline Complete';
-  banner.appendChild(h3);
-
-  if (researcher && researcher.research_summary) {
-    const lbl = document.createElement('div');
-    lbl.className = 'label';
-    lbl.textContent = 'RESEARCH SUMMARY';
-    banner.appendChild(lbl);
-    const p = document.createElement('p');
-    p.textContent = researcher.research_summary;
-    banner.appendChild(p);
-  }
-
-  if (analyst && analyst.analysis) {
-    const lbl = document.createElement('div');
-    lbl.className = 'label';
-    lbl.textContent = 'ANALYSIS';
-    lbl.style.color = '#3fb950';
-    banner.appendChild(lbl);
-    const p = document.createElement('p');
-    p.textContent = analyst.analysis;
-    banner.appendChild(p);
-  }
-
-  if (tokens) {
-    const t = document.createElement('div');
-    t.className = 'tokens';
-    t.textContent = 'Total tokens: ' + tokens.toLocaleString();
-    banner.appendChild(t);
-  }
-
-  chat.appendChild(banner);
-  chat.scrollTop = chat.scrollHeight;
-}
-
-function connect() {
-  ws = new WebSocket('ws://' + location.host + '/ws');
-  ws.onopen = () => {
-    setPhase('Ready', 'done');
-    goBtn.disabled = false;
-  };
-  ws.onmessage = handleEvent;
-  ws.onerror = () => { setPhase('Error', 'error'); };
-  ws.onclose = () => {
-    setPhase('Reconnecting...', '');
-    goBtn.disabled = true;
-    setTimeout(connect, 2000);
-  };
-}
-
-function handleEvent(msg) {
-  const evt = JSON.parse(msg.data);
-
-  if (evt.type === 'phase') {
-    if (evt.phase === 'researcher') {
-      setPhase('Researcher', 'researcher');
-    } else if (evt.phase === 'handoff') {
-      setPhase('Handoff', 'handoff');
-    } else if (evt.phase === 'analyst') {
-      setPhase('Analyst', 'analyst');
-    }
-    iterCount = 0;
-    iterEl.style.display = 'none';
-  }
-  else if (evt.type === 'llm_text_delta') {
-    if (currentAssistantEl) {
-      currentAssistantEl.textContent += evt.content;
-      chat.scrollTop = chat.scrollHeight;
-    }
-  }
-  else if (evt.type === 'node_loop_iteration') {
-    iterCount = evt.iteration || (iterCount + 1);
-    iterEl.textContent = 'Step ' + iterCount;
-    iterEl.style.display = '';
-  }
-  else if (evt.type === 'tool_call_started') {
-    var info = evt.tool_name + '('
-      + JSON.stringify(evt.tool_input).slice(0, 120) + ')';
-    addMsg('TOOL  ' + info, 'event tool');
-  }
-  else if (evt.type === 'tool_call_completed') {
-    var preview = (evt.result || '').slice(0, 200);
-    var cls = evt.is_error ? 'stall' : 'tool';
-    addMsg(
-      'RESULT  ' + evt.tool_name + ': ' + preview,
-      'event ' + cls
-    );
-    var assistCls = currentPhase === 'analyst'
-      ? 'assistant analyst-msg' : 'assistant';
-    currentAssistantEl = addMsg('', assistCls);
-  }
-  else if (evt.type === 'handoff_context') {
-    addHandoffBanner(evt.summary);
-    var assistCls = 'assistant analyst-msg';
-    currentAssistantEl = addMsg('', assistCls);
-  }
-  else if (evt.type === 'node_result') {
-    if (evt.node_id === 'researcher') {
-      if (currentAssistantEl
-          && !currentAssistantEl.textContent) {
-        currentAssistantEl.remove();
-      }
-    }
-  }
-  else if (evt.type === 'done') {
-    setPhase('Done', 'done');
-    iterEl.style.display = 'none';
-    if (currentAssistantEl
-        && !currentAssistantEl.textContent) {
-      currentAssistantEl.remove();
-    }
-    currentAssistantEl = null;
-    addResultBanner(
-      evt.researcher, evt.analyst, evt.total_tokens
-    );
-    goBtn.disabled = false;
-    inputEl.placeholder = 'Enter another topic...';
-  }
-  else if (evt.type === 'error') {
-    setPhase('Error', 'error');
-    addMsg('ERROR  ' + evt.message, 'event stall');
-    goBtn.disabled = false;
-  }
-  else if (evt.type === 'node_stalled') {
-    addMsg('STALLED  ' + evt.reason, 'event stall');
-  }
-}
-
-function run() {
-  const text = inputEl.value.trim();
-  if (!text || !ws || ws.readyState !== 1) return;
-  chat.innerHTML = '';
-  addMsg(text, 'user');
-  currentAssistantEl = addMsg('', 'assistant');
-  inputEl.value = '';
-  goBtn.disabled = true;
-  ws.send(JSON.stringify({ topic: text }));
-}
-
-connect();
-</script>
-</body>
-</html>"""
-)
-
-
-# -------------------------------------------------------------------------
-# WebSocket handler — sequential Node A → Handoff → Node B
-# -------------------------------------------------------------------------
-
-
-async def handle_ws(websocket):
-    """Run the two-node handoff pipeline per user message."""
-    try:
-        async for raw in websocket:
-            try:
-                msg = json.loads(raw)
-            except Exception:
-                continue
-
-            topic = msg.get("topic", "")
-            if not topic:
-                continue
-
-            logger.info(f"Starting handoff pipeline for: {topic}")
-
-            try:
-                await _run_pipeline(websocket, topic)
-            except websockets.exceptions.ConnectionClosed:
-                logger.info("WebSocket closed during pipeline")
-                return
-            except Exception as e:
-                logger.exception("Pipeline error")
-                try:
-                    await websocket.send(json.dumps({"type": "error", "message": str(e)}))
-                except Exception:
-                    pass
-
-    except websockets.exceptions.ConnectionClosed:
-        pass
-
-
-async def _run_pipeline(websocket, topic: str):
-    """Execute: Node A (research) → ContextHandoff → Node B (analysis)."""
-    import shutil
-
-    # Fresh stores for each run
-    run_dir = Path(tempfile.mkdtemp(prefix="hive_run_", dir=STORE_DIR))
-    store_a = FileConversationStore(run_dir / "node_a")
-    store_b = FileConversationStore(run_dir / "node_b")
-
-    # Shared event bus
-    bus = EventBus()
-
-    async def forward_event(event):
-        try:
-            payload = {"type": event.type.value, **event.data}
-            if event.node_id:
-                payload["node_id"] = event.node_id
-            await websocket.send(json.dumps(payload))
-        except Exception:
-            pass
-
-    bus.subscribe(
-        event_types=[
-            EventType.NODE_LOOP_STARTED,
-            EventType.NODE_LOOP_ITERATION,
-            EventType.NODE_LOOP_COMPLETED,
-            EventType.LLM_TEXT_DELTA,
-            EventType.TOOL_CALL_STARTED,
-            EventType.TOOL_CALL_COMPLETED,
-            EventType.NODE_STALLED,
-        ],
-        handler=forward_event,
-    )
-
-    tools = list(TOOL_REGISTRY.get_tools().values())
-    tool_executor = TOOL_REGISTRY.get_executor()
-
-    # ---- Phase 1: Researcher ------------------------------------------------
-    await websocket.send(json.dumps({"type": "phase", "phase": "researcher"}))
-
-    node_a = EventLoopNode(
-        event_bus=bus,
-        judge=None,  # implicit judge: accept when output_keys filled
-        config=LoopConfig(
-            max_iterations=20,
-            max_tool_calls_per_turn=30,
-            max_history_tokens=32_000,
-        ),
-        conversation_store=store_a,
-        tool_executor=tool_executor,
-    )
-
-    ctx_a = NodeContext(
-        runtime=RUNTIME,
-        node_id="researcher",
-        node_spec=RESEARCHER_SPEC,
-        memory=SharedMemory(),
-        input_data={"topic": topic},
-        llm=LLM,
-        available_tools=tools,
-    )
-
-    result_a = await node_a.execute(ctx_a)
-    logger.info(
-        "Researcher done: success=%s, tokens=%s",
-        result_a.success,
-        result_a.tokens_used,
-    )
-
-    await websocket.send(
-        json.dumps(
-            {
-                "type": "node_result",
-                "node_id": "researcher",
-                "success": result_a.success,
-                "output": result_a.output,
-            }
-        )
-    )
-
-    if not result_a.success:
-        await websocket.send(
-            json.dumps(
-                {
-                    "type": "error",
-                    "message": f"Researcher failed: {result_a.error}",
-                }
-            )
-        )
-        return
-
-    # ---- Phase 2: Context Handoff -------------------------------------------
-    await websocket.send(json.dumps({"type": "phase", "phase": "handoff"}))
-
-    # Restore the researcher's conversation from store
-    conversation_a = await NodeConversation.restore(store_a)
-    if conversation_a is None:
-        await websocket.send(
-            json.dumps(
-                {
-                    "type": "error",
-                    "message": "Failed to restore researcher conversation",
-                }
-            )
-        )
-        return
-
-    handoff_engine = ContextHandoff(llm=LLM)
-    handoff_context = handoff_engine.summarize_conversation(
-        conversation=conversation_a,
-        node_id="researcher",
-        output_keys=["research_summary"],
-    )
-
-    formatted_handoff = ContextHandoff.format_as_input(handoff_context)
-    logger.info(
-        "Handoff: %d turns, ~%d tokens, keys=%s",
-        handoff_context.turn_count,
-        handoff_context.total_tokens_used,
-        list(handoff_context.key_outputs.keys()),
-    )
-
-    # Send handoff context to browser
-    await websocket.send(
-        json.dumps(
-            {
-                "type": "handoff_context",
-                "summary": handoff_context.summary[:500],
-                "turn_count": handoff_context.turn_count,
-                "tokens": handoff_context.total_tokens_used,
-                "key_outputs": handoff_context.key_outputs,
-            }
-        )
-    )
-
-    # ---- Phase 3: Analyst ---------------------------------------------------
-    await websocket.send(json.dumps({"type": "phase", "phase": "analyst"}))
-
-    node_b = EventLoopNode(
-        event_bus=bus,
-        judge=None,  # implicit judge
-        config=LoopConfig(
-            max_iterations=10,
-            max_tool_calls_per_turn=30,
-            max_history_tokens=32_000,
-        ),
-        conversation_store=store_b,
-    )
-
-    ctx_b = NodeContext(
-        runtime=RUNTIME,
-        node_id="analyst",
-        node_spec=ANALYST_SPEC,
-        memory=SharedMemory(),
-        input_data={"context": formatted_handoff},
-        llm=LLM,
-        available_tools=[],
-    )
-
-    result_b = await node_b.execute(ctx_b)
-    logger.info(
-        "Analyst done: success=%s, tokens=%s",
-        result_b.success,
-        result_b.tokens_used,
-    )
-
-    # ---- Done ---------------------------------------------------------------
-    await websocket.send(
-        json.dumps(
-            {
-                "type": "done",
-                "researcher": result_a.output,
-                "analyst": result_b.output,
-                "total_tokens": ((result_a.tokens_used or 0) + (result_b.tokens_used or 0)),
-            }
-        )
-    )
-
-    # Clean up temp stores
-    try:
-        shutil.rmtree(run_dir)
-    except Exception:
-        pass
-
-
-# -------------------------------------------------------------------------
-# HTTP handler
-# -------------------------------------------------------------------------
-
-
-async def process_request(connection, request: Request):
-    """Serve HTML on GET /, upgrade to WebSocket on /ws."""
-    if request.path == "/ws":
-        return None
-    return Response(
-        HTTPStatus.OK,
-        "OK",
-        websockets.Headers({"Content-Type": "text/html; charset=utf-8"}),
-        HTML_PAGE.encode(),
-    )
-
-
-# -------------------------------------------------------------------------
-# Main
-# -------------------------------------------------------------------------
-
-
-async def main():
-    port = 8766
-    async with websockets.serve(
-        handle_ws,
-        "0.0.0.0",
-        port,
-        process_request=process_request,
-    ):
-        logger.info(f"Handoff demo at http://localhost:{port}")
-        logger.info("Enter a research topic to start the pipeline.")
-        await asyncio.Future()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

core/examples/manual_agent.py

@@ -1,132 +0,0 @@
-"""
-Minimal Manual Agent Example
-----------------------------
-This example demonstrates how to build and run an agent programmatically
-without using the Claude Code CLI or external LLM APIs.
-
-It uses custom NodeProtocol implementations to define logic in pure Python,
-making it perfect for understanding the core runtime loop:
-Setup -> Graph definition -> Execution -> Result
-
-Run with:
-    uv run python core/examples/manual_agent.py
-"""
-
-import asyncio
-
-from framework.graph import EdgeCondition, EdgeSpec, Goal, GraphSpec, NodeSpec
-from framework.graph.executor import GraphExecutor
-from framework.graph.node import NodeContext, NodeProtocol, NodeResult
-from framework.runtime.core import Runtime
-
-
-# 1. Define Node Logic (Custom NodeProtocol implementations)
-class GreeterNode(NodeProtocol):
-    """Generate a simple greeting."""
-
-    async def execute(self, ctx: NodeContext) -> NodeResult:
-        name = ctx.input_data.get("name", "World")
-        greeting = f"Hello, {name}!"
-        ctx.memory.write("greeting", greeting)
-        return NodeResult(success=True, output={"greeting": greeting})
-
-
-class UppercaserNode(NodeProtocol):
-    """Convert text to uppercase."""
-
-    async def execute(self, ctx: NodeContext) -> NodeResult:
-        greeting = ctx.input_data.get("greeting") or ctx.memory.read("greeting") or ""
-        result = greeting.upper()
-        ctx.memory.write("final_greeting", result)
-        return NodeResult(success=True, output={"final_greeting": result})
-
-
-async def main():
-    print("Setting up Manual Agent...")
-
-    # 2. Define the Goal
-    # Every agent needs a goal with success criteria
-    goal = Goal(
-        id="greet-user",
-        name="Greet User",
-        description="Generate a friendly uppercase greeting",
-        success_criteria=[
-            {
-                "id": "greeting_generated",
-                "description": "Greeting produced",
-                "metric": "custom",
-                "target": "any",
-            }
-        ],
-    )
-
-    # 3. Define Nodes
-    # Nodes describe steps in the process
-    node1 = NodeSpec(
-        id="greeter",
-        name="Greeter",
-        description="Generates a simple greeting",
-        node_type="event_loop",
-        input_keys=["name"],
-        output_keys=["greeting"],
-    )
-
-    node2 = NodeSpec(
-        id="uppercaser",
-        name="Uppercaser",
-        description="Converts greeting to uppercase",
-        node_type="event_loop",
-        input_keys=["greeting"],
-        output_keys=["final_greeting"],
-    )
-
-    # 4. Define Edges
-    # Edges define the flow between nodes
-    edge1 = EdgeSpec(
-        id="greet-to-upper",
-        source="greeter",
-        target="uppercaser",
-        condition=EdgeCondition.ON_SUCCESS,
-    )
-
-    # 5. Create Graph
-    # The graph works like a blueprint connecting nodes and edges
-    graph = GraphSpec(
-        id="greeting-agent",
-        goal_id="greet-user",
-        entry_node="greeter",
-        terminal_nodes=["uppercaser"],
-        nodes=[node1, node2],
-        edges=[edge1],
-    )
-
-    # 6. Initialize Runtime & Executor
-    # Runtime handles state/memory; Executor runs the graph
-    from pathlib import Path
-
-    runtime = Runtime(storage_path=Path("./agent_logs"))
-    executor = GraphExecutor(runtime=runtime)
-
-    # 7. Register Node Implementations
-    # Connect node IDs in the graph to actual Python implementations
-    executor.register_node("greeter", GreeterNode())
-    executor.register_node("uppercaser", UppercaserNode())
-
-    # 8. Execute Agent
-    print("Executing agent with input: name='Alice'...")
-
-    result = await executor.execute(graph=graph, goal=goal, input_data={"name": "Alice"})
-
-    # 9. Verify Results
-    if result.success:
-        print("\nSuccess!")
-        print(f"Path taken: {' -> '.join(result.path)}")
-        print(f"Final output: {result.output.get('final_greeting')}")
-    else:
-        print(f"\nFailed: {result.error}")
-
-
-if __name__ == "__main__":
-    # Optional: Enable logging to see internal decision flow
-    # logging.basicConfig(level=logging.INFO)
-    asyncio.run(main())

core/examples/mcp_integration_example.py

@@ -1,119 +0,0 @@
-#!/usr/bin/env python3
-"""
-Example: Integrating MCP Servers with the Core Framework
-
-This example demonstrates how to:
-1. Register MCP servers programmatically
-2. Use MCP tools in agents
-3. Load MCP servers from configuration files
-"""
-
-import asyncio
-from pathlib import Path
-
-from framework.runner.runner import AgentRunner
-
-
-async def example_1_programmatic_registration():
-    """Example 1: Register MCP server programmatically"""
-    print("\n=== Example 1: Programmatic MCP Server Registration ===\n")
-
-    # Load an existing agent
-    runner = AgentRunner.load("exports/task-planner")
-
-    # Register tools MCP server via STDIO
-    num_tools = runner.register_mcp_server(
-        name="tools",
-        transport="stdio",
-        command="python",
-        args=["-m", "aden_tools.mcp_server", "--stdio"],
-        cwd="../tools",
-    )
-
-    print(f"Registered {num_tools} tools from tools MCP server")
-
-    # List all available tools
-    tools = runner._tool_registry.get_tools()
-    print(f"\nAvailable tools: {list(tools.keys())}")
-
-    # Run the agent with MCP tools available
-    result = await runner.run(
-        {"objective": "Search for 'Claude AI' and summarize the top 3 results"}
-    )
-
-    print(f"\nAgent result: {result}")
-
-    # Cleanup
-    runner.cleanup()
-
-
-async def example_2_http_transport():
-    """Example 2: Connect to MCP server via HTTP"""
-    print("\n=== Example 2: HTTP MCP Server Connection ===\n")
-
-    # First, start the tools MCP server in HTTP mode:
-    # cd tools && python mcp_server.py --port 4001
-
-    runner = AgentRunner.load("exports/task-planner")
-
-    # Register tools via HTTP
-    num_tools = runner.register_mcp_server(
-        name="tools-http",
-        transport="http",
-        url="http://localhost:4001",
-    )
-
-    print(f"Registered {num_tools} tools from HTTP MCP server")
-
-    # Cleanup
-    runner.cleanup()
-
-
-async def example_3_config_file():
-    """Example 3: Load MCP servers from configuration file"""
-    print("\n=== Example 3: Load from Configuration File ===\n")
-
-    # Create a test agent folder with mcp_servers.json
-    test_agent_path = Path("exports/task-planner")
-
-    # Copy example config (in practice, you'd place this in your agent folder)
-    import shutil
-
-    shutil.copy("examples/mcp_servers.json", test_agent_path / "mcp_servers.json")
-
-    # Load agent - MCP servers will be auto-discovered
-    runner = AgentRunner.load(test_agent_path)
-
-    # Tools are automatically available
-    tools = runner._tool_registry.get_tools()
-    print(f"Available tools: {list(tools.keys())}")
-
-    # Cleanup
-    runner.cleanup()
-
-    # Clean up the test config
-    (test_agent_path / "mcp_servers.json").unlink()
-
-
-async def main():
-    """Run all examples"""
-    print("=" * 60)
-    print("MCP Integration Examples")
-    print("=" * 60)
-
-    try:
-        # Run examples
-        await example_1_programmatic_registration()
-        # await example_2_http_transport()  # Requires HTTP server running
-        # await example_3_config_file()
-        # await example_4_custom_agent_with_mcp_tools()
-
-    except Exception as e:
-        print(f"\nError running example: {e}")
-        import traceback
-
-        traceback.print_exc()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

core/framework/__init__.py

@@ -1,70 +1,20 @@
-"""
-Aden Hive Framework: A goal-driven agent runtime optimized for Builder observability.
+"""Hive Agent Framework.
 
-The runtime is designed around DECISIONS, not just actions. Every significant
-choice the agent makes is captured with:
-- What it was trying to do (intent)
-- What options it considered
-- What it chose and why
-- What happened as a result
-- Whether that was good or bad (evaluated post-hoc)
-
-This gives the Builder LLM the information it needs to improve agent behavior.
-
-## Testing Framework
-
-The framework includes a Goal-Based Testing system (Goal → Agent → Eval):
-- Generate tests from Goal success_criteria and constraints
-- Mandatory user approval before tests are stored
-- Parallel test execution with error categorization
-- Debug tools with fix suggestions
-
-See `framework.testing` for details.
+Core classes:
+    ColonyRuntime -- orchestrates parallel worker clones in a colony
+    AgentLoop      -- the LLM + tool execution loop (one per worker)
+    AgentLoader    -- loads agent config from disk, builds pipeline
+    DecisionTracker -- records decisions for post-hoc analysis
 """
 
-from framework.builder.query import BuilderQuery
-from framework.llm import AnthropicProvider, LLMProvider
-from framework.runner import AgentOrchestrator, AgentRunner
-from framework.runtime.core import Runtime
-from framework.schemas.decision import Decision, DecisionEvaluation, Option, Outcome
-from framework.schemas.run import Problem, Run, RunSummary
-
-# Testing framework
-from framework.testing import (
-    ApprovalStatus,
-    DebugTool,
-    ErrorCategory,
-    Test,
-    TestResult,
-    TestStorage,
-    TestSuiteResult,
-)
+from framework.agent_loop import AgentLoop
+from framework.host import ColonyRuntime
+from framework.loader import AgentLoader
+from framework.tracker import DecisionTracker
 
 __all__ = [
-    # Schemas
-    "Decision",
-    "Option",
-    "Outcome",
-    "DecisionEvaluation",
-    "Run",
-    "RunSummary",
-    "Problem",
-    # Runtime
-    "Runtime",
-    # Builder
-    "BuilderQuery",
-    # LLM
-    "LLMProvider",
-    "AnthropicProvider",
-    # Runner
-    "AgentRunner",
-    "AgentOrchestrator",
-    # Testing
-    "Test",
-    "TestResult",
-    "TestSuiteResult",
-    "TestStorage",
-    "ApprovalStatus",
-    "ErrorCategory",
-    "DebugTool",
+    "ColonyRuntime",
+    "AgentLoader",
+    "AgentLoop",
+    "DecisionTracker",
 ]

core/framework/agent_loop/__init__.py

@@ -0,0 +1,34 @@
+"""Agent loop -- the core agent execution primitive."""
+
+from framework.agent_loop.conversation import (  # noqa: F401
+    ConversationStore,
+    Message,
+    NodeConversation,
+)
+from framework.agent_loop.types import (  # noqa: F401
+    AgentContext,
+    AgentProtocol,
+    AgentResult,
+    AgentSpec,
+)
+
+
+def __getattr__(name: str):
+    if name in ("AgentLoop", "JudgeProtocol", "JudgeVerdict", "LoopConfig", "OutputAccumulator"):
+        from framework.agent_loop.agent_loop import (
+            AgentLoop,
+            JudgeProtocol,
+            JudgeVerdict,
+            LoopConfig,
+            OutputAccumulator,
+        )
+
+        _exports = {
+            "AgentLoop": AgentLoop,
+            "JudgeProtocol": JudgeProtocol,
+            "JudgeVerdict": JudgeVerdict,
+            "LoopConfig": LoopConfig,
+            "OutputAccumulator": OutputAccumulator,
+        }
+        return _exports[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

core/framework/agent_loop/conversation.py

@@ -3,11 +3,20 @@
 from __future__ import annotations
 
 import json
+import logging
 import re
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Literal, Protocol, runtime_checkable
 
+LEGACY_RUN_ID = "__legacy_run__"
+logger = logging.getLogger(__name__)
+
+
+def is_legacy_run_id(run_id: str | None) -> bool:
+    """True when run_id represents pre-migration (no run boundary) data."""
+    return run_id is None or run_id == LEGACY_RUN_ID
+
 
 @dataclass
 class Message:
@@ -33,20 +42,44 @@ class Message:
     is_transition_marker: bool = False
     # True when this message is real human input (from /chat), not a system prompt
     is_client_input: bool = False
+    # Optional image content blocks (e.g. from browser_screenshot)
+    image_content: list[dict[str, Any]] | None = None
+    # True when message contains an activated skill body (AS-10: never prune)
+    is_skill_content: bool = False
+    # Logical worker run identifier for shared-session persistence
+    run_id: str | None = None
 
     def to_llm_dict(self) -> dict[str, Any]:
         """Convert to OpenAI-format message dict."""
         if self.role == "user":
+            if self.image_content:
+                blocks: list[dict[str, Any]] = []
+                if self.content:
+                    blocks.append({"type": "text", "text": self.content})
+                blocks.extend(self.image_content)
+                return {"role": "user", "content": blocks}
             return {"role": "user", "content": self.content}
 
         if self.role == "assistant":
-            d: dict[str, Any] = {"role": "assistant", "content": self.content}
+            d: dict[str, Any] = {"role": "assistant"}
             if self.tool_calls:
                 d["tool_calls"] = self.tool_calls
+                d["content"] = self.content if self.content else None
+            else:
+                d["content"] = self.content or ""
             return d
 
         # role == "tool"
         content = f"ERROR: {self.content}" if self.is_error else self.content
+        if self.image_content:
+            # Multimodal tool result: text + image content blocks
+            blocks: list[dict[str, Any]] = [{"type": "text", "text": content}]
+            blocks.extend(self.image_content)
+            return {
+                "role": "tool",
+                "tool_call_id": self.tool_use_id,
+                "content": blocks,
+            }
         return {
             "role": "tool",
             "tool_call_id": self.tool_use_id,
@@ -72,6 +105,10 @@ class Message:
             d["is_transition_marker"] = self.is_transition_marker
         if self.is_client_input:
             d["is_client_input"] = self.is_client_input
+        if self.image_content is not None:
+            d["image_content"] = self.image_content
+        if self.run_id is not None:
+            d["run_id"] = self.run_id
         return d
 
     @classmethod
@@ -87,9 +124,41 @@ class Message:
             phase_id=data.get("phase_id"),
             is_transition_marker=data.get("is_transition_marker", False),
             is_client_input=data.get("is_client_input", False),
+            image_content=data.get("image_content"),
+            run_id=data.get("run_id"),
         )
 
 
+def _normalize_cursor(cursor: dict[str, Any] | None) -> dict[str, Any]:
+    """Normalize legacy and run-scoped cursor formats into one flat shape."""
+    return dict(cursor) if cursor else {}
+
+
+def get_cursor_next_seq(cursor: dict[str, Any] | None) -> int | None:
+    next_seq = (cursor or {}).get("next_seq")
+    return next_seq if isinstance(next_seq, int) else None
+
+
+def update_cursor_next_seq(cursor: dict[str, Any] | None, next_seq: int) -> dict[str, Any]:
+    updated = dict(cursor or {})
+    updated["next_seq"] = next_seq
+    return updated
+
+
+def get_run_cursor(cursor: dict[str, Any] | None, run_id: str | None) -> dict[str, Any] | None:
+    return dict(cursor) if cursor else None
+
+
+def update_run_cursor(
+    cursor: dict[str, Any] | None,
+    run_id: str | None,
+    values: dict[str, Any],
+) -> dict[str, Any]:
+    updated = dict(cursor or {})
+    updated.update(values)
+    return updated
+
+
 def _extract_spillover_filename(content: str) -> str | None:
     """Extract spillover filename from a tool result annotation.
 
@@ -169,8 +238,8 @@ def extract_tool_call_history(messages: list[Message], max_entries: int = 30) ->
             return args.get("query", "")
         if name == "web_scrape":
             return args.get("url", "")
-        if name in ("load_data", "save_data"):
-            return args.get("filename", "")
+        if name == "read_file":
+            return args.get("path", "")
         return ""
 
     for msg in messages:
@@ -186,8 +255,8 @@ def extract_tool_call_history(messages: list[Message], max_entries: int = 30) ->
                 summary = _summarize_input(name, args)
                 tool_calls_detail.setdefault(name, []).append(summary)
 
-                if name == "save_data" and args.get("filename"):
-                    files_saved.append(args["filename"])
+                if name == "read_file" and args.get("path"):
+                    files_saved.append(args["path"])
                 if name == "set_output" and args.get("key"):
                     outputs_set.append(args["key"])
 
@@ -239,7 +308,7 @@ class ConversationStore(Protocol):
 
     async def read_cursor(self) -> dict[str, Any] | None: ...
 
-    async def delete_parts_before(self, seq: int) -> None: ...
+    async def delete_parts_before(self, seq: int, run_id: str | None = None) -> None: ...
 
     async def close(self) -> None: ...
 
@@ -260,7 +329,7 @@ def _try_extract_key(content: str, key: str) -> str | None:
     3. Colon format: ``key: value``.
     4. Equals format: ``key = value``.
     """
-    from framework.graph.node import find_json_object
+    from framework.orchestrator.node import find_json_object
 
     # 1. Whole message is JSON
     try:
@@ -307,14 +376,25 @@ 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,
+        run_id: str | None = None,
+        compaction_buffer_tokens: int | None = None,
+        compaction_warning_buffer_tokens: int | 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
+        # Buffer-based compaction trigger (Gap 7). When set, takes
+        # precedence over the multiplicative compaction_threshold so the
+        # loop reserves a fixed headroom for the next turn's input+output
+        # instead of trying to get exactly X% of the way to the hard
+        # limit. If left as None the legacy threshold-based rule is
+        # used, keeping old call sites behaving identically.
+        self._compaction_buffer_tokens = compaction_buffer_tokens
+        self._compaction_warning_buffer_tokens = compaction_warning_buffer_tokens
         self._output_keys = output_keys
         self._store = store
         self._messages: list[Message] = []
@@ -322,6 +402,7 @@ class NodeConversation:
         self._meta_persisted: bool = False
         self._last_api_input_tokens: int | None = None
         self._current_phase: str | None = None
+        self._run_id: str | None = run_id
 
     # --- Properties --------------------------------------------------------
 
@@ -373,17 +454,23 @@ class NodeConversation:
         *,
         is_transition_marker: bool = False,
         is_client_input: bool = False,
+        image_content: list[dict[str, Any]] | None = None,
     ) -> Message:
         msg = Message(
             seq=self._next_seq,
             role="user",
             content=content,
             phase_id=self._current_phase,
+            run_id=self._run_id,
             is_transition_marker=is_transition_marker,
             is_client_input=is_client_input,
+            image_content=image_content,
         )
         self._messages.append(msg)
         self._next_seq += 1
+        # Invalidate stale API token count so estimate_tokens() uses
+        # the char-based heuristic which reflects the new message.
+        self._last_api_input_tokens = None
         await self._persist(msg)
         return msg
 
@@ -398,9 +485,11 @@ class NodeConversation:
             content=content,
             tool_calls=tool_calls,
             phase_id=self._current_phase,
+            run_id=self._run_id,
         )
         self._messages.append(msg)
         self._next_seq += 1
+        self._last_api_input_tokens = None
         await self._persist(msg)
         return msg
 
@@ -409,7 +498,30 @@ class NodeConversation:
         tool_use_id: str,
         content: str,
         is_error: bool = False,
+        image_content: list[dict[str, Any]] | None = None,
+        is_skill_content: bool = False,
     ) -> Message:
+        # Dedup guard: reject a second tool_result for the same tool_use_id.
+        # Anthropic's API only accepts one result per tool_call, and a duplicate
+        # causes a hard 400 two turns later ("messages with role 'tool' must
+        # be a response to a preceding message with 'tool_calls'"). Duplicates
+        # can arise when a tool_call_timeout fires and records a placeholder
+        # error, then the real executor thread eventually delivers the actual
+        # result (the thread kept running inside run_in_executor — see
+        # tool_result_handler.execute_tool).  We keep the FIRST result to
+        # preserve whatever state the agent already reasoned about.
+        for existing in reversed(self._messages):
+            if existing.role == "tool" and existing.tool_use_id == tool_use_id:
+                import logging as _logging
+
+                _logging.getLogger(__name__).warning(
+                    "add_tool_result: dropping duplicate result for tool_use_id=%s "
+                    "(first result preserved, %d chars; new result ignored, %d chars)",
+                    tool_use_id,
+                    len(existing.content),
+                    len(content),
+                )
+                return existing
         msg = Message(
             seq=self._next_seq,
             role="tool",
@@ -417,9 +529,13 @@ class NodeConversation:
             tool_use_id=tool_use_id,
             is_error=is_error,
             phase_id=self._current_phase,
+            image_content=image_content,
+            is_skill_content=is_skill_content,
+            run_id=self._run_id,
         )
         self._messages.append(msg)
         self._next_seq += 1
+        self._last_api_input_tokens = None
         await self._persist(msg)
         return msg
 
@@ -433,7 +549,48 @@ class NodeConversation:
         can happen when a loop is cancelled mid-tool-execution.
         """
         msgs = [m.to_llm_dict() for m in self._messages]
-        return self._repair_orphaned_tool_calls(msgs)
+        msgs = self._repair_orphaned_tool_calls(msgs)
+        msgs = self._sanitize_for_api(msgs)
+        return msgs
+
+    @staticmethod
+    def _sanitize_for_api(msgs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Final pass: ensure message sequence is valid for strict APIs.
+
+        Rules:
+        1. No two consecutive messages with the same role (merge or drop)
+        2. Tool messages must have a tool_call_id
+        3. Assistant messages with tool_calls must have content=null, not ""
+        4. First message must not be 'tool' or 'assistant' (without prior context)
+        """
+        cleaned: list[dict[str, Any]] = []
+        for m in msgs:
+            role = m.get("role")
+
+            # Fix assistant content when tool_calls present
+            if role == "assistant" and m.get("tool_calls"):
+                if m.get("content") == "":
+                    m["content"] = None
+
+            # Drop tool messages without tool_call_id
+            if role == "tool" and not m.get("tool_call_id"):
+                continue
+
+            # Drop consecutive duplicate roles (merge user messages)
+            if cleaned and cleaned[-1].get("role") == role == "user":
+                prev_content = cleaned[-1].get("content", "")
+                curr_content = m.get("content", "")
+                if isinstance(prev_content, str) and isinstance(curr_content, str):
+                    cleaned[-1]["content"] = f"{prev_content}\n{curr_content}"
+                    continue
+
+            cleaned.append(m)
+
+        # Drop leading assistant/tool messages (no prior context)
+        while cleaned and cleaned[0].get("role") in ("assistant", "tool"):
+            cleaned.pop(0)
+
+        return cleaned
 
     @staticmethod
     def _repair_orphaned_tool_calls(
@@ -441,11 +598,18 @@ class NodeConversation:
     ) -> list[dict[str, Any]]:
         """Ensure tool_call / tool_result pairs are consistent.
 
-        1. **Orphaned tool results** (tool_result with no preceding tool_use)
-           are dropped.  This happens when compaction removes an assistant
-           message but leaves its tool-result messages behind.
-        2. **Orphaned tool calls** (tool_use with no following tool_result)
-           get a synthetic error result appended.  This happens when a loop
+        1. **Orphaned tool results** (tool_result with no matching tool_use
+           anywhere) are dropped.  Happens after compaction removes the
+           parent assistant message.
+        2. **Positionally orphaned tool results** (tool_result separated
+           from its parent by a non-tool message, e.g. a user injection)
+           are dropped.  The Anthropic API requires tool messages to
+           follow immediately after the assistant message that issued
+           the matching tool_call.
+        3. **Duplicate tool results** (same tool_call_id appearing more
+           than once) are dropped; only the first is kept.
+        4. **Orphaned tool calls** (tool_use with no following tool_result)
+           get a synthetic error result appended.  Happens when the loop
            is cancelled mid-tool-execution.
         """
         # Pass 1: collect all tool_call IDs from assistant messages so we
@@ -458,41 +622,75 @@ class NodeConversation:
                     if tc_id:
                         all_tool_call_ids.add(tc_id)
 
-        # Pass 2: build repaired list — drop orphaned tool results, patch
-        # missing tool results.
+        # Pass 2: build repaired list — drop orphaned tool results, drop
+        # positional orphans and duplicates, patch missing tool results.
+        #
+        # ``open_tool_calls`` holds the tool_call IDs we're still expecting
+        # results for: it's populated when we emit an assistant-with-tool_calls
+        # and drained as matching tool messages follow. Any tool message
+        # whose id is not currently open is positionally invalid and gets
+        # dropped — that closes the gap that caused the tool-after-user
+        # 400 errors.
         repaired: list[dict[str, Any]] = []
-        for i, m in enumerate(msgs):
-            # Drop tool-result messages whose tool_call_id has no matching
-            # tool_use in any assistant message (orphaned by compaction).
-            if m.get("role") == "tool":
-                tid = m.get("tool_call_id")
-                if tid and tid not in all_tool_call_ids:
-                    continue  # skip orphaned result
+        open_tool_calls: set[str] = set()
+        seen_tool_ids: set[str] = set()
+        for m in msgs:
+            role = m.get("role")
 
-            repaired.append(m)
-            tool_calls = m.get("tool_calls")
-            if m.get("role") != "assistant" or not tool_calls:
+            if role == "tool":
+                tid = m.get("tool_call_id")
+                # Drop tool results with no matching tool_use anywhere.
+                if not tid or tid not in all_tool_call_ids:
+                    continue
+                # Drop duplicates (same id appearing twice) — keep first.
+                if tid in seen_tool_ids:
+                    continue
+                # Drop positional orphans — tool messages whose parent
+                # assistant isn't the still-open assistant block.
+                if tid not in open_tool_calls:
+                    continue
+                open_tool_calls.discard(tid)
+                seen_tool_ids.add(tid)
+                repaired.append(m)
                 continue
-            # Collect IDs of tool results that follow this assistant message
-            answered: set[str] = set()
-            for j in range(i + 1, len(msgs)):
-                if msgs[j].get("role") == "tool":
-                    tid = msgs[j].get("tool_call_id")
-                    if tid:
-                        answered.add(tid)
-                else:
-                    break  # stop at first non-tool message
-            # Patch any missing results
-            for tc in tool_calls:
-                tc_id = tc.get("id")
-                if tc_id and tc_id not in answered:
+
+            # Any non-tool message closes the current assistant tool block.
+            # If the previous assistant left tool_calls unanswered, patch
+            # synthetic error results before emitting this message so the
+            # API sees a complete pairing.
+            if open_tool_calls:
+                for stale_id in list(open_tool_calls):
                     repaired.append(
                         {
                             "role": "tool",
-                            "tool_call_id": tc_id,
+                            "tool_call_id": stale_id,
                             "content": "ERROR: Tool execution was interrupted.",
                         }
                     )
+                    seen_tool_ids.add(stale_id)
+                open_tool_calls.clear()
+
+            repaired.append(m)
+
+            if role == "assistant":
+                for tc in m.get("tool_calls") or []:
+                    tc_id = tc.get("id")
+                    if tc_id and tc_id not in seen_tool_ids:
+                        open_tool_calls.add(tc_id)
+
+        # Tail: if the conversation ends with an assistant that issued
+        # tool_calls and no results followed, patch them so the next
+        # turn's first message can be a valid assistant/user response.
+        if open_tool_calls:
+            for stale_id in list(open_tool_calls):
+                repaired.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": stale_id,
+                        "content": "ERROR: Tool execution was interrupted.",
+                    }
+                )
+
         return repaired
 
     def estimate_tokens(self) -> int:
@@ -500,12 +698,15 @@ class NodeConversation:
 
         Uses actual API input token count when available (set via
         :meth:`update_token_count`), otherwise falls back to a
-        ``total_chars / 4`` heuristic that includes both message content
-        AND tool_call argument sizes.
+        character-based heuristic that includes message content, tool_call
+        arguments, and image blocks.  The heuristic applies a 4/3 safety
+        margin to avoid under-counting (inspired by Claude Code's compact
+        service).
         """
         if self._last_api_input_tokens is not None:
             return self._last_api_input_tokens
         total_chars = 0
+        image_tokens = 0
         for m in self._messages:
             total_chars += len(m.content)
             if m.tool_calls:
@@ -513,7 +714,11 @@ class NodeConversation:
                     func = tc.get("function", {})
                     total_chars += len(func.get("arguments", ""))
                     total_chars += len(func.get("name", ""))
-        return total_chars // 4
+            if m.image_content:
+                # Images/documents have a fixed token cost per block
+                image_tokens += len(m.image_content) * 2000
+        # Apply 4/3 safety margin to character-based estimate
+        return (total_chars * 4) // (3 * 4) + image_tokens
 
     def update_token_count(self, actual_input_tokens: int) -> None:
         """Store actual API input token count for more accurate compaction.
@@ -525,16 +730,45 @@ 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
+        """True when the conversation should be compacted before the
+        next LLM call.
+
+        Buffer-based rule (Gap 7): trigger when the current estimate
+        plus the configured buffer would exceed the hard context limit.
+        Prevents compaction from firing only AFTER we're already over
+        the wire and forced into a reactive binary-split pass.
+
+        When no buffer is configured, falls back to the multiplicative
+        threshold the old callers were built around.
+        """
+        if self._max_context_tokens <= 0:
+            return False
+        if self._compaction_buffer_tokens is not None:
+            budget = self._max_context_tokens - self._compaction_buffer_tokens
+            return self.estimate_tokens() >= max(0, budget)
+        return self.estimate_tokens() >= self._max_context_tokens * self._compaction_threshold
+
+    def compaction_warning(self) -> bool:
+        """True when the conversation has crossed the warning threshold
+        but not yet the hard compaction trigger.
+
+        Used by telemetry / UI to show a "context getting tight" hint
+        before a compaction pass actually runs. Returns False when no
+        warning buffer is configured (legacy behaviour).
+        """
+        if self._max_context_tokens <= 0 or self._compaction_warning_buffer_tokens is None:
+            return False
+        warn_at = self._max_context_tokens - self._compaction_warning_buffer_tokens
+        return self.estimate_tokens() >= max(0, warn_at)
 
     # --- Output-key extraction ---------------------------------------------
 
@@ -610,8 +844,15 @@ class NodeConversation:
                 continue
             if msg.is_error:
                 continue  # never prune errors
+            if msg.is_skill_content:
+                continue  # never prune activated skill instructions (AS-10)
             if msg.content.startswith("[Pruned tool result"):
                 continue  # already pruned
+            # Tiny results (set_output acks, confirmations) — pruning
+            # saves negligible space but makes the LLM think the call
+            # failed, causing costly retries.
+            if len(msg.content) < 100:
+                continue
 
             # Phase-aware: protect current phase messages
             if self._current_phase and msg.phase_id == self._current_phase:
@@ -639,7 +880,7 @@ class NodeConversation:
                 placeholder = (
                     f"[Pruned tool result: {orig_len} chars. "
                     f"Full data in '{spillover}'. "
-                    f"Use load_data('{spillover}') to retrieve.]"
+                    f"Use read_file('{spillover}') to retrieve.]"
                 )
             else:
                 placeholder = f"[Pruned tool result: {orig_len} chars cleared from context.]"
@@ -653,6 +894,7 @@ class NodeConversation:
                 is_error=msg.is_error,
                 phase_id=msg.phase_id,
                 is_transition_marker=msg.is_transition_marker,
+                run_id=msg.run_id,
             )
             count += 1
 
@@ -729,14 +971,14 @@ class NodeConversation:
             summary_seq = self._next_seq
             self._next_seq += 1
 
-        summary_msg = Message(seq=summary_seq, role="user", content=summary)
+        summary_msg = Message(seq=summary_seq, role="user", content=summary, run_id=self._run_id)
 
         # Persist
         if self._store:
             delete_before = recent_messages[0].seq if recent_messages else self._next_seq
             await self._store.delete_parts_before(delete_before)
             await self._store.write_part(summary_msg.seq, summary_msg.to_storage_dict())
-            await self._store.write_cursor({"next_seq": self._next_seq})
+            await self._write_next_seq()
 
         self._messages = [summary_msg] + recent_messages
         self._last_api_input_tokens = None  # reset; next LLM call will recalibrate
@@ -794,6 +1036,15 @@ class NodeConversation:
         freeform_lines: list[str] = []
         collapsed_msgs: list[Message] = []
 
+        # Collect all tool_use IDs present in old messages so we can detect
+        # orphaned tool results whose parent assistant message was already
+        # compacted away (API invariant protection).
+        old_tc_ids: set[str] = set()
+        for msg in old_messages:
+            if msg.tool_calls:
+                for tc in msg.tool_calls:
+                    old_tc_ids.add(tc.get("id", ""))
+
         if aggressive:
             # Aggressive: only keep set_output tool pairs and error results.
             # Everything else is collapsed into a tool-call history summary.
@@ -815,9 +1066,17 @@ class NodeConversation:
                 else:
                     collapsible_tc_ids |= tc_ids
 
+            # Skill content and transition markers are always protected
+            for msg in old_messages:
+                if msg.role == "tool" and msg.is_skill_content and msg.tool_use_id:
+                    protected_tc_ids.add(msg.tool_use_id)
+
             # Second pass: classify all messages
             for msg in old_messages:
-                if msg.role == "tool":
+                if msg.is_transition_marker:
+                    # Transition markers are always kept (phase boundaries)
+                    kept_structural.append(msg)
+                elif msg.role == "tool":
                     tc_id = msg.tool_use_id or ""
                     if tc_id in protected_tc_ids:
                         kept_structural.append(msg)
@@ -826,6 +1085,12 @@ class NodeConversation:
                         kept_structural.append(msg)
                         # Protect the parent assistant message too
                         protected_tc_ids.add(tc_id)
+                    elif msg.is_skill_content:
+                        kept_structural.append(msg)
+                    elif tc_id and tc_id not in old_tc_ids:
+                        # Orphaned tool result — parent tool_use not in old msgs.
+                        # Keep it to maintain API invariants.
+                        kept_structural.append(msg)
                     else:
                         collapsed_msgs.append(msg)
                 elif msg.role == "assistant" and msg.tool_calls:
@@ -842,6 +1107,7 @@ class NodeConversation:
                                 is_error=msg.is_error,
                                 phase_id=msg.phase_id,
                                 is_transition_marker=msg.is_transition_marker,
+                                run_id=msg.run_id,
                             )
                         )
                     else:
@@ -856,7 +1122,10 @@ class NodeConversation:
         else:
             # Standard mode: keep all tool call pairs as structural
             for msg in old_messages:
-                if msg.role == "tool":
+                if msg.is_transition_marker:
+                    # Transition markers are always kept (phase boundaries)
+                    kept_structural.append(msg)
+                elif msg.role == "tool":
                     kept_structural.append(msg)
                 elif msg.role == "assistant" and msg.tool_calls:
                     compact_tcs = _compact_tool_calls(msg.tool_calls)
@@ -869,6 +1138,7 @@ class NodeConversation:
                             is_error=msg.is_error,
                             phase_id=msg.phase_id,
                             is_transition_marker=msg.is_transition_marker,
+                            run_id=msg.run_id,
                         )
                     )
                 else:
@@ -901,8 +1171,7 @@ class NodeConversation:
             full_path = str((spill_path / conv_filename).resolve())
             ref_parts.append(
                 f"[Previous conversation saved to '{full_path}'. "
-                f"Use load_data('{conv_filename}'), read_file('{full_path}'), "
-                f"or run_command('cat \"{full_path}\"') to review if needed.]"
+                f"Use read_file('{conv_filename}') to review if needed.]"
             )
         elif not collapsed_msgs:
             ref_parts.append("[Previous freeform messages compacted.]")
@@ -927,7 +1196,7 @@ class NodeConversation:
             ref_seq = self._next_seq
             self._next_seq += 1
 
-        ref_msg = Message(seq=ref_seq, role="user", content=ref_content)
+        ref_msg = Message(seq=ref_seq, role="user", content=ref_content, run_id=self._run_id)
 
         # Persist: delete old messages from store, write reference + kept structural.
         # In aggressive mode, collapsed messages may be interspersed with kept
@@ -941,7 +1210,7 @@ class NodeConversation:
             # Write kept structural messages (they may have been modified)
             for msg in kept_structural:
                 await self._store.write_part(msg.seq, msg.to_storage_dict())
-            await self._store.write_cursor({"next_seq": self._next_seq})
+            await self._write_next_seq()
 
         # Reassemble: reference + kept structural (in original order) + recent
         self._messages = [ref_msg] + kept_structural + recent_messages
@@ -978,7 +1247,7 @@ class NodeConversation:
         """Remove all messages, keep system prompt, preserve ``_next_seq``."""
         if self._store:
             await self._store.delete_parts_before(self._next_seq)
-            await self._store.write_cursor({"next_seq": self._next_seq})
+            await self._write_next_seq()
         self._messages.clear()
         self._last_api_input_tokens = None
 
@@ -1020,22 +1289,36 @@ class NodeConversation:
         if not self._meta_persisted:
             await self._persist_meta()
         await self._store.write_part(message.seq, message.to_storage_dict())
-        await self._store.write_cursor({"next_seq": self._next_seq})
+        await self._write_next_seq()
 
     async def _persist_meta(self) -> None:
-        """Lazily write conversation metadata to the store (called once)."""
+        """Lazily write conversation metadata to the store (called once).
+
+        When ``self._run_id`` is set, metadata is written flat for backward
+        compatibility (run-scoped isolation has been reverted).
+        """
         if self._store is None:
             return
-        await self._store.write_meta(
-            {
-                "system_prompt": self._system_prompt,
-                "max_history_tokens": self._max_history_tokens,
-                "compaction_threshold": self._compaction_threshold,
-                "output_keys": self._output_keys,
-            }
-        )
+        run_meta = {
+            "system_prompt": self._system_prompt,
+            "max_context_tokens": self._max_context_tokens,
+            "compaction_threshold": self._compaction_threshold,
+            "compaction_buffer_tokens": self._compaction_buffer_tokens,
+            "compaction_warning_buffer_tokens": (
+                self._compaction_warning_buffer_tokens
+            ),
+            "output_keys": self._output_keys,
+        }
+        await self._store.write_meta(run_meta)
         self._meta_persisted = True
 
+    async def _write_next_seq(self) -> None:
+        if self._store is None:
+            return
+        cursor = await self._store.read_cursor() or {}
+        cursor["next_seq"] = self._next_seq
+        await self._store.write_cursor(cursor)
+
     # --- Restore -----------------------------------------------------------
 
     @classmethod
@@ -1043,6 +1326,7 @@ class NodeConversation:
         cls,
         store: ConversationStore,
         phase_id: str | None = None,
+        run_id: str | None = None,
     ) -> NodeConversation | None:
         """Reconstruct a NodeConversation from a store.
 
@@ -1052,6 +1336,9 @@ class NodeConversation:
                 Used in isolated mode so a node only sees its own
                 messages in the shared flat store.  In continuous mode
                 pass ``None`` to load all parts.
+            run_id: If set, only load parts matching this run_id.
+                Ensures intentional restarts (new run_id) start fresh
+                while crash recovery (same run_id) resumes correctly.
 
         Returns ``None`` if the store contains no metadata (i.e. the
         conversation was never persisted).
@@ -1062,21 +1349,45 @@ 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,
+            run_id=run_id,
+            compaction_buffer_tokens=meta.get("compaction_buffer_tokens"),
+            compaction_warning_buffer_tokens=meta.get(
+                "compaction_warning_buffer_tokens"
+            ),
         )
         conv._meta_persisted = True
 
         parts = await store.read_parts()
         if phase_id:
-            parts = [p for p in parts if p.get("phase_id") == phase_id]
+            filtered_parts = [p for p in parts if p.get("phase_id") == phase_id]
+            if filtered_parts:
+                parts = filtered_parts
+            elif parts and all(p.get("phase_id") is None for p in parts):
+                # Backward compatibility: older isolated stores (including queen
+                # sessions) persisted parts without phase_id. In that case, the
+                # phase filter would incorrectly hide the entire conversation.
+                logger.info(
+                    "Restoring legacy unphased conversation without applying "
+                    "phase filter (phase_id=%s, parts=%d)",
+                    phase_id,
+                    len(parts),
+                )
+            else:
+                parts = filtered_parts
+        # Filter by run_id so intentional restarts (new run_id) start fresh
+        # while crash recovery (same run_id) loads prior parts.
+        if run_id and not is_legacy_run_id(run_id):
+            parts = [p for p in parts if p.get("run_id") == run_id]
         conv._messages = [Message.from_storage_dict(p) for p in parts]
 
         cursor = await store.read_cursor()
-        if cursor:
-            conv._next_seq = cursor["next_seq"]
+        next_seq = get_cursor_next_seq(cursor)
+        if next_seq is not None:
+            conv._next_seq = next_seq
         elif conv._messages:
             conv._next_seq = conv._messages[-1].seq + 1
 

core/framework/agent_loop/internals/__init__.py

@@ -0,0 +1,7 @@
+"""Agent loop internals -- compaction, judge, tools, subagent execution.
+
+Re-exports from legacy locations for the new import path.
+"""
+
+from framework.agent_loop.internals.compaction import *  # noqa: F401, F403
+from framework.agent_loop.internals.synthetic_tools import *  # noqa: F401, F403

core/framework/agent_loop/internals/compaction.py

@@ -0,0 +1,871 @@
+"""Conversation compaction pipeline.
+
+Implements the multi-level compaction strategy:
+0. Microcompaction (count-based tool result clearing — cheapest)
+1. Prune old tool results (token-budget based)
+2. Structure-preserving compaction (spillover)
+3. LLM summary compaction (with recursive splitting)
+4. Emergency deterministic summary (no LLM)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from framework.agent_loop.conversation import Message, NodeConversation
+from framework.agent_loop.internals.event_publishing import publish_context_usage
+from framework.agent_loop.internals.types import LoopConfig, OutputAccumulator
+from framework.host.event_bus import EventBus
+from framework.orchestrator.node import NodeContext
+
+logger = logging.getLogger(__name__)
+
+# Limits for LLM compaction
+LLM_COMPACT_CHAR_LIMIT: int = 240_000
+LLM_COMPACT_MAX_DEPTH: int = 10
+
+# Microcompaction: tools whose results can be safely cleared
+COMPACTABLE_TOOLS: frozenset[str] = frozenset(
+    {
+        "read_file",
+        "run_command",
+        "web_search",
+        "web_fetch",
+        "grep_search",
+        "glob_search",
+        "write_file",
+        "edit_file",
+        "browser_screenshot",
+        "list_directory",
+    }
+)
+
+# Keep at most this many compactable tool results; clear older ones
+MICROCOMPACT_KEEP_RECENT: int = 8
+
+# Circuit-breaker: stop auto-compacting after this many consecutive failures
+MAX_CONSECUTIVE_FAILURES: int = 3
+
+# Track consecutive compaction failures per conversation (module-level)
+_failure_counts: dict[int, int] = {}
+
+# Track last compaction time per conversation for recompaction detection
+_last_compact_times: dict[int, float] = {}
+
+
+def microcompact(
+    conversation: NodeConversation,
+    *,
+    keep_recent: int = MICROCOMPACT_KEEP_RECENT,
+) -> int:
+    """Clear old compactable tool results by count, keeping only the most recent.
+
+    This is the cheapest possible compaction — no LLM call, no structural
+    changes, just replaces old tool result content with a short placeholder.
+    Inspired by Claude Code's cached-microcompact strategy.
+
+    Returns the number of tool results cleared.
+    """
+    # Collect indices of compactable tool results (newest first)
+    compactable_indices: list[int] = []
+    messages = conversation.messages
+    for i in range(len(messages) - 1, -1, -1):
+        msg = messages[i]
+        if msg.role != "tool" or msg.is_error or msg.is_skill_content:
+            continue
+        if msg.content.startswith(("[Pruned tool result", "[Old tool result")):
+            continue
+        if len(msg.content) < 100:
+            continue
+
+        # Check if the tool that produced this result is compactable
+        tool_name = _find_tool_name_for_result(messages, msg)
+        if tool_name and tool_name in COMPACTABLE_TOOLS:
+            compactable_indices.append(i)
+
+    # Keep the most recent N, clear the rest
+    to_clear = compactable_indices[keep_recent:]
+    if not to_clear:
+        return 0
+
+    cleared = 0
+    for i in to_clear:
+        msg = messages[i]
+        spillover = _extract_spillover_filename_inline(msg.content)
+        orig_len = len(msg.content)
+        if spillover:
+            placeholder = (
+                f"[Old tool result cleared: {orig_len} chars. "
+                f"Full data in '{spillover}'. "
+                f"Use read_file('{spillover}') to retrieve.]"
+            )
+        else:
+            placeholder = f"[Old tool result cleared: {orig_len} chars.]"
+
+        # Mutate in-place (microcompact is synchronous, no store writes)
+        conversation._messages[i] = Message(
+            seq=msg.seq,
+            role=msg.role,
+            content=placeholder,
+            tool_use_id=msg.tool_use_id,
+            tool_calls=msg.tool_calls,
+            is_error=msg.is_error,
+            phase_id=msg.phase_id,
+            is_transition_marker=msg.is_transition_marker,
+        )
+        cleared += 1
+
+    if cleared > 0:
+        # Invalidate cached token count
+        conversation._last_api_input_tokens = None
+
+    return cleared
+
+
+def _find_tool_name_for_result(messages: list[Message], tool_msg: Message) -> str | None:
+    """Find the tool name from the assistant message that triggered this tool result."""
+    if not tool_msg.tool_use_id:
+        return None
+    for msg in messages:
+        if msg.tool_calls:
+            for tc in msg.tool_calls:
+                if tc.get("id") == tool_msg.tool_use_id:
+                    return tc.get("function", {}).get("name")
+    return None
+
+
+def _extract_spillover_filename_inline(content: str) -> str | None:
+    """Quick inline check for spillover filename in tool result content."""
+    match = re.search(r"saved to '([^']+)'", content, re.IGNORECASE)
+    return match.group(1) if match else None
+
+
+async def compact(
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    accumulator: OutputAccumulator | None,
+    *,
+    config: LoopConfig,
+    event_bus: EventBus | None,
+    char_limit: int = LLM_COMPACT_CHAR_LIMIT,
+    max_depth: int = LLM_COMPACT_MAX_DEPTH,
+) -> None:
+    """Run the full compaction pipeline if conversation needs compaction.
+
+    Pipeline stages (in order, short-circuits when budget is restored):
+    0. Microcompaction (count-based tool result clearing — cheapest)
+    1. Prune old tool results (token-budget based)
+    2. Structure-preserving compaction (free, no LLM)
+    3. LLM summary compaction (recursive split if too large)
+    4. Emergency deterministic summary (fallback)
+    """
+    conv_id = id(conversation)
+
+    # Circuit breaker: stop LLM-based compaction after repeated failures,
+    # but still fall through to the emergency deterministic summary so
+    # the conversation doesn't silently grow past the context window.
+    # Without this, a persistent LLM outage during compaction would
+    # leave the agent stuck sending oversized prompts until the API 400s.
+    _llm_compaction_skipped = _failure_counts.get(conv_id, 0) >= MAX_CONSECUTIVE_FAILURES
+    if _llm_compaction_skipped:
+        logger.warning(
+            "Circuit breaker: LLM compaction disabled after %d failures — "
+            "skipping straight to emergency summary",
+            _failure_counts[conv_id],
+        )
+
+    # Recompaction detection
+    now = time.monotonic()
+    last_time = _last_compact_times.get(conv_id)
+    if last_time is not None and (now - last_time) < 30:
+        logger.warning(
+            "Recompaction chain detected: only %.1fs since last compaction",
+            now - last_time,
+        )
+
+    ratio_before = conversation.usage_ratio()
+    phase_grad = getattr(ctx, "continuous_mode", False)
+    pre_inventory: list[dict[str, Any]] | None = None
+
+    if ratio_before >= 1.0:
+        pre_inventory = build_message_inventory(conversation)
+
+    # --- Step 0: Microcompaction (count-based, cheapest) ---
+    mc_cleared = microcompact(conversation)
+    if mc_cleared > 0:
+        logger.info(
+            "Microcompact cleared %d old tool results: %.0f%% -> %.0f%%",
+            mc_cleared,
+            ratio_before * 100,
+            conversation.usage_ratio() * 100,
+        )
+    if not conversation.needs_compaction():
+        _record_success(conv_id, now)
+        await log_compaction(
+            ctx,
+            conversation,
+            ratio_before,
+            event_bus,
+            pre_inventory=pre_inventory,
+        )
+        return
+
+    # --- Step 1: Prune old tool results (free, fast) ---
+    protect = max(2000, config.max_context_tokens // 12)
+    pruned = await conversation.prune_old_tool_results(
+        protect_tokens=protect,
+        min_prune_tokens=max(1000, protect // 3),
+    )
+    if pruned > 0:
+        logger.info(
+            "Pruned %d old tool results: %.0f%% -> %.0f%%",
+            pruned,
+            ratio_before * 100,
+            conversation.usage_ratio() * 100,
+        )
+    if not conversation.needs_compaction():
+        _record_success(conv_id, now)
+        await log_compaction(
+            ctx,
+            conversation,
+            ratio_before,
+            event_bus,
+            pre_inventory=pre_inventory,
+        )
+        return
+
+    # --- Step 2: Standard structure-preserving compaction (free, no LLM) ---
+    spill_dir = config.spillover_dir
+    if spill_dir:
+        await conversation.compact_preserving_structure(
+            spillover_dir=spill_dir,
+            keep_recent=4,
+            phase_graduated=phase_grad,
+        )
+    if not conversation.needs_compaction():
+        _record_success(conv_id, now)
+        await log_compaction(
+            ctx,
+            conversation,
+            ratio_before,
+            event_bus,
+            pre_inventory=pre_inventory,
+        )
+        return
+
+    # --- Step 3: LLM summary compaction ---
+    if ctx.llm is not None and not _llm_compaction_skipped:
+        logger.info(
+            "LLM summary compaction triggered (%.0f%% usage)",
+            conversation.usage_ratio() * 100,
+        )
+        try:
+            summary = await llm_compact(
+                ctx,
+                list(conversation.messages),
+                accumulator,
+                char_limit=char_limit,
+                max_depth=max_depth,
+                max_context_tokens=config.max_context_tokens,
+            )
+            await conversation.compact(
+                summary,
+                keep_recent=2,
+                phase_graduated=phase_grad,
+            )
+        except Exception as e:
+            logger.warning("LLM compaction failed: %s", e)
+            _failure_counts[conv_id] = _failure_counts.get(conv_id, 0) + 1
+
+    if not conversation.needs_compaction():
+        _record_success(conv_id, now)
+        await log_compaction(
+            ctx,
+            conversation,
+            ratio_before,
+            event_bus,
+            pre_inventory=pre_inventory,
+        )
+        return
+
+    # --- Step 4: Emergency deterministic summary (LLM failed/unavailable) ---
+    logger.warning(
+        "Emergency compaction (%.0f%% usage)",
+        conversation.usage_ratio() * 100,
+    )
+    summary = build_emergency_summary(ctx, accumulator, conversation, config)
+    await conversation.compact(
+        summary,
+        keep_recent=1,
+        phase_graduated=phase_grad,
+    )
+    _record_success(conv_id, now)
+    await log_compaction(
+        ctx,
+        conversation,
+        ratio_before,
+        event_bus,
+        pre_inventory=pre_inventory,
+    )
+
+
+def _record_success(conv_id: int, timestamp: float) -> None:
+    """Reset failure counter and record compaction time on success."""
+    _failure_counts.pop(conv_id, None)
+    _last_compact_times[conv_id] = timestamp
+
+
+# --- LLM compaction with binary-search splitting ----------------------
+
+
+def strip_images_from_messages(messages: list[Message]) -> list[Message]:
+    """Strip image_content from messages before LLM summarisation.
+
+    Images/documents are replaced with ``[image]`` markers so the summary
+    notes they existed without wasting tokens sending binary data to the
+    compaction LLM.  Returns a new list (original messages are not mutated).
+    """
+    stripped: list[Message] = []
+    for msg in messages:
+        if msg.image_content:
+            n_images = len(msg.image_content)
+            marker = " ".join("[image]" for _ in range(n_images))
+            content = f"{msg.content}\n{marker}" if msg.content else marker
+            stripped.append(
+                Message(
+                    seq=msg.seq,
+                    role=msg.role,
+                    content=content,
+                    tool_use_id=msg.tool_use_id,
+                    tool_calls=msg.tool_calls,
+                    is_error=msg.is_error,
+                    phase_id=msg.phase_id,
+                    is_transition_marker=msg.is_transition_marker,
+                    image_content=None,  # stripped
+                )
+            )
+        else:
+            stripped.append(msg)
+    return stripped
+
+
+async def llm_compact(
+    ctx: NodeContext,
+    messages: list,
+    accumulator: OutputAccumulator | None = None,
+    _depth: int = 0,
+    *,
+    char_limit: int = LLM_COMPACT_CHAR_LIMIT,
+    max_depth: int = LLM_COMPACT_MAX_DEPTH,
+    max_context_tokens: int = 128_000,
+) -> str:
+    """Summarise *messages* with LLM, splitting recursively if too large.
+
+    If the formatted text exceeds ``LLM_COMPACT_CHAR_LIMIT`` or the LLM
+    rejects the call with a context-length error, the messages are split
+    in half and each half is summarised independently.  Tool history is
+    appended once at the top-level call (``_depth == 0``).
+    """
+    from framework.agent_loop.conversation import extract_tool_call_history
+    from framework.agent_loop.internals.tool_result_handler import is_context_too_large_error
+
+    if _depth > max_depth:
+        raise RuntimeError(f"LLM compaction recursion limit ({max_depth})")
+
+    # Strip images before summarisation to avoid wasting tokens
+    if _depth == 0:
+        messages = strip_images_from_messages(messages)
+
+    formatted = format_messages_for_summary(messages)
+
+    # Proactive split: avoid wasting an API call on oversized input
+    if len(formatted) > char_limit and len(messages) > 1:
+        summary = await _llm_compact_split(
+            ctx,
+            messages,
+            accumulator,
+            _depth,
+            char_limit=char_limit,
+            max_depth=max_depth,
+            max_context_tokens=max_context_tokens,
+        )
+    else:
+        prompt = build_llm_compaction_prompt(
+            ctx,
+            accumulator,
+            formatted,
+            max_context_tokens=max_context_tokens,
+        )
+        summary_budget = max(1024, max_context_tokens // 2)
+        try:
+            response = await ctx.llm.acomplete(
+                messages=[{"role": "user", "content": prompt}],
+                system=(
+                    "You are a conversation compactor for an AI agent. "
+                    "Write a detailed summary that allows the agent to "
+                    "continue its work. Preserve user-stated rules, "
+                    "constraints, and account/identity preferences verbatim."
+                ),
+                max_tokens=summary_budget,
+            )
+            summary = response.content
+        except Exception as e:
+            if is_context_too_large_error(e) and len(messages) > 1:
+                logger.info(
+                    "LLM context too large (depth=%d, msgs=%d) — splitting",
+                    _depth,
+                    len(messages),
+                )
+                summary = await _llm_compact_split(
+                    ctx,
+                    messages,
+                    accumulator,
+                    _depth,
+                    char_limit=char_limit,
+                    max_depth=max_depth,
+                    max_context_tokens=max_context_tokens,
+                )
+            else:
+                raise
+
+    # Append tool history at top level only
+    if _depth == 0:
+        tool_history = extract_tool_call_history(messages)
+        if tool_history and "TOOLS ALREADY CALLED" not in summary:
+            summary += "\n\n" + tool_history
+
+    return summary
+
+
+async def _llm_compact_split(
+    ctx: NodeContext,
+    messages: list,
+    accumulator: OutputAccumulator | None,
+    _depth: int,
+    *,
+    char_limit: int = LLM_COMPACT_CHAR_LIMIT,
+    max_depth: int = LLM_COMPACT_MAX_DEPTH,
+    max_context_tokens: int = 128_000,
+) -> str:
+    """Split messages in half and summarise each half independently."""
+    mid = max(1, len(messages) // 2)
+    s1 = await llm_compact(
+        ctx,
+        messages[:mid],
+        None,
+        _depth + 1,
+        char_limit=char_limit,
+        max_depth=max_depth,
+        max_context_tokens=max_context_tokens,
+    )
+    s2 = await llm_compact(
+        ctx,
+        messages[mid:],
+        accumulator,
+        _depth + 1,
+        char_limit=char_limit,
+        max_depth=max_depth,
+        max_context_tokens=max_context_tokens,
+    )
+    return s1 + "\n\n" + s2
+
+
+# --- Compaction helpers ------------------------------------------------
+
+
+def format_messages_for_summary(messages: list) -> str:
+    """Format messages as text for LLM summarisation."""
+    lines: list[str] = []
+    for m in messages:
+        if m.role == "tool":
+            content = m.content[:500]
+            if len(m.content) > 500:
+                content += "..."
+            lines.append(f"[tool result]: {content}")
+        elif m.role == "assistant" and m.tool_calls:
+            names = [tc.get("function", {}).get("name", "?") for tc in m.tool_calls]
+            text = m.content[:200] if m.content else ""
+            lines.append(f"[assistant (calls: {', '.join(names)})]: {text}")
+        else:
+            lines.append(f"[{m.role}]: {m.content}")
+    return "\n\n".join(lines)
+
+
+def build_llm_compaction_prompt(
+    ctx: NodeContext,
+    accumulator: OutputAccumulator | None,
+    formatted_messages: str,
+    *,
+    max_context_tokens: int = 128_000,
+) -> str:
+    """Build prompt for LLM compaction targeting 50% of token budget.
+
+    Uses a structured section format inspired by Claude Code's compact
+    service.  Each section focuses on a different aspect of the conversation
+    so the summariser produces consistently useful, well-organised output.
+    """
+    spec = ctx.agent_spec
+    ctx_lines = [f"NODE: {spec.name} (id={spec.id})"]
+    if spec.description:
+        ctx_lines.append(f"PURPOSE: {spec.description}")
+    if spec.success_criteria:
+        ctx_lines.append(f"SUCCESS CRITERIA: {spec.success_criteria}")
+
+    if accumulator:
+        acc = accumulator.to_dict()
+        done = {k: v for k, v in acc.items() if v is not None}
+        todo = [k for k, v in acc.items() if v is None]
+        if done:
+            ctx_lines.append(
+                "OUTPUTS ALREADY SET:\n"
+                + "\n".join(f"  {k}: {str(v)[:150]}" for k, v in done.items())
+            )
+        if todo:
+            ctx_lines.append(f"OUTPUTS STILL NEEDED: {', '.join(todo)}")
+    elif spec.output_keys:
+        ctx_lines.append(f"OUTPUTS STILL NEEDED: {', '.join(spec.output_keys)}")
+
+    target_tokens = max_context_tokens // 2
+    target_chars = target_tokens * 4
+    node_ctx = "\n".join(ctx_lines)
+
+    return (
+        "You are compacting an AI agent's conversation history. "
+        "The agent is still working and needs to continue.\n\n"
+        f"AGENT CONTEXT:\n{node_ctx}\n\n"
+        f"CONVERSATION MESSAGES:\n{formatted_messages}\n\n"
+        "INSTRUCTIONS:\n"
+        f"Write a summary of approximately {target_chars} characters "
+        f"(~{target_tokens} tokens).\n\n"
+        "Organise the summary into these sections (omit empty ones):\n\n"
+        "1. **Primary Request and Intent** — What the user originally asked "
+        "for and the high-level goal the agent is working toward.\n"
+        "2. **Key Technical Concepts** — Important domain-specific terms, "
+        "patterns, or architectural decisions established in the conversation.\n"
+        "3. **Files and Code Sections** — Specific files read/written/edited "
+        "with brief descriptions of changes. Include short code snippets only "
+        "when they capture critical logic.\n"
+        "4. **Errors and Fixes** — Problems encountered and how they were "
+        "resolved. Include root causes so the agent doesn't repeat them.\n"
+        "5. **Problem Solving Efforts** — Approaches tried, dead ends hit, "
+        "and reasoning behind the current strategy.\n"
+        "6. **User Messages** — Preserve ALL user-stated rules, constraints, "
+        "identity preferences, and account details verbatim.\n"
+        "7. **Pending Tasks** — Work remaining, outputs still needed, and "
+        "any blockers.\n"
+        "8. **Current Work** — The most recent action taken and the immediate "
+        "next step the agent should perform. This section is the most important "
+        "for seamless resumption.\n\n"
+        "Additional rules:\n"
+        "- Be detailed enough that the agent can resume without re-doing work.\n"
+        "- Preserve key decisions made and results obtained.\n"
+        "- When in doubt, keep information rather than discard it.\n"
+    )
+
+
+def build_message_inventory(conversation: NodeConversation) -> list[dict[str, Any]]:
+    """Build a per-message size inventory for debug logging."""
+    inventory: list[dict[str, Any]] = []
+    for message in conversation.messages:
+        content_chars = len(message.content)
+        tool_call_args_chars = 0
+        tool_name = None
+        if message.tool_calls:
+            for tool_call in message.tool_calls:
+                args = tool_call.get("function", {}).get("arguments", "")
+                tool_call_args_chars += (
+                    len(args) if isinstance(args, str) else len(json.dumps(args))
+                )
+            names = [
+                tool_call.get("function", {}).get("name", "?") for tool_call in message.tool_calls
+            ]
+            tool_name = ", ".join(names)
+        elif message.role == "tool" and message.tool_use_id:
+            for previous in conversation.messages:
+                if previous.tool_calls:
+                    for tool_call in previous.tool_calls:
+                        if tool_call.get("id") == message.tool_use_id:
+                            tool_name = tool_call.get("function", {}).get("name", "?")
+                            break
+                if tool_name:
+                    break
+        entry: dict[str, Any] = {
+            "seq": message.seq,
+            "role": message.role,
+            "content_chars": content_chars,
+        }
+        if tool_call_args_chars:
+            entry["tool_call_args_chars"] = tool_call_args_chars
+        if tool_name:
+            entry["tool"] = tool_name
+        if message.is_error:
+            entry["is_error"] = True
+        if message.phase_id:
+            entry["phase"] = message.phase_id
+        if content_chars > 2000:
+            entry["preview"] = message.content[:200] + "…"
+        inventory.append(entry)
+    return inventory
+
+
+def write_compaction_debug_log(
+    ctx: NodeContext,
+    before_pct: int,
+    after_pct: int,
+    level: str,
+    inventory: list[dict[str, Any]] | None,
+) -> None:
+    """Write detailed compaction analysis to ~/.hive/compaction_log/."""
+    log_dir = Path.home() / ".hive" / "compaction_log"
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    ts = datetime.now(UTC).strftime("%Y%m%dT%H%M%S_%f")
+    node_label = ctx.agent_id.replace("/", "_")
+    log_path = log_dir / f"{ts}_{node_label}.md"
+
+    lines: list[str] = [
+        f"# Compaction Debug — {ctx.agent_id}",
+        f"**Time:** {datetime.now(UTC).isoformat()}",
+        f"**Node:** {ctx.agent_spec.name} (`{ctx.agent_id}`)",
+    ]
+    if ctx.stream_id:
+        lines.append(f"**Stream:** {ctx.stream_id}")
+    lines.append(f"**Level:** {level}")
+    lines.append(f"**Usage:** {before_pct}% → {after_pct}%")
+    lines.append("")
+
+    if inventory:
+        total_chars = sum(
+            entry.get("content_chars", 0) + entry.get("tool_call_args_chars", 0)
+            for entry in inventory
+        )
+        lines.append(
+            "## Pre-Compaction Message Inventory "
+            f"({len(inventory)} messages, {total_chars:,} total chars)"
+        )
+        lines.append("")
+        ranked = sorted(
+            inventory,
+            key=lambda entry: entry.get("content_chars", 0) + entry.get("tool_call_args_chars", 0),
+            reverse=True,
+        )
+        lines.append("| # | seq | role | tool | chars | % of total | flags |")
+        lines.append("|---|-----|------|------|------:|------------|-------|")
+        for i, entry in enumerate(ranked, 1):
+            chars = entry.get("content_chars", 0) + entry.get("tool_call_args_chars", 0)
+            pct = (chars / total_chars * 100) if total_chars else 0
+            tool = entry.get("tool", "")
+            flags: list[str] = []
+            if entry.get("is_error"):
+                flags.append("error")
+            if entry.get("phase"):
+                flags.append(f"phase={entry['phase']}")
+            lines.append(
+                f"| {i} | {entry['seq']} | {entry['role']} | {tool} "
+                f"| {chars:,} | {pct:.1f}% | {', '.join(flags)} |"
+            )
+
+        large = [entry for entry in ranked if entry.get("preview")]
+        if large:
+            lines.append("")
+            lines.append("### Large message previews")
+            for entry in large:
+                lines.append(
+                    f"\n**seq={entry['seq']}** ({entry['role']}, {entry.get('tool', '')}):"
+                )
+                lines.append(f"```\n{entry['preview']}\n```")
+    lines.append("")
+
+    try:
+        log_path.write_text("\n".join(lines), encoding="utf-8")
+        logger.debug("Compaction debug log written to %s", log_path)
+    except OSError:
+        logger.debug("Failed to write compaction debug log to %s", log_path)
+
+
+async def log_compaction(
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    ratio_before: float,
+    event_bus: EventBus | None,
+    *,
+    pre_inventory: list[dict[str, Any]] | None = None,
+) -> None:
+    """Log compaction result to runtime logger and event bus."""
+    ratio_after = conversation.usage_ratio()
+    before_pct = round(ratio_before * 100)
+    after_pct = round(ratio_after * 100)
+
+    # Determine label from what happened
+    if after_pct >= before_pct - 1:
+        level = "prune_only"
+    elif ratio_after <= 0.6:
+        level = "llm"
+    else:
+        level = "structural"
+
+    logger.info(
+        "Compaction complete (%s): %d%% -> %d%%",
+        level,
+        before_pct,
+        after_pct,
+    )
+
+    if ctx.runtime_logger:
+        ctx.runtime_logger.log_step(
+            node_id=ctx.agent_id,
+            node_type="event_loop",
+            step_index=-1,
+            llm_text=f"Context compacted ({level}): {before_pct}% \u2192 {after_pct}%",
+            verdict="COMPACTION",
+            verdict_feedback=f"level={level} before={before_pct}% after={after_pct}%",
+        )
+
+    if event_bus:
+        from framework.host.event_bus import AgentEvent, EventType
+
+        event_data: dict[str, Any] = {
+            "level": level,
+            "usage_before": before_pct,
+            "usage_after": after_pct,
+        }
+        if pre_inventory is not None:
+            event_data["message_inventory"] = pre_inventory
+        await event_bus.publish(
+            AgentEvent(
+                type=EventType.CONTEXT_COMPACTED,
+                stream_id=ctx.stream_id or ctx.agent_id,
+                node_id=ctx.agent_id,
+                data=event_data,
+            )
+        )
+
+    await publish_context_usage(event_bus, ctx, conversation, "post_compaction")
+
+    if os.environ.get("HIVE_COMPACTION_DEBUG"):
+        write_compaction_debug_log(ctx, before_pct, after_pct, level, pre_inventory)
+
+
+def build_emergency_summary(
+    ctx: NodeContext,
+    accumulator: OutputAccumulator | None = None,
+    conversation: NodeConversation | None = None,
+    config: LoopConfig | None = None,
+) -> str:
+    """Build a structured emergency compaction summary.
+
+    Unlike normal/aggressive compaction which uses an LLM summary,
+    emergency compaction cannot afford an LLM call (context is already
+    way over budget).  Instead, build a deterministic summary from the
+    node's known state so the LLM can continue working after
+    compaction without losing track of its task and inputs.
+    """
+    parts = [
+        "EMERGENCY COMPACTION — previous conversation was too large "
+        "and has been replaced with this summary.\n"
+    ]
+
+    # 1. Node identity
+    spec = ctx.agent_spec
+    parts.append(f"NODE: {spec.name} (id={spec.id})")
+    if spec.description:
+        parts.append(f"PURPOSE: {spec.description}")
+
+    # 2. Inputs the node received
+    input_lines = []
+    for key in spec.input_keys:
+        value = ctx.input_data.get(key)
+        if value is not None:
+            # Truncate long values but keep them recognisable
+            v_str = str(value)
+            if len(v_str) > 200:
+                v_str = v_str[:200] + "…"
+            input_lines.append(f"  {key}: {v_str}")
+    if input_lines:
+        parts.append("INPUTS:\n" + "\n".join(input_lines))
+
+    # 3. Output accumulator state (what's been set so far)
+    if accumulator:
+        acc_state = accumulator.to_dict()
+        set_keys = {k: v for k, v in acc_state.items() if v is not None}
+        missing = [k for k, v in acc_state.items() if v is None]
+        if set_keys:
+            lines = [f"  {k}: {str(v)[:150]}" for k, v in set_keys.items()]
+            parts.append("OUTPUTS ALREADY SET:\n" + "\n".join(lines))
+        if missing:
+            parts.append(f"OUTPUTS STILL NEEDED: {', '.join(missing)}")
+    elif spec.output_keys:
+        parts.append(f"OUTPUTS STILL NEEDED: {', '.join(spec.output_keys)}")
+
+    # 4. Available tools reminder
+    if spec.tools:
+        parts.append(f"AVAILABLE TOOLS: {', '.join(spec.tools)}")
+
+    # 5. Spillover files — list actual files so the LLM can load
+    # them immediately instead of having to call list_data_files first.
+    spillover_dir = config.spillover_dir if config else None
+    if spillover_dir:
+        try:
+            from pathlib import Path
+
+            data_dir = Path(spillover_dir)
+            if data_dir.is_dir():
+                all_files = sorted(f.name for f in data_dir.iterdir() if f.is_file())
+                # Separate conversation history files from regular data files
+                conv_files = [f for f in all_files if re.match(r"conversation_\d+\.md$", f)]
+                data_files = [f for f in all_files if f not in conv_files]
+
+                if conv_files:
+                    conv_list = "\n".join(
+                        f"  - {f}  (full path: {data_dir / f})" for f in conv_files
+                    )
+                    parts.append(
+                        "CONVERSATION HISTORY (freeform messages saved during compaction — "
+                        "use read_file('<filename>') to review earlier dialogue):\n" + conv_list
+                    )
+                if data_files:
+                    file_list = "\n".join(
+                        f"  - {f}  (full path: {data_dir / f})" for f in data_files[:30]
+                    )
+                    parts.append("DATA FILES (use read_file('<filename>') to read):\n" + file_list)
+                if not all_files:
+                    parts.append(
+                        "NOTE: Large tool results may have been saved to files. "
+                        "Use list_directory to check the data directory."
+                    )
+        except Exception:
+            parts.append(
+                "NOTE: Large tool results were saved to files. "
+                "Use read_file(path='<path>') to read them."
+            )
+
+    # 6. Tool call history (prevent re-calling tools)
+    if conversation is not None:
+        tool_history = _extract_tool_call_history(conversation)
+        if tool_history:
+            parts.append(tool_history)
+
+    parts.append(
+        "\nContinue working towards setting the remaining outputs. "
+        "Use your tools and the inputs above."
+    )
+    return "\n\n".join(parts)
+
+
+def _extract_tool_call_history(conversation: NodeConversation) -> str:
+    """Extract tool call history from conversation messages.
+
+    This is the instance-level variant that operates on a NodeConversation
+    directly (vs. the module-level extract_tool_call_history in conversation.py
+    which works on raw message lists).
+    """
+    from framework.agent_loop.conversation import extract_tool_call_history
+
+    return extract_tool_call_history(list(conversation.messages))

core/framework/agent_loop/internals/cursor_persistence.py

@@ -0,0 +1,269 @@
+"""Cursor persistence, queue draining, and pause detection.
+
+Handles the checkpoint/resume cycle: restoring state from a previous
+conversation store, writing cursor data, and managing injection/trigger
+queues between iterations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from framework.agent_loop.conversation import ConversationStore, NodeConversation
+from framework.agent_loop.internals.types import LoopConfig, OutputAccumulator, TriggerEvent
+from framework.llm.capabilities import supports_image_tool_results
+from framework.orchestrator.node import NodeContext
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RestoredState:
+    """State recovered from a previous checkpoint."""
+
+    conversation: NodeConversation
+    accumulator: OutputAccumulator
+    start_iteration: int
+    recent_responses: list[str]
+    recent_tool_fingerprints: list[list[tuple[str, str]]]
+    pending_input: dict[str, Any] | None
+
+
+async def restore(
+    conversation_store: ConversationStore | None,
+    ctx: NodeContext,
+    config: LoopConfig,
+) -> RestoredState | None:
+    """Attempt to restore from a previous checkpoint.
+
+    Returns a ``RestoredState`` with conversation, accumulator, iteration
+    counter, and stall/doom-loop detection state — everything needed to
+    resume exactly where execution stopped.
+    """
+    if conversation_store is None:
+        return None
+
+    # In isolated mode, filter parts by phase_id so the node only sees
+    # its own messages in the shared flat conversation store.  In
+    # continuous mode (or when _restore is called for timer-resume)
+    # load all parts — the full conversation threads across nodes.
+    _is_continuous = getattr(ctx, "continuous_mode", False)
+    # The queen has agent_id="queen" but messages are stored with phase_id=None.
+    # Only apply phase filtering for non-queen workers in a multi-agent setup.
+    phase_filter = None if (_is_continuous or ctx.agent_id == "queen") else ctx.agent_id
+    conversation = await NodeConversation.restore(
+        conversation_store,
+        phase_id=phase_filter,
+        run_id=ctx.effective_run_id,
+    )
+    if conversation is None:
+        logger.info(
+            "[restore] No conversation found for agent_id=%s phase_filter=%s run_id=%s",
+            ctx.agent_id,
+            phase_filter,
+            ctx.effective_run_id,
+        )
+        return None
+
+    logger.info(
+        "[restore] Restored %d messages for agent_id=%s phase_filter=%s run_id=%s",
+        conversation.message_count,
+        ctx.agent_id,
+        phase_filter,
+        ctx.effective_run_id,
+    )
+
+    # If run_id filtering removed all messages, this is an intentional
+    # restart (new run), not a crash recovery.  Return None so the caller
+    # falls through to the fresh-conversation path.
+    if conversation.message_count == 0:
+        return None
+
+    accumulator = await OutputAccumulator.restore(conversation_store, run_id=ctx.effective_run_id)
+    accumulator.spillover_dir = config.spillover_dir
+    accumulator.max_value_chars = config.max_output_value_chars
+
+    cursor = await conversation_store.read_cursor() or {}
+    start_iteration = cursor.get("iteration", 0) + 1
+
+    # Restore stall/doom-loop detection state
+    recent_responses: list[str] = cursor.get("recent_responses", [])
+    raw_fps = cursor.get("recent_tool_fingerprints", [])
+    recent_tool_fingerprints: list[list[tuple[str, str]]] = [
+        [tuple(pair) for pair in fps]  # type: ignore[misc]
+        for fps in raw_fps
+    ]
+    pending_input = cursor.get("pending_input")
+    if not isinstance(pending_input, dict):
+        pending_input = None
+
+    logger.info(
+        f"Restored event loop: iteration={start_iteration}, "
+        f"messages={conversation.message_count}, "
+        f"outputs={list(accumulator.values.keys())}, "
+        f"stall_window={len(recent_responses)}, "
+        f"doom_window={len(recent_tool_fingerprints)}"
+    )
+    return RestoredState(
+        conversation=conversation,
+        accumulator=accumulator,
+        start_iteration=start_iteration,
+        recent_responses=recent_responses,
+        recent_tool_fingerprints=recent_tool_fingerprints,
+        pending_input=pending_input,
+    )
+
+
+async def write_cursor(
+    conversation_store: ConversationStore | None,
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    accumulator: OutputAccumulator,
+    iteration: int,
+    *,
+    recent_responses: list[str] | None = None,
+    recent_tool_fingerprints: list[list[tuple[str, str]]] | None = None,
+    pending_input: dict[str, Any] | None = None,
+) -> None:
+    """Write checkpoint cursor for crash recovery.
+
+    Persists iteration counter, accumulator outputs, and stall/doom-loop
+    detection state so that resume picks up exactly where execution stopped.
+    """
+    if conversation_store:
+        cursor = await conversation_store.read_cursor() or {}
+        cursor.update(
+            {
+                "iteration": iteration,
+                "node_id": ctx.agent_id,
+                "outputs": accumulator.to_dict(),
+            }
+        )
+        # Persist stall/doom-loop detection state for reliable resume
+        if recent_responses is not None:
+            cursor["recent_responses"] = recent_responses
+        if recent_tool_fingerprints is not None:
+            # Convert list[list[tuple]] → list[list[list]] for JSON
+            cursor["recent_tool_fingerprints"] = [
+                [list(pair) for pair in fps] for fps in recent_tool_fingerprints
+            ]
+        # Persist blocked-input state so restored runs re-block instead of
+        # manufacturing a synthetic continuation turn.
+        cursor["pending_input"] = pending_input
+        await conversation_store.write_cursor(cursor)
+
+
+async def drain_injection_queue(
+    queue: asyncio.Queue,
+    conversation: NodeConversation,
+    *,
+    ctx: NodeContext,
+    describe_images_as_text_fn: (
+        Callable[[list[dict[str, Any]]], Awaitable[str | None]] | None
+    ) = None,
+) -> int:
+    """Drain all pending injected events as user messages. Returns count."""
+    count = 0
+    logger.debug(
+        "[drain_injection_queue] Starting to drain queue, initial queue size: %s",
+        queue.qsize() if hasattr(queue, "qsize") else "unknown",
+    )
+    while not queue.empty():
+        try:
+            content, is_client_input, image_content = queue.get_nowait()
+            logger.info(
+                "[drain] injected message (client_input=%s, images=%d): %s",
+                is_client_input,
+                len(image_content) if image_content else 0,
+                content[:200] if content else "(empty)",
+            )
+            if image_content and ctx.llm and not supports_image_tool_results(ctx.llm.model):
+                logger.info(
+                    "Model '%s' does not support images; attempting vision fallback",
+                    ctx.llm.model,
+                )
+                if describe_images_as_text_fn is not None:
+                    description = await describe_images_as_text_fn(image_content)
+                    if description:
+                        content = f"{content}\n\n{description}" if content else description
+                        logger.info("[drain] image described as text via vision fallback")
+                    else:
+                        logger.info("[drain] no vision fallback available; images dropped")
+                image_content = None
+            # Real user input is stored as-is; external events get a prefix
+            if is_client_input:
+                await conversation.add_user_message(
+                    content,
+                    is_client_input=True,
+                    image_content=image_content,
+                )
+            else:
+                await conversation.add_user_message(f"[External event]: {content}")
+            count += 1
+        except asyncio.QueueEmpty:
+            break
+    return count
+
+
+async def drain_trigger_queue(
+    queue: asyncio.Queue,
+    conversation: NodeConversation,
+) -> int:
+    """Drain all pending trigger events as a single batched user message.
+
+    Multiple triggers are merged so the LLM sees them atomically and can
+    reason about all pending triggers before acting.
+    """
+    triggers: list[TriggerEvent] = []
+    while not queue.empty():
+        try:
+            triggers.append(queue.get_nowait())
+        except asyncio.QueueEmpty:
+            break
+
+    if not triggers:
+        return 0
+
+    parts: list[str] = []
+    for t in triggers:
+        task = t.payload.get("task", "")
+        task_line = f"\nTask: {task}" if task else ""
+        payload_str = json.dumps(t.payload, default=str)
+        parts.append(f"[TRIGGER: {t.trigger_type}/{t.source_id}]{task_line}\n{payload_str}")
+
+    combined = "\n\n".join(parts)
+    logger.info("[drain] %d trigger(s): %s", len(triggers), combined[:200])
+    await conversation.add_user_message(combined)
+    return len(triggers)
+
+
+async def check_pause(
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    iteration: int,
+) -> bool:
+    """
+    Check if pause has been requested. Returns True if paused.
+
+    Note: This check happens BEFORE starting iteration N, after completing N-1.
+    If paused, the node exits having completed {iteration} iterations (0 to iteration-1).
+    """
+    # Check executor-level pause event (for /pause command, Ctrl+Z)
+    if ctx.pause_event and ctx.pause_event.is_set():
+        completed = iteration  # 0-indexed: iteration=3 means 3 iterations completed (0,1,2)
+        logger.info(f"⏸ Pausing after {completed} iteration(s) completed (executor-level)")
+        return True
+
+    # Check context-level pause flags (legacy/alternative methods)
+    pause_requested = ctx.input_data.get("pause_requested", False)
+    if pause_requested:
+        completed = iteration
+        logger.info(f"⏸ Pausing after {completed} iteration(s) completed (context-level)")
+        return True
+
+    return False

core/framework/agent_loop/internals/event_publishing.py

@@ -0,0 +1,358 @@
+"""EventBus publishing helpers for the event loop.
+
+Thin wrappers around EventBus.emit_*() calls that check for bus existence
+before publishing.  Extracted to reduce noise in the main orchestrator.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from framework.agent_loop.conversation import NodeConversation
+from framework.agent_loop.internals.types import HookContext
+from framework.host.event_bus import EventBus
+from framework.orchestrator.node import NodeContext
+
+logger = logging.getLogger(__name__)
+
+
+async def publish_loop_started(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    max_iterations: int,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_node_loop_started(
+            stream_id=stream_id,
+            node_id=node_id,
+            max_iterations=max_iterations,
+            execution_id=execution_id,
+        )
+
+
+async def generate_action_plan(
+    event_bus: EventBus | None,
+    ctx: NodeContext,
+    stream_id: str,
+    node_id: str,
+    execution_id: str,
+) -> None:
+    """Generate a brief action plan via LLM and emit it as an SSE event.
+
+    Runs as a fire-and-forget task so it never blocks the main loop.
+    """
+    try:
+        system_prompt = ctx.agent_spec.system_prompt or ""
+        # Trim to keep the prompt small
+        prompt_summary = system_prompt[:500]
+        if len(system_prompt) > 500:
+            prompt_summary += "..."
+
+        tool_names = [t.name for t in ctx.available_tools]
+        output_keys = ctx.agent_spec.output_keys or []
+
+        prompt = (
+            f'You are about to work on a task as node "{node_id}".\n\n'
+            f"System prompt:\n{prompt_summary}\n\n"
+            f"Tools available: {tool_names}\n"
+            f"Required outputs: {output_keys}\n\n"
+            f"Write a brief action plan (2-5 bullet points) describing "
+            f"what you will do to complete this task. Be specific and concise.\n"
+            f"Return ONLY the plan text, no preamble."
+        )
+
+        response = await ctx.llm.acomplete(
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=1024,
+        )
+
+        plan = response.content.strip()
+        if plan and event_bus:
+            await event_bus.emit_node_action_plan(
+                stream_id=stream_id,
+                node_id=node_id,
+                plan=plan,
+                execution_id=execution_id,
+            )
+    except Exception as e:
+        logger.warning("Action plan generation failed for node '%s': %s", node_id, e)
+
+
+async def publish_iteration(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    iteration: int,
+    execution_id: str = "",
+    extra_data: dict | None = None,
+) -> None:
+    if event_bus:
+        await event_bus.emit_node_loop_iteration(
+            stream_id=stream_id,
+            node_id=node_id,
+            iteration=iteration,
+            execution_id=execution_id,
+            extra_data=extra_data,
+        )
+
+
+async def publish_llm_turn_complete(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    stop_reason: str,
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cached_tokens: int = 0,
+    execution_id: str = "",
+    iteration: int | None = None,
+) -> None:
+    if event_bus:
+        await event_bus.emit_llm_turn_complete(
+            stream_id=stream_id,
+            node_id=node_id,
+            stop_reason=stop_reason,
+            model=model,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+            execution_id=execution_id,
+            iteration=iteration,
+        )
+
+
+def log_skip_judge(
+    ctx: NodeContext,
+    node_id: str,
+    iteration: int,
+    feedback: str,
+    tool_calls: list[dict],
+    llm_text: str,
+    turn_tokens: dict[str, int],
+    iter_start: float,
+) -> None:
+    """Log a CONTINUE step that skips judge evaluation (e.g., waiting for input)."""
+    if ctx.runtime_logger:
+        ctx.runtime_logger.log_step(
+            node_id=node_id,
+            node_type="event_loop",
+            step_index=iteration,
+            verdict="CONTINUE",
+            verdict_feedback=feedback,
+            tool_calls=tool_calls,
+            llm_text=llm_text,
+            input_tokens=turn_tokens.get("input", 0),
+            output_tokens=turn_tokens.get("output", 0),
+            latency_ms=int((time.time() - iter_start) * 1000),
+        )
+
+
+async def publish_loop_completed(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    iterations: int,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_node_loop_completed(
+            stream_id=stream_id,
+            node_id=node_id,
+            iterations=iterations,
+            execution_id=execution_id,
+        )
+
+
+async def publish_context_usage(
+    event_bus: EventBus | None,
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    trigger: str,
+) -> None:
+    """Emit a CONTEXT_USAGE_UPDATED event with current context window state."""
+    if not event_bus:
+        return
+
+    from framework.host.event_bus import AgentEvent, EventType
+
+    estimated = conversation.estimate_tokens()
+    max_tokens = conversation._max_context_tokens
+    ratio = estimated / max_tokens if max_tokens > 0 else 0.0
+    await event_bus.publish(
+        AgentEvent(
+            type=EventType.CONTEXT_USAGE_UPDATED,
+            stream_id=ctx.stream_id or ctx.agent_id,
+            node_id=ctx.agent_id,
+            data={
+                "usage_ratio": round(ratio, 4),
+                "usage_pct": round(ratio * 100),
+                "message_count": conversation.message_count,
+                "estimated_tokens": estimated,
+                "max_context_tokens": max_tokens,
+                "trigger": trigger,
+            },
+        )
+    )
+
+
+async def publish_stalled(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_node_stalled(
+            stream_id=stream_id,
+            node_id=node_id,
+            reason="Consecutive similar responses detected",
+            execution_id=execution_id,
+        )
+
+
+async def publish_text_delta(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    content: str,
+    snapshot: str,
+    ctx: NodeContext,
+    execution_id: str = "",
+    iteration: int | None = None,
+    inner_turn: int = 0,
+) -> None:
+    if event_bus:
+        if ctx.emits_client_io:
+            await event_bus.emit_client_output_delta(
+                stream_id=stream_id,
+                node_id=node_id,
+                content=content,
+                snapshot=snapshot,
+                execution_id=execution_id,
+                iteration=iteration,
+                inner_turn=inner_turn,
+            )
+        else:
+            await event_bus.emit_llm_text_delta(
+                stream_id=stream_id,
+                node_id=node_id,
+                content=content,
+                snapshot=snapshot,
+                execution_id=execution_id,
+                inner_turn=inner_turn,
+            )
+
+
+async def publish_tool_started(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    tool_use_id: str,
+    tool_name: str,
+    tool_input: dict,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_tool_call_started(
+            stream_id=stream_id,
+            node_id=node_id,
+            tool_use_id=tool_use_id,
+            tool_name=tool_name,
+            tool_input=tool_input,
+            execution_id=execution_id,
+        )
+
+
+async def publish_tool_completed(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    tool_use_id: str,
+    tool_name: str,
+    result: str,
+    is_error: bool,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_tool_call_completed(
+            stream_id=stream_id,
+            node_id=node_id,
+            tool_use_id=tool_use_id,
+            tool_name=tool_name,
+            result=result,
+            is_error=is_error,
+            execution_id=execution_id,
+        )
+
+
+async def publish_judge_verdict(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    action: str,
+    feedback: str = "",
+    judge_type: str = "implicit",
+    iteration: int = 0,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        await event_bus.emit_judge_verdict(
+            stream_id=stream_id,
+            node_id=node_id,
+            action=action,
+            feedback=feedback,
+            judge_type=judge_type,
+            iteration=iteration,
+            execution_id=execution_id,
+        )
+
+
+async def publish_output_key_set(
+    event_bus: EventBus | None,
+    stream_id: str,
+    node_id: str,
+    key: str,
+    execution_id: str = "",
+) -> None:
+    if event_bus:
+        pass
+
+
+async def run_hooks(
+    hooks_config: dict[str, list],
+    event: str,
+    conversation: NodeConversation,
+    trigger: str | None = None,
+) -> None:
+    """Run all registered hooks for *event*, applying their results.
+
+    Each hook receives a HookContext and may return a HookResult that:
+    - replaces the system prompt (result.system_prompt)
+    - injects an extra user message (result.inject)
+    Hooks run in registration order; each sees the prompt as left by the
+    previous hook.
+    """
+    hook_list = hooks_config.get(event, [])
+    if not hook_list:
+        return
+    for hook in hook_list:
+        ctx = HookContext(
+            event=event,
+            trigger=trigger,
+            system_prompt=conversation.system_prompt,
+        )
+        try:
+            result = await hook(ctx)
+        except Exception:
+            logger.warning("Hook '%s' raised an exception", event, exc_info=True)
+            continue
+        if result is None:
+            continue
+        if result.system_prompt:
+            conversation.update_system_prompt(result.system_prompt)
+        if result.inject:
+            await conversation.add_user_message(result.inject)

core/framework/agent_loop/internals/judge_pipeline.py

@@ -0,0 +1,161 @@
+"""Judge evaluation pipeline for the event loop."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+from framework.agent_loop.conversation import NodeConversation
+from framework.agent_loop.internals.types import JudgeProtocol, JudgeVerdict, OutputAccumulator
+from framework.orchestrator.node import NodeContext
+
+logger = logging.getLogger(__name__)
+
+
+class SubagentJudge:
+    """Judge for subagent execution."""
+
+    def __init__(self, task: str, max_iterations: int = 10):
+        self._task = task
+        self._max_iterations = max_iterations
+
+    async def evaluate(self, context: dict[str, object]) -> JudgeVerdict:
+        missing = context.get("missing_keys", [])
+        if not isinstance(missing, list) or not missing:
+            return JudgeVerdict(action="ACCEPT", feedback="")
+
+        iteration = context.get("iteration", 0)
+        if not isinstance(iteration, int):
+            iteration = 0
+        remaining = self._max_iterations - iteration - 1
+
+        if remaining <= 3:
+            urgency = (
+                f"URGENT: Only {remaining} iterations left. "
+                f"Stop all other work and call set_output NOW for: {missing}"
+            )
+        elif remaining <= self._max_iterations // 2:
+            urgency = (
+                f"WARNING: {remaining} iterations remaining. "
+                f"You must call set_output for: {missing}"
+            )
+        else:
+            urgency = f"Missing output keys: {missing}. Use set_output to provide them."
+
+        return JudgeVerdict(action="RETRY", feedback=f"Your task: {self._task}\n{urgency}")
+
+
+async def judge_turn(
+    *,
+    mark_complete_flag: bool,
+    judge: JudgeProtocol | None,
+    ctx: NodeContext,
+    conversation: NodeConversation,
+    accumulator: OutputAccumulator,
+    assistant_text: str,
+    tool_results: list[dict[str, object]],
+    iteration: int,
+    get_missing_output_keys_fn: Callable[
+        [OutputAccumulator, list[str] | None, list[str] | None],
+        list[str],
+    ],
+    max_context_tokens: int,
+) -> JudgeVerdict:
+    """Evaluate the current state using judge or implicit logic.
+
+    Evaluation levels (in order):
+      0. Short-circuits: mark_complete, skip_judge, tool-continue.
+      1. Custom judge (JudgeProtocol) — full authority when set.
+      2. Implicit judge — output-key check + optional conversation-aware
+         quality gate (when ``success_criteria`` is defined).
+
+    Returns a JudgeVerdict.  ``feedback=None`` means no real evaluation
+    happened (skip_judge, tool-continue); the caller must not inject a
+    feedback message.  Any non-None feedback (including ``""``) means a
+    real evaluation occurred and will be logged into the conversation.
+    """
+    # --- Level 0: short-circuits (no evaluation) -----------------------
+
+    if mark_complete_flag:
+        return JudgeVerdict(action="ACCEPT")
+
+    if ctx.agent_spec.skip_judge:
+        return JudgeVerdict(action="RETRY")  # feedback=None → not logged
+
+    # --- Level 1: custom judge -----------------------------------------
+
+    if judge is not None:
+        context = {
+            "assistant_text": assistant_text,
+            "tool_calls": tool_results,
+            "output_accumulator": accumulator.to_dict(),
+            "accumulator": accumulator,
+            "iteration": iteration,
+            "conversation_summary": conversation.export_summary(),
+            "output_keys": ctx.agent_spec.output_keys,
+            "missing_keys": get_missing_output_keys_fn(
+                accumulator, ctx.agent_spec.output_keys, ctx.agent_spec.nullable_output_keys
+            ),
+        }
+        verdict = await judge.evaluate(context)
+        # Ensure evaluated RETRY always carries feedback for logging.
+        if verdict.action == "RETRY" and not verdict.feedback:
+            return JudgeVerdict(action="RETRY", feedback="Custom judge returned RETRY.")
+        return verdict
+
+    # --- Level 2: implicit judge ---------------------------------------
+
+    # Real tool calls were made — let the agent keep working.
+    if tool_results:
+        return JudgeVerdict(action="RETRY")  # feedback=None → not logged
+
+    missing = get_missing_output_keys_fn(
+        accumulator, ctx.agent_spec.output_keys, ctx.agent_spec.nullable_output_keys
+    )
+
+    if missing:
+        return JudgeVerdict(
+            action="RETRY",
+            feedback=(
+                f"Task incomplete. Required outputs not yet produced: {missing}. "
+                f"Follow your system prompt instructions to complete the work."
+            ),
+        )
+
+    # All output keys present — run safety checks before accepting.
+
+    output_keys = ctx.agent_spec.output_keys or []
+    nullable_keys = set(ctx.agent_spec.nullable_output_keys or [])
+
+    # All-nullable with nothing set → node produced nothing useful.
+    all_nullable = output_keys and nullable_keys >= set(output_keys)
+    none_set = not any(accumulator.get(k) is not None for k in output_keys)
+    if all_nullable and none_set:
+        return JudgeVerdict(
+            action="RETRY",
+            feedback=(
+                f"No output keys have been set yet. "
+                f"Use set_output to set at least one of: {output_keys}"
+            ),
+        )
+
+    # Level 2b: conversation-aware quality check (if success_criteria set)
+    if ctx.agent_spec.success_criteria and ctx.llm:
+        from framework.orchestrator.conversation_judge import evaluate_phase_completion
+
+        verdict = await evaluate_phase_completion(
+            llm=ctx.llm,
+            conversation=conversation,
+            phase_name=ctx.agent_spec.name,
+            phase_description=ctx.agent_spec.description,
+            success_criteria=ctx.agent_spec.success_criteria,
+            accumulator_state=accumulator.to_dict(),
+            max_context_tokens=max_context_tokens,
+        )
+        if verdict.action != "ACCEPT":
+            return JudgeVerdict(
+                action=verdict.action,
+                feedback=verdict.feedback or "Phase criteria not met.",
+            )
+
+    return JudgeVerdict(action="ACCEPT", feedback="")

core/framework/agent_loop/internals/stall_detector.py

@@ -0,0 +1,106 @@
+"""Stall and doom-loop detection for the event loop.
+
+Pure functions with no class dependencies — safe to call from any context.
+"""
+
+from __future__ import annotations
+
+import json
+
+
+def ngram_similarity(s1: str, s2: str, n: int = 2) -> float:
+    """Jaccard similarity of n-gram sets.
+
+    Returns 0.0-1.0, where 1.0 is exact match.
+    Fast: O(len(s) + len(s2)) using set operations.
+    """
+
+    def _ngrams(s: str) -> set[str]:
+        return {s[i : i + n] for i in range(len(s) - n + 1) if s.strip()}
+
+    if not s1 or not s2:
+        return 0.0
+
+    ngrams1, ngrams2 = _ngrams(s1.lower()), _ngrams(s2.lower())
+    if not ngrams1 or not ngrams2:
+        return 0.0
+
+    intersection = len(ngrams1 & ngrams2)
+    union = len(ngrams1 | ngrams2)
+    return intersection / union if union else 0.0
+
+
+def is_stalled(
+    recent_responses: list[str],
+    threshold: int,
+    similarity_threshold: float,
+) -> bool:
+    """Detect stall using n-gram similarity.
+
+    Detects when ALL N consecutive responses are mutually similar
+    (>= threshold).  A single dissimilar response resets the signal.
+    This catches phrases like "I'm still stuck" vs "I'm stuck"
+    without false-positives on "attempt 1" vs "attempt 2".
+    """
+    if len(recent_responses) < threshold:
+        return False
+    if not recent_responses[0]:
+        return False
+
+    # Every consecutive pair must be similar
+    for i in range(1, len(recent_responses)):
+        if ngram_similarity(recent_responses[i], recent_responses[i - 1]) < similarity_threshold:
+            return False
+    return True
+
+
+def fingerprint_tool_calls(
+    tool_results: list[dict],
+) -> list[tuple[str, str]]:
+    """Create deterministic fingerprints for a turn's tool calls.
+
+    Each fingerprint is (tool_name, canonical_args_json).  Order-sensitive
+    so [search("a"), fetch("b")] != [fetch("b"), search("a")].
+    """
+    fingerprints = []
+    for tr in tool_results:
+        name = tr.get("tool_name", "")
+        args = tr.get("tool_input", {})
+        try:
+            canonical = json.dumps(args, sort_keys=True, default=str)
+        except (TypeError, ValueError):
+            canonical = str(args)
+        fingerprints.append((name, canonical))
+    return fingerprints
+
+
+def is_tool_doom_loop(
+    recent_tool_fingerprints: list[list[tuple[str, str]]],
+    threshold: int,
+    enabled: bool = True,
+) -> tuple[bool, str]:
+    """Detect doom loop via exact fingerprint match.
+
+    Detects when N consecutive turns invoke the same tools with
+    identical (canonicalized) arguments.  Different arguments mean
+    different work, so only exact matches count.
+
+    Returns (is_doom_loop, description).
+    """
+    if not enabled:
+        return False, ""
+    if len(recent_tool_fingerprints) < threshold:
+        return False, ""
+    first = recent_tool_fingerprints[0]
+    if not first:
+        return False, ""
+
+    # All turns in the window must match the first exactly
+    if all(fp == first for fp in recent_tool_fingerprints[1:]):
+        tool_names = [name for name, _ in first]
+        desc = (
+            f"Doom loop detected: {len(recent_tool_fingerprints)} "
+            f"identical consecutive tool calls ({', '.join(tool_names)})"
+        )
+        return True, desc
+    return False, ""

core/framework/agent_loop/internals/synthetic_tools.py

@@ -0,0 +1,437 @@
+"""Synthetic tool builders for the event loop.
+
+Factory functions that create ``Tool`` definitions for framework-level
+synthetic tools (set_output, ask_user, escalate, delegate, report_to_parent).
+Also includes the ``handle_set_output`` validation logic.
+
+All functions are pure — they receive explicit parameters and return
+``Tool`` or ``ToolResult`` objects with no side effects.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from framework.llm.provider import Tool, ToolResult
+
+
+def sanitize_ask_user_inputs(
+    raw_question: Any,
+    raw_options: Any,
+) -> tuple[str, list[str] | None]:
+    """Self-heal a malformed ``ask_user`` tool call.
+
+    Some model families (notably when the system prompt teaches them
+    XML-ish scratchpad tags like ``<relationship>...</relationship>``)
+    carry that style into tool arguments and produce calls like::
+
+        ask_user({
+            "question": "What now?</question>\\n_OPTIONS: [\\"A\\", \\"B\\"]"
+        })
+
+    Symptoms:
+    - The chat UI renders ``</question>`` and ``_OPTIONS: [...]`` as
+      literal text in the question bubble.
+    - No buttons appear because the real ``options`` parameter is
+      empty.
+
+    This function:
+    - Strips leading/trailing whitespace.
+    - Removes a trailing ``</question>`` (with optional preceding
+      whitespace) from the question text.
+    - Detects an inline ``_OPTIONS:``, ``OPTIONS:``, or ``options:``
+      line followed by a JSON array, parses it, and returns the
+      recovered list as the second element.
+    - Removes the parsed line from the returned question text.
+
+    Returns ``(cleaned_question, recovered_options_or_None)``. The
+    caller should treat the recovered list as a fallback only when
+    the model did not also supply a real ``options`` array.
+    """
+    import json as _json
+    import re as _re
+
+    if raw_question is None:
+        return "", None
+    q = str(raw_question)
+
+    # Strip a stray </question> tag (case-insensitive, with optional
+    # preceding whitespace) anywhere in the string. This is the most
+    # common failure mode and never represents valid content.
+    q = _re.sub(r"\s*</\s*question\s*>\s*", "\n", q, flags=_re.IGNORECASE)
+
+    # Look for an inline options line. Match _OPTIONS, OPTIONS, options
+    # (with or without leading underscore), followed by ':' or '=', then
+    # a JSON array on the same line OR on the next line.
+    inline_options_re = _re.compile(
+        r"(?im)^\s*_?options\s*[:=]\s*(\[.*?\])\s*$",
+        _re.DOTALL,
+    )
+
+    recovered: list[str] | None = None
+    match = inline_options_re.search(q)
+    if match is not None:
+        try:
+            parsed = _json.loads(match.group(1))
+            if isinstance(parsed, list):
+                cleaned = [str(o).strip() for o in parsed if str(o).strip()]
+                if 1 <= len(cleaned) <= 8:
+                    recovered = cleaned
+        except (ValueError, TypeError):
+            pass
+        if recovered is not None:
+            # Remove the parsed line so it doesn't leak into the
+            # rendered question text.
+            q = inline_options_re.sub("", q, count=1)
+
+    # Strip any final whitespace / leftover blank lines from the
+    # question after removals.
+    q = _re.sub(r"\n{3,}", "\n\n", q).strip()
+
+    return q, recovered
+
+
+def build_ask_user_tool() -> Tool:
+    """Build the synthetic ask_user tool for explicit user-input requests.
+
+    The queen calls ask_user() when it needs to pause and wait
+    for user input.  Text-only turns WITHOUT ask_user flow through without
+    blocking, allowing progress updates and summaries to stream freely.
+    """
+    return Tool(
+        name="ask_user",
+        description=(
+            "You MUST call this tool whenever you need the user's response. "
+            "Always call it after greeting the user, asking a question, or "
+            "requesting approval. Do NOT call it for status updates or "
+            "summaries that don't require a response.\n\n"
+            "STRUCTURE RULES (CRITICAL):\n"
+            "- The 'question' field is PLAIN TEXT shown to the user. Do NOT "
+            "include XML tags, pseudo-tags like </question>, or option lists "
+            "in the question string. The UI does not parse them — they "
+            "render as raw text and look broken.\n"
+            "- The 'options' parameter is the ONLY way to render buttons. "
+            "If you want buttons, put them in the 'options' array, not in "
+            "the question string. Do NOT write 'OPTIONS: [...]', "
+            "'_options: [...]', or any inline list inside 'question'.\n"
+            "- The question text must read as a single clean prompt with "
+            "no markup. Example: 'What would you like to do?' — not "
+            "'What would you like to do?</question>'.\n\n"
+            "USAGE:\n"
+            "Always include 2-3 predefined options. The UI automatically "
+            "appends an 'Other' free-text input after your options, so NEVER "
+            "include catch-all options like 'Custom idea', 'Something else', "
+            "'Other', or 'None of the above' — the UI handles that. "
+            "When the question primarily needs a typed answer but you must "
+            "include options, make one option signal that typing is expected "
+            "(e.g. 'I\\'ll type my response'). This helps users discover the "
+            "free-text input. "
+            "The ONLY exception: omit options when the question demands a "
+            "free-form answer the user must type out (e.g. 'Describe your "
+            "agent idea', 'Paste the error message').\n\n"
+            "CORRECT EXAMPLE:\n"
+            '{"question": "What would you like to do?", "options": '
+            '["Build a new agent", "Modify existing agent", "Run tests"]}\n\n'
+            "FREE-FORM EXAMPLE:\n"
+            '{"question": "Describe the agent you want to build."}\n\n'
+            "WRONG (do NOT do this — buttons will not render):\n"
+            '{"question": "What now?</question>\\n_OPTIONS: [\\"A\\", \\"B\\"]"}'
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "question": {
+                    "type": "string",
+                    "description": "The question or prompt shown to the user.",
+                },
+                "options": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "2-3 specific predefined choices. Include in most cases. "
+                        'Example: ["Option A", "Option B", "Option C"]. '
+                        "The UI always appends an 'Other' free-text input, so "
+                        "do NOT include catch-alls like 'Custom idea' or 'Other'. "
+                        "Omit ONLY when the user must type a free-form answer."
+                    ),
+                    "minItems": 2,
+                    "maxItems": 3,
+                },
+            },
+            "required": ["question"],
+        },
+    )
+
+
+def build_ask_user_multiple_tool() -> 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. "
+            '{"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(output_keys: list[str] | None) -> Tool | None:
+    """Build the synthetic set_output tool for explicit output declaration."""
+    if not output_keys:
+        return None
+    return Tool(
+        name="set_output",
+        description=(
+            "Set an output value for this node. Call once per output key. "
+            "Use this for brief notes, counts, status, and file references — "
+            "NOT for large data payloads. When a tool result was saved to a "
+            "data file, pass the filename as the value "
+            "(e.g. 'google_sheets_get_values_1.txt') so the next phase can "
+            "load the full data. Values exceeding ~2000 characters are "
+            "auto-saved to data files. "
+            f"Valid keys: {output_keys}"
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "description": f"Output key. Must be one of: {output_keys}",
+                    "enum": output_keys,
+                },
+                "value": {
+                    "type": "string",
+                    "description": (
+                        "The output value — a brief note, count, status, "
+                        "or data filename reference."
+                    ),
+                },
+            },
+            "required": ["key", "value"],
+        },
+    )
+
+
+def build_escalate_tool() -> Tool:
+    """Build the synthetic escalate tool for worker -> queen handoff."""
+    return Tool(
+        name="escalate",
+        description=(
+            "Escalate to the queen when requesting user input, "
+            "blocked by errors, missing "
+            "credentials, or ambiguous constraints that require supervisor "
+            "guidance. Include a concise reason and optional context. "
+            "The node will pause until the queen injects guidance."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "reason": {
+                    "type": "string",
+                    "description": (
+                        "Short reason for escalation (e.g. 'Tool repeatedly failing')."
+                    ),
+                },
+                "context": {
+                    "type": "string",
+                    "description": "Optional diagnostic details for the queen.",
+                },
+            },
+            "required": ["reason"],
+        },
+    )
+
+
+def build_report_to_parent_tool() -> Tool:
+    """Build the synthetic ``report_to_parent`` tool.
+
+    Parallel workers (those spawned by the overseer via
+    ``run_parallel_workers``) call this to send a structured report back
+    to the overseer queen when they have finished their task. Calling
+    ``report_to_parent`` terminates the worker's loop cleanly -- do not
+    call other tools after it.
+
+    The overseer receives these as ``SUBAGENT_REPORT`` events and
+    aggregates them into a single summary for the user.
+    """
+    return Tool(
+        name="report_to_parent",
+        description=(
+            "Send a structured report back to the parent overseer and "
+            "terminate. Call this when you have finished your task "
+            "(success, partial, or failed) or cannot make further "
+            "progress. Your loop ends after this call -- do not call any "
+            "other tool afterwards. The overseer reads the summary + "
+            "data fields and aggregates them into a user-facing response."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "enum": ["success", "partial", "failed"],
+                    "description": (
+                        "Overall outcome. 'success' = task complete. "
+                        "'partial' = some progress but incomplete. "
+                        "'failed' = could not make progress."
+                    ),
+                },
+                "summary": {
+                    "type": "string",
+                    "description": (
+                        "One-paragraph narrative for the overseer. What "
+                        "you did, what you found, and any notable issues."
+                    ),
+                },
+                "data": {
+                    "type": "object",
+                    "description": (
+                        "Optional structured payload (rows fetched, IDs "
+                        "processed, files written, etc.) that the "
+                        "overseer can merge into its final summary."
+                    ),
+                },
+            },
+            "required": ["status", "summary"],
+        },
+    )
+
+
+def handle_report_to_parent(tool_input: dict[str, Any]) -> ToolResult:
+    """Normalise + validate a ``report_to_parent`` tool call.
+
+    Returns a ``ToolResult`` with the acknowledgement text the LLM sees;
+    the side effects (record on Worker, emit SUBAGENT_REPORT, terminate
+    loop) are performed by ``AgentLoop`` after this helper returns.
+    """
+    status = str(tool_input.get("status", "success")).strip().lower()
+    if status not in ("success", "partial", "failed"):
+        status = "success"
+    summary = str(tool_input.get("summary", "")).strip()
+    if not summary:
+        summary = f"(worker returned {status} with no summary)"
+    data = tool_input.get("data") or {}
+    if not isinstance(data, dict):
+        data = {"value": data}
+    # Store the normalised payload back on the input dict so the caller
+    # can pick it up without re-parsing.
+    tool_input["_normalised"] = {
+        "status": status,
+        "summary": summary,
+        "data": data,
+    }
+    return ToolResult(
+        tool_use_id=tool_input.get("tool_use_id", ""),
+        content=(
+            f"Report delivered to overseer (status={status}). "
+            f"This worker will terminate now."
+        ),
+    )
+
+
+def handle_set_output(
+    tool_input: dict[str, Any],
+    output_keys: list[str] | None,
+) -> ToolResult:
+    """Handle set_output tool call. Returns ToolResult (sync)."""
+    import logging
+    import re
+
+    logger = logging.getLogger(__name__)
+
+    key = tool_input.get("key", "")
+    value = tool_input.get("value", "")
+    valid_keys = output_keys or []
+
+    # Recover from truncated JSON (max_tokens hit mid-argument).
+    # The _raw key is set by litellm when json.loads fails.
+    if not key and "_raw" in tool_input:
+        raw = tool_input["_raw"]
+        key_match = re.search(r'"key"\s*:\s*"(\w+)"', raw)
+        if key_match:
+            key = key_match.group(1)
+        val_match = re.search(r'"value"\s*:\s*"', raw)
+        if val_match:
+            start = val_match.end()
+            value = raw[start:].rstrip()
+            for suffix in ('"}\n', '"}', '"'):
+                if value.endswith(suffix):
+                    value = value[: -len(suffix)]
+                    break
+        if key:
+            logger.warning(
+                "Recovered set_output args from truncated JSON: key=%s, value_len=%d",
+                key,
+                len(value),
+            )
+            # Re-inject so the caller sees proper key/value
+            tool_input["key"] = key
+            tool_input["value"] = value
+
+    if key not in valid_keys:
+        return ToolResult(
+            tool_use_id="",
+            content=f"Invalid output key '{key}'. Valid keys: {valid_keys}",
+            is_error=True,
+        )
+
+    return ToolResult(
+        tool_use_id="",
+        content=f"Output '{key}' set successfully.",
+        is_error=False,
+    )

core/framework/agent_loop/internals/tool_result_handler.py

@@ -0,0 +1,515 @@
+"""Tool result handling: truncation, spillover, JSON preview, and execution.
+
+Manages tool result size limits, file spillover for large results, and
+smart JSON previews.  Also includes transient error classification and
+the context-window-exceeded error detector.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from framework.llm.provider import ToolResult, ToolUse
+from framework.llm.stream_events import ToolCallEvent
+
+logger = logging.getLogger(__name__)
+
+# Pattern for detecting context-window-exceeded errors across LLM providers.
+_CONTEXT_TOO_LARGE_RE = re.compile(
+    r"context.{0,20}(length|window|limit|size)|"
+    r"too.{0,10}(long|large|many.{0,10}tokens)|"
+    r"(exceed|exceeds|exceeded).{0,30}(limit|window|context|tokens)|"
+    r"maximum.{0,20}token|prompt.{0,20}too.{0,10}long",
+    re.IGNORECASE,
+)
+
+
+def is_context_too_large_error(exc: BaseException) -> bool:
+    """Detect whether an exception indicates the LLM input was too large."""
+    cls = type(exc).__name__
+    if "ContextWindow" in cls:
+        return True
+    return bool(_CONTEXT_TOO_LARGE_RE.search(str(exc)))
+
+
+def is_transient_error(exc: BaseException) -> bool:
+    """Classify whether an exception is transient (retryable) vs permanent.
+
+    Transient: network errors, rate limits, server errors, timeouts.
+    Permanent: auth errors, bad requests, context window exceeded.
+    """
+    try:
+        from litellm.exceptions import (
+            APIConnectionError,
+            BadGatewayError,
+            InternalServerError,
+            RateLimitError,
+            ServiceUnavailableError,
+        )
+
+        transient_types: tuple[type[BaseException], ...] = (
+            RateLimitError,
+            APIConnectionError,
+            InternalServerError,
+            BadGatewayError,
+            ServiceUnavailableError,
+            TimeoutError,
+            ConnectionError,
+            OSError,
+        )
+    except ImportError:
+        transient_types = (TimeoutError, ConnectionError, OSError)
+
+    if isinstance(exc, transient_types):
+        return True
+
+    # RuntimeError from StreamErrorEvent with "Stream error:" prefix
+    if isinstance(exc, RuntimeError):
+        error_str = str(exc).lower()
+        transient_keywords = [
+            "rate limit",
+            "429",
+            "timeout",
+            "connection",
+            "internal server",
+            "502",
+            "503",
+            "504",
+            "service unavailable",
+            "bad gateway",
+            "overloaded",
+            "failed to parse tool call",
+        ]
+        return any(kw in error_str for kw in transient_keywords)
+
+    return False
+
+
+def extract_json_metadata(parsed: Any, *, _depth: int = 0, _max_depth: int = 3) -> str:
+    """Return a concise structural summary of parsed JSON.
+
+    Reports key names, value types, and — crucially — array lengths so
+    the LLM knows how much data exists beyond the preview.
+
+    Returns an empty string for simple scalars.
+    """
+    if _depth >= _max_depth:
+        if isinstance(parsed, dict):
+            return f"dict with {len(parsed)} keys"
+        if isinstance(parsed, list):
+            return f"list of {len(parsed)} items"
+        return type(parsed).__name__
+
+    if isinstance(parsed, dict):
+        if not parsed:
+            return "empty dict"
+        lines: list[str] = []
+        indent = "  " * (_depth + 1)
+        for key, value in list(parsed.items())[:20]:
+            if isinstance(value, list):
+                line = f'{indent}"{key}": list of {len(value)} items'
+                if value:
+                    first = value[0]
+                    if isinstance(first, dict):
+                        sample_keys = list(first.keys())[:10]
+                        line += f" (each item: dict with keys {sample_keys})"
+                    elif isinstance(first, list):
+                        line += f" (each item: list of {len(first)} elements)"
+                lines.append(line)
+            elif isinstance(value, dict):
+                child = extract_json_metadata(value, _depth=_depth + 1, _max_depth=_max_depth)
+                lines.append(f'{indent}"{key}": {child}')
+            else:
+                lines.append(f'{indent}"{key}": {type(value).__name__}')
+        if len(parsed) > 20:
+            lines.append(f"{indent}... and {len(parsed) - 20} more keys")
+        return "\n".join(lines)
+
+    if isinstance(parsed, list):
+        if not parsed:
+            return "empty list"
+        desc = f"list of {len(parsed)} items"
+        first = parsed[0]
+        if isinstance(first, dict):
+            sample_keys = list(first.keys())[:10]
+            desc += f" (each item: dict with keys {sample_keys})"
+        elif isinstance(first, list):
+            desc += f" (each item: list of {len(first)} elements)"
+        return desc
+
+    return ""
+
+
+def build_json_preview(parsed: Any, *, max_chars: int = 5000) -> str | None:
+    """Build a smart preview of parsed JSON, truncating large arrays.
+
+    Shows first 3 + last 1 items of large arrays with explicit count
+    markers so the LLM cannot mistake the preview for the full dataset.
+
+    Returns ``None`` if no truncation was needed (no large arrays).
+    """
+    _LARGE_ARRAY_THRESHOLD = 10
+
+    def _truncate_arrays(obj: Any) -> tuple[Any, bool]:
+        """Return (truncated_copy, was_truncated)."""
+        if isinstance(obj, list) and len(obj) > _LARGE_ARRAY_THRESHOLD:
+            n = len(obj)
+            head = obj[:3]
+            tail = obj[-1:]
+            marker = f"... ({n - 4} more items omitted, {n} total) ..."
+            return head + [marker] + tail, True
+        if isinstance(obj, dict):
+            changed = False
+            out: dict[str, Any] = {}
+            for k, v in obj.items():
+                new_v, did = _truncate_arrays(v)
+                out[k] = new_v
+                changed = changed or did
+            return (out, True) if changed else (obj, False)
+        return obj, False
+
+    preview_obj, was_truncated = _truncate_arrays(parsed)
+    if not was_truncated:
+        return None  # No large arrays — caller should use raw slicing
+
+    try:
+        result = json.dumps(preview_obj, indent=2, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return None
+
+    if len(result) > max_chars:
+        # Even 3+1 items too big — try just 1 item
+        def _minimal_arrays(obj: Any) -> Any:
+            if isinstance(obj, list) and len(obj) > _LARGE_ARRAY_THRESHOLD:
+                n = len(obj)
+                return obj[:1] + [f"... ({n - 1} more items omitted, {n} total) ..."]
+            if isinstance(obj, dict):
+                return {k: _minimal_arrays(v) for k, v in obj.items()}
+            return obj
+
+        preview_obj = _minimal_arrays(parsed)
+        try:
+            result = json.dumps(preview_obj, indent=2, ensure_ascii=False)
+        except (TypeError, ValueError):
+            return None
+        if len(result) > max_chars:
+            result = result[:max_chars] + "…"
+
+    return result
+
+
+def truncate_tool_result(
+    result: ToolResult,
+    tool_name: str,
+    *,
+    max_tool_result_chars: int,
+    spillover_dir: str | None,
+    next_spill_filename_fn: Any,  # Callable[[str], str]
+) -> ToolResult:
+    """Persist tool result to file and optionally truncate for context.
+
+    When *spillover_dir* is configured, EVERY non-error tool result is
+    saved to a file (short filename like ``web_search_1.txt``).  A
+    ``[Saved to '...']`` annotation is appended so the reference
+    survives pruning and compaction.
+
+    - Small results (≤ limit): full content kept + file annotation
+    - Large results (> limit): preview + file reference
+    - Errors: pass through unchanged
+    - read_file results: truncate with pagination hint (no re-spill)
+    """
+    limit = max_tool_result_chars
+
+    # Errors always pass through unchanged
+    if result.is_error:
+        return result
+
+    # read_file reads FROM spilled files — never re-spill (circular).
+    # Just truncate with a pagination hint if the result is too large.
+    if tool_name == "read_file":
+        if limit <= 0 or len(result.content) <= limit:
+            return result  # Small result — pass through as-is
+        # Large result — truncate with smart preview
+        PREVIEW_CAP = min(5000, max(limit - 500, limit // 2))
+
+        metadata_str = ""
+        smart_preview: str | None = None
+        try:
+            parsed_ld = json.loads(result.content)
+            metadata_str = extract_json_metadata(parsed_ld)
+            smart_preview = build_json_preview(parsed_ld, max_chars=PREVIEW_CAP)
+        except (json.JSONDecodeError, TypeError, ValueError):
+            pass
+
+        if smart_preview is not None:
+            preview_block = smart_preview
+        else:
+            preview_block = result.content[:PREVIEW_CAP] + "…"
+
+        header = (
+            f"[{tool_name} result: {len(result.content):,} chars — "
+            f"too large for context. Use offset_bytes/limit_bytes "
+            f"parameters to read smaller chunks.]"
+        )
+        if metadata_str:
+            header += f"\n\nData structure:\n{metadata_str}"
+        header += (
+            "\n\nWARNING: This is an INCOMPLETE preview. Do NOT draw conclusions or counts from it."
+        )
+
+        truncated = f"{header}\n\nPreview (small sample only):\n{preview_block}"
+        logger.info(
+            "%s result truncated: %d → %d chars (use offset/limit to paginate)",
+            tool_name,
+            len(result.content),
+            len(truncated),
+        )
+        return ToolResult(
+            tool_use_id=result.tool_use_id,
+            content=truncated,
+            is_error=False,
+            image_content=result.image_content,
+            is_skill_content=result.is_skill_content,
+        )
+
+    spill_dir = spillover_dir
+    if spill_dir:
+        spill_path = Path(spill_dir)
+        spill_path.mkdir(parents=True, exist_ok=True)
+        filename = next_spill_filename_fn(tool_name)
+
+        # Pretty-print JSON content so read_file's line-based
+        # pagination works correctly.
+        write_content = result.content
+        parsed_json: Any = None  # track for metadata extraction
+        try:
+            parsed_json = json.loads(result.content)
+            write_content = json.dumps(parsed_json, indent=2, ensure_ascii=False)
+        except (json.JSONDecodeError, TypeError, ValueError):
+            pass  # Not JSON — write as-is
+
+        file_path = spill_path / filename
+        file_path.write_text(write_content, encoding="utf-8")
+        # Use absolute path so parent agents can find files from subagents
+        abs_path = str(file_path.resolve())
+
+        if limit > 0 and len(result.content) > limit:
+            # Large result: build a small, metadata-rich preview so the
+            # LLM cannot mistake it for the complete dataset.
+            PREVIEW_CAP = 5000
+
+            # Extract structural metadata (array lengths, key names)
+            metadata_str = ""
+            smart_preview: str | None = None
+            if parsed_json is not None:
+                metadata_str = extract_json_metadata(parsed_json)
+                smart_preview = build_json_preview(parsed_json, max_chars=PREVIEW_CAP)
+
+            if smart_preview is not None:
+                preview_block = smart_preview
+            else:
+                preview_block = result.content[:PREVIEW_CAP] + "…"
+
+            # Assemble header with structural info + warning
+            header = (
+                f"[Result from {tool_name}: {len(result.content):,} chars — "
+                f"too large for context, saved to '{abs_path}'.]\n"
+            )
+            if metadata_str:
+                header += f"\nData structure:\n{metadata_str}"
+            header += (
+                f"\n\nWARNING: The preview below is INCOMPLETE. "
+                f"Do NOT draw conclusions or counts from it. "
+                f"Use read_file(path='{abs_path}') to read the "
+                f"full data before analysis."
+            )
+
+            content = f"{header}\n\nPreview (small sample only):\n{preview_block}"
+            logger.info(
+                "Tool result spilled to file: %s (%d chars → %s)",
+                tool_name,
+                len(result.content),
+                abs_path,
+            )
+        else:
+            # Small result: keep full content + annotation with absolute path
+            content = f"{result.content}\n\n[Saved to '{abs_path}']"
+            logger.info(
+                "Tool result saved to file: %s (%d chars → %s)",
+                tool_name,
+                len(result.content),
+                filename,
+            )
+
+        return ToolResult(
+            tool_use_id=result.tool_use_id,
+            content=content,
+            is_error=False,
+            image_content=result.image_content,
+            is_skill_content=result.is_skill_content,
+        )
+
+    # No spillover_dir — truncate in-place if needed
+    if limit > 0 and len(result.content) > limit:
+        PREVIEW_CAP = min(5000, max(limit - 500, limit // 2))
+
+        metadata_str = ""
+        smart_preview: str | None = None
+        try:
+            parsed_inline = json.loads(result.content)
+            metadata_str = extract_json_metadata(parsed_inline)
+            smart_preview = build_json_preview(parsed_inline, max_chars=PREVIEW_CAP)
+        except (json.JSONDecodeError, TypeError, ValueError):
+            pass
+
+        if smart_preview is not None:
+            preview_block = smart_preview
+        else:
+            preview_block = result.content[:PREVIEW_CAP] + "…"
+
+        header = (
+            f"[Result from {tool_name}: {len(result.content):,} chars — "
+            f"truncated to fit context budget.]"
+        )
+        if metadata_str:
+            header += f"\n\nData structure:\n{metadata_str}"
+        header += (
+            "\n\nWARNING: This is an INCOMPLETE preview. "
+            "Do NOT draw conclusions or counts from the preview alone."
+        )
+
+        truncated = f"{header}\n\n{preview_block}"
+        logger.info(
+            "Tool result truncated in-place: %s (%d → %d chars)",
+            tool_name,
+            len(result.content),
+            len(truncated),
+        )
+        return ToolResult(
+            tool_use_id=result.tool_use_id,
+            content=truncated,
+            is_error=False,
+            image_content=result.image_content,
+            is_skill_content=result.is_skill_content,
+        )
+
+    return result
+
+
+async def execute_tool(
+    tool_executor: Any,  # Callable[[ToolUse], ToolResult | Awaitable[ToolResult]] | None
+    tc: ToolCallEvent,
+    timeout: float,
+    skill_dirs: list[str] | None = None,
+) -> ToolResult:
+    """Execute a tool call, handling both sync and async executors.
+
+    Applies ``tool_call_timeout_seconds`` to prevent hung MCP servers
+    from blocking the event loop indefinitely.  The initial executor
+    call is offloaded to a thread pool so that sync executors don't
+    freeze the event loop.
+    """
+    if tool_executor is None:
+        return ToolResult(
+            tool_use_id=tc.tool_use_id,
+            content=f"No tool executor configured for '{tc.tool_name}'",
+            is_error=True,
+        )
+
+    skill_dirs = skill_dirs or []
+    skill_read_tools = {"view_file", "read_file"}
+    if tc.tool_name in skill_read_tools and skill_dirs:
+        raw_path = tc.tool_input.get("path", "")
+        if raw_path:
+            resolved = Path(raw_path).resolve(strict=False)
+            resolved_roots = [Path(skill_dir).resolve(strict=False) for skill_dir in skill_dirs]
+            if any(resolved.is_relative_to(root) for root in resolved_roots):
+                try:
+                    content = resolved.read_text(encoding="utf-8")
+                except Exception as exc:
+                    return ToolResult(
+                        tool_use_id=tc.tool_use_id,
+                        content=f"Could not read skill resource '{raw_path}': {exc}",
+                        is_error=True,
+                    )
+                return ToolResult(
+                    tool_use_id=tc.tool_use_id,
+                    content=content,
+                    is_skill_content=resolved.name == "SKILL.md",
+                )
+
+    tool_use = ToolUse(id=tc.tool_use_id, name=tc.tool_name, input=tc.tool_input)
+
+    async def _run() -> ToolResult:
+        # Offload the executor call to a thread.  Sync MCP executors
+        # block on future.result() — running in a thread keeps the
+        # event loop free so asyncio.wait_for can fire the timeout.
+        # Copy the current context so contextvars (e.g. data_dir from
+        # execution context) propagate into the worker thread.
+        loop = asyncio.get_running_loop()
+        ctx = contextvars.copy_context()
+        result = await loop.run_in_executor(None, ctx.run, tool_executor, tool_use)
+        # Async executors return a coroutine — await it on the loop
+        if asyncio.iscoroutine(result) or asyncio.isfuture(result):
+            result = await result
+        return result
+
+    try:
+        if timeout > 0:
+            result = await asyncio.wait_for(_run(), timeout=timeout)
+        else:
+            result = await _run()
+    except TimeoutError:
+        logger.warning("Tool '%s' timed out after %.0fs", tc.tool_name, timeout)
+        # asyncio.wait_for cancels the awaiting coroutine, but the sync
+        # executor running inside run_in_executor keeps going — and so
+        # does any MCP subprocess it is blocked on. Reach through to the
+        # owning MCPClient and force-disconnect it so the subprocess is
+        # torn down. Next call_tool triggers a reconnect. Without this
+        # the executor thread and MCP child leak on every timeout.
+        kill_for_tool = getattr(tool_executor, "kill_for_tool", None)
+        if callable(kill_for_tool):
+            try:
+                await asyncio.to_thread(kill_for_tool, tc.tool_name)
+            except Exception as exc:  # defensive — never let cleanup crash the loop
+                logger.warning(
+                    "kill_for_tool('%s') raised during timeout handling: %s",
+                    tc.tool_name,
+                    exc,
+                )
+        return ToolResult(
+            tool_use_id=tc.tool_use_id,
+            content=(
+                f"Tool '{tc.tool_name}' timed out after {timeout:.0f}s. "
+                "The operation took too long and was cancelled. "
+                "Try a simpler request or a different approach."
+            ),
+            is_error=True,
+        )
+    return result
+
+
+def restore_spill_counter(spillover_dir: str | None) -> int:
+    """Scan spillover_dir for existing spill files and return the max counter.
+
+    Returns the highest spill number found (or 0 if none).
+    """
+    if not spillover_dir:
+        return 0
+    spill_path = Path(spillover_dir)
+    if not spill_path.is_dir():
+        return 0
+    max_n = 0
+    for f in spill_path.iterdir():
+        if not f.is_file():
+            continue
+        m = re.search(r"_(\d+)\.txt$", f.name)
+        if m:
+            max_n = max(max_n, int(m.group(1)))
+    return max_n

core/framework/agent_loop/internals/types.py

@@ -0,0 +1,234 @@
+"""Shared types and state containers for the event loop package."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from framework.agent_loop.conversation import (
+    ConversationStore,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TriggerEvent:
+    """A framework-level trigger signal (timer tick or webhook hit)."""
+
+    trigger_type: str
+    source_id: str
+    payload: dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class JudgeVerdict:
+    """Result of judge evaluation for the event loop."""
+
+    action: Literal["ACCEPT", "RETRY", "ESCALATE"]
+    # None  = no evaluation happened (skip_judge, tool-continue); not logged.
+    # ""    = evaluated but no feedback; logged with default text.
+    # "..." = evaluated with feedback; logged as-is.
+    feedback: str | None = None
+
+
+@runtime_checkable
+class JudgeProtocol(Protocol):
+    """Protocol for event-loop judges."""
+
+    async def evaluate(self, context: dict[str, Any]) -> JudgeVerdict: ...
+
+
+@dataclass
+class LoopConfig:
+    """Configuration for the event loop."""
+
+    max_iterations: int = 50
+    max_tool_calls_per_turn: int = 30
+    judge_every_n_turns: int = 1
+    stall_detection_threshold: int = 3
+    stall_similarity_threshold: float = 0.85
+    max_context_tokens: int = 32_000
+    # Headroom reserved for the NEXT turn's input + output so that
+    # proactive compaction always finishes before the hard context limit
+    # is hit mid-stream. Scaled to match Claude Code's 13k-buffer-on-
+    # 200k-window ratio (~6.5%) applied to hive's default 32k window,
+    # with extra margin because hive's token estimator is char-based
+    # and less tight than Anthropic's own counting. Override via
+    # LoopConfig for larger windows.
+    compaction_buffer_tokens: int = 8_000
+    # Warning is emitted one buffer earlier so the user/telemetry gets
+    # a "we're close" signal without triggering a compaction pass.
+    compaction_warning_buffer_tokens: int = 12_000
+    store_prefix: str = ""
+
+    # Overflow margin for max_tool_calls_per_turn. Tool calls are only
+    # discarded when the count exceeds max_tool_calls_per_turn * (1 + margin).
+    tool_call_overflow_margin: float = 0.5
+
+    # Tool result context management.
+    max_tool_result_chars: int = 30_000
+    spillover_dir: str | None = None
+
+    # set_output value spilling.
+    max_output_value_chars: int = 2_000
+
+    # Stream retry.
+    max_stream_retries: int = 5
+    stream_retry_backoff_base: float = 2.0
+    stream_retry_max_delay: float = 60.0
+    # Persistent retry for capacity-class errors (429, 529, overloaded).
+    # Unlike the bounded retry above, these keep trying until the wall-clock
+    # budget below is exhausted — modelled after claude-code's withRetry.
+    # The loop still publishes a retry event each attempt so the UI can
+    # see progress. Set to 0 to disable and fall back to bounded retry.
+    capacity_retry_max_seconds: float = 600.0
+    capacity_retry_max_delay: float = 60.0
+
+    # Tool doom loop detection.
+    tool_doom_loop_threshold: int = 3
+
+    # Client-facing auto-block grace period.
+    cf_grace_turns: int = 1
+    # Worker auto-escalation: text-only turns before escalating to queen.
+    worker_escalation_grace_turns: int = 1
+    tool_doom_loop_enabled: bool = True
+    # Silent worker: consecutive tool-only turns (no user-facing text)
+    # before injecting a nudge to communicate progress.
+    silent_tool_streak_threshold: int = 5
+
+    # Per-tool-call timeout.
+    tool_call_timeout_seconds: float = 60.0
+
+    # LLM stream inactivity watchdog. If no stream event (delta, tool call,
+    # finish) arrives within this many seconds, the stream task is cancelled
+    # and a transient error is raised so the retry loop can back off and
+    # reconnect. Prevents agents from hanging forever on a silently dead
+    # HTTP connection (no provider heartbeat, no exception, just silence).
+    # Set to 0 to disable.
+    llm_stream_inactivity_timeout_seconds: float = 120.0
+
+    # Subagent delegation timeout (wall-clock max).
+    subagent_timeout_seconds: float = 3600.0
+
+    # Subagent inactivity timeout - only timeout if no activity for this duration.
+    # This resets whenever the subagent makes progress (tool calls, LLM responses).
+    # Set to 0 to use only the wall-clock timeout.
+    subagent_inactivity_timeout_seconds: float = 300.0
+
+    # Lifecycle hooks.
+    hooks: dict[str, list] | None = None
+
+    def __post_init__(self) -> None:
+        if self.hooks is None:
+            object.__setattr__(self, "hooks", {})
+
+
+@dataclass
+class HookContext:
+    """Context passed to every lifecycle hook."""
+
+    event: str
+    trigger: str | None
+    system_prompt: str
+
+
+@dataclass
+class HookResult:
+    """What a hook may return to modify node state."""
+
+    system_prompt: str | None = None
+    inject: str | None = None
+
+
+@dataclass
+class OutputAccumulator:
+    """Accumulates output key-value pairs with optional write-through persistence."""
+
+    values: dict[str, Any] = field(default_factory=dict)
+    store: ConversationStore | None = None
+    spillover_dir: str | None = None
+    max_value_chars: int = 0
+    run_id: str | None = None
+
+    async def set(self, key: str, value: Any) -> None:
+        """Set a key-value pair, auto-spilling large values to files."""
+        value = self._auto_spill(key, value)
+        self.values[key] = value
+        if self.store:
+            cursor = await self.store.read_cursor() or {}
+            outputs = cursor.get("outputs", {})
+            outputs[key] = value
+            cursor["outputs"] = outputs
+            await self.store.write_cursor(cursor)
+
+    def _auto_spill(self, key: str, value: Any) -> Any:
+        """Save large values to a file and return a reference string."""
+        if self.max_value_chars <= 0 or not self.spillover_dir:
+            return value
+
+        val_str = json.dumps(value, ensure_ascii=False) if not isinstance(value, str) else value
+        if len(val_str) <= self.max_value_chars:
+            return value
+
+        spill_path = Path(self.spillover_dir)
+        spill_path.mkdir(parents=True, exist_ok=True)
+        ext = ".json" if isinstance(value, (dict, list)) else ".txt"
+        filename = f"output_{key}{ext}"
+        write_content = (
+            json.dumps(value, indent=2, ensure_ascii=False)
+            if isinstance(value, (dict, list))
+            else str(value)
+        )
+        file_path = spill_path / filename
+        file_path.write_text(write_content, encoding="utf-8")
+        file_size = file_path.stat().st_size
+        logger.info(
+            "set_output value auto-spilled: key=%s, %d chars -> %s (%d bytes)",
+            key,
+            len(val_str),
+            filename,
+            file_size,
+        )
+        # Use absolute path so parent agents can find files from subagents
+        abs_path = str(file_path.resolve())
+        return (
+            f"[Saved to '{abs_path}' ({file_size:,} bytes). "
+            f"Use read_file(path='{abs_path}') "
+            f"to access full data.]"
+        )
+
+    def get(self, key: str) -> Any | None:
+        return self.values.get(key)
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.values)
+
+    def has_all_keys(self, required: list[str]) -> bool:
+        return all(key in self.values and self.values[key] is not None for key in required)
+
+    @classmethod
+    async def restore(
+        cls,
+        store: ConversationStore,
+        run_id: str | None = None,
+    ) -> OutputAccumulator:
+        cursor = await store.read_cursor()
+        values = cursor.get("outputs", {}) if cursor else {}
+        return cls(values=values, store=store, run_id=run_id)
+
+
+__all__ = [
+    "HookContext",
+    "HookResult",
+    "JudgeProtocol",
+    "JudgeVerdict",
+    "LoopConfig",
+    "OutputAccumulator",
+    "TriggerEvent",
+]

core/framework/agent_loop/prompting.py

@@ -0,0 +1,93 @@
+"""Prompt composition for agent loops.
+
+Builds canonical system prompts from AgentContext fields.
+Extracted from the former orchestrator/prompting module.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass(frozen=True)
+class PromptSpec:
+    identity_prompt: str = ""
+    focus_prompt: str = ""
+    narrative: str = ""
+    accounts_prompt: str = ""
+    skills_catalog_prompt: str = ""
+    protocols_prompt: str = ""
+    memory_prompt: str = ""
+    agent_type: str = "event_loop"
+    output_keys: tuple[str, ...] = ()
+
+
+def stamp_prompt_datetime(prompt: str) -> str:
+    local = datetime.now().astimezone()
+    stamp = f"Current date and time: {local.strftime('%Y-%m-%d %H:%M %Z (UTC%z)')}"
+    return f"{prompt}\n\n{stamp}" if prompt else stamp
+
+
+def build_prompt_spec(
+    ctx: Any,
+    *,
+    focus_prompt: str | None = None,
+    narrative: str | None = None,
+    memory_prompt: str | None = None,
+) -> PromptSpec:
+    resolved_memory = memory_prompt
+    if resolved_memory is None:
+        resolved_memory = getattr(ctx, "memory_prompt", "") or ""
+        dynamic = getattr(ctx, "dynamic_memory_provider", None)
+        if dynamic is not None:
+            try:
+                resolved_memory = dynamic() or ""
+            except Exception:
+                resolved_memory = getattr(ctx, "memory_prompt", "") or ""
+    return PromptSpec(
+        identity_prompt=ctx.identity_prompt or "",
+        focus_prompt=focus_prompt
+        if focus_prompt is not None
+        else (ctx.agent_spec.system_prompt or ""),
+        narrative=narrative if narrative is not None else (ctx.narrative or ""),
+        accounts_prompt=ctx.accounts_prompt or "",
+        skills_catalog_prompt=ctx.skills_catalog_prompt or "",
+        protocols_prompt=ctx.protocols_prompt or "",
+        memory_prompt=resolved_memory,
+        agent_type=ctx.agent_spec.agent_type,
+        output_keys=tuple(ctx.agent_spec.output_keys or ()),
+    )
+
+
+def build_system_prompt(spec: PromptSpec) -> str:
+    parts: list[str] = []
+    if spec.identity_prompt:
+        parts.append(spec.identity_prompt)
+    if spec.accounts_prompt:
+        parts.append(f"\n{spec.accounts_prompt}")
+    if spec.skills_catalog_prompt:
+        parts.append(f"\n{spec.skills_catalog_prompt}")
+    if spec.protocols_prompt:
+        parts.append(f"\n{spec.protocols_prompt}")
+    if spec.memory_prompt:
+        parts.append(f"\n{spec.memory_prompt}")
+    if spec.focus_prompt:
+        parts.append(f"\n{spec.focus_prompt}")
+    if spec.narrative:
+        parts.append(f"\n{spec.narrative}")
+    return "\n".join(parts)
+
+
+def build_system_prompt_for_context(
+    ctx: Any,
+    *,
+    focus_prompt: str | None = None,
+    narrative: str | None = None,
+    memory_prompt: str | None = None,
+) -> str:
+    spec = build_prompt_spec(
+        ctx, focus_prompt=focus_prompt, narrative=narrative, memory_prompt=memory_prompt
+    )
+    return build_system_prompt(spec)

core/framework/agent_loop/types.py

@@ -0,0 +1,267 @@
+"""Core types for the agent loop — the execution primitive of the colony.
+
+AgentSpec:    Declarative definition of what an agent does.
+AgentContext: Everything an agent loop needs to execute.
+AgentResult:  What comes out of an agent loop execution.
+AgentProtocol: Interface that all agent implementations must satisfy.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from framework.llm.provider import LLMProvider, Tool
+from framework.tracker.decision_tracker import DecisionTracker
+
+
+class AgentSpec(BaseModel):
+    """Declarative definition of an agent's capabilities and configuration.
+
+    This is the blueprint from which AgentLoop instances are created.
+    Workers in a colony are exact copies of the queen's AgentSpec.
+    """
+
+    id: str
+    name: str
+    description: str
+
+    agent_type: str = Field(
+        default="event_loop",
+        description="Type: 'event_loop' (recommended), 'gcu' (browser automation).",
+    )
+
+    input_keys: list[str] = Field(
+        default_factory=list,
+        description="Keys this agent reads from input data",
+    )
+    output_keys: list[str] = Field(
+        default_factory=list,
+        description="Keys this agent produces as output",
+    )
+    nullable_output_keys: list[str] = Field(
+        default_factory=list,
+        description="Output keys that can be None without triggering validation errors",
+    )
+
+    input_schema: dict[str, dict] = Field(
+        default_factory=dict,
+        description="Optional schema for input validation.",
+    )
+    output_schema: dict[str, dict] = Field(
+        default_factory=dict,
+        description="Optional schema for output validation.",
+    )
+
+    system_prompt: str | None = Field(default=None, description="System prompt for the LLM")
+    tools: list[str] = Field(default_factory=list, description="Tool names this agent can use")
+    tool_access_policy: str = Field(
+        default="explicit",
+        description=(
+            "'all' = all tools from registry, "
+            "'explicit' = only tools listed in `tools` (default), "
+            "'none' = no tools at all."
+        ),
+    )
+    model: str | None = Field(default=None, description="Specific model override")
+
+    function: str | None = Field(default=None, description="Function name or path")
+    routes: dict[str, str] = Field(default_factory=dict, description="Condition -> target mapping")
+
+    max_retries: int = Field(default=3)
+    retry_on: list[str] = Field(default_factory=list, description="Error types to retry on")
+
+    max_visits: int = Field(
+        default=0,
+        description=(
+            "Max times this agent executes in one colony run. "
+            "0 = unlimited. Set >1 for one-shot agents."
+        ),
+    )
+
+    output_model: type[BaseModel] | None = Field(
+        default=None,
+        description="Optional Pydantic model for validating LLM output.",
+    )
+    max_validation_retries: int = Field(
+        default=2,
+        description="Maximum retries when Pydantic validation fails",
+    )
+
+    client_facing: bool = Field(
+        default=False,
+        description="Deprecated — the queen is intrinsically interactive.",
+    )
+
+    success_criteria: str | None = Field(
+        default=None,
+        description="Natural-language criteria for phase completion.",
+    )
+
+    skip_judge: bool = Field(
+        default=False,
+        description="When True, the implicit judge is bypassed entirely.",
+    )
+
+    model_config = {"extra": "allow", "arbitrary_types_allowed": True}
+
+    def is_queen(self) -> bool:
+        return self.id == "queen"
+
+    def supports_direct_user_io(self) -> bool:
+        return self.is_queen()
+
+
+def deprecated_client_facing_warning(spec: AgentSpec) -> str | None:
+    if spec.client_facing and not spec.is_queen():
+        return (
+            f"Agent '{spec.id}' sets deprecated client_facing=True. "
+            "Non-queen direct human I/O is no longer supported; route worker "
+            "questions and approvals through queen escalation instead."
+        )
+    return None
+
+
+def warn_if_deprecated_client_facing(spec: AgentSpec) -> None:
+    import logging
+
+    warning = deprecated_client_facing_warning(spec)
+    if warning:
+        logging.getLogger(__name__).warning(warning)
+
+
+@dataclass
+class AgentContext:
+    """Everything an agent loop needs to execute.
+
+    Passed to every agent implementation and provides:
+    - Runtime (for decision logging)
+    - LLM access
+    - Tools
+    - Goal context
+    - Execution metadata
+    """
+
+    runtime: DecisionTracker
+
+    agent_id: str
+    agent_spec: AgentSpec
+
+    input_data: dict[str, Any] = field(default_factory=dict)
+
+    llm: LLMProvider | None = None
+    available_tools: list[Tool] = field(default_factory=list)
+
+    goal_context: str = ""
+    goal: Any = None
+
+    max_tokens: int = 4096
+
+    attempt: int = 1
+    max_attempts: int = 3
+
+    runtime_logger: Any = None
+    pause_event: Any = None
+
+    accounts_prompt: str = ""
+
+    identity_prompt: str = ""
+    narrative: str = ""
+    memory_prompt: str = ""
+
+    event_triggered: bool = False
+
+    execution_id: str = ""
+    run_id: str = ""
+
+    @property
+    def effective_run_id(self) -> str | None:
+        return self.run_id or None
+
+    stream_id: str = ""
+
+    dynamic_tools_provider: Any = None
+    dynamic_prompt_provider: Any = None
+    dynamic_memory_provider: Any = None
+
+    skills_catalog_prompt: str = ""
+    protocols_prompt: str = ""
+    skill_dirs: list[str] = field(default_factory=list)
+    default_skill_batch_nudge: str | None = None
+    default_skill_warn_ratio: float | None = None
+
+    iteration_metadata_provider: Any = None
+
+    @property
+    def is_queen_stream(self) -> bool:
+        return self.stream_id == "queen" or self.agent_spec.is_queen()
+
+    @property
+    def emits_client_io(self) -> bool:
+        return self.is_queen_stream
+
+    @property
+    def supports_direct_user_io(self) -> bool:
+        return self.is_queen_stream and not self.event_triggered
+
+
+@dataclass
+class AgentResult:
+    """Output of an agent loop execution."""
+
+    success: bool
+    output: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+
+    next_agent: str | None = None
+    route_reason: str | None = None
+
+    tokens_used: int = 0
+    latency_ms: int = 0
+
+    validation_errors: list[str] = field(default_factory=list)
+
+    conversation: Any = None
+
+    # Machine-readable reason the loop stopped (see LoopExitReason in
+    # agent_loop/internals/types.py). "?" means the loop didn't set one,
+    # which should itself be treated as a diagnostic.
+    exit_reason: str = "?"
+    # Counters for reliability events surfaced during this execution.
+    # Populated from the loop's TaskRegistry-style counters at return
+    # time so callers can spot recurring failure modes without tailing
+    # logs. Keys are stable strings; missing keys mean "zero".
+    reliability_stats: dict[str, int] = field(default_factory=dict)
+
+    def to_summary(self, spec: Any = None) -> str:
+        if not self.success:
+            return f"Failed: {self.error}"
+
+        if not self.output:
+            return "Completed (no output)"
+
+        parts = [f"Completed with {len(self.output)} outputs:"]
+        for key, value in list(self.output.items())[:5]:
+            value_str = str(value)[:100]
+            if len(str(value)) > 100:
+                value_str += "..."
+            parts.append(f"  - {key}: {value_str}")
+        return "\n".join(parts)
+
+
+class AgentProtocol(ABC):
+    """Interface all agent implementations must satisfy."""
+
+    @abstractmethod
+    async def execute(self, ctx: AgentContext) -> AgentResult:
+        pass
+
+    def validate_input(self, ctx: AgentContext) -> list[str]:
+        errors = []
+        for key in ctx.agent_spec.input_keys:
+            if key not in ctx.input_data:
+                errors.append(f"Missing required input: {key}")
+        return errors

core/framework/agents/__init__.py

@@ -8,6 +8,10 @@ FRAMEWORK_AGENTS_DIR = Path(__file__).parent
 def list_framework_agents() -> list[Path]:
     """List all framework agent directories."""
     return sorted(
-        [p for p in FRAMEWORK_AGENTS_DIR.iterdir() if p.is_dir() and (p / "agent.py").exists()],
+        [
+            p
+            for p in FRAMEWORK_AGENTS_DIR.iterdir()
+            if p.is_dir() and ((p / "agent.json").exists() or (p / "agent.py").exists())
+        ],
         key=lambda p: p.name,
     )

core/framework/agents/credential_tester/__main__.py

@@ -1,8 +1,6 @@
 """CLI entry point for Credential Tester agent."""
 
 import asyncio
-import logging
-import sys
 
 import click
 
@@ -10,13 +8,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 +50,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

@@ -16,23 +16,30 @@ after the user picks an account programmatically.
 
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from framework.graph import Goal, NodeSpec, SuccessCriterion
-from framework.graph.checkpoint_config import CheckpointConfig
-from framework.graph.edge import GraphSpec
-from framework.graph.executor import ExecutionResult
+from framework.config import get_max_context_tokens
+from framework.host.agent_host import AgentHost
+from framework.host.execution_manager import EntryPointSpec
 from framework.llm import LiteLLMProvider
-from framework.runner.tool_registry import ToolRegistry
-from framework.runtime.agent_runtime import AgentRuntime, create_agent_runtime
-from framework.runtime.execution_stream import EntryPointSpec
+from framework.loader.mcp_registry import MCPRegistry
+from framework.loader.tool_registry import ToolRegistry
+from framework.orchestrator import Goal, NodeSpec, SuccessCriterion
+from framework.orchestrator.checkpoint_config import CheckpointConfig
+from framework.orchestrator.edge import GraphSpec
+from framework.orchestrator.orchestrator import ExecutionResult
 
 from .config import default_config
 from .nodes import build_tester_node
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
-    from framework.runner import AgentRunner
+    from framework.loader import AgentLoader
+
+logger = logging.getLogger(__name__)
 
 # ---------------------------------------------------------------------------
 # Goal
@@ -106,7 +113,11 @@ def _list_aden_accounts() -> list[dict]:
             for c in integrations
             if c.status == "active"
         ]
+    except (ImportError, OSError) as exc:
+        logger.debug("Could not list Aden accounts: %s", exc)
+        return []
     except Exception:
+        logger.warning("Unexpected error listing Aden accounts", exc_info=True)
         return []
 
 
@@ -118,7 +129,11 @@ def _list_local_accounts() -> list[dict]:
         return [
             info.to_account_dict() for info in LocalCredentialRegistry.default().list_accounts()
         ]
+    except ImportError as exc:
+        logger.debug("Local credential registry unavailable: %s", exc)
+        return []
     except Exception:
+        logger.warning("Unexpected error listing local accounts", exc_info=True)
         return []
 
 
@@ -139,7 +154,11 @@ def _list_env_fallback_accounts() -> list[dict]:
         from framework.credentials.storage import EncryptedFileStorage
 
         encrypted_ids: set[str] = set(EncryptedFileStorage().list_all())
+    except (ImportError, OSError) as exc:
+        logger.debug("Could not read encrypted store: %s", exc)
+        encrypted_ids = set()
     except Exception:
+        logger.warning("Unexpected error reading encrypted store", exc_info=True)
         encrypted_ids = set()
 
     def _is_configured(cred_name: str, spec) -> bool:
@@ -214,7 +233,7 @@ requires_account_selection = True
 """Signal TUI to show account picker before starting the agent."""
 
 
-def configure_for_account(runner: AgentRunner, account: dict) -> None:
+def configure_for_account(runner: AgentLoader, account: dict) -> None:
     """Scope the tester node's tools to the selected provider.
 
     Handles both Aden accounts (account= routing) and local accounts
@@ -299,12 +318,14 @@ def _activate_local_account(credential_id: str, alias: str) -> None:
 
             if key:
                 os.environ[spec.env_var] = key
+    except (ImportError, KeyError, OSError) as exc:
+        logger.debug("Could not inject credentials: %s", exc)
     except Exception:
-        pass
+        logger.warning("Unexpected error injecting credentials", exc_info=True)
 
 
 def _configure_aden_node(
-    runner: AgentRunner,
+    runner: AgentLoader,
     provider: str,
     alias: str,
     detail: str,
@@ -347,7 +368,7 @@ or any other identifier — always use the alias exactly as shown.
 
 
 def _configure_local_node(
-    runner: AgentRunner,
+    runner: AgentLoader,
     provider: str,
     alias: str,
     identity: dict,
@@ -455,7 +476,6 @@ identity_prompt = (
 loop_config = {
     "max_iterations": 50,
     "max_tool_calls_per_turn": 30,
-    "max_history_tokens": 32000,
 }
 
 # ---------------------------------------------------------------------------
@@ -477,7 +497,7 @@ class CredentialTesterAgent:
     def __init__(self, config=None):
         self.config = config or default_config
         self._selected_account: dict | None = None
-        self._agent_runtime: AgentRuntime | None = None
+        self._agent_runtime: AgentHost | None = None
         self._tool_registry: ToolRegistry | None = None
         self._storage_path: Path | None = None
 
@@ -541,7 +561,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=(
@@ -563,6 +583,23 @@ class CredentialTesterAgent:
         if mcp_config_path.exists():
             self._tool_registry.load_mcp_config(mcp_config_path)
 
+        try:
+            agent_dir = Path(__file__).parent
+            registry = MCPRegistry()
+            registry.initialize()
+            if (agent_dir / "mcp_registry.json").is_file():
+                self._tool_registry.set_mcp_registry_agent_path(agent_dir)
+            registry_configs, selection_max_tools = registry.load_agent_selection(agent_dir)
+            if registry_configs:
+                self._tool_registry.load_registry_servers(
+                    registry_configs,
+                    preserve_existing_tools=True,
+                    log_collisions=True,
+                    max_tools=selection_max_tools,
+                )
+        except Exception:
+            logger.warning("MCP registry config failed to load", exc_info=True)
+
         extra_kwargs = getattr(self.config, "extra_kwargs", {}) or {}
         llm = LiteLLMProvider(
             model=self.config.model,
@@ -576,7 +613,7 @@ class CredentialTesterAgent:
 
         graph = self._build_graph()
 
-        self._agent_runtime = create_agent_runtime(
+        self._agent_runtime = AgentHost(
             graph=graph,
             goal=goal,
             storage_path=self._storage_path,

core/framework/agents/credential_tester/mcp_servers.json

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

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

@@ -1,6 +1,6 @@
 """Node definitions for Credential Tester agent."""
 
-from framework.graph import NodeSpec
+from framework.orchestrator import NodeSpec
 
 
 def build_tester_node(

core/framework/agents/discovery.py

@@ -0,0 +1,279 @@
+"""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 WorkerEntry:
+    """A single worker within a colony."""
+
+    name: str
+    config_path: Path
+    description: str = ""
+    tool_count: int = 0
+    task: str = ""
+    spawned_at: str = ""
+    queen_name: str = ""
+    colony_name: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "config_path": str(self.config_path),
+            "description": self.description,
+            "tool_count": self.tool_count,
+            "task": self.task,
+            "spawned_at": self.spawned_at,
+            "queen_name": self.queen_name,
+            "colony_name": self.colony_name,
+        }
+
+
+@dataclass
+class AgentEntry:
+    """Lightweight agent metadata for the picker / API discover endpoint."""
+
+    path: Path
+    name: str
+    description: str
+    category: str
+    session_count: int = 0
+    run_count: int = 0
+    node_count: int = 0
+    tool_count: int = 0
+    tags: list[str] = field(default_factory=list)
+    last_active: str | None = None
+    workers: list[WorkerEntry] = field(default_factory=list)
+
+
+def _get_last_active(agent_path: Path) -> str | None:
+    """Return the most recent updated_at timestamp across all sessions.
+
+    Checks both worker sessions (``~/.hive/agents/{name}/sessions/``) and
+    queen sessions (``~/.hive/agents/queens/default/sessions/``) whose
+    ``meta.json`` references the same *agent_path*.
+    """
+    from datetime import datetime
+
+    agent_name = agent_path.name
+    latest: str | None = None
+
+    # 1. Worker sessions
+    sessions_dir = Path.home() / ".hive" / "agents" / agent_name / "sessions"
+    if sessions_dir.exists():
+        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
+
+    # 2. Queen sessions (scan all queen identity directories)
+    from framework.config import QUEENS_DIR
+
+    if QUEENS_DIR.exists():
+        resolved = agent_path.resolve()
+        for queen_dir in QUEENS_DIR.iterdir():
+            if not queen_dir.is_dir():
+                continue
+            sessions_dir = queen_dir / "sessions"
+            if not sessions_dir.exists():
+                continue
+            for d in sessions_dir.iterdir():
+                if not d.is_dir():
+                    continue
+                meta_file = d / "meta.json"
+                if not meta_file.exists():
+                    continue
+                try:
+                    meta = json.loads(meta_file.read_text(encoding="utf-8"))
+                    stored = meta.get("agent_path")
+                    if not stored or Path(stored).resolve() != resolved:
+                        continue
+                    ts = datetime.fromtimestamp(d.stat().st_mtime).isoformat()
+                    if 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 _count_runs(agent_name: str) -> int:
+    """Count unique run_ids across all sessions for an agent."""
+    sessions_dir = Path.home() / ".hive" / "agents" / agent_name / "sessions"
+    if not sessions_dir.exists():
+        return 0
+    run_ids: set[str] = set()
+    for session_dir in sessions_dir.iterdir():
+        if not session_dir.is_dir() or not session_dir.name.startswith("session_"):
+            continue
+        # runs.jsonl lives inside workspace subdirectories
+        for runs_file in session_dir.rglob("runs.jsonl"):
+            try:
+                for line in runs_file.read_text(encoding="utf-8").splitlines():
+                    line = line.strip()
+                    if not line:
+                        continue
+                    record = json.loads(line)
+                    rid = record.get("run_id")
+                    if rid:
+                        run_ids.add(rid)
+            except Exception:
+                continue
+    return len(run_ids)
+
+
+_EXCLUDED_JSON_STEMS = {"agent", "flowchart", "triggers", "configuration", "metadata"}
+
+
+def _is_colony_dir(path: Path) -> bool:
+    """Check if a directory is a colony with worker config files."""
+    if not path.is_dir():
+        return False
+    return any(
+        f.suffix == ".json"
+        and f.stem not in _EXCLUDED_JSON_STEMS
+        for f in path.iterdir()
+        if f.is_file()
+    )
+
+
+def _find_worker_configs(colony_dir: Path) -> list[Path]:
+    """Find all worker config JSON files in a colony directory."""
+    return sorted(
+        p
+        for p in colony_dir.iterdir()
+        if p.is_file()
+        and p.suffix == ".json"
+        and p.stem not in _EXCLUDED_JSON_STEMS
+    )
+
+
+def _extract_agent_stats(agent_path: Path) -> tuple[int, int, list[str]]:
+    """Extract worker count, tool count, and tags from a colony directory."""
+    tool_count, tags = 0, []
+
+    worker_configs = _find_worker_configs(agent_path)
+    if worker_configs:
+        all_tools: set[str] = set()
+        for wc_path in worker_configs:
+            try:
+                data = json.loads(wc_path.read_text(encoding="utf-8"))
+                if isinstance(data, dict):
+                    tools = data.get("tools", [])
+                    if isinstance(tools, list):
+                        all_tools.update(tools)
+            except Exception:
+                pass
+        return len(worker_configs), len(all_tools), tags
+
+    return 0, 0, tags
+
+
+def discover_agents() -> dict[str, list[AgentEntry]]:
+    """Discover agents from all known sources grouped by category."""
+    from framework.config import COLONIES_DIR
+
+    groups: dict[str, list[AgentEntry]] = {}
+    sources = [
+        ("Your Agents", COLONIES_DIR),
+    ]
+
+    # Track seen agent directory names to avoid duplicates when the same
+    # agent exists in both colonies/ and exports/ (colonies takes priority).
+    _seen_agent_names: set[str] = set()
+
+    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_colony_dir(path):
+                continue
+            if path.name in _seen_agent_names:
+                continue
+            _seen_agent_names.add(path.name)
+
+            config_fallback_name = path.name.replace("_", " ").title()
+            name = config_fallback_name
+            desc = ""
+
+            # Read colony metadata for queen provenance
+            colony_queen_name = ""
+            metadata_path = path / "metadata.json"
+            if metadata_path.exists():
+                try:
+                    mdata = json.loads(metadata_path.read_text(encoding="utf-8"))
+                    colony_queen_name = mdata.get("queen_name", "")
+                except Exception:
+                    pass
+
+            worker_entries: list[WorkerEntry] = []
+            worker_configs = _find_worker_configs(path)
+            for wc_path in worker_configs:
+                try:
+                    data = json.loads(wc_path.read_text(encoding="utf-8"))
+                    if isinstance(data, dict):
+                        w = WorkerEntry(
+                            name=data.get("name", wc_path.stem),
+                            config_path=wc_path,
+                            description=data.get("description", ""),
+                            tool_count=len(data.get("tools", [])),
+                            task=data.get("goal", {}).get("description", ""),
+                            spawned_at=data.get("spawned_at", ""),
+                            queen_name=colony_queen_name,
+                            colony_name=path.name,
+                        )
+                        worker_entries.append(w)
+                        if not desc:
+                            desc = data.get("description", "")
+                except Exception:
+                    pass
+
+            node_count = len(worker_entries)
+            all_tools: set[str] = set()
+            for w in worker_entries:
+                pass  # tool_count already per-worker
+            tool_count = max((w.tool_count for w in worker_entries), default=0)
+
+            entries.append(
+                AgentEntry(
+                    path=path,
+                    name=name,
+                    description=desc,
+                    category=category,
+                    session_count=_count_sessions(path.name),
+                    run_count=_count_runs(path.name),
+                    node_count=node_count,
+                    tool_count=tool_count,
+                    tags=[],
+                    last_active=_get_last_active(path),
+                    workers=worker_entries,
+                )
+            )
+        if entries:
+            existing = groups.get(category, [])
+            existing.extend(entries)
+            groups[category] = existing
+
+    return groups

core/framework/agents/hive_coder/__main__.py

@@ -1,60 +0,0 @@
-"""CLI entry point for Hive Coder agent."""
-
-import json
-import logging
-import sys
-
-import click
-
-from .agent import entry_node, goal, nodes
-from .config import metadata
-
-
-def setup_logging(verbose=False, debug=False):
-    """Configure logging for execution visibility."""
-    if debug:
-        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
-    elif verbose:
-        level, fmt = logging.INFO, "%(message)s"
-    else:
-        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
-    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
-    logging.getLogger("framework").setLevel(level)
-
-
-@click.group()
-@click.version_option(version="1.0.0")
-def cli():
-    """Hive Coder — Build Hive agent packages from natural language."""
-    pass
-
-
-@cli.command()
-@click.option("--json", "output_json", is_flag=True)
-def info(output_json):
-    """Show agent information."""
-    info_data = {
-        "name": metadata.name,
-        "version": metadata.version,
-        "description": metadata.description,
-        "goal": {
-            "name": goal.name,
-            "description": goal.description,
-        },
-        "nodes": [n.id for n in nodes],
-        "entry_node": entry_node,
-        "client_facing_nodes": [n.id for n in nodes if n.client_facing],
-    }
-    if output_json:
-        click.echo(json.dumps(info_data, indent=2))
-    else:
-        click.echo(f"Agent: {info_data['name']}")
-        click.echo(f"Version: {info_data['version']}")
-        click.echo(f"Description: {info_data['description']}")
-        click.echo(f"\nNodes: {', '.join(info_data['nodes'])}")
-        click.echo(f"Client-facing: {', '.join(info_data['client_facing_nodes'])}")
-        click.echo(f"Entry: {info_data['entry_node']}")
-
-
-if __name__ == "__main__":
-    cli()

core/framework/agents/hive_coder/agent.py

@@ -1,153 +0,0 @@
-"""Agent graph construction for Hive Coder."""
-
-from framework.graph import Constraint, Goal, SuccessCriterion
-from framework.graph.edge import GraphSpec
-
-from .nodes import coder_node, queen_node
-
-# Goal definition
-goal = Goal(
-    id="hive-coder",
-    name="Hive Agent Builder",
-    description=(
-        "Build complete, validated Hive agent packages from natural language "
-        "specifications. Produces production-ready Python packages with goals, "
-        "nodes, edges, system prompts, MCP configuration, and tests."
-    ),
-    success_criteria=[
-        SuccessCriterion(
-            id="valid-package",
-            description="Generated agent package passes structural validation",
-            metric="validation_pass",
-            target="true",
-            weight=0.30,
-        ),
-        SuccessCriterion(
-            id="complete-files",
-            description=(
-                "All required files generated: agent.py, config.py, "
-                "nodes/__init__.py, __init__.py, __main__.py, mcp_servers.json"
-            ),
-            metric="file_count",
-            target=">=6",
-            weight=0.25,
-        ),
-        SuccessCriterion(
-            id="user-satisfaction",
-            description="User reviews and approves the generated agent",
-            metric="user_approval",
-            target="true",
-            weight=0.25,
-        ),
-        SuccessCriterion(
-            id="framework-compliance",
-            description=(
-                "Generated code follows framework patterns: STEP 1/STEP 2 "
-                "for client-facing and correct imports"
-            ),
-            metric="pattern_compliance",
-            target="100%",
-            weight=0.20,
-        ),
-    ],
-    constraints=[
-        Constraint(
-            id="dynamic-tool-discovery",
-            description=(
-                "Always discover available tools dynamically via "
-                "list_agent_tools before referencing tools in agent designs"
-            ),
-            constraint_type="hard",
-            category="correctness",
-        ),
-        Constraint(
-            id="no-fabricated-tools",
-            description="Only reference tools that exist in hive-tools MCP",
-            constraint_type="hard",
-            category="correctness",
-        ),
-        Constraint(
-            id="valid-python",
-            description="All generated Python files must be syntactically correct",
-            constraint_type="hard",
-            category="correctness",
-        ),
-        Constraint(
-            id="self-verification",
-            description="Run validation after writing code; fix errors before presenting",
-            constraint_type="hard",
-            category="quality",
-        ),
-    ],
-)
-
-# Nodes: primary coder node only.  The queen runs as an independent
-# GraphExecutor with queen_node — not as part of this graph.
-nodes = [coder_node]
-
-# No edges needed — single event_loop node
-edges = []
-
-# Graph configuration
-entry_node = "coder"
-entry_points = {"start": "coder"}
-pause_nodes = []
-terminal_nodes = []  # Coder node has output_keys and can terminate
-
-# No async entry points needed — the queen is now an independent executor,
-# not a secondary graph receiving events via add_graph().
-async_entry_points = []
-
-# Module-level variables read by AgentRunner.load()
-conversation_mode = "continuous"
-identity_prompt = (
-    "You are Hive Coder, the best agent-building coding agent on the planet. "
-    "You deeply understand the Hive agent framework at the source code level "
-    "and produce production-ready agent packages from natural language. "
-    "You can dynamically discover available framework tools, inspect runtime "
-    "sessions and checkpoints from agents you build, and run their test suites. "
-    "You follow coding agent discipline: read before writing, verify "
-    "assumptions by reading actual code, adhere to project conventions, "
-    "self-verify with validation, and fix your own errors. You are concise, "
-    "direct, and technically rigorous. No emojis. No fluff."
-)
-loop_config = {
-    "max_iterations": 100,
-    "max_tool_calls_per_turn": 30,
-    "max_history_tokens": 32000,
-}
-
-
-# ---------------------------------------------------------------------------
-# Queen graph — runs as an independent persistent conversation in the TUI.
-# Loaded by _load_judge_and_queen() in app.py, NOT by AgentRunner.
-# ---------------------------------------------------------------------------
-
-queen_goal = Goal(
-    id="queen-manager",
-    name="Queen Manager",
-    description=(
-        "Manage the worker agent lifecycle and serve as the user's primary "
-        "interactive interface. Triage health escalations from the judge."
-    ),
-    success_criteria=[],
-    constraints=[],
-)
-
-queen_graph = GraphSpec(
-    id="queen-graph",
-    goal_id=queen_goal.id,
-    version="1.0.0",
-    entry_node="queen",
-    entry_points={"start": "queen"},
-    terminal_nodes=[],
-    pause_nodes=[],
-    nodes=[queen_node],
-    edges=[],
-    conversation_mode="continuous",
-    loop_config={
-        "max_iterations": 999_999,
-        "max_tool_calls_per_turn": 30,
-        "max_history_tokens": 32000,
-    },
-)

core/framework/agents/hive_coder/mcp_servers.json

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

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

@@ -1,933 +0,0 @@
-"""Node definitions for Hive Coder agent."""
-
-from pathlib import Path
-
-from framework.graph import NodeSpec
-
-# Load reference docs at import time so they're always in the system prompt.
-# No voluntary read_file() calls needed — the LLM gets everything upfront.
-_ref_dir = Path(__file__).parent.parent / "reference"
-_framework_guide = (_ref_dir / "framework_guide.md").read_text(encoding="utf-8")
-_anti_patterns = (_ref_dir / "anti_patterns.md").read_text(encoding="utf-8")
-_gcu_guide_path = _ref_dir / "gcu_guide.md"
-_gcu_guide = _gcu_guide_path.read_text(encoding="utf-8") if _gcu_guide_path.exists() else ""
-
-
-def _is_gcu_enabled() -> bool:
-    try:
-        from framework.config import get_gcu_enabled
-
-        return get_gcu_enabled()
-    except Exception:
-        return False
-
-
-def _build_appendices() -> str:
-    parts = (
-        "\n\n# Appendix: Framework Reference\n\n"
-        + _framework_guide
-        + "\n\n# Appendix: Anti-Patterns\n\n"
-        + _anti_patterns
-    )
-    return parts
-
-
-# Shared appendices — appended to every coding node's system prompt.
-_appendices = _build_appendices()
-
-# GCU first-class section for building phase (when GCU is enabled).
-# This is placed prominently in the main prompt body, not as an appendix.
-_gcu_building_section = (
-    ("\n\n# GCU Nodes — Browser Automation\n\n" + _gcu_guide)
-    if _is_gcu_enabled() and _gcu_guide
-    else ""
-)
-
-# Tools available to both coder (worker) and queen.
-_SHARED_TOOLS = [
-    # File I/O
-    "read_file",
-    "write_file",
-    "edit_file",
-    "hashline_edit",
-    "list_directory",
-    "search_files",
-    "run_command",
-    "undo_changes",
-    # Meta-agent
-    "list_agent_tools",
-    "validate_agent_package",
-    "list_agents",
-    "list_agent_sessions",
-    "list_agent_checkpoints",
-    "get_agent_checkpoint",
-    "initialize_agent_package",
-]
-
-# Queen phase-specific tool sets.
-# Building phase: full coding + agent construction tools.
-_QUEEN_BUILDING_TOOLS = _SHARED_TOOLS + [
-    "load_built_agent",
-    "list_credentials",
-]
-
-# Staging phase: agent loaded but not yet running — inspect, configure, launch.
-_QUEEN_STAGING_TOOLS = [
-    # Read-only (inspect agent files, logs)
-    "read_file",
-    "list_directory",
-    "search_files",
-    "run_command",
-    # Agent inspection
-    "list_credentials",
-    "get_worker_status",
-    # Launch or go back
-    "run_agent_with_input",
-    "stop_worker_and_edit",
-]
-
-# Running phase: worker is executing — monitor and control.
-_QUEEN_RUNNING_TOOLS = [
-    # Read-only coding (for inspecting logs, files)
-    "read_file",
-    "list_directory",
-    "search_files",
-    "run_command",
-    # Credentials
-    "list_credentials",
-    # Worker lifecycle
-    "stop_worker",
-    "stop_worker_and_edit",
-    "get_worker_status",
-    "inject_worker_message",
-    # Monitoring
-    "get_worker_health_summary",
-    "notify_operator",
-]
-
-
-# ---------------------------------------------------------------------------
-# Shared agent-building knowledge: core mandates, tool docs, meta-agent
-# capabilities, and workflow phases 1-6.  Both the coder (worker) and
-# queen compose their system prompts from this block + role-specific
-# additions.
-# ---------------------------------------------------------------------------
-
-_package_builder_knowledge = """\
-**A responsible engineer doesn't jump into building. First, \
-understand the problem and be transparent about what the framework can and cannot do.**
-
-Use the user's selection (or their custom description if they chose "Other") \
-as context when shaping the goal below. If the user already described \
-what they want before this step, skip the question and proceed directly.
-
-# Core Mandates
-- **DO NOT propose a complete goal on your own.** Instead, \
-collaborate with the user to define it.
-- **Verify assumptions.** Never assume a class, import, or pattern \
-exists. Read actual source to confirm. Search if unsure.
-- **Discover tools dynamically.** NEVER reference tools from static \
-docs. Always run list_agent_tools() to see what actually exists.
-- **Self-verify.** After writing code, run validation and tests. Fix \
-errors yourself. Don't declare success until validation passes.
-
-# Tools
-## Paths (MANDATORY)
-**Always use RELATIVE paths**
-(e.g. `exports/agent_name/config.py`, `exports/agent_name/nodes/__init__.py`).
-**Never use absolute paths** like `/mnt/data/...` or `/workspace/...` — they fail.
-The project root is implicit.
-
-## File I/O
-- read_file(path, offset?, limit?, hashline?) — read with line numbers; \
-hashline=True for N:hhhh|content anchors (use with hashline_edit)
-- write_file(path, content) — create/overwrite, auto-mkdir
-- edit_file(path, old_text, new_text, replace_all?) — fuzzy-match edit
-- hashline_edit(path, edits, auto_cleanup?, encoding?) — anchor-based \
-editing using N:hhhh refs from read_file(hashline=True). Ops: set_line, \
-replace_lines, insert_after, insert_before, replace, append
-- list_directory(path, recursive?) — list contents
-- search_files(pattern, path?, include?, hashline?) — regex search; \
-hashline=True for anchors in results
-- run_command(command, cwd?, timeout?) — shell execution
-- 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.
-- 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
-- list_agent_sessions(agent_name, status?, limit?) — list sessions
-- list_agent_checkpoints(agent_name, session_id) — list checkpoints
-- get_agent_checkpoint(agent_name, session_id, checkpoint_id?) — load checkpoint
-
-# Meta-Agent Capabilities
-
-You are not just a file writer. You have deep integration with the \
-Hive framework:
-
-## Tool Discovery (MANDATORY before designing)
-Before designing any agent, run list_agent_tools() with NO arguments \
-to see ALL available tools (names + descriptions, grouped by category). \
-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
-
-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.
-
-## Post-Build Validation
-After writing agent code, run a single comprehensive check:
-  validate_agent_package("{name}")
-This runs class validation, runner load, tool validation, and tests \
-in one call. Do NOT run these steps individually.
-
-## Debugging Built Agents
-When a user says "my agent is failing" or "debug this agent":
-1. list_agent_sessions("{agent_name}") — find the session
-2. get_worker_status(focus="issues") — check for problems
-3. list_agent_checkpoints / get_agent_checkpoint — trace execution
-
-# Agent Building Workflow
-
-You operate in a continuous loop. The user describes what they want, \
-you build it. No rigid phases — use judgment. But the general flow is:
-
-## 1: Fast Discovery (3-6 Turns)
-
-**The core principle**: Discovery should feel like progress, not paperwork. \
-The stakeholder should walk away feeling like you understood them faster \
-than anyone else would have.
-
-**Communication sytle**: Be concise. Say less. Mean more. Impatient stakeholders \
-don't want a wall of text — they want to know you get it. Every sentence you say \
-should either move the conversation forward or prove you understood something. \
-If it does neither, cut it.
-
-**Ask Question Rules: Respect Their Time.** Every question must earn its place by:
-1. **Preventing a costly wrong turn** — you're about to build the wrong thing
-2. **Unlocking a shortcut** — their answer lets you simplify the design
-3. **Surfacing a dealbreaker** — there's a constraint that changes everything
-4. **Provide Options** - Provide options to your questions if possible, \
-but also always allow the user to type something beyong the options.
-
-If a question doesn't do one of these, don't ask it. Make an assumption, state it, and move on.
-
----
-
-### 1.1: Let Them Talk, But Listen Like an Solution Architect
-
-When the stakeholder describes what they want, mentally construct:
-
-- **The pain**: What about today's situation is broken, slow, or missing?
-- **The actors**: Who are the people/systems involved?
-- **The trigger**: What kicks off the workflow?
-- **The core loop**: What's the main thing that happens repeatedly?
-- **The output**: What's the valuable thing produced at the end?
-
----
-
-### 1.2: Use Domain Knowledge to Fill In the Blanks
-
-You have broad knowledge of how systems work. Use it aggressively.
-
-If they say "I need a research agent," you already know it probably involves: \
-search, summarization, source tracking, and iteration. Don't ask about each — \
-use them as your starting mental model and let their specifics override your defaults.
-
-If they say "I need to monitor files and alert me," you know this probably involves: \
-watch patterns, triggers, notifications, and state tracking.
-
----
-
-### 1.3: Play Back a Proposed Model (Not a List of Questions)
-
-After listening, present a **concrete picture** of what you think they need. \
-Make it specific enough that they can spot what's wrong. \
-Can you ASCII to show the user
-
-**Pattern: "Here's what I heard — tell me where I'm off"**
-
-> "OK here's how I'm picturing this: [User type] needs to [core action]. \
-Right now they're [current painful workflow]. \
-What you want is [proposed solution that replaces the pain].
-> The way I'd structure this: [key entities] connected by [key relationships], \
-with the main flow being [trigger → steps → outcome].
-> For the MVP, I'd focus on [the one thing that delivers the most value] \
-and hold off on [things that can wait].
-> Before I start — [1-2 specific questions you genuinely can't infer]."
-
----
-
-### 1.4: Ask Only What You Cannot Infer
-
-Your questions should be **narrow, specific, and consequential**. \
-Never ask what you could answer yourself.
-
-**Good questions** (high-stakes, can't infer):
-- "Who's the primary user — you or your end customers?"
-- "Is this replacing a spreadsheet, or is there literally nothing today?"
-- "Does this need to integrate with anything, or standalone?"
-- "Is there existing data to migrate, or starting fresh?"
-
-**Bad questions** (low-stakes, inferable):
-- "What should happen if there's an error?" *(handle gracefully, obviously)*
-- "Should it have search?" *(if there's a list, yes)*
-- "How should we handle permissions?" *(follow standard patterns)*
-- "What tools should I use?" *(your call, not theirs)*
-
----
-
-## 2: Capability Assessment & Gap Analysis
-
-**After the user responds, assess fit and gaps together.** Be honest and specific. \
-Reference tools from list_agent_tools() AND built-in capabilities:
-- **GCU browser automation** (`node_type="gcu"`) provides full Playwright-based \
-browser control (navigation, clicking, typing, scrolling, JS-rendered pages, \
-multi-tab). Do NOT list browser automation as missing — use GCU nodes.
-
-Present a short **Framework Fit Assessment**:
-- **Works well**: 2-4 strengths for this use case
-- **Limitations**: 2-3 workable constraints (e.g., LLM latency, context limits)
-- **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
-
-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. \
-Use as many nodes as the use case requires, but don't create nodes without \
-tools — merge them into nodes that do real work.
-- Edges: on_success for linear, conditional for routing
-- Lifecycle: ALWAYS have terminal_nodes
-
-**MERGE nodes when:**
-- Node has NO tools (pure LLM reasoning) → merge into predecessor/successor
-- Node sets only 1 trivial output → collapse into predecessor
-
-**SEPARATE nodes when:**
-- Fundamentally different tool sets (e.g., search vs. write vs. validate)
-- Fan-out parallelism (parallel branches MUST be separate)
-- Different failure/retry semantics (e.g., gather can retry, transform cannot)
-- Distinct phases of work (e.g., research, transform, validate, deliver)
-- A node would need more than ~5 tools — split by responsibility
-
-**Typical patterns (queen manages all user interaction):**
-- 3 nodes: `gather → work → review`
-- 4 nodes: `gather → analyze → transform → review`
-- 5 nodes: `gather → research → transform → validate → deliver`
-- WRONG: 2 nodes where everything is crammed into one giant node
-- WRONG: 7 nodes where half have no tools and just do LLM reasoning
-
-Read reference agents before designing:
-  list_agents()
-  read_file("exports/deep_research_agent/agent.py")
-  read_file("exports/deep_research_agent/nodes/__init__.py")
-
-Present the design 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:
-
-```
-┌─────────────────────────┐
-│  gather                 │
-│  subagent: gcu_search   │
-│  input:  user_request   │
-│  tools: web_search,     │
-│         write_file      │
-└────────────┬────────────┘
-             │ on_success
-             ▼
-┌─────────────────────────┐
-│  work                   │
-│  subagent: gcu_interact │
-│  tools: read_file,      │
-│         write_file      │
-└────────────┬────────────┘
-             │ on_success
-             ▼
-┌─────────────────────────┐
-│  review                 │
-│  tools: write_file      │
-└────────────┬────────────┘
-             │ on_failure
-             └──────► back to gather
-```
-
-The queen owns intake: she gathers user requirements, then calls \
-`run_agent_with_input(task)` with a structured task description. \
-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 by ask_user
-
-**WAIT for user response.**
-- If **Proceed**: Move to next implementing
-- 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
-
-## 5. Implement
-
-**Please make sure you have propose the design to the user before implementing**
-
-Call `initialize_agent_package(agent_name)` to generate all package files \
-from your graph session. The agent_name must be snake_case (e.g., "my_agent").
-The tool creates: config.py, nodes/__init__.py, agent.py, \
-__init__.py, __main__.py, mcp_servers.json, tests/conftest.py, \
-agent.json, README.md.
-
-`mcp_servers.json` is auto-generated with hive-tools as the default. \
-Do NOT manually create or overwrite `mcp_servers.json`.
-
-After initialization, review and customize if needed:
-- System prompts in nodes/__init__.py
-- CLI options in __main__.py
-- Identity prompt in agent.py
-- For async entry points (timers/webhooks), add AsyncEntryPointSpec \
-and AgentRuntimeConfig to agent.py manually
-
-Do NOT manually write these files from scratch — always use the tool.
-
-## 6. Verify and Load
-
-Call `validate_agent_package("{name}")` after initialization. \
-It runs structural checks (class validation, graph validation, tool \
-validation, tests) and returns a consolidated result. If anything \
-fails: read the error, fix with edit_file, re-validate. Up to 3x.
-
-When validation passes, immediately call \
-`load_built_agent("exports/{name}")` to load the agent into the \
-session. This switches to STAGING phase and shows the graph in the \
-visualizer. Do NOT wait for user input between validation and loading.
-"""
-
-
-# ---------------------------------------------------------------------------
-# Queen-specific: extra tool docs, behavior, phase 7, style
-# ---------------------------------------------------------------------------
-
-# -- Phase-specific identities --
-
-_queen_identity_building = """\
-You are an experienced, responsible and curious Solution Architect. \
-"Queen" is the internal alias.\
-You design and build production-ready agent systems \
-from natural language requirements. You understand the Hive framework at the \
-source code level and create agents that are robust, well-tested, and follow \
-best practices. You collaborate with users to refine requirements, assess fit, \
-and deliver complete solutions. \
-You design and build the agent to do the job but don't do the job on your own
-"""
-
-_queen_identity_staging = """\
-You are a Solution Engineer preparing an agent for deployment. \
-"Queen" is your internal alias. \
-The agent is loaded and ready. \
-Your role is to verify configuration, confirm credentials, and ensure the user \
-understands what the agent will do. You guide the user through the final checks \
-before execution.
-"""
-
-_queen_identity_running = """\
-You are a Solution Engineer running agents on behalf of the user. \
-"Queen" is your internal alias. You monitor execution, handle \
-escalations when the agent gets stuck, and care deeply about outcomes. When the \
-agent finishes, you report results clearly and help the user decide what to do next.
-"""
-
-# -- Phase-specific tool docs --
-
-_queen_tools_building = """
-# Tools (BUILDING phase)
-
-You have full coding tools for building and modifying agents:
-- File I/O: read_file, write_file, edit_file, list_directory, search_files, \
-run_command, undo_changes
-- Meta-agent: list_agent_tools, validate_agent_package, \
-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
-
-When you finish building an agent, call load_built_agent(path) to stage it.
-"""
-
-_queen_tools_staging = """
-# Tools (STAGING phase)
-
-The agent is loaded and ready to run. You can inspect it and launch it:
-- Read-only: read_file, list_directory, search_files, run_command
-- list_credentials(credential_id?) — Verify credentials are configured
-- get_worker_status(focus?) — Brief status. Drill in with focus: memory, tools, issues, progress
-- run_agent_with_input(task) — Start the worker and switch to RUNNING phase
-- stop_worker_and_edit() — Go back to BUILDING phase
-
-You do NOT have write tools. If you need to modify the agent, \
-call stop_worker_and_edit() to go back to BUILDING phase.
-"""
-
-_queen_tools_running = """
-# Tools (RUNNING phase)
-
-The worker is running. You have monitoring and lifecycle tools:
-- Read-only: read_file, list_directory, search_files, run_command
-- get_worker_status(focus?) — Brief status. Drill in: activity, memory, tools, issues, progress
-- inject_worker_message(content) — Send a message to the running worker
-- get_worker_health_summary() — Read the latest health data
-- notify_operator(ticket_id, analysis, urgency) — Alert the user (use sparingly)
-- stop_worker() — Stop the worker and return to STAGING phase, then ask the user what to do next
-- stop_worker_and_edit() — Stop the worker and switch back to BUILDING phase
-
-You do NOT have write tools or agent construction tools. \
-If you need to modify the agent, call stop_worker_and_edit() to switch back \
-to BUILDING phase. To stop the worker and ask the user what to do next, call \
-stop_worker() to return to STAGING phase.
-"""
-
-# -- Behavior shared across all phases --
-
-_queen_behavior_always = """
-# Behavior
-
-## CRITICAL RULE — ask_user tool
-
-Every response that ends with a question, a prompt, or expects user \
-input MUST finish with a call to ask_user(prompt, options). \
-The system CANNOT detect that you are waiting for \
-input unless you call ask_user. You MUST call ask_user 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.
-
-Always provide 2-4 short options that cover the most likely answers. \
-The user can always type a custom response.
-
-Examples:
-- 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"])
-
-## Greeting
-
-When the user greets you, respond concisely (under 10 lines) with worker \
-status only:
-1. Use plain, user-facing wording about load/run state; avoid internal phase \
-labels ("staging phase", "building phase", "running phase") unless the user \
-explicitly asks for phase details.
-2. If loaded, prefer this format: "<worker_name> has been loaded. <one sentence \
-on what it does from Worker Profile>."
-3. Do NOT include identity details unless the user explicitly asks about identity.
-4. THEN call ask_user to prompt them — do NOT just write text.
-5. Preferred loaded example:
-   local_business_extractor/*agent name*/ has been loaded. It finds local businesses on \
-Google Maps, extracts contact details, and syncs them to Google Sheets.
-   ask_user("Do you want to run it?", ["Yes, run it", "Check credentials first",
-            "Modify the worker"])
-
-## When user ask identity and responsibility
-
-Only answer identity when the user explicitly asks (for example: "who are you?", \
-"what is your identity?", "what does Queen mean?").
-1. Use the alias "Queen" and "Worker" in the response.
-2. Explain role/responsibility for the current phase:
-   - BUILDING: architect and implement agents.
-   - STAGING: verify readiness, credentials, and launch conditions.
-   - RUNNING: monitor execution, handle escalations, and report outcomes.
-3. Keep identity responses concise and do NOT include extra process details.
-"""
-
-# -- BUILDING phase behavior --
-
-_queen_behavior_building = """
-
-## Direct coding
-You can do any coding task directly — reading files, writing code, running \
-commands, building agents, debugging. For quick tasks, do them yourself.
-
-**Decision rule — if worker exists, read the Worker Profile first:**
-- The user's request directly matches the worker's goal → use \
-run_agent_with_input(task) (if in staging) or load then run (if in building)
-- Anything else → do it yourself. Do NOT reframe user requests into \
-subtasks to justify delegation.
-- Building, modifying, or configuring agents is ALWAYS your job. Never \
-delegate agent construction to the worker, even as a "research" subtask.
-"""
-
-# -- STAGING phase behavior --
-
-_queen_behavior_staging = """
-## Worker delegation
-The worker is a specialized agent (see Worker Profile at the end of this \
-prompt). It can ONLY do what its goal and tools allow.
-
-**Decision rule — read the Worker Profile first:**
-- The user's request directly matches the worker's goal → use \
-run_agent_with_input(task) (if in staging) or load then run (if in building)
-- Anything else → do it yourself. Do NOT reframe user requests into \
-subtasks to justify delegation.
-- Building, modifying, or configuring agents is ALWAYS your job. \
-Use stop_worker_and_edit when you need to.
-
-## When the user says "run", "execute", or "start" (without specifics)
-
-The loaded worker is described in the Worker Profile below. You MUST \
-ask the user what task or input they want using ask_user — do NOT \
-invent a task, do NOT call list_agents() or list directories. \
-The worker is already loaded. Just ask for the specific input the \
-worker needs (e.g., a research topic, a target domain, a job description). \
-NEVER call run_agent_with_input until the user has provided their input.
-
-If NO worker is loaded, say so and offer to build one.
-
-## When in staging phase (agent loaded, not running):
-- Tell the user the agent is loaded and ready in plain language (for example, \
-"<worker_name> has been loaded.").
-- Avoid lead-ins like "A worker is loaded and ready in staging phase: ...".
-- For tasks matching the worker's goal: ALWAYS ask the user for their \
-specific input BEFORE calling run_agent_with_input(task). NEVER make up \
-or assume what the user wants. Use ask_user to collect the task details \
-(e.g., topic, target, requirements). Once you have the user's answer, \
-compose a structured task description from their input and call \
-run_agent_with_input(task). The worker has no intake node — it receives \
-your task and starts processing.
-- If the user wants to modify the agent, call stop_worker_and_edit().
-
-## When idle (worker not running):
-- Greet the user. Mention what the worker can do in one sentence.
-- For tasks matching the worker's goal, use run_agent_with_input(task) \
-(if in staging) or load the agent first (if in building).
-- For everything else, do it directly.
-
-## When the user clicks Run (external event notification)
-When you receive an event that the user clicked Run:
-- If the worker started successfully, briefly acknowledge it — do NOT \
-repeat the full status. The user can see the graph is running.
-- If the worker failed to start (credential or structural error), \
-explain the problem clearly and help fix it. For credential errors, \
-guide the user to set up the missing credentials. For structural \
-issues, offer to fix the agent graph directly.
-
-## Showing or describing the loaded worker
-
-When the user asks to "show the graph", "describe the agent", or \
-"re-generate the graph", read the Worker Profile and present the \
-worker's current architecture as an ASCII diagram. Use the processing \
-stages, tools, and edges from the loaded worker. Do NOT enter the \
-agent building workflow — you are describing what already exists, not \
-building something new.
-
-## Modifying the loaded worker
-
-When the user asks to change, modify, or update the loaded worker \
-(e.g., "change the report node", "add a node", "delete node X"):
-
-1. Call stop_worker_and_edit() — this stops the worker and gives you \
-coding tools (switches to BUILDING phase).
-"""
-
-# -- RUNNING phase behavior --
-
-_queen_behavior_running = """
-## When worker is running — queen is the only user interface
-
-After run_agent_with_input(task), the worker should run autonomously and \
-talk to YOU (queen) via  when blocked. The worker should \
-NOT ask the user directly.
-
-You wake up when:
-- The user explicitly addresses you
-- A worker escalation arrives (`[WORKER_ESCALATION_REQUEST]`)
-- An escalation ticket arrives from the judge
-- The worker finishes (`[WORKER_TERMINAL]`)
-
-If the user asks for progress, call get_worker_status() ONCE and report. \
-If the summary mentions issues, follow up with get_worker_status(focus="issues").
-
-## Handling worker termination ([WORKER_TERMINAL])
-
-When you receive a `[WORKER_TERMINAL]` event, the worker has finished:
-
-1. **Report to the user** — Summarize what the worker accomplished (from the \
-output keys) or explain the failure (from the error message).
-
-2. **Ask what's next** — Use ask_user to offer options:
-   - If successful: "Run again with new input", "Modify the agent", "Done for now"
-   - If failed: "Retry with same input", "Debug/modify the agent", "Done for now"
-
-3. **Default behavior** — Always report and wait for user direction. Only \
-start another run if the user EXPLICITLY asks to continue.
-
-Example response:
-> "The worker finished. It found 5 relevant articles and saved them to \
-output.md.
->
-> What would you like to do next?"
-> [ask_user with options]
-
-## Handling worker escalations ([WORKER_ESCALATION_REQUEST])
-
-When a worker escalation arrives, read the reason/context and handle by type. \
-IMPORTANT: Only auto-handle if the user has NOT explicitly told you how to handle \
-escalations. If the user gave you instructions (e.g., "just retry on errors", \
-"skip any auth issues"), follow those instructions instead.
-
-**Auth blocks / credential issues:**
-- ALWAYS ask the user (unless user explicitly told you how to handle this).
-- The worker cannot proceed without valid credentials.
-- Explain which credential is missing or invalid.
-- Use ask_user to get guidance: "Provide credentials", "Skip this task", "Stop and edit agent"
-- Use inject_worker_message() to relay user decisions back to the worker.
-
-**Need human review / approval:**
-- ALWAYS ask the user (unless user explicitly told you how to handle this).
-- The worker is explicitly requesting human judgment.
-- Present the context clearly (what decision is needed, what are the options).
-- Use ask_user with the actual decision options.
-- Use inject_worker_message() to relay user decisions back to the worker.
-
-**Errors / unexpected failures:**
-- Explain what went wrong in plain terms.
-- Ask the user: "Fix the agent and retry?" → use stop_worker_and_edit() if yes.
-- Or offer: "Retry as-is", "Skip this task", "Abort run"
-- (Skip asking if user explicitly told you to auto-retry or auto-skip errors.)
-
-**Informational / progress updates:**
-- Acknowledge briefly and let the worker continue.
-- Only interrupt the user if the escalation is truly important.
-
-## Showing or describing the loaded worker
-
-When the user asks to "show the graph", "describe the agent", or \
-"re-generate the graph", read the Worker Profile and present the \
-worker's current architecture as an ASCII diagram. Use the processing \
-stages, tools, and edges from the loaded worker. Do NOT enter the \
-agent building workflow — you are describing what already exists, not \
-building something new.
-
-- Call get_worker_status(focus="issues") for more details when needed.
-
-## Modifying the loaded worker
-
-When the user asks to change, modify, or update the loaded worker \
-(e.g., "change the report node", "add a node", "delete node X"):
-
-1. Call stop_worker_and_edit() — this stops the worker and gives you \
-coding tools (switches to BUILDING phase).
-"""
-
-# -- Backward-compatible composed versions (used by queen_node.system_prompt default) --
-
-_queen_tools_docs = (
-    "\n\n## Queen Operating Phases\n\n"
-    "You operate in one of three phases. Your available tools change based on the "
-    "phase. The system notifies you when a phase change occurs.\n\n"
-    "### BUILDING phase (default)\n"
-    + _queen_tools_building.strip()
-    + "\n\n### STAGING phase (agent loaded, not yet running)\n"
-    + _queen_tools_staging.strip()
-    + "\n\n### RUNNING phase (worker is executing)\n"
-    + _queen_tools_running.strip()
-    + "\n\n### Phase transitions\n"
-    "- load_built_agent(path) → switches to STAGING phase\n"
-    "- run_agent_with_input(task) → starts worker, switches to RUNNING phase\n"
-    "- stop_worker() → stops worker, switches to STAGING phase (ask user: re-run or edit?)\n"
-    "- stop_worker_and_edit() → stops worker (if running), switches to BUILDING phase\n"
-)
-
-_queen_behavior = (
-    _queen_behavior_always
-    + _queen_behavior_building
-    + _queen_behavior_staging
-    + _queen_behavior_running
-)
-
-_queen_phase_7 = """
-## Running the Agent
-
-After validation passes and load_built_agent succeeds (STAGING phase), \
-offer to run the agent. Call run_agent_with_input(task) to start it. \
-Do NOT tell the user to run `python -m {name} run` — run it here.
-"""
-
-_queen_style = """
-# Style
-- Responsible and thoughtful
-- Concise. No fluff. Direct. No emojis.
-- When starting the worker, describe what you told it in one sentence.
-- When an escalation arrives, lead with severity and recommended action.
-"""
-
-
-# ---------------------------------------------------------------------------
-# Node definitions
-# ---------------------------------------------------------------------------
-
-# Single node — like opencode's while(true) loop.
-# One continuous context handles the entire workflow:
-# discover → design → implement → verify → present → iterate.
-coder_node = NodeSpec(
-    id="coder",
-    name="Hive Coder",
-    description=(
-        "Autonomous coding agent that builds Hive agent packages. "
-        "Handles the full lifecycle: understanding user intent, "
-        "designing architecture, writing code, validating, and "
-        "iterating on feedback — all in one continuous conversation."
-    ),
-    node_type="event_loop",
-    client_facing=True,
-    max_node_visits=0,
-    input_keys=["user_request"],
-    output_keys=["agent_name", "validation_result"],
-    success_criteria=(
-        "A complete, validated Hive agent package exists at "
-        "exports/{agent_name}/ and passes structural validation."
-    ),
-    tools=_SHARED_TOOLS
-    + [
-        # Graph lifecycle tools (multi-graph sessions)
-        "load_agent",
-        "unload_agent",
-        "start_agent",
-        "restart_agent",
-        "get_user_presence",
-    ],
-    system_prompt=(
-        "You are Hive Coder, the best agent-building coding agent. You build "
-        "production-ready Hive agent packages from natural language.\n"
-        + _package_builder_knowledge
-        + _gcu_building_section
-        + _appendices
-    ),
-)
-
-
-ticket_triage_node = NodeSpec(
-    id="ticket_triage",
-    name="Ticket Triage",
-    description=(
-        "Queen's triage node. Receives an EscalationTicket from the Health Judge "
-        "via event-driven entry point and decides: dismiss or notify the operator."
-    ),
-    node_type="event_loop",
-    client_facing=True,  # Operator can chat with queen once connected (Ctrl+Q)
-    max_node_visits=0,
-    input_keys=["ticket"],
-    output_keys=["intervention_decision"],
-    nullable_output_keys=["intervention_decision"],
-    success_criteria=(
-        "A clear intervention decision: either dismissed with documented reasoning, "
-        "or operator notified via notify_operator with specific analysis."
-    ),
-    tools=["notify_operator"],
-    system_prompt="""\
-You are the Queen (Hive Coder). The Worker Health Judge has escalated a worker \
-issue to you. The ticket is in your memory under key "ticket". Read it carefully.
-
-## Dismiss criteria — do NOT call notify_operator:
-- severity is "low" AND steps_since_last_accept < 8
-- Cause is clearly a transient issue (single API timeout, brief stall that \
-  self-resolved based on the evidence)
-- Evidence shows the agent is making real progress despite bad verdicts
-
-## Intervene criteria — call notify_operator:
-- severity is "high" or "critical"
-- steps_since_last_accept >= 10 with no sign of recovery
-- stall_minutes > 4 (worker definitively stuck)
-- Evidence shows a doom loop (same error, same tool, no progress)
-- Cause suggests a logic bug, missing configuration, or unrecoverable state
-
-## When intervening:
-Call notify_operator with:
-  ticket_id: <ticket["ticket_id"]>
-  analysis: "<2-3 sentences: what is wrong, why it matters, suggested action>"
-  urgency: "<low|medium|high|critical>"
-
-## After deciding:
-set_output("intervention_decision", "dismissed: <reason>" or "escalated: <summary>")
-
-Be conservative but not passive. You are the last quality gate before the human \
-is disturbed. One unnecessary alert is less costly than alert fatigue — but \
-genuine stuck agents must be caught.
-""",
-)
-
-ALL_QUEEN_TRIAGE_TOOLS = ["notify_operator"]
-
-
-queen_node = NodeSpec(
-    id="queen",
-    name="Queen",
-    description=(
-        "User's primary interactive interface with full coding capability. "
-        "Can build agents directly or delegate to the worker. Manages the "
-        "worker agent lifecycle and triages health escalations from the judge."
-    ),
-    node_type="event_loop",
-    client_facing=True,
-    max_node_visits=0,
-    input_keys=["greeting"],
-    output_keys=[],  # Queen should never have this
-    nullable_output_keys=[],  # Queen should never have this
-    skip_judge=True,  # Queen is a conversational agent; suppress tool-use pressure feedback
-    tools=sorted(set(_QUEEN_BUILDING_TOOLS + _QUEEN_STAGING_TOOLS + _QUEEN_RUNNING_TOOLS)),
-    system_prompt=(
-        _queen_identity_building
-        + _queen_style
-        + _package_builder_knowledge
-        + _gcu_building_section  # GCU as first-class citizen (not appendix)
-        + _queen_tools_docs
-        + _queen_behavior
-        + _queen_phase_7
-        + _appendices
-    ),
-)
-
-ALL_QUEEN_TOOLS = sorted(set(_QUEEN_BUILDING_TOOLS + _QUEEN_STAGING_TOOLS + _QUEEN_RUNNING_TOOLS))
-
-__all__ = [
-    "coder_node",
-    "ticket_triage_node",
-    "queen_node",
-    "ALL_QUEEN_TRIAGE_TOOLS",
-    "ALL_QUEEN_TOOLS",
-    "_QUEEN_BUILDING_TOOLS",
-    "_QUEEN_STAGING_TOOLS",
-    "_QUEEN_RUNNING_TOOLS",
-    # Phase-specific prompt segments (used by session_manager for dynamic prompts)
-    "_queen_identity_building",
-    "_queen_identity_staging",
-    "_queen_identity_running",
-    "_queen_tools_building",
-    "_queen_tools_staging",
-    "_queen_tools_running",
-    "_queen_behavior_always",
-    "_queen_behavior_building",
-    "_queen_behavior_staging",
-    "_queen_behavior_running",
-    "_queen_phase_7",
-    "_queen_style",
-    "_package_builder_knowledge",
-    "_appendices",
-    "_gcu_building_section",
-]

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

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

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

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

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

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

core/framework/agents/hive_coder/ticket_receiver.py

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

core/framework/agents/queen/__init__.py

@@ -0,0 +1,15 @@
+"""Queen -- the agent builder for the Hive framework."""
+
+from .agent import queen_goal, queen_loop_config
+from .config import AgentMetadata, RuntimeConfig, default_config, metadata
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "queen_goal",
+    "queen_loop_config",
+    "RuntimeConfig",
+    "AgentMetadata",
+    "default_config",
+    "metadata",
+]

core/framework/agents/queen/agent.py

@@ -0,0 +1,28 @@
+"""Queen agent definition.
+
+The queen is a single AgentLoop — no orchestrator dependency.
+Loaded by queen_orchestrator.create_queen().
+"""
+
+from framework.schemas.goal import Goal
+
+from .nodes import queen_node
+
+queen_goal = Goal(
+    id="queen-manager",
+    name="Queen Manager",
+    description=(
+        "Manage the worker agent lifecycle and serve as the user's primary interactive interface."
+    ),
+    success_criteria=[],
+    constraints=[],
+)
+
+# Loop config -- used by queen_orchestrator to build LoopConfig
+queen_loop_config = {
+    "max_iterations": 999_999,
+    "max_tool_calls_per_turn": 30,
+    "max_context_tokens": 180_000,
+}
+
+__all__ = ["queen_goal", "queen_loop_config", "queen_node"]

core/framework/agents/queen/config.py

@@ -1,4 +1,4 @@
-"""Runtime configuration for Hive Coder agent."""
+"""Runtime configuration for Queen agent."""
 
 import json
 from dataclasses import dataclass, field
@@ -34,7 +34,7 @@ default_config = RuntimeConfig()
 
 @dataclass
 class AgentMetadata:
-    name: str = "Hive Coder"
+    name: str = "Queen"
     version: str = "1.0.0"
     description: str = (
         "Native coding agent that builds production-ready Hive agent packages "
@@ -43,7 +43,7 @@ class AgentMetadata:
         "MCP configuration, and tests."
     )
     intro_message: str = (
-        "I'm Hive Coder — I build Hive agents. Describe what kind of agent "
+        "I'm Queen — I build Hive agents. Describe what kind of agent "
         "you want to create and I'll design, implement, and validate it for you."
     )
 

core/framework/agents/queen/mcp_registry.json

@@ -0,0 +1,3 @@
+{
+  "include": ["gcu-tools", "hive_tools"]
+}

core/framework/agents/queen/mcp_servers.json

@@ -0,0 +1,23 @@
+{
+  "coder-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "coder_tools_server.py", "--stdio"],
+    "cwd": "../../../../tools",
+    "description": "Unsandboxed file system tools for code generation and validation"
+  },
+  "gcu-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "-m", "gcu.server", "--stdio", "--capabilities", "browser"],
+    "cwd": "../../../../tools",
+    "description": "Browser automation tools (Playwright-based)"
+  },
+  "hive_tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "mcp_server.py", "--stdio"],
+    "cwd": "../../../../tools",
+    "description": "Aden integration tools (gmail, calendar, hubspot, etc.) — gated by credentials and the verified manifest"
+  }
+}

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

@@ -0,0 +1,729 @@
+"""Node definitions for Queen agent."""
+
+from pathlib import Path
+
+from framework.orchestrator import NodeSpec
+
+# Load reference docs at import time so they're always in the system prompt.
+# No voluntary read_file() calls needed — the LLM gets everything upfront.
+_ref_dir = Path(__file__).parent.parent / "reference"
+_gcu_guide_path = _ref_dir / "gcu_guide.md"
+_gcu_guide = _gcu_guide_path.read_text(encoding="utf-8") if _gcu_guide_path.exists() else ""
+
+
+def _is_gcu_enabled() -> bool:
+    try:
+        from framework.config import get_gcu_enabled
+
+        return get_gcu_enabled()
+    except Exception:
+        return False
+
+
+# GCU guide — appended to phase prompts that need browser automation context.
+_gcu_section = (
+    ("\n\n# Browser Automation Nodes\n\n" + _gcu_guide) if _is_gcu_enabled() and _gcu_guide else ""
+)
+
+# Queen phase-specific tool sets.
+
+# Staging phase: agent loaded but not yet running — inspect, configure, launch.
+# No backward transitions — staging only goes forward to running.
+_QUEEN_STAGING_TOOLS = [
+    # Read-only (inspect agent files, logs)
+    "read_file",
+    "list_directory",
+    "search_files",
+    "run_command",
+    # Agent inspection
+    "list_credentials",
+    "get_worker_status",
+    # Launch
+    "run_agent_with_input",
+    # Trigger management
+    "set_trigger",
+    "remove_trigger",
+    "list_triggers",
+]
+
+# Running phase: worker is executing — monitor, control, or switch to editing.
+# switch_to_editing lets the queen explicitly stop and tweak without rebuilding.
+_QUEEN_RUNNING_TOOLS = [
+    # Read-only coding (for inspecting logs, files)
+    "read_file",
+    "list_directory",
+    "search_files",
+    "run_command",
+    # Credentials
+    "list_credentials",
+    # Worker lifecycle
+    "stop_worker",
+    "switch_to_reviewing",
+    "get_worker_status",
+    "run_agent_with_input",
+    "run_parallel_workers",
+    "inject_message",
+    # Worker escalation inbox
+    "list_worker_questions",
+    "reply_to_worker",
+    # Monitoring
+    "set_trigger",
+    "remove_trigger",
+    "list_triggers",
+]
+
+# Editing phase: worker done, still loaded — tweak config and re-run.
+# Has inject_message for live adjustments.
+_QUEEN_EDITING_TOOLS = [
+    # Read-only (inspect)
+    "read_file",
+    "list_directory",
+    "search_files",
+    "run_command",
+    # Credentials
+    "list_credentials",
+    "get_worker_status",
+    # Re-run or tweak
+    "run_agent_with_input",
+    "inject_message",
+    # Worker escalation inbox
+    "list_worker_questions",
+    "reply_to_worker",
+    # Monitoring
+    "set_trigger",
+    "remove_trigger",
+    "list_triggers",
+]
+
+# Independent phase: queen operates as a standalone agent — no worker.
+# Core tools are listed here; MCP tools (coder-tools, gcu-tools) are added
+# dynamically in queen_orchestrator.py because their tool names aren't known
+# at import time.
+_QUEEN_INDEPENDENT_TOOLS = [
+    # File I/O (full access)
+    "read_file",
+    "write_file",
+    "edit_file",
+    "hashline_edit",
+    "list_directory",
+    "search_files",
+    "run_command",
+    "undo_changes",
+    # Parallel fan-out (Phase 4 unified ColonyRuntime)
+    "run_parallel_workers",
+    # Fork this session into a persistent colony for headless /
+    # recurring / background work that needs to keep running in
+    # parallel to (or after) this chat.
+    "create_colony",
+]
+
+
+
+
+# ---------------------------------------------------------------------------
+# Queen-specific: extra tool docs, behavior, phase 7, style
+# ---------------------------------------------------------------------------
+
+# -- Character core (immutable across all phases) --
+
+_queen_character_core = """\
+You are the advisor defined in <core_identity> above. Stay in character.
+
+Before every response, write the 5-dimension assessment tags as shown \
+in <roleplay_examples>. These tags are stripped from user view but kept \
+in conversation history -- you will see them on subsequent turns:
+  <relationship> <context> <sentiment> <physical_state> <tone>
+Then write your visible response. Direct, in character, no preamble.
+
+You remember people. When you've worked with someone before, build on \
+what you know. The instructions that follow tell you what to DO in each \
+phase. Your identity tells you WHO you are.\
+"""
+
+# -- Phase-specific work roles (what you DO, not who you ARE) --
+
+_queen_role_staging = """\
+You are in STAGING phase. The agent is loaded and ready. \
+Your work: verify configuration, confirm credentials, and launch \
+when the user is ready. \
+If the user opens with a greeting or chat, reply in plain prose in \
+character first — check recall memory for name and past topics and weave \
+them in. No tool calls on chat turns.\
+"""
+
+_queen_role_running = """\
+You are in RUNNING phase. The agent is executing. \
+Your work: monitor progress, handle escalations when the agent gets stuck, \
+and report outcomes clearly. Help the user decide what to do next. \
+If the user opens with a greeting or chat, reply in plain prose in \
+character first — check recall memory for name and past topics and weave \
+them in. No tool calls on chat turns.\
+"""
+
+_queen_identity_editing = """\
+You are in EDITING mode. The worker has finished executing and is still loaded. \
+You can tweak configuration, inject messages, and re-run with different input \
+without rebuilding.
+If the user opens with a greeting or chat, reply in plain prose in \
+character first — check recall memory for name and past topics and weave \
+them in. No tool calls on chat turns.
+"""
+
+_queen_role_independent = """\
+You are in INDEPENDENT mode. No worker layout — you do the work yourself. \
+You have full coding tools (read/write/edit/search/run) and MCP tools \
+(file operations via coder-tools, browser automation via gcu-tools). \
+Execute the user's task directly using conversation and tools. \
+You are the agent. \
+If the user opens with a greeting or chat, reply in plain prose in \
+character first — check recall memory for name and past topics and weave \
+them in. If you ask the user a question, you MUST use the \
+ask_user or ask_user_multiple tools. \
+"""
+
+_queen_tools_staging = """
+# Tools (STAGING phase)
+
+The agent is loaded and ready to run. You can inspect it and launch it:
+- Read-only: read_file, list_directory, search_files, run_command
+- list_credentials(credential_id?) — Verify credentials are configured
+- get_worker_status(focus?) — Brief status
+- run_agent_with_input(task) — Start the worker and switch to RUNNING phase
+- set_trigger / remove_trigger / list_triggers — Timer management
+
+You do NOT have write tools or backward transition tools in staging. \
+To modify the agent, run it first — after it finishes you enter EDITING \
+phase where you can escalate to building or planning.
+"""
+
+_queen_tools_running = """
+# Tools (RUNNING phase)
+
+The worker is running. You have monitoring and lifecycle tools:
+- Read-only: read_file, list_directory, search_files, run_command
+- get_worker_status(focus?) — Brief status
+- inject_message(content) — Send a message to the running worker
+- get_worker_health_summary() — Read the latest health data
+- stop_worker() — Stop the worker immediately
+- switch_to_editing() — Stop the worker and enter EDITING phase \
+for config tweaks, re-runs, or escalation to building/planning
+- run_agent_with_input(task) — Re-run the worker with new input
+- set_trigger / remove_trigger / list_triggers — Timer management
+
+When the worker finishes on its own, you automatically move to EDITING \
+phase. You can also call switch_to_editing() to stop early and tweak.
+"""
+
+_queen_tools_editing = """
+# Tools (EDITING phase)
+
+The worker has finished executing and is still loaded. You can tweak and re-run:
+- Read-only: read_file, list_directory, search_files, run_command
+- get_worker_status(focus?) — Brief status of the loaded agent
+- inject_message(content) — Send a config tweak or prompt adjustment
+- run_agent_with_input(task) — Re-run the worker with new input
+- get_worker_health_summary() — Review last run's health data
+- set_trigger / remove_trigger / list_triggers — Timer management
+
+You do NOT have write/edit file tools or backward transition tools. \
+You can only re-run or tweak from this phase.
+"""
+
+_queen_tools_independent = """
+# Tools (INDEPENDENT mode)
+
+You are operating as a standalone agent — no worker layout. You do the work directly.
+
+## File I/O (coder-tools MCP)
+- read_file, write_file, edit_file, hashline_edit, list_directory, \
+search_files, run_command, undo_changes
+
+## Browser Automation (gcu-tools MCP)
+All browser tools are prefixed with `browser_` (browser_start, browser_navigate, \
+browser_click, browser_fill, browser_snapshot, browser_screenshot, browser_scroll, \
+browser_tabs, browser_close, browser_evaluate, etc.).
+Follow the browser-automation skill protocol — activate it before using browser tools.
+
+## Parallel fan-out (one-off batch work)
+- run_parallel_workers(tasks, timeout?) — Spawn N workers concurrently and \
+wait for all reports. Use when the user asks for batch / parallel work \
+RIGHT NOW that can be split into independent subtasks (e.g. "fetch batches \
+1–5 from this API", "summarise these 10 PDFs", "compare these candidates"). \
+Each task is a dict `{"task": "...", "data"?: {...}}`. Workers have zero \
+context from your chat — each task string must be FULL and self-contained. \
+The tool returns aggregated `{worker_id, status, summary, data, error}` \
+reports. Read them on your next turn and write a single user-facing \
+synthesis.
+
+## Forking this session into a persistent colony
+
+**When to use create_colony:** the user needs work to run \
+**headless, recurring, or in parallel to this chat** — something \
+that should keep going after this conversation ends. Typical \
+triggers:
+  - "run this every morning / every hour / on a cron"
+  - "keep monitoring X and alert me when Y changes"
+  - "fire this off in the background so I can keep working here"
+  - "spin up a dedicated agent for this job"
+  - any task that needs to survive the current session
+
+**When NOT to use it:** if the user just wants results RIGHT NOW \
+in this chat, use `run_parallel_workers` instead. Don't create a \
+colony just because you "learned something reusable" — the \
+trigger is operational (needs to keep running), not epistemic \
+(knowledge worth saving).
+
+**Two-step flow:**
+  1. AUTHOR A SKILL FIRST in a SCRATCH location so the colony \
+     worker has the operational context it needs to run \
+     unattended. Use write_file to create a skill folder \
+     somewhere temporary (e.g. `/tmp/{skill-name}/` or your \
+     working directory) capturing the procedure — API endpoints, \
+     auth flow, pagination, gotchas, rate limits, response \
+     shapes. DO NOT author it under `~/.hive/skills/` — that path \
+     is user-global and would leak the skill to every other \
+     agent. The SKILL.md needs YAML frontmatter with `name` \
+     (matching the directory name) and `description` (1-1024 \
+     chars including trigger keywords), followed by a markdown \
+     body. Optional subdirs: scripts/, references/, assets/. \
+     Read your writing-hive-skills default skill for the full \
+     spec.
+  2. create_colony(colony_name, task, skill_path) — Validates \
+     the skill folder, forks this session into a new colony, and \
+     installs the skill COLONY-SCOPED at \
+     `~/.hive/colonies/{colony_name}/skills/{skill_name}/`. Only \
+     that colony's worker sees it, no other agent. NOTHING RUNS \
+     after this call — the task is baked into worker.json and \
+     the user starts the worker (or wires up a trigger) later \
+     from the new colony page. The task string must be FULL and \
+     self-contained because the worker has zero memory of your \
+     chat when it eventually runs.
+"""
+
+_queen_behavior_editing = """
+## Editing — tweak and re-run
+
+The worker finished. Review the results and decide:
+1. **Re-run** with different input: call run_agent_with_input(task)
+2. **Inject adjustments**: use inject_message to tweak prompts or config
+
+Do NOT suggest rebuilding. You cannot go back to building or planning \
+from this phase. Default to re-running with adjusted input.
+Report the last run's results to the user and ask what they want to do next.
+"""
+
+_queen_behavior_independent = """
+## Independent — do the work yourself
+
+You are the agent. No pre-loaded worker — you execute directly.
+1. Understand the task from the user
+2. Plan your approach briefly (no flowcharts or agent design)
+3. Execute using your tools: file I/O, shell commands, browser automation
+4. Report results, iterate if needed
+
+## Scaling up from independent mode
+
+You have no pre-loaded worker in this phase, but you DO have two \
+lifecycle tools for spinning up work dynamically:
+
+- **run_parallel_workers(tasks)** — for one-off batch work the user \
+  wants results for RIGHT NOW. Fan out N subtasks concurrently and \
+  synthesize the aggregated reports. No colony is created; the \
+  workers exist only for this call.
+- **create_colony(colony_name, task, skill_path)** — when the user \
+  wants work to run **headless, recurring, or in parallel to this \
+  chat** (e.g. "run nightly", "keep monitoring X", "fire this off \
+  in the background"). Write a skill folder to scratch capturing \
+  the operational procedure, then call this to fork the session \
+  and install the skill colony-scoped. Nothing runs after fork — \
+  the user starts the worker (or sets a trigger) later from the \
+  new colony page. Do NOT use this just because you "learned \
+  something reusable" — the trigger is operational (needs to keep \
+  running), not epistemic.
+"""
+
+# -- Behavior shared across all phases --
+
+_queen_behavior_always = """
+# System Rules
+
+## Communication
+
+Plain-text output IS how you talk to the user — your response is \
+displayed directly in the chat. Use text for conversational replies, \
+open-ended questions, explanations, and short status updates before \
+tool calls. When the user just wants to chat, chat back naturally; \
+you don't need a tool call to "hand off" the turn — the system \
+detects the end of your response and waits for their next message.
+
+## Visible response channel
+
+Your visible response is the plain text in your LLM reply — the text \
+you write after the closing `<tone>` tag of your internal assessment. \
+NEVER use `run_command`, `echo`, or any other tool to emit what you \
+want the user to read. Tools are for work: reading files, running \
+commands, searching, editing. Tools are not for speaking. If you \
+ever find yourself about to call `run_command("echo ...")` to say \
+something, stop — write it as plain text instead. The LLM reply \
+itself is the channel; there is no other.
+
+## ask_user / ask_user_multiple
+
+Use these tools ONLY when you need the user to pick from a small set \
+of concrete options — approval gates, structured preference questions, \
+decision points with 2-4 clear alternatives. Typical triggers:
+- "Postgres or SQLite?" with buttoned options
+- "Approve this draft? (Yes / Revise / Cancel)"
+- Batching 2+ structured questions with ask_user_multiple
+
+DO NOT reach for ask_user on ordinary conversational beats. "What's \
+your name?", "Tell me more about that", "How are you?" — just write \
+those as text. Free-form questions belong in prose. Using ask_user \
+for every reply feels robotic and blocks natural conversation. \
+When you do use it, keep your text to a brief intro; the widget \
+renders the question and options.
+
+## Chatting vs acting
+
+**When the user greets you or chats, reply in plain prose — no tool \
+calls.** A bare "hi", "hey", "hello", "how's it going" is a \
+conversational opener, not a hidden task. Do NOT call `list_directory`, \
+`search_files`, `run_command`, `ask_user`, or any other tool to \
+"discover" what they want. Instead, check what you already know about \
+this user from your recall memory — their name, role, past topics, \
+preferences — and write a 1–2 sentence greeting in character that \
+references it. If you know their name, use it. If you remember what \
+you last worked on together, reference it. Then stop and wait. They \
+will bring the task when they have one. Presuming a task that wasn't \
+stated is worse than waiting a turn.
+
+**When the user asks you to DO something** (build, edit, run, \
+investigate, search), call the appropriate tool directly on the same \
+turn — don't narrate intent and stop. "Let me check that file." \
+followed by an immediate read_file is fine; "I'll check that file." \
+with no tool call and then waiting is not. If you can act now, act now.
+
+You decide turn-by-turn based on what the user actually said. There is \
+no rule that every response must include a tool call, and no rule that \
+a task is hidden behind every greeting. Read what they wrote and \
+respond to that.
+
+## Images
+
+Users can attach images to messages. Analyze them directly using your \
+vision capability — the image is embedded, no tool call needed.
+"""
+
+_queen_memory_instructions = """
+## Your Memory
+
+Relevant global memories about the user may appear at the end of this prompt \
+under "--- Global Memories ---". These are automatically maintained across \
+sessions. Use them to inform your responses but verify stale claims before \
+asserting them as fact.
+"""
+
+_queen_behavior_always = _queen_behavior_always + _queen_memory_instructions
+
+# -- STAGING phase behavior --
+
+_queen_behavior_staging = """
+## Worker delegation
+The worker is a specialized agent (see Worker Profile at the end of this \
+prompt). It can ONLY do what its goal and tools allow.
+
+**Decision rule — read the Worker Profile first:**
+- The user's request directly matches the worker's goal → use \
+run_agent_with_input(task) (if in staging) or load then run (if in building)
+- Anything else → do it yourself. Do NOT reframe user requests into \
+subtasks to justify delegation.
+- Building, modifying, or configuring agents is ALWAYS your job.
+
+## When the user says "run", "execute", or "start" (without specifics)
+
+The loaded worker is described in the Worker Profile below. You MUST \
+ask the user what task or input they want using ask_user — do NOT \
+invent a task, do NOT call list_agents() or list directories. \
+The worker is already loaded. Just ask for the specific input the \
+worker needs (e.g., a research topic, a target domain, a job description). \
+NEVER call run_agent_with_input until the user has provided their input.
+
+If NO worker is loaded, say so and offer to build one.
+
+## When in staging phase (agent loaded, not running):
+- Tell the user the agent is loaded and ready in plain language (for example, \
+"<worker_name> has been loaded.").
+- Avoid lead-ins like "A worker is loaded and ready in staging phase: ...".
+- For tasks matching the worker's goal: ALWAYS ask the user for their \
+specific input BEFORE calling run_agent_with_input(task). NEVER make up \
+or assume what the user wants. Use ask_user to collect the task details \
+(e.g., topic, target, requirements). Once you have the user's answer, \
+compose a structured task description from their input and call \
+run_agent_with_input(task). The worker has no intake node — it receives \
+your task and starts processing.
+- If the user wants to modify the agent, wait for EDITING phase \
+(after worker finishes) and use inject_message to tweak config.
+
+## When idle (worker not running):
+- Greet the user. Mention what the worker can do in one sentence.
+- For tasks matching the worker's goal, use run_agent_with_input(task).
+- For everything else, do it directly.
+
+## When the user clicks Run (external event notification)
+When you receive an event that the user clicked Run:
+- If the worker started successfully, briefly acknowledge it — do NOT \
+repeat the full status. The user can see the layout is running.
+- If the worker failed to start (credential or structural error), \
+explain the problem clearly and help fix it. For credential errors, \
+guide the user to set up the missing credentials. For structural \
+issues, offer to fix the agent layout directly.
+
+## Showing or describing the loaded worker
+
+When the user asks to "show the layout", "describe the agent", or \
+"re-generate the layout", read the Worker Profile and present the \
+worker's current architecture as an ASCII diagram. Use the processing \
+stages, tools, and edges from the loaded worker. Do NOT enter the \
+agent building workflow — you are describing what already exists, not \
+building something new.
+
+## Fixing or Modifying the loaded worker
+
+When the worker finishes, you move to EDITING where you can:
+- Re-run with different input via run_agent_with_input(task)
+- Tweak config via inject_message(content)
+
+## Trigger Management
+
+Use list_triggers() to see available triggers from the loaded worker.
+Use set_trigger(trigger_id) to activate a timer. Once active, triggers \
+fire periodically and inject [TRIGGER: ...] messages so you can decide \
+whether to call run_agent_with_input(task).
+
+### When the user says "Enable trigger <id>" (or clicks Enable in the UI):
+
+1. Call get_worker_status(focus="memory") to check if the worker has \
+saved configuration (rules, preferences, settings from a prior run).
+2. If memory contains saved config: compose a task string from it \
+(e.g. "Process inbox emails using saved rules") and call \
+set_trigger(trigger_id, task="...") immediately. Tell the user the \
+trigger is now active and what schedule it uses. Do NOT ask them to \
+provide the task — you derive it from memory.
+3. If memory is empty (no prior run): tell the user the agent needs to \
+run once first so its configuration can be saved. Offer to run it now. \
+Once the worker finishes, enable the trigger.
+4. If the user just provided config this session (rules/task context \
+already in conversation): use that directly, no memory lookup needed. \
+Enable the trigger immediately.
+
+Never ask "what should the task be?" when enabling a trigger for an \
+agent with a clear purpose. The task string is a brief description of \
+what the worker does, derived from its saved state or your current context.
+"""
+
+# -- RUNNING phase behavior --
+
+_queen_behavior_running = """
+## When worker is running — queen is the only user interface
+
+After run_agent_with_input(task), the worker should run autonomously and \
+talk to YOU (queen) via  when blocked. The worker should \
+NOT ask the user directly.
+
+You wake up when:
+- The user explicitly addresses you
+- A worker escalation arrives (`[WORKER_ESCALATION_REQUEST]`)
+- The worker finishes (`[WORKER_TERMINAL]`)
+
+If the user asks for progress, call get_worker_status() ONCE and report. \
+If the summary mentions issues, follow up with get_worker_status(focus="issues").
+
+## Browser automation nodes
+
+Browser nodes may take 2-5 minutes for web scraping tasks. During this time:
+- Progress will show 0% until the node calls set_output at the end.
+- Check get_worker_status(focus="full") for activity updates.
+- Do NOT conclude it is stuck just because you see repeated \
+browser_click/browser_snapshot calls — that is expected for web scraping.
+- Only intervene if: the node has been running for 5+ minutes with no new \
+activity updates, OR the judge escalates.
+
+## Handling worker termination ([WORKER_TERMINAL])
+
+When you receive a `[WORKER_TERMINAL]` event, the worker has finished:
+
+1. **Report to the user** — Summarize what the worker accomplished (from the \
+output keys) or explain the failure (from the error message).
+
+2. **Ask what's next** — Use ask_user to offer options:
+   - If successful: "Run again with new input", "Modify the agent", "Done for now"
+   - If failed: "Retry with same input", "Debug/modify the agent", "Done for now"
+
+3. **Default behavior** — Always report and wait for user direction. Only \
+start another run if the user EXPLICITLY asks to continue.
+
+Example response:
+> "The worker finished. It found 5 relevant articles and saved them to \
+output.md.
+>
+> What would you like to do next?"
+> [ask_user with options]
+
+## Handling worker escalations ([WORKER_ESCALATION_REQUEST])
+
+When a worker escalation arrives, read the reason/context and handle by type. \
+IMPORTANT: Only auto-handle if the user has NOT explicitly told you how to handle \
+escalations. If the user gave you instructions (e.g., "just retry on errors", \
+"skip any auth issues"), follow those instructions instead.
+
+CRITICAL — escalation relay protocol:
+When an escalation requires user input (auth blocks, human review), the worker \
+or is BLOCKED and waiting for your response. You MUST follow this \
+exact two-step sequence:
+  Step 1: call ask_user() to get the user's answer.
+  Step 2: call inject_message() with the user's answer IMMEDIATELY after.
+If you skip Step 2, the worker stays blocked FOREVER and the task hangs. \
+NEVER respond to the user without also calling inject_message() to unblock \
+the worker. Even if the user says "skip" or "cancel", you must still relay that \
+decision via inject_message() so the worker can clean up.
+
+**Auth blocks / credential issues:**
+- ALWAYS ask the user (unless user explicitly told you how to handle this).
+- The worker cannot proceed without valid credentials.
+- Explain which credential is missing or invalid.
+- Step 1: ask_user for guidance — "Provide credentials", "Skip this task", "Stop and edit agent"
+- Step 2: inject_message() with the user's response to unblock the worker.
+
+**Need human review / approval:**
+- ALWAYS ask the user (unless user explicitly told you how to handle this).
+- The worker is explicitly requesting human judgment.
+- Present the context clearly (what decision is needed, what are the options).
+- Step 1: ask_user with the actual decision options.
+- Step 2: inject_message() with the user's decision to unblock the worker.
+
+**Errors / unexpected failures:**
+- Explain what went wrong in plain terms.
+- Offer: "Retry as-is", "Skip this task", "Abort run".
+- (Skip asking if user explicitly told you to auto-retry or auto-skip errors.)
+- If the escalation had wait_for_response: inject_message() with the decision.
+
+**Informational / progress updates:**
+- Acknowledge briefly and let the worker continue.
+- Only interrupt the user if the escalation is truly important.
+
+## Showing or describing the loaded worker
+
+When the user asks to "show the layout", "describe the agent", or \
+"re-generate the layout", read the Worker Profile and present the \
+worker's current architecture as an ASCII diagram. Use the processing \
+stages, tools, and edges from the loaded worker. Do NOT enter the \
+agent building workflow — you are describing what already exists, not \
+building something new.
+
+- Call get_worker_status(focus="issues") for more details when needed.
+
+## Fixing or Modifying the loaded worker (while running)
+
+When the user asks to fix or modify the worker while it is running, \
+do NOT attempt to switch phases. Wait for the worker to finish — \
+you will move to EDITING phase automatically. From there you can \
+re-run with new input or inject configuration tweaks.
+
+## Trigger Handling
+
+You will receive [TRIGGER: ...] messages when a scheduled timer fires. \
+These are framework-level signals, not user messages.
+
+Rules:
+- Check get_worker_status() before calling run_agent_with_input(task). If the worker \
+is already RUNNING, decide: skip this trigger, or note it for after completion.
+- When multiple [TRIGGER] messages arrive at once, read them all before acting. \
+Batch your response — do not call run_agent_with_input() once per trigger.
+- If a trigger fires but the task no longer makes sense (e.g., user changed \
+config since last run), skip it and inform the user.
+- Never disable a trigger without telling the user. Use remove_trigger() only \
+when explicitly asked or when the trigger is clearly obsolete.
+- When the user asks to remove or disable a trigger, you MUST call remove_trigger(trigger_id). \
+Never just say "it's removed" without actually calling the tool.
+"""
+
+_queen_style = """
+# Communication
+
+## Adaptive Calibration
+
+Read the user's signals and calibrate your register:
+- Short responses -> they want brevity. Match it.
+- "Why?" questions -> they want reasoning. Provide it.
+- Correct technical terms -> they know the domain. Skip basics.
+- Terse or frustrated ("just do X") -> acknowledge and simplify.
+- Exploratory ("what if...", "could we also...") -> slow down and explore.
+"""
+
+
+queen_node = NodeSpec(
+    id="queen",
+    name="Queen",
+    description=(
+        "User's primary interactive interface with full coding capability. "
+        "Can build agents directly or delegate to the worker. Manages the "
+        "worker agent lifecycle."
+    ),
+    node_type="event_loop",
+    max_node_visits=0,
+    input_keys=["greeting"],
+    output_keys=[],  # Queen should never have this
+    nullable_output_keys=[],  # Queen should never have this
+    skip_judge=True,  # Queen is a conversational agent; suppress tool-use pressure feedback
+    tools=sorted(
+        set(
+            _QUEEN_STAGING_TOOLS
+            + _QUEEN_RUNNING_TOOLS
+            + _QUEEN_EDITING_TOOLS
+            + _QUEEN_INDEPENDENT_TOOLS
+        )
+    ),
+    system_prompt=(
+        _queen_character_core
+        + _queen_role_independent
+        + _queen_style
+        + _queen_tools_independent
+        + _queen_behavior_always
+        + _queen_behavior_independent
+    ),
+)
+
+ALL_QUEEN_TOOLS = sorted(
+    set(
+        _QUEEN_STAGING_TOOLS
+        + _QUEEN_RUNNING_TOOLS
+        + _QUEEN_EDITING_TOOLS
+        + _QUEEN_INDEPENDENT_TOOLS
+    )
+)
+
+__all__ = [
+    "queen_node",
+    "ALL_QUEEN_TOOLS",
+    "_QUEEN_STAGING_TOOLS",
+    "_QUEEN_RUNNING_TOOLS",
+    "_QUEEN_EDITING_TOOLS",
+    "_QUEEN_INDEPENDENT_TOOLS",
+    # Character + phase-specific prompt segments (used by session_manager for dynamic prompts)
+    "_queen_character_core",
+    "_queen_role_staging",
+    "_queen_role_running",
+    "_queen_identity_editing",
+    "_queen_role_independent",
+    "_queen_tools_staging",
+    "_queen_tools_running",
+    "_queen_tools_editing",
+    "_queen_tools_independent",
+    "_queen_behavior_always",
+    "_queen_behavior_staging",
+    "_queen_behavior_running",
+    "_queen_behavior_editing",
+    "_queen_behavior_independent",
+    "_queen_style",
+    "_gcu_section",
+]

core/framework/agents/queen/queen_memory_v2.py

@@ -0,0 +1,235 @@
+"""Queen global memory helpers.
+
+Memory hierarchy::
+
+    ~/.hive/memories/
+        global/              # shared across all queens and colonies
+        colonies/{name}/     # colony-scoped memories
+        agents/queens/{name}/ # queen-specific memories
+        agents/{name}/       # per-worker-agent memories
+
+Each memory is an individual ``.md`` file with optional YAML frontmatter
+(name, type, description).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+GLOBAL_MEMORY_CATEGORIES: tuple[str, ...] = ("profile", "preference", "environment", "feedback")
+
+from framework.config import MEMORIES_DIR
+
+MAX_FILES: int = 200
+MAX_FILE_SIZE_BYTES: int = 4096  # 4 KB hard limit per memory file
+
+# How many lines of a memory file to read for header scanning.
+_HEADER_LINE_LIMIT: int = 30
+
+
+def global_memory_dir() -> Path:
+    """Return the global memory directory (shared across all queens/colonies)."""
+    return MEMORIES_DIR / "global"
+
+
+def colony_memory_dir(colony_name: str) -> Path:
+    """Return the memory directory for a named colony."""
+    return MEMORIES_DIR / "colonies" / colony_name
+
+
+def queen_memory_dir(queen_name: str = "default") -> Path:
+    """Return the memory directory for a named queen."""
+    return MEMORIES_DIR / "agents" / "queens" / queen_name
+
+
+def agent_memory_dir(agent_name: str) -> Path:
+    """Return the memory directory for a worker agent."""
+    return MEMORIES_DIR / "agents" / agent_name
+
+
+# ---------------------------------------------------------------------------
+# Frontmatter parsing (lenient)
+# ---------------------------------------------------------------------------
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n?", re.DOTALL)
+
+
+def parse_frontmatter(text: str) -> dict[str, str]:
+    """Extract YAML-ish frontmatter from *text*.
+
+    Returns a dict of key-value pairs.  Never raises — returns ``{}`` on
+    any parse failure.  Values are stripped strings; no nested structures.
+    """
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    result: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        colon = line.find(":")
+        if colon < 1:
+            continue
+        key = line[:colon].strip().lower()
+        val = line[colon + 1 :].strip()
+        if val:
+            result[key] = val
+    return result
+
+
+def parse_global_memory_category(raw: str | None) -> str | None:
+    """Validate *raw* against ``GLOBAL_MEMORY_CATEGORIES``."""
+    if raw is None:
+        return None
+    normalized = raw.strip().lower()
+    return normalized if normalized in GLOBAL_MEMORY_CATEGORIES else None
+
+
+# ---------------------------------------------------------------------------
+# MemoryFile dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class MemoryFile:
+    """Parsed representation of a single memory file on disk."""
+
+    filename: str
+    path: Path
+    # Frontmatter fields — all nullable (lenient parsing).
+    name: str | None = None
+    type: str | None = None
+    description: str | None = None
+    # First N lines of the file (for manifest / header scanning).
+    header_lines: list[str] = field(default_factory=list)
+    # Filesystem modification time (seconds since epoch).
+    mtime: float = 0.0
+
+    @classmethod
+    def from_path(cls, path: Path) -> MemoryFile:
+        """Read a memory file and leniently parse its frontmatter."""
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            return cls(filename=path.name, path=path)
+
+        fm = parse_frontmatter(text)
+        lines = text.splitlines()[:_HEADER_LINE_LIMIT]
+
+        try:
+            mtime = path.stat().st_mtime
+        except OSError:
+            mtime = 0.0
+
+        return cls(
+            filename=path.name,
+            path=path,
+            name=fm.get("name"),
+            type=parse_global_memory_category(fm.get("type")),
+            description=fm.get("description"),
+            header_lines=lines,
+            mtime=mtime,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Scanning
+# ---------------------------------------------------------------------------
+
+
+def scan_memory_files(memory_dir: Path | None = None) -> list[MemoryFile]:
+    """Scan *memory_dir* for ``.md`` files, returning up to ``MAX_FILES``.
+
+    Files are sorted by modification time (newest first).  Dotfiles and
+    subdirectories are ignored.
+    """
+    d = memory_dir or global_memory_dir()
+    if not d.is_dir():
+        return []
+
+    md_files = sorted(
+        (f for f in d.glob("*.md") if f.is_file() and not f.name.startswith(".")),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+
+    return [MemoryFile.from_path(f) for f in md_files[:MAX_FILES]]
+
+
+def slugify_memory_name(raw: str) -> str:
+    """Create a filesystem-safe slug for a memory filename."""
+    slug = re.sub(r"[^a-z0-9]+", "-", raw.strip().lower()).strip("-")
+    return slug or "memory"
+
+
+def allocate_memory_filename(
+    memory_dir: Path,
+    name: str,
+    *,
+    suffix: str = ".md",
+) -> str:
+    """Allocate a unique filename in *memory_dir* based on *name*."""
+    base = slugify_memory_name(name)
+    candidate = f"{base}{suffix}"
+    counter = 2
+    while (memory_dir / candidate).exists():
+        candidate = f"{base}-{counter}{suffix}"
+        counter += 1
+    return candidate
+
+
+def build_memory_document(
+    *,
+    name: str,
+    description: str,
+    mem_type: str,
+    body: str,
+) -> str:
+    """Build one memory file with frontmatter and body."""
+    return (
+        f"---\n"
+        f"name: {name.strip()}\n"
+        f"description: {description.strip()}\n"
+        f"type: {mem_type.strip()}\n"
+        f"---\n\n"
+        f"{body.strip()}\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Manifest formatting
+# ---------------------------------------------------------------------------
+
+
+def format_memory_manifest(files: list[MemoryFile]) -> str:
+    """One-line-per-file text manifest.
+
+    Format: ``[type] filename: description``
+    """
+    lines: list[str] = []
+    for mf in files:
+        t = mf.type or "unknown"
+        desc = mf.description or "(no description)"
+        lines.append(f"[{t}] {mf.filename}: {desc}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Initialisation
+# ---------------------------------------------------------------------------
+
+
+def init_memory_dir(memory_dir: Path | None = None) -> None:
+    """Create the memory directory if missing."""
+    d = memory_dir or global_memory_dir()
+    d.mkdir(parents=True, exist_ok=True)

core/framework/agents/queen/recall_selector.py

@@ -0,0 +1,215 @@
+"""Recall selector — pre-turn memory selection for the queen.
+
+Before each conversation turn the system:
+  1. Scans one or more memory directories for ``.md`` files (cap: 200 each).
+  2. Reads headers (frontmatter + first 30 lines).
+  3. Uses an LLM call with structured JSON output to pick the most relevant
+     memories for each scope.
+  4. Injects them into the system prompt.
+
+The selector only sees the user's query string — no full conversation
+context.  This keeps it cheap and fast.  Errors are caught and return
+``[]`` so the main conversation is never blocked.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from framework.agents.queen.queen_memory_v2 import (
+    format_memory_manifest,
+    global_memory_dir as _default_global_memory_dir,
+    scan_memory_files,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Structured output schema
+# ---------------------------------------------------------------------------
+
+SELECT_MEMORIES_SYSTEM_PROMPT = """\
+You are selecting memories that will be useful to the Queen agent as it \
+processes a user's query.
+
+You will be given the user's query and a list of available memory files \
+with their filenames and descriptions.
+
+Return a JSON object with a single key "selected_memories" containing a \
+list of filenames for the memories that will clearly be useful as the \
+Queen processes the user's query (up to 5).
+
+Only include memories that you are certain will be helpful based on their \
+name and description.
+- If you are unsure if a memory will be useful in processing the user's \
+query, then do not include it in your list.  Be selective and discerning.
+- If there are no memories in the list that would clearly be useful, \
+return an empty list.
+"""
+
+# ---------------------------------------------------------------------------
+# Core functions
+# ---------------------------------------------------------------------------
+
+
+async def select_memories(
+    query: str,
+    llm: Any,
+    memory_dir: Path | None = None,
+    *,
+    max_results: int = 5,
+) -> list[str]:
+    """Select up to 5 relevant memory filenames for *query*.
+
+    Returns a list of filenames.  Best-effort: on any error returns ``[]``.
+    """
+    mem_dir = memory_dir or _default_global_memory_dir()
+    files = scan_memory_files(mem_dir)
+    if not files:
+        logger.debug("recall: no memory files found, skipping selection")
+        return []
+
+    logger.debug("recall: selecting from %d memories for query: %.100s", len(files), query)
+    manifest = format_memory_manifest(files)
+    user_msg = f"## User query\n\n{query}\n\n## Available memories\n\n{manifest}"
+
+    try:
+        resp = await llm.acomplete(
+            messages=[{"role": "user", "content": user_msg}],
+            system=SELECT_MEMORIES_SYSTEM_PROMPT,
+            max_tokens=1024,
+            response_format={"type": "json_object"},
+        )
+        raw = (resp.content or "").strip()
+        if not raw:
+            logger.warning(
+                "recall: LLM returned empty response (model=%s, stop=%s)",
+                resp.model,
+                resp.stop_reason,
+            )
+            return []
+        # Some models wrap JSON in markdown fences or add preamble text.
+        # Try to extract the JSON object if raw parse fails.
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            import re
+
+            m = re.search(r"\{.*\}", raw, re.DOTALL)
+            if m:
+                data = json.loads(m.group())
+            else:
+                logger.warning("recall: LLM returned non-JSON: %.200s", raw)
+                return []
+        selected = data.get("selected_memories", [])
+        valid_names = {f.filename for f in files}
+        result = [s for s in selected if s in valid_names][:max_results]
+        logger.debug("recall: selected %d memories: %s", len(result), result)
+        return result
+    except Exception as exc:
+        logger.warning("recall: memory selection failed (%s), returning []", exc)
+        return []
+
+
+def _format_relative_age(mtime: float) -> str | None:
+    """Return age description if memory is older than 48 hours.
+
+    Returns None if 48 hours or newer, otherwise returns "X days old".
+    """
+    import time
+
+    age_seconds = time.time() - mtime
+    hours = age_seconds / 3600
+    if hours <= 48:
+        return None
+    days = int(age_seconds / 86400)
+    if days == 1:
+        return "1 day old"
+    return f"{days} days old"
+
+
+def format_recall_injection(
+    filenames: list[str],
+    memory_dir: Path | None = None,
+    *,
+    label: str = "Global Memories",
+) -> str:
+    """Read selected memory files and format for system prompt injection.
+
+    Includes relative timestamp (e.g., "3 days old") for memories older than 48 hours.
+    """
+
+    mem_dir = memory_dir or _default_global_memory_dir()
+    if not filenames:
+        return ""
+
+    blocks: list[str] = []
+    for fname in filenames:
+        path = mem_dir / fname
+        if not path.is_file():
+            continue
+        try:
+            content = path.read_text(encoding="utf-8").strip()
+            # Get file modification time for age calculation
+            mtime = path.stat().st_mtime
+            age_note = _format_relative_age(mtime)
+        except OSError:
+            continue
+
+        # Build header with optional age note
+        if age_note:
+            header = f"### {fname} ({age_note})"
+        else:
+            header = f"### {fname}"
+        blocks.append(f"{header}\n\n{content}")
+
+    if not blocks:
+        return ""
+
+    body = "\n\n---\n\n".join(blocks)
+    return f"--- {label} ---\n\n{body}\n\n--- End {label} ---"
+
+
+async def build_scoped_recall_blocks(
+    query: str,
+    llm: Any,
+    *,
+    global_memory_dir: Path | None = None,
+    queen_memory_dir: Path | None = None,
+    queen_id: str | None = None,
+    global_max_results: int = 3,
+    queen_max_results: int = 3,
+) -> tuple[str, str]:
+    """Build separate recall blocks for global and queen-scoped memory."""
+    global_dir = global_memory_dir or _default_global_memory_dir()
+    global_selected = await select_memories(
+        query,
+        llm,
+        memory_dir=global_dir,
+        max_results=global_max_results,
+    )
+    global_block = format_recall_injection(
+        global_selected,
+        memory_dir=global_dir,
+        label="Global Memories",
+    )
+
+    queen_block = ""
+    if queen_memory_dir is not None:
+        queen_selected = await select_memories(
+            query,
+            llm,
+            memory_dir=queen_memory_dir,
+            max_results=queen_max_results,
+        )
+        queen_label = f"Queen Memories: {queen_id}" if queen_id else "Queen Memories"
+        queen_block = format_recall_injection(
+            queen_selected,
+            memory_dir=queen_memory_dir,
+            label=queen_label,
+        )
+
+    return global_block, queen_block

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

@@ -13,7 +13,7 @@
 6. **Calling set_output in same turn as tool calls** — Call set_output in a SEPARATE turn.
 
 ## File Template Errors
-7. **Wrong import paths** — Use `from framework.graph import ...`, NOT `from core.framework.graph import ...`.
+7. **Wrong import paths** — Use `from framework.orchestrator import ...`, NOT `from framework.graph import ...` or `from core.framework...`.
 8. **Missing storage path** — Agent class must set `self._storage_path = Path.home() / ".hive" / "agents" / "agent_name"`.
 9. **Missing mcp_servers.json** — Without this, the agent has no tools at runtime.
 10. **Bare `python` command** — Use `"command": "uv"` with args `["run", "python", ...]`.
@@ -25,9 +25,8 @@
 14. **Forgetting sys.path setup in conftest.py** — Tests need `exports/` and `core/` on sys.path.
 
 ## GCU Errors
-15. **Manually wiring browser tools on event_loop nodes** — Use `node_type="gcu"` which auto-includes browser tools. Do NOT manually list browser tool names.
-16. **Using GCU nodes as regular graph nodes** — GCU nodes are subagents only. They must ONLY appear in `sub_agents=["gcu-node-id"]` and be invoked via `delegate_to_sub_agent()`. Never connect via edges or use as entry/terminal nodes.
+15. **Manually wiring browser tools on event_loop nodes** — Browser nodes use tools: {policy: "all"} to get all browser tools.
 
 ## Worker Agent Errors
-17. **Adding client-facing intake node to workers** — The queen owns intake. Workers should start with an autonomous processing node. Client-facing nodes in workers are for mid-execution review/approval only.
-18. **Putting `escalate` or `set_output` in NodeSpec `tools=[]`** — These are synthetic framework tools, auto-injected at runtime. Only list MCP tools from `list_agent_tools()`.
+19. **Adding client-facing intake node to workers** — The queen owns intake. Workers should start with an autonomous processing node. Route worker review/approval through queen escalation instead of direct worker HITL.
+20. **Putting `escalate` or `set_output` in NodeSpec `tools=[]`** — These are synthetic framework tools, auto-injected at runtime. Only list MCP tools from `list_agent_tools()`.

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

@@ -55,7 +55,7 @@ metadata = AgentMetadata()
 ```python
 """Node definitions for My Agent."""
 
-from framework.graph import NodeSpec
+from framework.orchestrator import NodeSpec
 
 # Node 1: Process (autonomous entry node)
 # The queen handles intake and passes structured input via
@@ -123,14 +123,15 @@ __all__ = ["process_node", "handoff_node"]
 
 from pathlib import Path
 
-from framework.graph import EdgeSpec, EdgeCondition, Goal, SuccessCriterion, Constraint
-from framework.graph.edge import GraphSpec
-from framework.graph.executor import ExecutionResult
-from framework.graph.checkpoint_config import CheckpointConfig
+from framework.orchestrator import EdgeSpec, EdgeCondition, Goal, SuccessCriterion, Constraint
+from framework.orchestrator.edge import GraphSpec
+from framework.orchestrator.orchestrator import ExecutionResult
+from framework.orchestrator.checkpoint_config import CheckpointConfig
 from framework.llm import LiteLLMProvider
-from framework.runner.tool_registry import ToolRegistry
-from framework.runtime.agent_runtime import AgentRuntime, create_agent_runtime
-from framework.runtime.execution_stream import EntryPointSpec
+from framework.loader.tool_registry import ToolRegistry
+from framework.host.agent_host import AgentHost
+from framework.host.execution_manager import EntryPointSpec
+
 
 from .config import default_config, metadata
 from .nodes import process_node, handoff_node
@@ -180,7 +181,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:
@@ -227,7 +228,7 @@ class MyAgent:
         tools = list(self._tool_registry.get_tools().values())
         tool_executor = self._tool_registry.get_executor()
         self._graph = self._build_graph()
-        self._agent_runtime = create_agent_runtime(
+        self._agent_runtime = AgentHost(
             graph=self._graph, goal=self.goal, storage_path=self._storage_path,
             entry_points=[EntryPointSpec(id="default", name="Default", entry_node=self.entry_node,
                                          trigger_type="manual", isolation_level="shared")],
@@ -332,81 +333,46 @@ class MyAgent:
 default_agent = MyAgent()
 ```
 
-## agent.py — Async Entry Points Variant
+## triggers.json — Timer and Webhook Triggers
 
-When an agent needs timers, webhooks, or event-driven triggers, add
-`async_entry_points` and optionally `runtime_config` as module-level variables.
-These are IN ADDITION to the standard variables above.
+When an agent needs timers, webhooks, or event-driven triggers, create a
+`triggers.json` file in the agent's directory (alongside `agent.py`).
+The queen loads these at session start and the user can manage them via
+the `set_trigger` / `remove_trigger` tools at runtime.
 
-```python
-# Additional imports for async entry points
-from framework.graph.edge import GraphSpec, AsyncEntryPointSpec
-from framework.runtime.agent_runtime import (
-    AgentRuntime, AgentRuntimeConfig, create_agent_runtime,
-)
-
-# ... (goal, nodes, edges, entry_node, entry_points, etc. as above) ...
-
-# Async entry points — event-driven triggers
-async_entry_points = [
-    # Timer with cron: daily at 9am
-    AsyncEntryPointSpec(
-        id="daily-check",
-        name="Daily Check",
-        entry_node="process-node",
-        trigger_type="timer",
-        trigger_config={"cron": "0 9 * * *"},
-        isolation_level="shared",
-        max_concurrent=1,
-    ),
-    # Timer with fixed interval: every 20 minutes
-    AsyncEntryPointSpec(
-        id="scheduled-check",
-        name="Scheduled Check",
-        entry_node="process-node",
-        trigger_type="timer",
-        trigger_config={"interval_minutes": 20, "run_immediately": False},
-        isolation_level="shared",
-        max_concurrent=1,
-    ),
-    # Event: reacts to webhook events
-    AsyncEntryPointSpec(
-        id="webhook-event",
-        name="Webhook Event Handler",
-        entry_node="process-node",
-        trigger_type="event",
-        trigger_config={"event_types": ["webhook_received"]},
-        isolation_level="shared",
-        max_concurrent=10,
-    ),
+```json
+[
+  {
+    "id": "daily-check",
+    "name": "Daily Check",
+    "trigger_type": "timer",
+    "trigger_config": {"cron": "0 9 * * *"},
+    "task": "Run the daily check process"
+  },
+  {
+    "id": "scheduled-check",
+    "name": "Scheduled Check",
+    "trigger_type": "timer",
+    "trigger_config": {"interval_minutes": 20},
+    "task": "Run the scheduled check"
+  },
+  {
+    "id": "webhook-event",
+    "name": "Webhook Event Handler",
+    "trigger_type": "webhook",
+    "trigger_config": {"event_types": ["webhook_received"]},
+    "task": "Process incoming webhook event"
+  }
 ]
-
-# Webhook server config (only needed if using webhooks)
-runtime_config = AgentRuntimeConfig(
-    webhook_host="127.0.0.1",
-    webhook_port=8080,
-    webhook_routes=[
-        {
-            "source_id": "my-source",
-            "path": "/webhooks/my-source",
-            "methods": ["POST"],
-        },
-    ],
-)
 ```
 
-**Key rules for async entry points:**
-- `async_entry_points` is a list of `AsyncEntryPointSpec` (NOT `EntryPointSpec`)
-- `runtime_config` is `AgentRuntimeConfig` (NOT `RuntimeConfig` from config.py)
-- Valid trigger_types: `timer`, `event`, `webhook`, `manual`, `api`
-- Valid isolation_levels: `isolated`, `shared`, `synchronized`
+**Key rules for triggers.json:**
+- Valid trigger_types: `timer`, `webhook`
 - Timer trigger_config (cron): `{"cron": "0 9 * * *"}` — standard 5-field cron expression
-- Timer trigger_config (interval): `{"interval_minutes": float, "run_immediately": bool}`
-- Event trigger_config: `{"event_types": ["webhook_received"], "filter_stream": "...", "filter_node": "..."}`
-- Use `isolation_level="shared"` for async entry points that need to read
-  the primary session's memory (e.g., user-configured rules)
-- The `_build_graph()` method passes `async_entry_points` to GraphSpec
-- Reference: `exports/gmail_inbox_guardian/agent.py`
+- Timer trigger_config (interval): `{"interval_minutes": float}`
+- Each trigger must have a unique `id`
+- The `task` field describes what the worker should do when the trigger fires
+- Triggers are persisted back to `triggers.json` when modified via queen tools
 
 ## __init__.py
 
@@ -453,21 +419,6 @@ __all__ = [
 ]
 ```
 
-**If the agent uses async entry points**, also import and export:
-```python
-from .agent import (
-    ...,
-    async_entry_points,
-    runtime_config,  # Only if using webhooks
-)
-
-__all__ = [
-    ...,
-    "async_entry_points",
-    "runtime_config",
-]
-```
-
 ## __main__.py
 
 ```python
@@ -510,8 +461,8 @@ def tui():
     from framework.tui.app import AdenTUI
     from framework.llm import LiteLLMProvider
     from framework.runner.tool_registry import ToolRegistry
-    from framework.runtime.agent_runtime import create_agent_runtime
-    from framework.runtime.execution_stream import EntryPointSpec
+    from framework.host.agent_host import AgentHost
+    from framework.host.execution_manager import EntryPointSpec
 
     async def run_tui():
         agent = MyAgent()
@@ -521,7 +472,7 @@ def tui():
         mcp_cfg = Path(__file__).parent / "mcp_servers.json"
         if mcp_cfg.exists(): agent._tool_registry.load_mcp_config(mcp_cfg)
         llm = LiteLLMProvider(model=agent.config.model, api_key=agent.config.api_key, api_base=agent.config.api_base)
-        runtime = create_agent_runtime(
+        runtime = AgentHost(
             graph=agent._build_graph(), goal=agent.goal, storage_path=storage,
             entry_points=[EntryPointSpec(id="start", name="Start", entry_node="process", trigger_type="manual", isolation_level="isolated")],
             llm=llm, tools=list(agent._tool_registry.get_tools().values()), tool_executor=agent._tool_registry.get_executor())
@@ -559,17 +510,17 @@ if __name__ == "__main__":
 
 ## mcp_servers.json
 
-> **Auto-generated.** `initialize_agent_package` creates this file with hive-tools
+> **Auto-generated.** `initialize_and_build_agent` creates this file with hive_tools
 > as the default. Only edit manually to add additional MCP servers.
 
 ```json
 {
-  "hive-tools": {
+  "hive_tools": {
     "transport": "stdio",
     "command": "uv",
     "args": ["run", "python", "mcp_server.py", "--stdio"],
     "cwd": "../../tools",
-    "description": "Hive tools MCP server"
+    "description": "hive_tools MCP server"
   }
 }
 ```

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

@@ -0,0 +1,227 @@
+# Declarative Agent File Templates
+
+Agents are defined as a single `agent.yaml` file. No Python code needed.
+The runner loads this file directly -- no `agent.py`, `config.py`, or
+`nodes/__init__.py` required.
+
+## agent.yaml -- Complete Agent Definition
+
+```yaml
+name: my-agent
+version: 1.0.0
+description: What this agent does.
+
+metadata:
+  intro_message: Welcome! What would you like me to do?
+
+# Template variables -- substituted into system_prompt and identity_prompt
+# via {{variable_name}} syntax.  Use this for config values that appear
+# in prompts (spreadsheet IDs, API endpoints, account names, etc.)
+variables:
+  spreadsheet_id: "1ZVxWDL..."
+  sheet_name: "contacts"
+
+goal:
+  description: What this agent achieves.
+  success_criteria:
+    - "First success criterion"
+    - "Second success criterion"
+  constraints:
+    - "Hard constraint the agent must respect"
+
+identity_prompt: |
+  You are a helpful agent.
+
+conversation_mode: continuous   # always "continuous" for Hive agents
+
+loop_config:
+  max_iterations: 100
+  max_tool_calls_per_turn: 30
+  max_context_tokens: 32000
+
+# MCP servers to connect (resolved by name from ~/.hive/mcp_registry/)
+mcp_servers:
+  - name: hive_tools
+  - name: gcu-tools
+
+nodes:
+  # Node 1: Process (autonomous entry node)
+  # The queen handles intake and passes structured input via
+  # run_agent_with_input(task). NO client-facing intake node.
+  - id: process
+    name: Process
+    description: Execute the task using available tools
+    max_node_visits: 0   # 0 = unlimited (forever-alive agents)
+    input_keys: [user_request, feedback]
+    output_keys: [results]
+    nullable_output_keys: [feedback]
+    tools:
+      policy: explicit
+      allowed: [web_search, web_scrape, save_data, load_data, list_data_files]
+    success_criteria: Results are complete and accurate.
+    system_prompt: |
+      You are a processing agent. Your task is in memory under "user_request".
+      If "feedback" is present, this is a revision.
+
+      Work in phases:
+      1. Use tools to gather/process data
+      2. Analyze results
+      3. Call set_output in a SEPARATE turn:
+         - set_output("results", "structured results")
+
+  # Node 2: Handoff (autonomous)
+  - id: handoff
+    name: Handoff
+    description: Prepare worker results for queen review
+    max_node_visits: 0
+    input_keys: [results, user_request]
+    output_keys: [next_action, feedback, worker_summary]
+    nullable_output_keys: [feedback, worker_summary]
+    tools:
+      policy: none   # handoff nodes don't need tools
+    success_criteria: Results are packaged for queen decision-making.
+    system_prompt: |
+      Do NOT talk to the user directly. The queen is the only user interface.
+
+      If blocked, call escalate(reason, context) then set:
+      - set_output("next_action", "escalated")
+      - set_output("feedback", "what help is needed")
+
+      Otherwise summarize and set:
+      - set_output("worker_summary", "short summary for queen")
+      - set_output("next_action", "done") or "revise"
+      - set_output("feedback", "what to revise") only when revising
+
+edges:
+  - from_node: process
+    to_node: handoff
+  # Feedback loop
+  - from_node: handoff
+    to_node: process
+    condition: conditional
+    condition_expr: "str(next_action).lower() == 'revise'"
+    priority: 2
+  # Escalation loop
+  - from_node: handoff
+    to_node: process
+    condition: conditional
+    condition_expr: "str(next_action).lower() == 'escalated'"
+    priority: 3
+  # Loop back for next task
+  - from_node: handoff
+    to_node: process
+    condition: conditional
+    condition_expr: "str(next_action).lower() == 'done'"
+
+entry_node: process
+terminal_nodes: []   # [] = forever-alive
+```
+
+## Key differences from Python templates
+
+| Before (Python)                     | After (YAML)                           |
+|-------------------------------------|----------------------------------------|
+| `agent.py` (250 lines boilerplate)  | Not needed                             |
+| `config.py` (dataclass + metadata)  | `variables:` + `metadata:` in YAML     |
+| `nodes/__init__.py` (NodeSpec calls)| `nodes:` list in YAML                  |
+| `__init__.py`, `__main__.py`        | Not needed                             |
+| f-string config injection           | `{{variable_name}}` templates          |
+| `mcp_servers.json` (separate file)  | `mcp_servers:` in YAML (or keep file)  |
+
+## Node types
+
+| Type         | Description                           | Tools                    |
+|--------------|---------------------------------------|--------------------------|
+| `event_loop` | LLM-driven orchestration (default)    | Explicit list or `none`  |
+| `gcu`        | Browser automation via GCU tools      | `policy: all` (auto)     |
+
+## Tool access policies
+
+```yaml
+# Explicit list (recommended for most nodes)
+tools:
+  policy: explicit
+  allowed: [web_search, save_data]
+
+# All tools (for browser automation nodes)
+tools:
+  policy: all
+
+# No tools (for handoff/summary nodes)
+tools:
+  policy: none
+```
+
+## Edge conditions
+
+| Condition     | When to use                                           |
+|---------------|-------------------------------------------------------|
+| `on_success`  | Default. Next node after current succeeds.            |
+| `on_failure`  | Fallback path when current node fails.                |
+| `always`      | Always traverse regardless of outcome.                |
+| `conditional` | Evaluate `condition_expr` against shared memory keys. |
+| `llm_decide`  | Let the LLM decide at runtime.                        |
+
+## Template variables
+
+Use `{{variable_name}}` in `system_prompt` and `identity_prompt`.
+Variables are defined in the top-level `variables:` map.
+
+```yaml
+variables:
+  spreadsheet_id: "1ZVxWDL..."
+  api_endpoint: "https://api.example.com"
+
+nodes:
+  - id: start
+    system_prompt: |
+      Connect to spreadsheet: {{spreadsheet_id}}
+      API endpoint: {{api_endpoint}}
+```
+
+## Entry points
+
+Default is a single manual entry point. For timer/scheduled triggers:
+
+```yaml
+entry_points:
+  - id: default
+    trigger_type: manual
+  - id: daily-check
+    trigger_type: timer
+    trigger_config:
+      interval_minutes: 30
+```
+
+## mcp_servers.json -- Still Supported
+
+The `mcp_servers.json` file is still loaded automatically if present alongside
+`agent.yaml`.  You can also inline servers in the YAML:
+
+```yaml
+mcp_servers:
+  - name: hive_tools
+  - name: gcu-tools
+```
+
+Both approaches work. The JSON file takes precedence for backward compatibility.
+
+## Migration from Python agents
+
+Run the migration tool to convert existing agents:
+
+```bash
+uv run python -m framework.tools.migrate_agent exports/my_agent
+```
+
+This generates `agent.yaml` from the existing `agent.py` + `nodes/` + `config.py`.
+The original files are left untouched. Once verified, you can delete the Python files.
+
+## Files after migration
+
+```
+my_agent/
+  agent.yaml           # The only required file
+  mcp_servers.json     # Optional (can inline in YAML)
+  flowchart.json       # Optional (auto-generated)
+```

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

@@ -0,0 +1,193 @@
+# Hive Agent Framework -- Condensed Reference
+
+## Architecture
+
+Agents are declarative JSON configs in `exports/`:
+```
+exports/my_agent/
+  agent.json          # The entire agent definition
+  mcp_servers.json    # MCP tool server config (optional, prefer registry refs)
+```
+
+No Python files. No `__init__.py`, `__main__.py`, `config.py`, or `nodes/`.
+
+## Agent Loading
+
+`AgentLoader.load()` reads `agent.json` and builds the execution graph.
+If `agent.py` exists (legacy), it's loaded as a Python module instead.
+
+## agent.json Schema
+
+```json
+{
+  "name": "my-agent",
+  "version": "1.0.0",
+  "description": "What this agent does",
+  "goal": {
+    "description": "What to achieve",
+    "success_criteria": ["criterion 1", "criterion 2"],
+    "constraints": ["constraint 1"]
+  },
+  "identity_prompt": "You are a helpful agent.",
+  "conversation_mode": "continuous",
+  "loop_config": {
+    "max_iterations": 100,
+    "max_tool_calls_per_turn": 30,
+    "max_context_tokens": 32000
+  },
+  "mcp_servers": [
+    {"name": "hive_tools"},
+    {"name": "gcu-tools"}
+  ],
+  "variables": {
+    "spreadsheet_id": "1ZVx..."
+  },
+  "nodes": [...],
+  "edges": [...],
+  "entry_node": "process",
+  "terminal_nodes": []
+}
+```
+
+## Template Variables
+
+Use `{{variable_name}}` in `system_prompt` and `identity_prompt`. Variables
+are defined in the top-level `variables` object:
+
+```json
+{
+  "variables": {"sheet_id": "1ZVx..."},
+  "nodes": [{
+    "id": "start",
+    "system_prompt": "Use sheet: {{sheet_id}}"
+  }]
+}
+```
+
+## Node Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| id | str | required | kebab-case identifier |
+| name | str | id | Display name |
+| description | str | required | What the node does |
+| node_type | str | "event_loop" | `"event_loop"` |
+| input_keys | list | [] | Memory keys this node reads |
+| output_keys | list | [] | Memory keys this node writes via set_output |
+| system_prompt | str | "" | LLM instructions |
+| tools | object | {} | Tool access policy (see below) |
+| nullable_output_keys | list | [] | Keys that may remain unset |
+| max_node_visits | int | 1 | 0=unlimited (for forever-alive agents) |
+| success_criteria | str | "" | Natural language for judge evaluation |
+| client_facing | bool | false | Whether output is shown to user |
+
+## Tool Access Policies
+
+Each node declares its tools via a policy object:
+
+```json
+{"tools": {"policy": "explicit", "allowed": ["web_search", "save_data"]}}
+{"tools": {"policy": "all"}}
+{"tools": {"policy": "none"}}
+```
+
+- `explicit` (default): only named tools. Empty `allowed` = zero tools.
+- `all`: all tools from registry (e.g. for browser automation nodes).
+- `none`: no tools (for handoff/summary nodes).
+
+## Edge Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| from_node | str | Source node ID |
+| to_node | str | Target node ID |
+| condition | str | `on_success`, `on_failure`, `always`, `conditional` |
+| condition_expr | str | Python expression for conditional routing |
+| priority | int | Higher = evaluated first |
+
+condition_expr examples:
+- `"needs_more_research == True"`
+- `"str(next_action).lower() == 'revise'"`
+
+## Key Patterns
+
+### Fewer, Richer Nodes (CRITICAL)
+
+**Hard limit: 3-6 nodes for most agents.** Each node boundary serializes
+outputs and destroys in-context information. Merge unless:
+1. Client-facing boundary (different interaction models)
+2. Disjoint tool sets
+3. Parallel execution (fan-out branches)
+
+**Typical structure (2 nodes):**
+```
+process (autonomous) <-> review (queen-mediated)
+```
+
+The queen owns intake. Worker agents should NOT have a client-facing intake
+node. Mid-execution review should happen through queen escalation.
+
+### set_output
+- Synthetic tool injected by framework
+- Call separately from real tool calls (separate turn)
+- `set_output("key", "value")` stores to the shared buffer
+
+### Graph Lifecycle
+
+| Pattern | terminal_nodes | When |
+|---------|---------------|------|
+| Continuous loop | `["node-with-output-keys"]` | DEFAULT for all agents |
+| Linear | `["last-node"]` | One-shot/batch agents |
+
+Every graph must have at least one terminal node.
+
+### Continuous Conversation Mode
+
+`conversation_mode` has ONLY two valid states:
+- `"continuous"` -- recommended (context carries across node transitions)
+- Omit entirely -- isolated per-node conversations
+
+**INVALID values:** `"client_facing"`, `"interactive"`, `"shared"`.
+
+## loop_config
+
+Only three valid keys:
+```json
+{
+  "max_iterations": 100,
+  "max_tool_calls_per_turn": 20,
+  "max_context_tokens": 32000
+}
+```
+
+## Data Tools (Spillover)
+
+For large data that exceeds context:
+- `save_data(filename, data)` -- write to session data dir
+- `load_data(filename, offset, limit)` -- read with pagination
+- `list_data_files()` -- list files
+- `serve_file_to_user(filename, label)` -- clickable file URI
+
+`data_dir` is auto-injected by framework.
+
+## Fan-Out / Fan-In
+
+Multiple `on_success` edges from same source = parallel execution.
+Parallel nodes must have disjoint output_keys.
+
+## Judge System
+
+- **Implicit** (default): ACCEPTs when LLM finishes with no tool calls and all required outputs set
+- **SchemaJudge**: Validates against Pydantic model
+
+## Tool Discovery
+
+Always call `list_agent_tools()` first to see available tools.
+Do NOT rely on a static tool list.
+
+```
+list_agent_tools()                                      # full summary
+list_agent_tools(group="gmail", output_schema="full")   # drill into category
+```
+
+After building, run `validate_agent_package("{name}")` to check everything.

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

@@ -0,0 +1,78 @@
+# Browser Automation Guide
+
+## When to Use Browser Nodes
+
+Use browser nodes (with `tools: {policy: "all"}`) when:
+- The task requires interacting with web pages (clicking, typing, navigating)
+- No API is available for the target service
+- The user is already logged in to the target site
+
+## What Browser Nodes Are
+
+- Regular `event_loop` nodes with browser tools from gcu-tools MCP server
+- Set `tools: {policy: "all"}` to give access to all browser tools
+- Wire into the graph with edges like any other node
+- No special node_type needed
+
+## Available Browser Tools
+
+All tools are prefixed with `browser_`:
+- `browser_start`, `browser_open`, `browser_navigate` — launch/navigate
+- `browser_click`, `browser_click_coordinate`, `browser_fill`, `browser_type` — interact
+- `browser_press` (with optional `modifiers=["ctrl"]` etc.) — keyboard shortcuts
+- `browser_snapshot` — compact accessibility-tree read (structured)
+- `browser_screenshot` — visual capture (annotated PNG)
+- `browser_shadow_query`, `browser_get_rect` — locate elements (shadow-piercing via `>>>`)
+- `browser_coords` — convert image pixels to CSS pixels (always use `css_x/y`, never `physical_x/y`)
+- `browser_scroll`, `browser_wait` — navigation helpers
+- `browser_evaluate` — run JavaScript
+- `browser_close`, `browser_close_finished` — tab cleanup
+
+## Pick the right reading tool
+
+**`browser_snapshot`** — compact accessibility tree of interactive elements. Fast, cheap, good for static or form-heavy pages where the DOM matches what's visually rendered (documentation, simple dashboards, search results, settings pages).
+
+**`browser_screenshot`** — visual capture + metadata (`cssWidth`, `devicePixelRatio`, scale fields). **Use this on any complex SPA** — LinkedIn, Twitter/X, Reddit, Gmail, Notion, Slack, Discord, any site using shadow DOM, virtual scrolling, React reconciliation, or dynamic layout. On these pages, snapshot refs go stale in seconds, shadow contents aren't in the AX tree, and virtual-scrolled elements disappear from the tree entirely. Screenshot is the **only** reliable way to orient yourself.
+
+Neither tool is "preferred" universally — they're for different jobs. Default to snapshot on text-heavy static pages, screenshot on SPAs and anything shadow-DOM-heavy. Activate the `browser-automation` skill for the full decision tree.
+
+## Coordinate rule: always CSS pixels
+
+Chrome DevTools Protocol `Input.dispatchMouseEvent` takes **CSS pixels**, not physical pixels. After a screenshot, use `browser_coords(image_x, image_y)` and feed the returned `css_x/y` (NOT `physical_x/y`) to `browser_click_coordinate`, `browser_hover_coordinate`, `browser_press_at`. Feeding physical pixels on a HiDPI display (DPR=1.6, 2, or 3) overshoots by `DPR×` and clicks land in the wrong place. `getBoundingClientRect()` already returns CSS pixels — pass through unchanged, no DPR multiplication.
+
+## System prompt tips for browser nodes
+
+```
+1. On LinkedIn / X / Reddit / Gmail / any SPA — use browser_screenshot to orient,
+   not browser_snapshot. Shadow DOM and virtual scrolling make snapshots unreliable.
+2. For static pages (docs, forms, search results), browser_snapshot is fine.
+3. Before typing into a rich-text editor (X compose, LinkedIn DM, Gmail, Reddit),
+   click the input area first with browser_click_coordinate so React / Draft.js /
+   Lexical register a native focus event. Otherwise the send button stays disabled.
+4. Use browser_wait(seconds=2-3) after navigation for SPA hydration.
+5. If you hit an auth wall, call set_output with an error and move on.
+6. Keep tool calls per turn <= 10 for reliability.
+```
+
+## Example
+
+```json
+{
+  "id": "scan-profiles",
+  "name": "Scan LinkedIn Profiles",
+  "description": "Navigate LinkedIn search results and collect profile data",
+  "tools": {"policy": "all"},
+  "input_keys": ["search_url"],
+  "output_keys": ["profiles"],
+  "system_prompt": "Navigate to the search URL via browser_navigate(wait_until='load', timeout_ms=20000). Wait 3s for SPA hydration. On LinkedIn, use browser_screenshot to see the page — browser_snapshot misses shadow-DOM and virtual-scrolled content. Paginate through results by scrolling and screenshotting; extract each profile card by reading its visible layout..."
+}
+```
+
+Connected via regular edges:
+```
+search-setup -> scan-profiles -> process-results
+```
+
+## Further detail
+
+For rich-text editor quirks (Lexical, Draft.js, ProseMirror), shadow-DOM shortcuts, `beforeunload` dialog neutralization, Trusted Types CSP on LinkedIn, keyboard shortcut dispatch, and per-site selector tables — **activate the `browser-automation` skill**. That skill has the full verified guidance and is refreshed against real production sites.

core/framework/agents/queen/reflection_agent.py

@@ -0,0 +1,994 @@
+"""Reflection agent — background memory extraction for the queen.
+
+A lightweight side agent that runs after each queen LLM turn.  It inspects
+recent conversation messages and extracts durable user knowledge into
+individual memory files in the configured memory directories.
+
+Two reflection types:
+  - **Short reflection**: after conversational queen turns.  Distills
+    learnings into either global or queen-scoped memory.
+  - **Long reflection**: every 5 short reflections and on CONTEXT_COMPACTED.
+    Organises, deduplicates, and trims a memory directory.
+
+Concurrency: an ``asyncio.Lock`` prevents overlapping runs.  If a trigger
+fires while a reflection is already active the event is skipped.
+
+All reflections are fire-and-forget (spawned via ``asyncio.create_task``)
+so they never block the queen's event loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+import traceback
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from framework.agents.queen.queen_memory_v2 import (
+    GLOBAL_MEMORY_CATEGORIES,
+    MAX_FILE_SIZE_BYTES,
+    MAX_FILES,
+    format_memory_manifest,
+    global_memory_dir as _default_global_memory_dir,
+    parse_frontmatter,
+    scan_memory_files,
+)
+from framework.llm.provider import LLMResponse, Tool
+from framework.tracker.llm_debug_logger import log_llm_turn
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Reflection tool definitions (internal — not in queen's main registry)
+# ---------------------------------------------------------------------------
+
+_REFLECTION_TOOLS: list[Tool] = [
+    Tool(
+        name="list_memory_files",
+        description=(
+            "List memory files with their type, name, and description. "
+            "When scope is omitted, returns all scopes grouped by scope."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "scope": {
+                    "type": "string",
+                    "description": "Optional scope to inspect: 'global' or 'queen'.",
+                },
+            },
+            "additionalProperties": False,
+        },
+    ),
+    Tool(
+        name="read_memory_file",
+        description="Read the full content of a memory file by filename from a scope.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "filename": {
+                    "type": "string",
+                    "description": "The filename (e.g. 'user-prefers-dark-mode.md').",
+                },
+                "scope": {
+                    "type": "string",
+                    "description": "Memory scope: 'global' or 'queen'. Defaults to 'global'.",
+                },
+            },
+            "required": ["filename"],
+            "additionalProperties": False,
+        },
+    ),
+    Tool(
+        name="write_memory_file",
+        description=(
+            "Create or overwrite a memory file.  Content should include YAML "
+            "frontmatter (name, description, type) followed by the memory body.  "
+            f"Max file size: {MAX_FILE_SIZE_BYTES} bytes.  Max files: {MAX_FILES}."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "filename": {
+                    "type": "string",
+                    "description": "Filename ending in .md (e.g. 'user-prefers-dark-mode.md').",
+                },
+                "scope": {
+                    "type": "string",
+                    "description": "Memory scope: 'global' or 'queen'. Defaults to 'global'.",
+                },
+                "content": {
+                    "type": "string",
+                    "description": "Full file content including frontmatter.",
+                },
+            },
+            "required": ["filename", "content"],
+            "additionalProperties": False,
+        },
+    ),
+    Tool(
+        name="delete_memory_file",
+        description=(
+            "Delete a memory file by filename.  Use during long "
+            "reflection to prune stale or redundant memories."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "filename": {
+                    "type": "string",
+                    "description": "The filename to delete.",
+                },
+                "scope": {
+                    "type": "string",
+                    "description": "Memory scope: 'global' or 'queen'. Defaults to 'global'.",
+                },
+            },
+            "required": ["filename"],
+            "additionalProperties": False,
+        },
+    ),
+]
+
+
+def _normalize_memory_dirs(
+    memory_dir: Path | dict[str, Path],
+    *,
+    queen_memory_dir: Path | None = None,
+) -> dict[str, Path]:
+    """Normalize memory directory input into a scope -> path mapping."""
+    if isinstance(memory_dir, dict):
+        return {scope: path for scope, path in memory_dir.items() if path is not None}
+
+    dirs: dict[str, Path] = {"global": memory_dir}
+    if queen_memory_dir is not None:
+        dirs["queen"] = queen_memory_dir
+    return dirs
+
+
+def _scope_label(scope: str, queen_id: str | None = None) -> str:
+    """Human-readable label for a memory scope."""
+    if scope == "queen":
+        return f"queen ({queen_id})" if queen_id else "queen"
+    return scope
+
+
+def _resolve_memory_scope(args: dict[str, Any], memory_dirs: dict[str, Path]) -> str:
+    """Resolve and validate the requested memory scope."""
+    raw_scope = args.get("scope")
+    if raw_scope is None:
+        if len(memory_dirs) == 1:
+            return next(iter(memory_dirs))
+        scope = "global"
+    else:
+        scope = str(raw_scope).strip().lower() or "global"
+    if scope not in memory_dirs:
+        available = ", ".join(sorted(memory_dirs))
+        raise ValueError(f"Invalid scope '{scope}'. Available scopes: {available}.")
+    return scope
+
+
+def _format_multi_scope_manifest(
+    memory_dirs: dict[str, Path],
+    *,
+    queen_id: str | None = None,
+) -> str:
+    """Format a manifest that groups memory files by scope."""
+    blocks: list[str] = []
+    for scope, memory_dir in memory_dirs.items():
+        files = scan_memory_files(memory_dir)
+        label = _scope_label(scope, queen_id)
+        body = format_memory_manifest(files) if files else "(no memory files yet)"
+        blocks.append(f"## Scope: {label}\n\n{body}")
+    return "\n\n".join(blocks)
+
+
+def _safe_memory_path(filename: str, memory_dir: Path) -> Path:
+    """Resolve *filename* inside *memory_dir*, raising if it escapes."""
+    if not filename or filename.strip() != filename:
+        raise ValueError(f"Invalid filename: {filename!r}")
+    if "/" in filename or "\\" in filename or ".." in filename:
+        raise ValueError(f"Invalid filename: path components not allowed: {filename!r}")
+    candidate = (memory_dir / filename).resolve()
+    root = memory_dir.resolve()
+    if not candidate.is_relative_to(root):
+        raise ValueError(f"Path escapes memory directory: {filename!r}")
+    return candidate
+
+
+def _execute_tool(
+    name: str,
+    args: dict[str, Any],
+    memory_dir: Path | dict[str, Path],
+    *,
+    queen_id: str | None = None,
+) -> str:
+    """Execute a reflection tool synchronously.  Returns the result string."""
+    memory_dirs = _normalize_memory_dirs(memory_dir)
+    if name == "list_memory_files":
+        requested_scope = args.get("scope")
+        if requested_scope is not None:
+            try:
+                scope = _resolve_memory_scope(args, memory_dirs)
+            except ValueError as exc:
+                return f"ERROR: {exc}"
+            files = scan_memory_files(memory_dirs[scope])
+            logger.debug("reflect: tool list_memory_files[%s] → %d files", scope, len(files))
+            if not files:
+                return f"(no {scope} memory files yet)"
+            return format_memory_manifest(files)
+        return _format_multi_scope_manifest(memory_dirs, queen_id=queen_id)
+
+    if name == "read_memory_file":
+        filename = args.get("filename", "")
+        try:
+            scope = _resolve_memory_scope(args, memory_dirs)
+        except ValueError as exc:
+            return f"ERROR: {exc}"
+        try:
+            path = _safe_memory_path(filename, memory_dirs[scope])
+        except ValueError as exc:
+            return f"ERROR: {exc}"
+        if not path.exists() or not path.is_file():
+            return f"ERROR: File not found in {scope}: {filename}"
+        try:
+            return path.read_text(encoding="utf-8")
+        except OSError as e:
+            return f"ERROR: {e}"
+
+    if name == "write_memory_file":
+        filename = args.get("filename", "")
+        content = args.get("content", "")
+        try:
+            scope = _resolve_memory_scope(args, memory_dirs)
+        except ValueError as exc:
+            return f"ERROR: {exc}"
+        scope_dir = memory_dirs[scope]
+        if not filename.endswith(".md"):
+            return "ERROR: Filename must end with .md"
+        # Enforce global memory type restrictions.
+        fm = parse_frontmatter(content)
+        mem_type = (fm.get("type") or "").strip().lower()
+        if mem_type and mem_type not in GLOBAL_MEMORY_CATEGORIES:
+            return (
+                f"ERROR: Invalid memory type '{mem_type}'. "
+                f"Allowed types: {', '.join(GLOBAL_MEMORY_CATEGORIES)}."
+            )
+        # Enforce file size limit.
+        if len(content.encode("utf-8")) > MAX_FILE_SIZE_BYTES:
+            return f"ERROR: Content exceeds {MAX_FILE_SIZE_BYTES} byte limit."
+        # Enforce file cap (only for new files).
+        try:
+            path = _safe_memory_path(filename, scope_dir)
+        except ValueError as exc:
+            return f"ERROR: {exc}"
+        if not path.exists():
+            existing = list(scope_dir.glob("*.md"))
+            if len(existing) >= MAX_FILES:
+                return f"ERROR: File cap reached in {scope} ({MAX_FILES}). Delete a file first."
+        scope_dir.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        logger.debug(
+            "reflect: tool write_memory_file[%s] → %s (%d chars)",
+            scope,
+            filename,
+            len(content),
+        )
+        return f"Wrote {scope}:{filename} ({len(content)} chars)."
+
+    if name == "delete_memory_file":
+        filename = args.get("filename", "")
+        try:
+            scope = _resolve_memory_scope(args, memory_dirs)
+        except ValueError as exc:
+            return f"ERROR: {exc}"
+        try:
+            path = _safe_memory_path(filename, memory_dirs[scope])
+        except ValueError as exc:
+            return f"ERROR: {exc}"
+        if not path.exists():
+            return f"ERROR: File not found in {scope}: {filename}"
+        path.unlink()
+        logger.debug("reflect: tool delete_memory_file[%s] → %s", scope, filename)
+        return f"Deleted {scope}:{filename}."
+
+    return f"ERROR: Unknown tool: {name}"
+
+
+# ---------------------------------------------------------------------------
+# Reflection logging helper
+# ---------------------------------------------------------------------------
+
+
+def _log_reflection_turn(
+    *,
+    reflection_id: str,
+    iteration: int,
+    system_prompt: str,
+    messages: list[dict[str, Any]],
+    assistant_text: str,
+    tool_calls: list[dict[str, Any]],
+    tool_results: list[dict[str, Any]],
+    token_counts: dict[str, Any],
+) -> None:
+    """Log a reflection turn using the same JSONL format as the main agent loop."""
+    log_llm_turn(
+        node_id="reflection",
+        stream_id=reflection_id,
+        execution_id=reflection_id,
+        iteration=iteration,
+        system_prompt=system_prompt,
+        messages=messages,
+        assistant_text=assistant_text,
+        tool_calls=tool_calls,
+        tool_results=tool_results,
+        token_counts=token_counts,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Mini event loop
+# ---------------------------------------------------------------------------
+
+_MAX_TURNS = 5
+
+
+async def _reflection_loop(
+    llm: Any,
+    system: str,
+    user_msg: str,
+    memory_dir: Path | dict[str, Path],
+    max_turns: int = _MAX_TURNS,
+    *,
+    queen_id: str | None = None,
+) -> tuple[bool, list[str], str]:
+    """Run a mini tool-use loop: LLM → tool calls → repeat.
+
+    Returns (success, changed_files, last_text).
+    """
+    messages: list[dict[str, Any]] = [{"role": "user", "content": user_msg}]
+    changed_files: list[str] = []
+    last_text: str = ""
+    reflection_id = f"reflection_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+    token_counts: dict[str, Any] = {}
+    memory_dirs = _normalize_memory_dirs(memory_dir)
+
+    for _turn in range(max_turns):
+        logger.info("reflect: loop turn %d/%d (msgs=%d)", _turn + 1, max_turns, len(messages))
+        try:
+            resp: LLMResponse = await llm.acomplete(
+                messages=messages,
+                system=system,
+                tools=_REFLECTION_TOOLS,
+                max_tokens=2048,
+            )
+        except asyncio.CancelledError:
+            logger.warning("reflect: LLM call cancelled (task cancelled)")
+            return False, changed_files, last_text
+        except Exception:
+            logger.warning("reflect: LLM call failed", exc_info=True)
+            return False, changed_files, last_text
+
+        # Extract tool calls from litellm/OpenAI response object.
+        tool_calls_raw: list[dict[str, Any]] = []
+        raw = resp.raw_response
+        if raw is not None:
+            # litellm returns a ModelResponse object; tool calls live on
+            # choices[0].message.tool_calls as a list of ChatCompletionMessageToolCall.
+            try:
+                msg_obj = raw.choices[0].message
+                if hasattr(msg_obj, "tool_calls") and msg_obj.tool_calls:
+                    for tc in msg_obj.tool_calls:
+                        fn = tc.function
+                        try:
+                            args = json.loads(fn.arguments) if fn.arguments else {}
+                        except (json.JSONDecodeError, TypeError):
+                            args = {}
+                        tool_calls_raw.append(
+                            {
+                                "id": tc.id,
+                                "name": fn.name,
+                                "input": args,
+                            }
+                        )
+            except (AttributeError, IndexError):
+                pass
+
+        logger.info(
+            "reflect: LLM responded, text=%d chars, tool_calls=%d",
+            len(resp.content or ""),
+            len(tool_calls_raw),
+        )
+
+        # Capture token counts from the LLM response.
+        try:
+            raw_usage = getattr(raw, "usage", None) if raw else None
+            if raw_usage:
+                token_counts = {
+                    "model": getattr(raw, "model", ""),
+                    "input": getattr(raw_usage, "prompt_tokens", 0) or 0,
+                    "output": getattr(raw_usage, "completion_tokens", 0) or 0,
+                    "cached": getattr(raw_usage, "prompt_tokens_details", None)
+                    and getattr(raw_usage.prompt_tokens_details, "cached_tokens", 0),
+                    "stop_reason": getattr(raw.choices[0], "finish_reason", "") if raw else "",
+                }
+        except Exception:
+            token_counts = {}
+
+        turn_text = resp.content or ""
+        if turn_text:
+            last_text = turn_text
+        assistant_msg: dict[str, Any] = {"role": "assistant", "content": turn_text}
+        if tool_calls_raw:
+            assistant_msg["tool_calls"] = [
+                {
+                    "id": tc["id"],
+                    "type": "function",
+                    "function": {
+                        "name": tc["name"],
+                        "arguments": json.dumps(tc.get("input", {})),
+                    },
+                }
+                for tc in tool_calls_raw
+            ]
+        messages.append(assistant_msg)
+
+        if not tool_calls_raw:
+            break
+
+        tool_results: list[dict[str, Any]] = []
+        for tc in tool_calls_raw:
+            tc_input = tc.get("input", {})
+            result = _execute_tool(tc["name"], tc_input, memory_dirs, queen_id=queen_id)
+            if tc["name"] in ("write_memory_file", "delete_memory_file"):
+                fname = tc_input.get("filename", "")
+                try:
+                    scope = _resolve_memory_scope(tc_input, memory_dirs)
+                except ValueError:
+                    scope = str(tc_input.get("scope", "global")).strip().lower() or "global"
+                if fname and not result.startswith("ERROR"):
+                    changed_files.append(f"{scope}:{fname}")
+            messages.append({"role": "tool", "tool_call_id": tc["id"], "content": result})
+            tool_results.append({"tool_call_id": tc["id"], "name": tc["name"], "result": result})
+
+        # Log the reflection turn in the same JSONL format as the main agent loop.
+        _log_reflection_turn(
+            reflection_id=reflection_id,
+            iteration=_turn,
+            system_prompt=system,
+            messages=messages,
+            assistant_text=turn_text,
+            tool_calls=tool_calls_raw,
+            tool_results=tool_results,
+            token_counts=token_counts,
+        )
+
+    return True, changed_files, last_text
+
+
+# ---------------------------------------------------------------------------
+# System prompts
+# ---------------------------------------------------------------------------
+
+_CATEGORIES_STR = ", ".join(GLOBAL_MEMORY_CATEGORIES)
+
+
+def _build_unified_short_reflect_system(queen_id: str | None = None) -> str:
+    """Build the unified short reflection prompt across memory scopes."""
+    queen_scope = (
+        f"- `queen`: durable learnings specific to how queen '{queen_id}' should work with this user\n"
+        if queen_id
+        else ""
+    )
+    return f"""\
+You are a reflection agent that distills durable knowledge about the USER
+into persistent memory files. You run in the background after each
+assistant turn.
+
+Memory categories: {_CATEGORIES_STR}
+
+Available memory scopes:
+- `global`: durable user facts that should help every queen in future sessions
+{queen_scope}
+
+Expected format for each memory file:
+```markdown
+---
+name: {{{{memory name}}}}
+description: {{{{one-line description — specific and search-friendly}}}}
+type: {{{{{_CATEGORIES_STR}}}}}
+---
+
+{{{{memory content}}}}
+```
+
+Workflow (aim for 2 turns):
+  Turn 1 — call list_memory_files without a scope to inspect all scopes, then
+            read_memory_file for any files that might need updating.
+  Turn 2 — call write_memory_file / delete_memory_file with an explicit scope.
+
+Rules:
+- Make ONE coordinated storage decision per learning.
+- Prefer `global` for broad user facts: identity, general preferences, environment,
+  and feedback that should help all queens.
+- Prefer `queen` only for stable domain-specific learnings about how this queen
+  should reason, prioritize, communicate, or make tradeoffs for this user.
+- Avoid storing the same fact in both scopes unless the scoped version adds
+  genuinely distinct queen-specific nuance. When in doubt, keep only one copy.
+- Update existing files instead of creating duplicates when possible.
+- If the same learning already exists in the wrong scope or both scopes,
+  you may update one file and delete the redundant one.
+- Do NOT store task-specific details, code patterns, file paths, or ephemeral
+  session state.
+- Keep files concise. Each file should cover ONE topic.
+- If there is nothing worth remembering, do nothing (respond with a brief
+  reason — no tool calls needed).
+- File names should be kebab-case slugs ending in .md.
+- For user identity/profile information about the human user (name, role,
+  background), ALWAYS use the canonical filename 'user-profile.md' in the
+  `global` scope. This is the single source of truth for user profile data,
+  shared with the settings UI.
+- When updating `global:user-profile.md`, preserve the '## User Identity'
+  section — it is managed by the settings UI. Never describe the assistant,
+  queen, or agent as the identity in this file. Add/update other sections
+  below it.
+- Do NOT exceed {MAX_FILE_SIZE_BYTES} bytes per file or {MAX_FILES} total files per scope.
+"""
+
+
+def _build_unified_long_reflect_system(queen_id: str | None = None) -> str:
+    """Build the unified housekeeping prompt across memory scopes."""
+    queen_scope = (
+        f"- `queen`: memories specific to how queen '{queen_id}' should work with this user\n"
+        if queen_id
+        else ""
+    )
+    return f"""\
+You are a reflection agent performing a periodic housekeeping pass over the
+memory system for this user.
+
+Memory categories: {_CATEGORIES_STR}
+
+Available memory scopes:
+- `global`: facts useful to every queen
+{queen_scope}
+
+Workflow:
+  1. Call list_memory_files without a scope to inspect all scopes together.
+  2. Read files that look redundant, stale, overlapping, or misplaced.
+  3. Merge duplicates, move memories to the correct scope, and delete
+     redundant copies when appropriate.
+  4. Ensure descriptions are specific and search-friendly.
+  5. Enforce limits: max {MAX_FILES} files and {MAX_FILE_SIZE_BYTES} bytes per file in each scope.
+
+Rules:
+- Treat deduplication across scopes as part of the job, not just within a scope.
+- Prefer `global` for broad durable user facts and `queen` for queen-specific nuance.
+- If two files store materially the same fact, keep the best one and delete or
+  rewrite the redundant one.
+- Prefer merging over deleting when the memories contain complementary signal.
+- Remove memories that are stale, superseded, or misplaced.
+- Keep the total collection lean and high-signal.
+- Do NOT invent new information — only reorganise what exists.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Short & long reflection entry points
+# ---------------------------------------------------------------------------
+
+
+async def _read_conversation_parts(session_dir: Path) -> list[dict[str, Any]]:
+    """Read conversation parts from the queen session directory."""
+    from framework.storage.conversation_store import FileConversationStore
+
+    store = FileConversationStore(session_dir / "conversations")
+    return await store.read_parts()
+
+
+async def run_short_reflection(
+    session_dir: Path,
+    llm: Any,
+    memory_dir: Path | None = None,
+) -> None:
+    """Run a global-only short reflection (compatibility wrapper)."""
+    logger.info("reflect: starting global short reflection for %s", session_dir)
+    mem_dir = memory_dir or _default_global_memory_dir()
+    await _run_short_reflection_with_prompt(
+        session_dir,
+        llm,
+        mem_dir,
+        system_prompt=_build_unified_short_reflect_system(),
+        log_label="global",
+        queen_id=None,
+    )
+
+
+async def run_queen_short_reflection(
+    session_dir: Path,
+    llm: Any,
+    queen_id: str,
+    memory_dir: Path,
+) -> None:
+    """Run a queen-only short reflection (compatibility wrapper)."""
+    logger.info("reflect: starting queen short reflection for %s (%s)", session_dir, queen_id)
+    await _run_short_reflection_with_prompt(
+        session_dir,
+        llm,
+        {"queen": memory_dir},
+        system_prompt=_build_unified_short_reflect_system(queen_id),
+        log_label=f"queen:{queen_id}",
+        queen_id=queen_id,
+    )
+
+
+async def run_unified_short_reflection(
+    session_dir: Path,
+    llm: Any,
+    *,
+    global_memory_dir: Path | None = None,
+    queen_memory_dir: Path | None = None,
+    queen_id: str | None = None,
+) -> None:
+    """Run one short reflection loop over all active memory scopes."""
+    global_dir = global_memory_dir or _default_global_memory_dir()
+    memory_dirs = {"global": global_dir}
+    if queen_memory_dir is not None and queen_id:
+        memory_dirs["queen"] = queen_memory_dir
+
+    logger.info(
+        "reflect: starting unified short reflection for %s (scopes=%s)",
+        session_dir,
+        sorted(memory_dirs),
+    )
+    await _run_short_reflection_with_prompt(
+        session_dir,
+        llm,
+        memory_dirs,
+        system_prompt=_build_unified_short_reflect_system(
+            queen_id if "queen" in memory_dirs else None
+        ),
+        log_label="unified",
+        queen_id=queen_id if "queen" in memory_dirs else None,
+    )
+
+
+async def _run_short_reflection_with_prompt(
+    session_dir: Path,
+    llm: Any,
+    memory_dir: Path | dict[str, Path],
+    *,
+    system_prompt: str,
+    log_label: str,
+    queen_id: str | None,
+) -> None:
+    """Run a short reflection with a scope-specific system prompt."""
+    mem_dir = memory_dir
+
+    messages = await _read_conversation_parts(session_dir)
+    if not messages:
+        logger.info("reflect: no conversation parts found in %s, skipping", session_dir)
+        return
+
+    transcript_lines: list[str] = []
+    for msg in messages[-50:]:
+        role = msg.get("role", "")
+        content = str(msg.get("content", "")).strip()
+        if role == "tool" or not content:
+            continue
+        label = "user" if role == "user" else "assistant"
+        if len(content) > 800:
+            content = content[:800] + "…"
+        transcript_lines.append(f"[{label}]: {content}")
+
+    if not transcript_lines:
+        logger.info("reflect: no transcript lines after filtering, skipping")
+        return
+
+    transcript = "\n".join(transcript_lines)
+    user_msg = (
+        f"## Recent conversation ({len(messages)} messages total)\n\n"
+        f"{transcript}\n\n"
+        f"Timestamp: {datetime.now().isoformat(timespec='minutes')}"
+    )
+
+    _, changed, reason = await _reflection_loop(
+        llm,
+        system_prompt,
+        user_msg,
+        mem_dir,
+        queen_id=queen_id,
+    )
+    if changed:
+        logger.info("reflect: %s short reflection done, changed files: %s", log_label, changed)
+    else:
+        logger.info(
+            "reflect: %s short reflection done, no changes — %s",
+            log_label,
+            reason or "no reason",
+        )
+
+
+async def run_long_reflection(
+    llm: Any,
+    memory_dir: Path | None = None,
+    *,
+    scope_label: str = "global",
+) -> None:
+    """Run a single-scope long reflection (compatibility wrapper)."""
+    logger.debug("reflect: starting long reflection for %s", scope_label)
+    mem_dir = memory_dir or _default_global_memory_dir()
+    files = scan_memory_files(mem_dir)
+
+    if not files:
+        logger.debug("reflect: no %s memory files, skipping long reflection", scope_label)
+        return
+
+    manifest = format_memory_manifest(files)
+    user_msg = (
+        f"## Current memory manifest ({len(files)} files)\n\n"
+        f"{manifest}\n\n"
+        f"Timestamp: {datetime.now().isoformat(timespec='minutes')}"
+    )
+
+    _, changed, reason = await _reflection_loop(
+        llm,
+        _build_unified_long_reflect_system(),
+        user_msg,
+        mem_dir,
+        queen_id=None,
+    )
+    if changed:
+        logger.debug(
+            "reflect: long reflection done for %s (%d files), changed: %s",
+            scope_label,
+            len(files),
+            changed,
+        )
+    else:
+        logger.debug(
+            "reflect: long reflection done for %s (%d files), no changes — %s",
+            scope_label,
+            len(files),
+            reason or "no reason",
+        )
+
+
+async def run_unified_long_reflection(
+    llm: Any,
+    *,
+    global_memory_dir: Path | None = None,
+    queen_memory_dir: Path | None = None,
+    queen_id: str | None = None,
+) -> None:
+    """Run one housekeeping loop across all active memory scopes."""
+    global_dir = global_memory_dir or _default_global_memory_dir()
+    memory_dirs = {"global": global_dir}
+    if queen_memory_dir is not None and queen_id:
+        memory_dirs["queen"] = queen_memory_dir
+
+    manifest = _format_multi_scope_manifest(
+        memory_dirs, queen_id=queen_id if "queen" in memory_dirs else None
+    )
+    user_msg = (
+        "## Current memory manifest across scopes\n\n"
+        f"{manifest}\n\n"
+        f"Timestamp: {datetime.now().isoformat(timespec='minutes')}"
+    )
+
+    _, changed, reason = await _reflection_loop(
+        llm,
+        _build_unified_long_reflect_system(queen_id if "queen" in memory_dirs else None),
+        user_msg,
+        memory_dirs,
+        queen_id=queen_id if "queen" in memory_dirs else None,
+    )
+    if changed:
+        logger.debug("reflect: unified long reflection changed: %s", changed)
+    else:
+        logger.debug("reflect: unified long reflection no changes — %s", reason or "no reason")
+
+
+async def run_shutdown_reflection(
+    session_dir: Path,
+    llm: Any,
+    memory_dir: Path | None = None,
+    *,
+    global_memory_dir_override: Path | None = None,
+    queen_memory_dir: Path | None = None,
+    queen_id: str | None = None,
+) -> None:
+    """Run a final short reflection on session shutdown.
+
+    Called during session teardown so recent conversation insights are
+    persisted before the session is destroyed.
+    """
+    logger.info("reflect: running shutdown reflection for %s", session_dir)
+    try:
+        global_dir = global_memory_dir_override or memory_dir or _default_global_memory_dir()
+        await run_unified_short_reflection(
+            session_dir,
+            llm,
+            global_memory_dir=global_dir,
+            queen_memory_dir=queen_memory_dir,
+            queen_id=queen_id,
+        )
+        logger.info("reflect: shutdown reflection completed for %s", session_dir)
+    except asyncio.CancelledError:
+        logger.warning("reflect: shutdown reflection cancelled for %s", session_dir)
+    except Exception:
+        logger.warning("reflect: shutdown reflection failed", exc_info=True)
+        _write_error(
+            "shutdown reflection",
+            global_memory_dir_override or memory_dir or _default_global_memory_dir(),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Event-bus integration
+# ---------------------------------------------------------------------------
+
+_LONG_REFLECT_INTERVAL = 5
+_SHORT_REFLECT_TURN_INTERVAL = 2
+_SHORT_REFLECT_COOLDOWN_SEC = 120.0
+
+
+async def subscribe_reflection_triggers(
+    event_bus: Any,
+    session_dir: Path,
+    llm: Any,
+    global_memory_dir: Path | None = None,
+    queen_memory_dir: Path | None = None,
+    queen_id: str | None = None,
+) -> list[str]:
+    """Subscribe to queen turn events and return subscription IDs.
+
+    Call this once during queen setup.  Returns a list of event-bus
+    subscription IDs for cleanup during session teardown.
+    """
+    from framework.host.event_bus import EventType
+
+    global_mem_dir = global_memory_dir or _default_global_memory_dir()
+    queen_mem_dir = queen_memory_dir
+    _lock = asyncio.Lock()
+    _short_count = 0
+    _short_has_run = False
+    _last_short_time: float = 0.0
+    _background_tasks: set[asyncio.Task] = set()
+
+    async def _run_with_error_capture(coro: Any, *, context: str, memory_dir: Path) -> None:
+        try:
+            await coro
+        except Exception:
+            logger.warning("reflect: %s failed", context, exc_info=True)
+            _write_error(context, memory_dir)
+
+    async def _do_turn_reflect(is_interval: bool, count: int) -> None:
+        async with _lock:
+            await _run_with_error_capture(
+                run_unified_short_reflection(
+                    session_dir,
+                    llm,
+                    global_memory_dir=global_mem_dir,
+                    queen_memory_dir=queen_mem_dir,
+                    queen_id=queen_id,
+                ),
+                context="unified short reflection",
+                memory_dir=global_mem_dir,
+            )
+            if is_interval:
+                await _run_with_error_capture(
+                    run_unified_long_reflection(
+                        llm,
+                        global_memory_dir=global_mem_dir,
+                        queen_memory_dir=queen_mem_dir,
+                        queen_id=queen_id,
+                    ),
+                    context="unified long reflection",
+                    memory_dir=global_mem_dir,
+                )
+
+    async def _do_compaction_reflect() -> None:
+        async with _lock:
+            await _run_with_error_capture(
+                run_unified_long_reflection(
+                    llm,
+                    global_memory_dir=global_mem_dir,
+                    queen_memory_dir=queen_mem_dir,
+                    queen_id=queen_id,
+                ),
+                context="unified compaction reflection",
+                memory_dir=global_mem_dir,
+            )
+
+    def _fire_and_forget(coro: Any) -> None:
+        """Spawn a background task and prevent GC before it finishes."""
+        task = asyncio.create_task(coro)
+        _background_tasks.add(task)
+        task.add_done_callback(_background_tasks.discard)
+
+    async def _on_turn_complete(event: Any) -> None:
+        nonlocal _short_count, _short_has_run, _last_short_time
+
+        if getattr(event, "stream_id", None) != "queen":
+            return
+
+        _short_count += 1
+
+        event_data = getattr(event, "data", {}) or {}
+        stop_reason = event_data.get("stop_reason", "")
+        is_tool_turn = stop_reason in ("tool_use", "tool_calls")
+        is_interval = _short_count % _LONG_REFLECT_INTERVAL == 0
+
+        if is_tool_turn and not is_interval:
+            logger.debug("reflect: skipping tool turn (count=%d)", _short_count)
+            return
+
+        # Apply turn-interval and cooldown gates after the first reflection.
+        if _short_has_run:
+            now = time.monotonic()
+            turn_ok = _short_count % _SHORT_REFLECT_TURN_INTERVAL == 0
+            cooldown_ok = (now - _last_short_time) >= _SHORT_REFLECT_COOLDOWN_SEC
+            if not turn_ok and not cooldown_ok:
+                logger.debug(
+                    "reflect: skipping, below turn/cooldown threshold (count=%d)",
+                    _short_count,
+                )
+                return
+
+        if _lock.locked():
+            logger.debug("reflect: skipping, already running (count=%d)", _short_count)
+            return
+
+        _short_has_run = True
+        _last_short_time = time.monotonic()
+
+        logger.debug(
+            "reflect: triggered (count=%d, interval=%s, stop_reason=%s)",
+            _short_count,
+            is_interval,
+            stop_reason,
+        )
+        _fire_and_forget(_do_turn_reflect(is_interval, _short_count))
+
+    async def _on_compaction(event: Any) -> None:
+        if getattr(event, "stream_id", None) != "queen":
+            return
+        if _lock.locked():
+            logger.debug("reflect: skipping compaction trigger, already running")
+            return
+        logger.debug("reflect: compaction triggered long reflection")
+        _fire_and_forget(_do_compaction_reflect())
+
+    sub_ids: list[str] = []
+
+    sub1 = event_bus.subscribe(
+        event_types=[EventType.LLM_TURN_COMPLETE],
+        handler=_on_turn_complete,
+    )
+    sub_ids.append(sub1)
+
+    sub2 = event_bus.subscribe(
+        event_types=[EventType.CONTEXT_COMPACTED],
+        handler=_on_compaction,
+    )
+    sub_ids.append(sub2)
+
+    return sub_ids
+
+
+def _write_error(context: str, memory_dir: Path) -> None:
+    """Best-effort write of the last traceback to an error file."""
+    try:
+        error_path = memory_dir / ".reflection_error.txt"
+        error_path.parent.mkdir(parents=True, exist_ok=True)
+        error_path.write_text(
+            f"context: {context}\ntime: {datetime.now().isoformat()}\n\n{traceback.format_exc()}",
+            encoding="utf-8",
+        )
+    except OSError:
+        pass

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

@@ -1,4 +1,4 @@
-"""Test fixtures for Hive Coder agent."""
+"""Test fixtures for Queen agent."""
 
 import sys
 from pathlib import Path
@@ -22,10 +22,10 @@ def mock_mode():
 
 @pytest_asyncio.fixture(scope="session")
 async def runner(tmp_path_factory, mock_mode):
-    from framework.runner.runner import AgentRunner
+    from framework.loader.agent_loader import AgentLoader
 
     storage = tmp_path_factory.mktemp("agent_storage")
-    r = AgentRunner.load(AGENT_PATH, mock_mode=mock_mode, storage_path=storage)
+    r = AgentLoader.load(AGENT_PATH, mock_mode=mock_mode, storage_path=storage)
     r._setup()
     yield r
     await r.cleanup_async()

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/cli.py

@@ -2,18 +2,22 @@
 Command-line interface for Aden Hive.
 
 Usage:
-    hive run exports/my-agent --input '{"key": "value"}'
-    hive info exports/my-agent
-    hive validate exports/my-agent
-    hive list exports/
-    hive dispatch exports/ --input '{"key": "value"}'
-    hive shell exports/my-agent
+    hive serve                       Start the HTTP API server
+    hive open                        Start the server and open the dashboard
+    hive queen list                  List queen profiles
+    hive queen show <queen_id>       Inspect a queen profile
+    hive queen sessions <queen_id>   List a queen's sessions
+    hive colony list                 List colonies on disk
+    hive colony info <name>          Inspect a colony
+    hive colony delete <name>        Delete a colony
+    hive session list                List live sessions (use --cold for on-disk)
+    hive session stop <session_id>   Stop a live session
+    hive chat <session_id> "msg"     Send a message to a live queen
 
-Testing commands:
-    hive test-run <agent_path> --goal <goal_id>
-    hive test-debug <agent_path> <test_name>
-    hive test-list <agent_path>
-    hive test-stats <agent_path>
+Subsystems:
+    hive skill ...                   Manage skills (~/.hive/skills/)
+    hive mcp ...                     Manage MCP servers
+    hive debugger                    LLM debug log viewer
 """
 
 import argparse
@@ -21,73 +25,59 @@ import sys
 from pathlib import Path
 
 
-def _configure_paths():
-    """Auto-configure sys.path so agents in exports/ are discoverable.
+def _configure_paths() -> None:
+    """Auto-configure sys.path so the framework is importable from any cwd.
 
-    Resolves the project root by walking up from this file (framework/cli.py lives
-    inside core/framework/) or from CWD, then adds the exports/ directory to sys.path
-    if it exists. This eliminates the need for manual PYTHONPATH configuration.
+    Walks up from this file to find the project root, then ensures
+    `core/` is on sys.path so `framework.*` imports resolve when the
+    package isn't installed via `pip install -e .`.
     """
-    # Strategy 1: resolve relative to this file (works when installed via pip install -e core/)
     framework_dir = Path(__file__).resolve().parent  # core/framework/
     core_dir = framework_dir.parent  # core/
     project_root = core_dir.parent  # project root
 
-    # Strategy 2: if project_root doesn't look right, fall back to CWD
-    if not (project_root / "exports").is_dir() and not (project_root / "core").is_dir():
+    if not (project_root / "core").is_dir():
         project_root = Path.cwd()
 
-    # Add exports/ to sys.path so agents are importable as top-level packages
-    exports_dir = project_root / "exports"
-    if exports_dir.is_dir():
-        exports_str = str(exports_dir)
-        if exports_str not in sys.path:
-            sys.path.insert(0, exports_str)
-
-    # Add examples/templates/ to sys.path so template agents are importable
-    templates_dir = project_root / "examples" / "templates"
-    if templates_dir.is_dir():
-        templates_str = str(templates_dir)
-        if templates_str not in sys.path:
-            sys.path.insert(0, templates_str)
-
-    # Ensure core/ is also in sys.path (for non-editable-install scenarios)
     core_str = str(project_root / "core")
     if (project_root / "core").is_dir() and core_str not in sys.path:
         sys.path.insert(0, core_str)
 
-    # Add core/framework/agents/ so framework agents are importable as top-level packages
-    framework_agents_dir = project_root / "core" / "framework" / "agents"
-    if framework_agents_dir.is_dir():
-        fa_str = str(framework_agents_dir)
-        if fa_str not in sys.path:
-            sys.path.insert(0, fa_str)
 
-
-def main():
+def main() -> None:
     _configure_paths()
 
     parser = argparse.ArgumentParser(
         prog="hive",
-        description="Aden Hive - Build and run goal-driven agents",
+        description="Aden Hive — Queens, colonies, and live agent sessions",
     )
     parser.add_argument(
         "--model",
         default="claude-haiku-4-5-20251001",
-        help="Anthropic model to use",
+        help="Default LLM model (Anthropic ID)",
     )
 
     subparsers = parser.add_subparsers(dest="command", required=True)
 
-    # Register runner commands (run, info, validate, list, dispatch, shell)
-    from framework.runner.cli import register_commands
+    # Core commands: serve, open, queen, colony, session, chat
+    from framework.loader.cli import register_commands
 
     register_commands(subparsers)
 
-    # Register testing commands (test-run, test-debug, test-list, test-stats)
-    from framework.testing.cli import register_testing_commands
+    # Skill management (~/.hive/skills/)
+    from framework.skills.cli import register_skill_commands
 
-    register_testing_commands(subparsers)
+    register_skill_commands(subparsers)
+
+    # LLM debug log viewer
+    from framework.debugger.cli import register_debugger_commands
+
+    register_debugger_commands(subparsers)
+
+    # MCP server registry
+    from framework.loader.mcp_registry_cli import register_mcp_commands
+
+    register_mcp_commands(subparsers)
 
     args = parser.parse_args()
 

core/framework/config.py

@@ -12,13 +12,51 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
-from framework.graph.edge import DEFAULT_MAX_TOKENS
+DEFAULT_MAX_TOKENS = 8192
+
+# ---------------------------------------------------------------------------
+# Hive home directory structure
+# ---------------------------------------------------------------------------
+
+HIVE_HOME = Path.home() / ".hive"
+QUEENS_DIR = HIVE_HOME / "agents" / "queens"
+COLONIES_DIR = HIVE_HOME / "colonies"
+MEMORIES_DIR = HIVE_HOME / "memories"
+
+
+def queen_dir(queen_name: str = "default") -> Path:
+    """Return the storage directory for a named queen agent."""
+    return QUEENS_DIR / queen_name
+
+
+def colony_dir(colony_name: str) -> Path:
+    """Return the directory for a named colony."""
+    return COLONIES_DIR / colony_name
+
+
+def memory_dir(scope: str, name: str | None = None) -> Path:
+    """Return memory dir for a scope.
+
+    Examples::
+
+        memory_dir("global")                  -> ~/.hive/memories/global
+        memory_dir("colonies", "my_agent")    -> ~/.hive/memories/colonies/my_agent
+        memory_dir("agents/queens", "default")-> ~/.hive/memories/agents/queens/default
+        memory_dir("agents", "worker_name")   -> ~/.hive/memories/agents/worker_name
+    """
+    base = MEMORIES_DIR / scope
+    return base / name if name else base
+
 
 # ---------------------------------------------------------------------------
 # Low-level config file access
 # ---------------------------------------------------------------------------
 
-HIVE_CONFIG_FILE = Path.home() / ".hive" / "configuration.json"
+HIVE_CONFIG_FILE = HIVE_HOME / "configuration.json"
+
+# Hive LLM router endpoint (Anthropic-compatible).
+# litellm's Anthropic handler appends /v1/messages, so this is just the base host.
+HIVE_LLM_ENDPOINT = "https://api.adenhq.com"
 logger = logging.getLogger(__name__)
 
 
@@ -38,6 +76,48 @@ def get_hive_config() -> dict[str, Any]:
         return {}
 
 
+# ---------------------------------------------------------------------------
+# Credential store helpers (for BYOK keys)
+# ---------------------------------------------------------------------------
+
+# Provider name → credential store ID mapping
+_PROVIDER_CRED_MAP: dict[str, str] = {
+    "anthropic": "anthropic",
+    "openai": "openai",
+    "gemini": "gemini",
+    "google": "gemini",
+    "minimax": "minimax",
+    "groq": "groq",
+    "cerebras": "cerebras",
+    "openrouter": "openrouter",
+    "mistral": "mistral",
+    "together": "together",
+    "together_ai": "together",
+    "deepseek": "deepseek",
+    "kimi": "kimi",
+    "hive": "hive",
+}
+
+
+def _get_api_key_from_credential_store(provider: str) -> str | None:
+    """Look up a BYOK API key from the encrypted credential store.
+
+    Returns None if no key is found or the credential store is unavailable.
+    """
+    if not os.environ.get("HIVE_CREDENTIAL_KEY"):
+        return None
+    cred_id = _PROVIDER_CRED_MAP.get(provider.lower())
+    if not cred_id:
+        return None
+    try:
+        from framework.credentials import CredentialStore
+
+        store = CredentialStore.with_encrypted_storage()
+        return store.get(cred_id)
+    except Exception:
+        return None
+
+
 # ---------------------------------------------------------------------------
 # Derived helpers
 # ---------------------------------------------------------------------------
@@ -47,31 +127,213 @@ def get_preferred_model() -> str:
     """Return the user's preferred LLM model string (e.g. 'anthropic/claude-sonnet-4-20250514')."""
     llm = get_hive_config().get("llm", {})
     if llm.get("provider") and llm.get("model"):
-        return f"{llm['provider']}/{llm['model']}"
+        provider = str(llm["provider"])
+        model = str(llm["model"]).strip()
+        # OpenRouter quickstart stores raw model IDs; tolerate pasted "openrouter/<id>" too.
+        if provider.lower() == "openrouter" and model.lower().startswith("openrouter/"):
+            model = model[len("openrouter/") :]
+        if model:
+            return f"{provider}/{model}"
     return "anthropic/claude-sonnet-4-20250514"
 
 
+def get_preferred_worker_model() -> str | None:
+    """Return the user's preferred worker LLM model, or None if not configured.
+
+    Reads from the ``worker_llm`` section of ~/.hive/configuration.json.
+    Returns None when no worker-specific model is set, so callers can
+    fall back to the default (queen) model via ``get_preferred_model()``.
+    """
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if worker_llm.get("provider") and worker_llm.get("model"):
+        provider = str(worker_llm["provider"])
+        model = str(worker_llm["model"]).strip()
+        if provider.lower() == "openrouter" and model.lower().startswith("openrouter/"):
+            model = model[len("openrouter/") :]
+        if model:
+            return f"{provider}/{model}"
+    return None
+
+
+def get_worker_api_key() -> str | None:
+    """Return the API key for the worker LLM, falling back to the default key."""
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if not worker_llm:
+        return get_api_key()
+
+    # Worker-specific subscription / env var
+    if worker_llm.get("use_claude_code_subscription"):
+        try:
+            from framework.loader.agent_loader import get_claude_code_token
+
+            token = get_claude_code_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    if worker_llm.get("use_codex_subscription"):
+        try:
+            from framework.loader.agent_loader import get_codex_token
+
+            token = get_codex_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    if worker_llm.get("use_kimi_code_subscription"):
+        try:
+            from framework.loader.agent_loader import get_kimi_code_token
+
+            token = get_kimi_code_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    if worker_llm.get("use_antigravity_subscription"):
+        try:
+            from framework.loader.agent_loader import get_antigravity_token
+
+            token = get_antigravity_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    api_key_env_var = worker_llm.get("api_key_env_var")
+    if api_key_env_var:
+        return os.environ.get(api_key_env_var)
+
+    # Fall back to default key
+    return get_api_key()
+
+
+def get_worker_api_base() -> str | None:
+    """Return the api_base for the worker LLM, falling back to the default."""
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if not worker_llm:
+        return get_api_base()
+
+    if worker_llm.get("use_codex_subscription"):
+        return "https://chatgpt.com/backend-api/codex"
+    if worker_llm.get("use_kimi_code_subscription"):
+        return "https://api.kimi.com/coding"
+    if worker_llm.get("use_antigravity_subscription"):
+        # Antigravity uses AntigravityProvider directly — no api_base needed.
+        return None
+    if worker_llm.get("api_base"):
+        return worker_llm["api_base"]
+    if str(worker_llm.get("provider", "")).lower() == "openrouter":
+        return OPENROUTER_API_BASE
+    return None
+
+
+def get_worker_llm_extra_kwargs() -> dict[str, Any]:
+    """Return extra kwargs for the worker LLM provider."""
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if not worker_llm:
+        return get_llm_extra_kwargs()
+
+    if worker_llm.get("use_claude_code_subscription"):
+        api_key = get_worker_api_key()
+        if api_key:
+            return {
+                "extra_headers": {"authorization": f"Bearer {api_key}"},
+            }
+    if worker_llm.get("use_codex_subscription"):
+        api_key = get_worker_api_key()
+        if api_key:
+            headers: dict[str, str] = {
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": "CodexBar",
+            }
+            try:
+                from framework.loader.agent_loader import get_codex_account_id
+
+                account_id = get_codex_account_id()
+                if account_id:
+                    headers["ChatGPT-Account-Id"] = account_id
+            except ImportError:
+                pass
+            return {
+                "extra_headers": headers,
+                "store": False,
+                "allowed_openai_params": ["store"],
+            }
+    if worker_llm.get("provider") == "ollama":
+        return {"num_ctx": worker_llm.get("num_ctx", 16384)}
+    return {}
+
+
+def get_worker_max_tokens() -> int:
+    """Return max_tokens for the worker LLM, falling back to default."""
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if worker_llm and "max_tokens" in worker_llm:
+        return worker_llm["max_tokens"]
+    return get_max_tokens()
+
+
+def get_worker_max_context_tokens() -> int:
+    """Return max_context_tokens for the worker LLM, falling back to default."""
+    worker_llm = get_hive_config().get("worker_llm", {})
+    if worker_llm and "max_context_tokens" in worker_llm:
+        return worker_llm["max_context_tokens"]
+    return get_max_context_tokens()
+
+
 def get_max_tokens() -> int:
     """Return the configured max_tokens, falling back to DEFAULT_MAX_TOKENS."""
     return get_hive_config().get("llm", {}).get("max_tokens", DEFAULT_MAX_TOKENS)
 
 
+DEFAULT_MAX_CONTEXT_TOKENS = 32_000
+OPENROUTER_API_BASE = "https://openrouter.ai/api/v1"
+
+
+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_keys() -> list[str] | None:
+    """Return a list of API keys if ``api_keys`` is configured, else ``None``.
+
+    This supports key-pool rotation: configure multiple keys in
+    ``~/.hive/configuration.json`` under ``llm.api_keys`` and the
+    :class:`~framework.llm.key_pool.KeyPool` will rotate through them.
+    """
+    llm = get_hive_config().get("llm", {})
+    keys = llm.get("api_keys")
+    if keys and isinstance(keys, list) and len(keys) > 0:
+        return [k for k in keys if k]  # filter empties
+    return None
+
+
 def get_api_key() -> str | None:
     """Return the API key, supporting env var, Claude Code subscription, Codex, and ZAI Code.
 
     Priority:
+    0. Explicit key pool (``api_keys`` list) -- returns first key for
+       single-key callers; full pool available via :func:`get_api_keys`.
     1. Claude Code subscription (``use_claude_code_subscription: true``)
        reads the OAuth token from ``~/.claude/.credentials.json``.
     2. Codex subscription (``use_codex_subscription: true``)
        reads the OAuth token from macOS Keychain or ``~/.codex/auth.json``.
     3. Environment variable named in ``api_key_env_var``.
     """
+    # If an explicit key pool is configured, use the first key.
+    pool_keys = get_api_keys()
+    if pool_keys:
+        return pool_keys[0]
+
     llm = get_hive_config().get("llm", {})
 
     # Claude Code subscription: read OAuth token directly
     if llm.get("use_claude_code_subscription"):
         try:
-            from framework.runner.runner import get_claude_code_token
+            from framework.loader.agent_loader import get_claude_code_token
 
             token = get_claude_code_token()
             if token:
@@ -82,7 +344,7 @@ def get_api_key() -> str | None:
     # Codex subscription: read OAuth token from Keychain / auth.json
     if llm.get("use_codex_subscription"):
         try:
-            from framework.runner.runner import get_codex_token
+            from framework.loader.agent_loader import get_codex_token
 
             token = get_codex_token()
             if token:
@@ -90,11 +352,117 @@ 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.loader.agent_loader import get_kimi_code_token
+
+            token = get_kimi_code_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    # Antigravity subscription: read OAuth token from accounts JSON
+    if llm.get("use_antigravity_subscription"):
+        try:
+            from framework.loader.agent_loader import get_antigravity_token
+
+            token = get_antigravity_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
     # Standard env-var path (covers ZAI Code and all API-key providers)
     api_key_env_var = llm.get("api_key_env_var")
     if api_key_env_var:
-        return os.environ.get(api_key_env_var)
-    return None
+        key = os.environ.get(api_key_env_var)
+        if key:
+            return key
+
+    # Credential store fallback — BYOK keys stored via the UI
+    return _get_api_key_from_credential_store(llm.get("provider", ""))
+
+
+# OAuth credentials for Antigravity are fetched from the opencode-antigravity-auth project.
+# This project reverse-engineered and published the public OAuth credentials
+# for Google's Antigravity/Cloud Code Assist API.
+# Source: https://github.com/NoeFabris/opencode-antigravity-auth
+_ANTIGRAVITY_CREDENTIALS_URL = (
+    "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/dev/src/constants.ts"
+)
+_antigravity_credentials_cache: tuple[str | None, str | None] = (None, None)
+
+
+def _fetch_antigravity_credentials() -> tuple[str | None, str | None]:
+    """Fetch OAuth client ID and secret from the public npm package source on GitHub."""
+    global _antigravity_credentials_cache
+    if _antigravity_credentials_cache[0] and _antigravity_credentials_cache[1]:
+        return _antigravity_credentials_cache
+
+    import re
+    import urllib.request
+
+    try:
+        req = urllib.request.Request(
+            _ANTIGRAVITY_CREDENTIALS_URL, headers={"User-Agent": "Hive/1.0"}
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            content = resp.read().decode("utf-8")
+            id_match = re.search(r'ANTIGRAVITY_CLIENT_ID\s*=\s*"([^"]+)"', content)
+            secret_match = re.search(r'ANTIGRAVITY_CLIENT_SECRET\s*=\s*"([^"]+)"', content)
+            client_id = id_match.group(1) if id_match else None
+            client_secret = secret_match.group(1) if secret_match else None
+            if client_id and client_secret:
+                _antigravity_credentials_cache = (client_id, client_secret)
+            return client_id, client_secret
+    except Exception as e:
+        logger.debug("Failed to fetch Antigravity credentials from public source: %s", e)
+    return None, None
+
+
+def get_antigravity_client_id() -> str:
+    """Return the Antigravity OAuth application client ID.
+
+    Checked in order:
+    1. ``ANTIGRAVITY_CLIENT_ID`` environment variable
+    2. ``llm.antigravity_client_id`` in ~/.hive/configuration.json
+    3. Fetch from public source (opencode-antigravity-auth project on GitHub)
+    """
+    env = os.environ.get("ANTIGRAVITY_CLIENT_ID")
+    if env:
+        return env
+    cfg_val = get_hive_config().get("llm", {}).get("antigravity_client_id")
+    if cfg_val:
+        return cfg_val
+    # Fetch from public source
+    client_id, _ = _fetch_antigravity_credentials()
+    if client_id:
+        return client_id
+    raise RuntimeError("Could not obtain Antigravity OAuth client ID")
+
+
+def get_antigravity_client_secret() -> str | None:
+    """Return the Antigravity OAuth client secret.
+
+    Checked in order:
+    1. ``ANTIGRAVITY_CLIENT_SECRET`` environment variable
+    2. ``llm.antigravity_client_secret`` in ~/.hive/configuration.json
+    3. Fetch from public source (opencode-antigravity-auth project on GitHub)
+
+    Returns None when not found — token refresh will be skipped and
+    the caller must use whatever access token is already available.
+    """
+    env = os.environ.get("ANTIGRAVITY_CLIENT_SECRET")
+    if env:
+        return env
+    cfg_val = get_hive_config().get("llm", {}).get("antigravity_client_secret") or None
+    if cfg_val:
+        return cfg_val
+    # Fetch from public source
+    _, secret = _fetch_antigravity_credentials()
+    return secret
 
 
 def get_gcu_enabled() -> bool:
@@ -102,13 +470,31 @@ def get_gcu_enabled() -> bool:
     return get_hive_config().get("gcu_enabled", True)
 
 
+def get_gcu_viewport_scale() -> float:
+    """Return GCU viewport scale factor (0.1-1.0), default 0.8."""
+    scale = get_hive_config().get("gcu_viewport_scale", 0.8)
+    if isinstance(scale, (int, float)) and 0.1 <= scale <= 1.0:
+        return float(scale)
+    return 0.8
+
+
 def get_api_base() -> str | None:
     """Return the api_base URL for OpenAI-compatible endpoints, if configured."""
     llm = get_hive_config().get("llm", {})
     if llm.get("use_codex_subscription"):
         # Codex subscription routes through the ChatGPT backend, not api.openai.com.
         return "https://chatgpt.com/backend-api/codex"
-    return llm.get("api_base")
+    if llm.get("use_kimi_code_subscription"):
+        # Kimi Code uses an Anthropic-compatible endpoint (no /v1 suffix).
+        return "https://api.kimi.com/coding"
+    if llm.get("use_antigravity_subscription"):
+        # Antigravity uses AntigravityProvider directly — no api_base needed.
+        return None
+    if llm.get("api_base"):
+        return llm["api_base"]
+    if str(llm.get("provider", "")).lower() == "openrouter":
+        return OPENROUTER_API_BASE
+    return None
 
 
 def get_llm_extra_kwargs() -> dict[str, Any]:
@@ -137,7 +523,7 @@ def get_llm_extra_kwargs() -> dict[str, Any]:
                 "User-Agent": "CodexBar",
             }
             try:
-                from framework.runner.runner import get_codex_account_id
+                from framework.loader.agent_loader import get_codex_account_id
 
                 account_id = get_codex_account_id()
                 if account_id:
@@ -149,6 +535,11 @@ def get_llm_extra_kwargs() -> dict[str, Any]:
                 "store": False,
                 "allowed_openai_params": ["store"],
             }
+    if llm.get("provider") == "ollama":
+        # Pass num_ctx to Ollama so it doesn't silently truncate the ~9.5k Queen prompt.
+        # Ollama's default num_ctx is only 2048. We set it to 16384 here so LiteLLM
+        # passes it through as a provider-specific option.
+        return {"num_ctx": llm.get("num_ctx", 16384)}
     return {}
 
 
@@ -164,6 +555,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 (
@@ -53,6 +51,7 @@ from .key_storage import (
 from .models import (
     CredentialDecryptionError,
     CredentialError,
+    CredentialExpiredError,
     CredentialKey,
     CredentialKeyNotFoundError,
     CredentialNotFoundError,
@@ -86,6 +85,7 @@ from .template import TemplateResolver
 from .validation import (
     CredentialStatus,
     CredentialValidationResult,
+    compute_unavailable_tools,
     ensure_credential_key_env,
     validate_agent_credentials,
 )
@@ -138,6 +138,7 @@ __all__ = [
     "CredentialNotFoundError",
     "CredentialKeyNotFoundError",
     "CredentialRefreshError",
+    "CredentialExpiredError",
     "CredentialValidationError",
     "CredentialDecryptionError",
     # Key storage (bootstrap credentials)
@@ -150,6 +151,7 @@ __all__ = [
     # Validation
     "ensure_credential_key_env",
     "validate_agent_credentials",
+    "compute_unavailable_tools",
     "CredentialStatus",
     "CredentialValidationResult",
     # Interactive setup

core/framework/credentials/aden/storage.py

@@ -199,6 +199,19 @@ class AdenCachedStorage(CredentialStorage):
         if local_cred is None:
             return None
 
+        # Skip Aden fetch for credentials not managed by Aden (BYOK credentials).
+        # Only OAuth credentials synced from Aden are in the provider index.
+        # BYOK credentials like anthropic, brave_search are local-only.
+        # Also check the _aden_managed flag on the credential itself.
+        is_aden_managed = (
+            credential_id in self._provider_index
+            or any(credential_id in ids for ids in self._provider_index.values())
+            or (local_cred is not None and local_cred.keys.get("_aden_managed") is not None)
+        )
+        if not is_aden_managed:
+            logger.debug(f"Credential '{credential_id}' is local-only, skipping Aden refresh")
+            return local_cred
+
         # Try to refresh stale local credential from Aden
         try:
             aden_cred = self._aden_provider.fetch_from_aden(credential_id)

core/framework/credentials/key_storage.py

@@ -142,17 +142,27 @@ def save_aden_api_key(key: str) -> None:
     os.environ[ADEN_ENV_VAR] = key
 
 
-def delete_aden_api_key() -> None:
-    """Remove ADEN_API_KEY from the encrypted store and ``os.environ``."""
+def delete_aden_api_key() -> bool:
+    """Remove ADEN_API_KEY from the encrypted store and ``os.environ``.
+
+    Returns True if the key existed and was deleted, False otherwise.
+    """
+    deleted = False
     try:
         from .storage import EncryptedFileStorage
 
         storage = EncryptedFileStorage()
-        storage.delete(ADEN_CREDENTIAL_ID)
+        deleted = 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)
+    return deleted
 
 
 # ---------------------------------------------------------------------------
@@ -167,8 +177,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 +208,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/models.py

@@ -333,6 +333,29 @@ class CredentialRefreshError(CredentialError):
     pass
 
 
+class CredentialExpiredError(CredentialError):
+    """Raised when a credential is expired and refresh has failed.
+
+    Carries the metadata an agent (or the tool runner) needs to surface a
+    reauth request to the user without having to look anything else up.
+    """
+
+    def __init__(
+        self,
+        credential_id: str,
+        message: str,
+        *,
+        provider: str | None = None,
+        alias: str | None = None,
+        help_url: str | None = None,
+    ):
+        self.credential_id = credential_id
+        self.provider = provider
+        self.alias = alias
+        self.help_url = help_url
+        super().__init__(message)
+
+
 class CredentialValidationError(CredentialError):
     """Raised when credential validation fails."""
 

core/framework/credentials/setup.py

@@ -27,6 +27,7 @@ from __future__ import annotations
 
 import getpass
 import json
+import logging
 import os
 import sys
 from collections.abc import Callable
@@ -35,7 +36,9 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from framework.graph import NodeSpec
+    from framework.orchestrator import NodeSpec
+
+logger = logging.getLogger(__name__)
 
 
 # ANSI colors for terminal output
@@ -365,8 +368,11 @@ class CredentialSetupSession:
         self._print("")
         try:
             api_key = self.password_fn(f"Paste your {cred.env_var}: ").strip()
+        except (EOFError, OSError) as exc:
+            logger.debug("Password input unavailable, falling back to plain input: %s", exc)
+            api_key = self._input(f"Paste your {cred.env_var}: ").strip()
         except Exception:
-            # Fallback to regular input if password input fails
+            logger.warning("Unexpected error reading password input", exc_info=True)
             api_key = self._input(f"Paste your {cred.env_var}: ").strip()
 
         if not api_key:
@@ -403,7 +409,11 @@ class CredentialSetupSession:
 
             try:
                 aden_key = self.password_fn("Paste your ADEN_API_KEY: ").strip()
+            except (EOFError, OSError) as exc:
+                logger.debug("Password input unavailable for ADEN_API_KEY: %s", exc)
+                aden_key = self._input("Paste your ADEN_API_KEY: ").strip()
             except Exception:
+                logger.warning("Unexpected error reading ADEN_API_KEY input", exc_info=True)
                 aden_key = self._input("Paste your ADEN_API_KEY: ").strip()
 
             if not aden_key:
@@ -433,8 +443,10 @@ class CredentialSetupSession:
                     value = store.get_key(cred_id, cred.credential_key)
                     if value:
                         os.environ[cred.env_var] = value
+                except (KeyError, OSError) as exc:
+                    logger.debug("Could not export credential to env: %s", exc)
                 except Exception:
-                    pass
+                    logger.warning("Unexpected error exporting credential to env", exc_info=True)
                 return True
             else:
                 self._print(
@@ -457,9 +469,12 @@ class CredentialSetupSession:
                 "message": result.message,
                 "details": result.details,
             }
-        except Exception:
+        except ImportError:
             # No health checker available
             return None
+        except Exception:
+            logger.warning("Health check failed for %s", cred.credential_name, exc_info=True)
+            return None
 
     def _store_credential(self, cred: MissingCredential, value: str) -> None:
         """Store credential in encrypted store and export to env."""
@@ -518,7 +533,9 @@ class CredentialSetupSession:
 
 
 def load_agent_nodes(agent_path: str | Path) -> list:
-    """Load NodeSpec list from an agent's agent.py or agent.json.
+    """Load NodeSpec list from an agent directory.
+
+    Checks agent.json (declarative) first, then agent.py (legacy).
 
     Args:
         agent_path: Path to agent directory.
@@ -527,16 +544,28 @@ def load_agent_nodes(agent_path: str | Path) -> list:
         List of NodeSpec objects (empty list if agent can't be loaded).
     """
     agent_path = Path(agent_path)
+    agent_json_file = agent_path / "agent.json"
     agent_py = agent_path / "agent.py"
-    agent_json = agent_path / "agent.json"
 
-    if agent_py.exists():
+    if agent_json_file.exists():
+        return _load_nodes_from_json_declarative(agent_json_file)
+    elif agent_py.exists():
         return _load_nodes_from_python_agent(agent_path)
-    elif agent_json.exists():
-        return _load_nodes_from_json_agent(agent_json)
     return []
 
 
+def _load_nodes_from_json_declarative(agent_json: Path) -> list:
+    """Load nodes from a declarative JSON agent."""
+    try:
+        from framework.loader.agent_loader import load_agent_config
+
+        data = json.loads(agent_json.read_text(encoding="utf-8"))
+        graph, _ = load_agent_config(data)
+        return list(graph.nodes)
+    except Exception:
+        return []
+
+
 def _load_nodes_from_python_agent(agent_path: Path) -> list:
     """Load nodes from a Python-based agent."""
     import importlib.util
@@ -561,7 +590,11 @@ def _load_nodes_from_python_agent(agent_path: Path) -> list:
         sys.modules[spec.name] = module
         spec.loader.exec_module(module)
         return getattr(module, "nodes", [])
+    except (ImportError, OSError) as exc:
+        logger.debug("Could not load agent module: %s", exc)
+        return []
     except Exception:
+        logger.warning("Unexpected error loading agent module", exc_info=True)
         return []
 
 
@@ -571,7 +604,7 @@ def _load_nodes_from_json_agent(agent_json: Path) -> list:
         with open(agent_json, encoding="utf-8-sig") as f:
             data = json.load(f)
 
-        from framework.graph import NodeSpec
+        from framework.orchestrator import NodeSpec
 
         nodes_data = data.get("graph", {}).get("nodes", [])
         nodes = []
@@ -588,7 +621,11 @@ def _load_nodes_from_json_agent(agent_json: Path) -> list:
                 )
             )
         return nodes
+    except (json.JSONDecodeError, KeyError, OSError) as exc:
+        logger.debug("Could not load JSON agent: %s", exc)
+        return []
     except Exception:
+        logger.warning("Unexpected error loading JSON agent", exc_info=True)
         return []
 
 

core/framework/credentials/storage.py

@@ -161,6 +161,14 @@ class EncryptedFileStorage(CredentialStorage):
 
         self._fernet = Fernet(self._key)
 
+        # Rebuild the metadata index from disk if it's missing or older than
+        # the current index schema. The index is a developer-readable JSON
+        # snapshot of the encrypted store; the .enc files remain authoritative.
+        try:
+            self._maybe_rebuild_index()
+        except Exception:
+            logger.debug("Initial index rebuild failed (non-fatal)", exc_info=True)
+
     def _ensure_dirs(self) -> None:
         """Create directory structure."""
         (self.base_path / "credentials").mkdir(parents=True, exist_ok=True)
@@ -186,8 +194,8 @@ class EncryptedFileStorage(CredentialStorage):
         with open(cred_path, "wb") as f:
             f.write(encrypted)
 
-        # Update index
-        self._update_index(credential.id, "save", credential.credential_type.value)
+        # Update developer-readable index
+        self._index_upsert(credential)
         logger.debug(f"Saved encrypted credential '{credential.id}'")
 
     def load(self, credential_id: str) -> CredentialObject | None:
@@ -217,7 +225,7 @@ class EncryptedFileStorage(CredentialStorage):
         cred_path = self._cred_path(credential_id)
         if cred_path.exists():
             cred_path.unlink()
-            self._update_index(credential_id, "delete")
+            self._index_remove(credential_id)
             logger.debug(f"Deleted credential '{credential_id}'")
             return True
         return False
@@ -258,33 +266,154 @@ class EncryptedFileStorage(CredentialStorage):
 
         return CredentialObject.model_validate(data)
 
-    def _update_index(
-        self,
-        credential_id: str,
-        operation: str,
-        credential_type: str | None = None,
-    ) -> None:
-        """Update the metadata index."""
-        index_path = self.base_path / "metadata" / "index.json"
+    # ------------------------------------------------------------------
+    # Developer-readable metadata index
+    #
+    # The index lives at ``<base_path>/metadata/index.json`` and mirrors what
+    # is in the encrypted store at a glance: credential id, provider, alias,
+    # identity, key names, timestamps, and earliest expiry. It contains NO
+    # secret values and is safe to share when filing a bug report. The .enc
+    # files remain authoritative — the index is purely for human inspection
+    # and for cheap ``list_all()`` enumeration.
+    #
+    # Schema version is bumped whenever the entry shape changes; the store
+    # rebuilds the index from the encrypted files on load when the on-disk
+    # version is older.
+    # ------------------------------------------------------------------
 
-        if index_path.exists():
-            with open(index_path, encoding="utf-8-sig") as f:
-                index = json.load(f)
-        else:
-            index = {"credentials": {}, "version": "1.0"}
+    INDEX_VERSION = "2.0"
+    INDEX_INTERNAL_KEY_NAMES = ("_alias", "_integration_type")
 
-        if operation == "save":
-            index["credentials"][credential_id] = {
-                "updated_at": datetime.now(UTC).isoformat(),
-                "type": credential_type,
-            }
-        elif operation == "delete":
-            index["credentials"].pop(credential_id, None)
+    def _index_path(self) -> Path:
+        return self.base_path / "metadata" / "index.json"
 
-        index["last_modified"] = datetime.now(UTC).isoformat()
+    def _read_index(self) -> dict[str, Any]:
+        """Read the index from disk; return an empty skeleton if missing."""
+        path = self._index_path()
+        if not path.exists():
+            return {"version": self.INDEX_VERSION, "credentials": {}}
+        try:
+            with open(path, encoding="utf-8-sig") as f:
+                return json.load(f)
+        except Exception:
+            logger.debug("Failed to read credential index, starting fresh", exc_info=True)
+            return {"version": self.INDEX_VERSION, "credentials": {}}
 
-        with open(index_path, "w", encoding="utf-8") as f:
-            json.dump(index, f, indent=2)
+    def _write_index(self, index: dict[str, Any]) -> None:
+        """Write the index to disk with consistent envelope fields."""
+        index["version"] = self.INDEX_VERSION
+        index["store_path"] = str(self.base_path)
+        index["generated_at"] = datetime.now(UTC).isoformat()
+        path = self._index_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(index, f, indent=2, sort_keys=False, default=str)
+
+    def _index_entry_for(self, credential: CredentialObject) -> dict[str, Any]:
+        """Build a single index entry from a CredentialObject (no secrets)."""
+        # Visible key names: drop internal markers like _alias / _integration_type
+        # / _identity_* so the entry shows what's actually a credential key.
+        visible_keys = [
+            name
+            for name in credential.keys.keys()
+            if name not in self.INDEX_INTERNAL_KEY_NAMES
+            and not name.startswith("_identity_")
+        ]
+
+        # Earliest expiry across all keys (most likely the access_token).
+        earliest_expiry: datetime | None = None
+        for key in credential.keys.values():
+            if key.expires_at is None:
+                continue
+            if earliest_expiry is None or key.expires_at < earliest_expiry:
+                earliest_expiry = key.expires_at
+
+        return {
+            "credential_type": credential.credential_type.value,
+            "provider": credential.provider_type,
+            "alias": credential.alias,
+            "identity": credential.identity.to_dict(),
+            "key_names": sorted(visible_keys),
+            "created_at": credential.created_at.isoformat() if credential.created_at else None,
+            "updated_at": credential.updated_at.isoformat() if credential.updated_at else None,
+            "last_refreshed": (
+                credential.last_refreshed.isoformat() if credential.last_refreshed else None
+            ),
+            "expires_at": earliest_expiry.isoformat() if earliest_expiry else None,
+            "auto_refresh": credential.auto_refresh,
+            "tags": list(credential.tags),
+        }
+
+    def _index_upsert(self, credential: CredentialObject) -> None:
+        """Insert or update one credential entry in the index."""
+        try:
+            index = self._read_index()
+            if index.get("version") != self.INDEX_VERSION:
+                # Old schema — rebuild from disk so we don't blend formats.
+                self._rebuild_index()
+                return
+            credentials = index.setdefault("credentials", {})
+            credentials[credential.id] = self._index_entry_for(credential)
+            self._write_index(index)
+        except Exception:
+            logger.debug("Index upsert failed (non-fatal)", exc_info=True)
+
+    def _index_remove(self, credential_id: str) -> None:
+        """Remove one credential entry from the index."""
+        try:
+            index = self._read_index()
+            if index.get("version") != self.INDEX_VERSION:
+                self._rebuild_index()
+                return
+            credentials = index.setdefault("credentials", {})
+            credentials.pop(credential_id, None)
+            self._write_index(index)
+        except Exception:
+            logger.debug("Index remove failed (non-fatal)", exc_info=True)
+
+    def _maybe_rebuild_index(self) -> None:
+        """Rebuild the index if it's missing, malformed, or on an old schema.
+
+        Called once at startup. The check is cheap — read the version field
+        and bail out if it matches. Encrypted files remain authoritative; this
+        only refreshes the developer-facing snapshot.
+        """
+        path = self._index_path()
+        if path.exists():
+            try:
+                with open(path, encoding="utf-8-sig") as f:
+                    index = json.load(f)
+                if index.get("version") == self.INDEX_VERSION:
+                    return
+            except Exception:
+                pass  # fall through to rebuild
+        self._rebuild_index()
+
+    def _rebuild_index(self) -> None:
+        """Walk the encrypted credentials directory and rewrite a fresh index."""
+        cred_dir = self.base_path / "credentials"
+        if not cred_dir.is_dir():
+            return
+
+        entries: dict[str, Any] = {}
+        for cred_file in sorted(cred_dir.glob("*.enc")):
+            credential_id = cred_file.stem
+            try:
+                cred = self.load(credential_id)
+            except Exception:
+                logger.debug(
+                    "Failed to load %s during index rebuild — skipping",
+                    credential_id,
+                    exc_info=True,
+                )
+                continue
+            if cred is None:
+                continue
+            entries[cred.id] = self._index_entry_for(cred)
+
+        index = {"credentials": entries}
+        self._write_index(index)
+        logger.info("Rebuilt credential index with %d entries", len(entries))
 
 
 class EnvVarStorage(CredentialStorage):

core/framework/credentials/store.py

@@ -19,6 +19,7 @@ from typing import Any
 from pydantic import SecretStr
 
 from .models import (
+    CredentialExpiredError,
     CredentialKey,
     CredentialObject,
     CredentialRefreshError,
@@ -177,6 +178,8 @@ class CredentialStore:
         self,
         credential_id: str,
         refresh_if_needed: bool = True,
+        *,
+        raise_on_refresh_failure: bool = False,
     ) -> CredentialObject | None:
         """
         Get a credential by ID.
@@ -184,6 +187,11 @@ class CredentialStore:
         Args:
             credential_id: The credential identifier
             refresh_if_needed: If True, refresh expired credentials
+            raise_on_refresh_failure: If True, raise ``CredentialExpiredError``
+                when refresh fails instead of silently returning the stale
+                credential. Tool-execution call sites should pass True so the
+                agent gets a structured "reauth needed" signal rather than a
+                later 401 from the provider.
 
         Returns:
             CredentialObject or None if not found
@@ -193,7 +201,9 @@ class CredentialStore:
             cached = self._get_from_cache(credential_id)
             if cached is not None:
                 if refresh_if_needed and self._should_refresh(cached):
-                    return self._refresh_credential(cached)
+                    return self._refresh_credential(
+                        cached, raise_on_failure=raise_on_refresh_failure
+                    )
                 return cached
 
             # Load from storage
@@ -203,30 +213,46 @@ class CredentialStore:
 
             # Refresh if needed
             if refresh_if_needed and self._should_refresh(credential):
-                credential = self._refresh_credential(credential)
+                credential = self._refresh_credential(
+                    credential, raise_on_failure=raise_on_refresh_failure
+                )
 
             # Cache
             self._add_to_cache(credential)
 
             return credential
 
-    def get_key(self, credential_id: str, key_name: str) -> str | None:
+    def get_key(
+        self,
+        credential_id: str,
+        key_name: str,
+        *,
+        raise_on_refresh_failure: bool = False,
+    ) -> str | None:
         """
         Convenience method to get a specific key value.
 
         Args:
             credential_id: The credential identifier
             key_name: The key within the credential
+            raise_on_refresh_failure: See ``get_credential``.
 
         Returns:
             The key value or None if not found
         """
-        credential = self.get_credential(credential_id)
+        credential = self.get_credential(
+            credential_id, raise_on_refresh_failure=raise_on_refresh_failure
+        )
         if credential is None:
             return None
         return credential.get_key(key_name)
 
-    def get(self, credential_id: str) -> str | None:
+    def get(
+        self,
+        credential_id: str,
+        *,
+        raise_on_refresh_failure: bool = False,
+    ) -> str | None:
         """
         Legacy compatibility: get the primary key value.
 
@@ -235,11 +261,14 @@ class CredentialStore:
 
         Args:
             credential_id: The credential identifier
+            raise_on_refresh_failure: See ``get_credential``.
 
         Returns:
             The primary key value or None
         """
-        credential = self.get_credential(credential_id)
+        credential = self.get_credential(
+            credential_id, raise_on_refresh_failure=raise_on_refresh_failure
+        )
         if credential is None:
             return None
         return credential.get_default_key()
@@ -510,8 +539,20 @@ class CredentialStore:
 
         return provider.should_refresh(credential)
 
-    def _refresh_credential(self, credential: CredentialObject) -> CredentialObject:
-        """Refresh a credential using its provider."""
+    def _refresh_credential(
+        self,
+        credential: CredentialObject,
+        *,
+        raise_on_failure: bool = False,
+    ) -> CredentialObject:
+        """Refresh a credential using its provider.
+
+        When ``raise_on_failure`` is True, a refresh failure raises
+        ``CredentialExpiredError`` carrying provider/alias/help_url metadata
+        for the caller (typically the tool runner) to surface a reauth
+        request. Otherwise, the stale credential is returned to preserve
+        legacy best-effort behavior.
+        """
         provider = self.get_provider_for_credential(credential)
         if provider is None:
             logger.warning(f"No provider found for credential '{credential.id}'")
@@ -530,6 +571,16 @@ class CredentialStore:
 
         except CredentialRefreshError as e:
             logger.error(f"Failed to refresh credential '{credential.id}': {e}")
+            if raise_on_failure:
+                raise CredentialExpiredError(
+                    credential_id=credential.id,
+                    message=(
+                        f"OAuth token for '{credential.id}' is expired and "
+                        f"refresh failed: {e}. Reauthorization required."
+                    ),
+                    provider=credential.provider_type,
+                    alias=credential.alias,
+                ) from e
             return credential
 
     def refresh_credential(self, credential_id: str) -> CredentialObject | None: