fix mcp loading and spill large tool output

Author: cklxx

AGENTS.md

@@ -13,19 +13,21 @@ A CEO-class orchestrator. It owns the outcome end-to-end: from understanding the
 | Tool | Purpose |
 |------|---------|
 | `dispatch_agent` | Spawn an agent in a Kaku pane |
-| `read_pane_output` | Check agent progress (last 150 lines) |
+| `submit_plan` | Validate and register the task graph before dispatch |
+| `wait_for_agent_message` | Primary monitoring tool for batched progress/done events |
+| `read_pane_output` | Inspect a pane on demand when mailbox monitoring is insufficient |
 | `send_text_to_pane` | Send instructions or corrections |
 | `list_managed_panes` | Get pane topology and states |
 | `mark_task_done` | Mark a sub-task complete |
-| `wait` | Pause 5-120s between monitoring rounds |
+| `permanent_error` | Mark a sub-task permanently failed |
 | `record_phase_anchor` | Persist phase summary for session recovery |
 | `report_completion` | Final report with completion % |
 
 ### Constraints
 
-- NO direct file access. No Read/Write/Edit/Bash/Glob/Grep tools.
-- Works exclusively through dispatched agents.
-- Must call `wait` between monitoring rounds (30-60s).
+- No direct file mutation. Lightweight read/search helpers may exist for context, but implementation work must go through dispatched agents.
+- Works primarily through dispatched agents.
+- Prefer `wait_for_agent_message` for monitoring; use `read_pane_output` only for explicit inspection or stalled agents.
 - Must tell agents to commit their work when done.
 - After verification passes, must ensure the finished work is committed and landed on `main` before reporting completion.
 - When asking another LLM/agent for repo analysis or design feedback, ensure it can read/search the relevant repo context or provide the needed files explicitly. Do not ask for blind analysis.
@@ -44,7 +46,7 @@ A CEO-class orchestrator. It owns the outcome end-to-end: from understanding the
 The system prompt in `prompts/lead_agent.md` should:
 1. **Set the identity** — a decisive, proactive CEO who delivers results.
 2. **Define the workflow** — align, plan, dispatch, monitor, finish.
-3. **Enforce good habits** — wait between checks, write specific agent prompts, verify and commit.
+3. **Enforce good habits** — submit a plan first, write specific agent prompts, monitor via mailbox, verify and commit.
 4. **Stay concise** — every sentence should change behavior. Remove anything that doesn't.
 
 ### Sub-agents

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.9.55
+
+- **Fix**: Large MCP / lead-agent tool outputs now spill to `.openmax/tool-outputs/` and return a short pointer + preview instead of flooding the model context
+- **Fix**: `submit_plan` no longer blocks inline on long monitoring loops; it dispatches and returns immediately so MCP calls stop appearing hung
+- **Fix**: Interactive agent ready-wait no longer sits on a 30s floor; pane startup now exits early on dead panes and uses a short bounded timeout
+- **Fix**: Exited panes are no longer treated as success by default; auto-detect now requires a report or committed branch changes, otherwise the task is marked permanent error
+- **Fix**: Auto-detected successful exits now run the same mark/merge path as mailbox `done`, so they no longer bypass merge
+- **Docs**: Align lead-agent prompt and `AGENTS.md` with the actual tool contract (`submit_plan`, `wait_for_agent_message`, `permanent_error`, auto verify/report behavior)
+
 ## 0.9.54
 
 - **Fix**: Interactive agents (claude-code, codex, opencode) that exit without calling `report_done` are now auto-detected and marked DONE — previously they stayed in RUNNING state, causing the monitoring loop to spin until timeout with no notification

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openmax"
-version = "0.9.54"
+version = "0.9.55"
 description = "Extreme parallel acceleration — one command dispatches multiple AI agents with domain-aware task decomposition"
 readme = "README.md"
 license = "MIT"

src/openmax/__init__.py

@@ -1,3 +1,3 @@
 """openMax - Multi AI Agent orchestration hub."""
 
-__version__ = "0.9.54"
+__version__ = "0.9.55"

src/openmax/lead_agent/__init__.py

@@ -7,6 +7,7 @@
     dispatch_agent,
     mark_task_done,
     merge_agent_branch,
+    permanent_error,
     read_file_tool,
     read_pane_output,
     record_phase_anchor,
@@ -36,6 +37,7 @@
     "dispatch_agent",
     "mark_task_done",
     "merge_agent_branch",
+    "permanent_error",
     "read_file_tool",
     "read_pane_output",
     "record_phase_anchor",

src/openmax/lead_agent/core.py

@@ -148,6 +148,8 @@ def _task_status_from_value(value: str) -> TaskStatus:
         return TaskStatus.RUNNING
     if normalized == TaskStatus.DONE.value:
         return TaskStatus.DONE
+    if normalized == TaskStatus.PERMANENT_ERROR.value:
+        return TaskStatus.PERMANENT_ERROR
     if normalized == TaskStatus.ERROR.value:
         return TaskStatus.ERROR
     return TaskStatus.PENDING

src/openmax/lead_agent/formatting.py

@@ -21,6 +21,7 @@
     "ask_user": "intervention",
     "merge_agent_branch": "system",
     "mark_task_done": "system",
+    "permanent_error": "system",
     "record_phase_anchor": "system",
     "transition_phase": "system",
     "check_conflicts": "system",
@@ -77,6 +78,7 @@ def _coerce_tool_int(value: Any) -> int | None:
     "read_pane_output": ("Checking pane {0}", ["pane_id"]),
     "send_text_to_pane": ("Sending to pane {0}", ["pane_id"]),
     "mark_task_done": ("Marking {0} done", ["task_name"]),
+    "permanent_error": ("Marking {0} failed", ["task_name"]),
     "merge_agent_branch": ("Merging branch for {0}", ["task_name"]),
     "run_command": ("Running: {0}", ["command"]),
     "run_verification": ("Verifying: {0}", ["check_type"]),

src/openmax/lead_agent/prompts/lead_agent.md

@@ -150,7 +150,7 @@ Good: "The login endpoint in src/api/auth.py returns 500 when email contains '+'
 
 | `type`      | Action |
 |-------------|--------|
-| `done`      | **Auto-handled**: `mark_task_done` + `merge_agent_branch` + `lint verification` run automatically. Check `auto_merged` and `auto_verified` in response. Only intervene if auto-merge failed or verification failed. |
+| `done`      | **Auto-handled**: `mark_task_done` + `merge_agent_branch` run automatically. Final verification runs when all tasks finish. Check `auto_merged` and `auto_verified` in response. |
 | `question`  | Decide. Call `send_text_to_pane` with your answer. |
 | `blocked`   | Send guidance via `send_text_to_pane`. If unresolvable, `permanent_error`. |
 | `progress`  | No action needed unless pct=100. |
@@ -191,7 +191,7 @@ Include `check_checkpoints` in every monitoring round. For each pending item:
 
 Every dispatch prompt includes "Run tests and commit your changes when done." Agents self-verify.
 
-**Skip `run_verification`** when all agents reported `done` via mailbox AND were auto-merged AND auto-verified successfully (check `auto_verified.status == "pass"` in response). Go straight to `report_completion`.
+**Skip `run_verification`** when `wait_for_agent_message` already returned `auto_verified.status == "pass"` or `auto_verified.status == "skipped"`.
 
 Only run verification manually if:
 - An agent exited without a `done` message
@@ -200,9 +200,9 @@ Only run verification manually if:
 
 ### Finish
 
-0. **Mark done + merge + verify**: All auto-handled on `done` signal. Check `auto_merged` and `auto_verified` in `wait_for_agent_message` response.
-1. **When `all_done: true`**: Call `report_completion` immediately in the SAME response. Do not call `wait_for_agent_message` again. One tool call, done.
-2. Only intervene manually if auto-merge had conflicts or `auto_verified.status != "pass"`.
+0. **Mark done + merge**: Auto-handled on `done` signal. Check `auto_merged` in `wait_for_agent_message` response.
+1. **When `all_done: true`**: `wait_for_agent_message` already runs final verification and completion reporting. Read the response, summarize briefly, and stop.
+2. Only intervene manually if auto-merge had conflicts or `auto_verified.status == "fail"`.
 
 ### Phase Transitions
 
@@ -222,11 +222,11 @@ Simple tasks: skip to `implement` → `verify` only. Each transition requires a
 | Blackboard exists | `read_shared_context` before dispatching dependent agents. |
 | Checkpoint file detected | `check_checkpoints` → decide → `resolve_checkpoint`. |
 | Need deeper context mid-task | Dispatch research agent to investigate and report. |
-| Agent exited successfully | `mark_task_done` → `merge_agent_branch` immediately. |
+| Agent exited successfully | `mark_task_done` → `merge_agent_branch` immediately, or rely on auto-detect path if mailbox message never arrived. |
 | Agent exited with rate limit (`rate_limited: true`) | **Stop and `ask_user`**: "Rate limited — press Enter when ready to retry." Do NOT auto-retry. One rate limit likely means all agents are limited. After user confirms, re-dispatch. No retry cap for rate limits. |
-| Agent exited with error (not rate limit) | `permanent_error(task_name)`. |
-| Agent exited unexpectedly | retry_count <2: re-dispatch. ≥2: `permanent_error`. |
-| All agents done | `run_verification` for lint + test immediately. |
+| Agent exited with error (not rate limit) | `permanent_error(task_name, reason)`. |
+| Agent exited unexpectedly | retry_count <2: re-dispatch. ≥2: `permanent_error(task_name, reason)`. |
+| All agents done | Read `wait_for_agent_message` response first. It already triggers final verify/report. |
 
 ## 4. Employees
 

src/openmax/lead_agent/tools/__init__.py

@@ -31,6 +31,7 @@
 from openmax.lead_agent.tools._planning import (
     check_checkpoints,
     mark_task_done,
+    permanent_error,
     resolve_checkpoint,
     submit_plan,
     transition_phase,
@@ -50,6 +51,7 @@
     list_employees_tool,
     mark_task_done,
     merge_agent_branch,
+    permanent_error,
     list_managed_panes,
     read_file_tool,
     read_pane_output,

src/openmax/lead_agent/tools/_helpers.py

@@ -19,7 +19,7 @@
 from openmax.pane_backend import PaneBackendError
 from openmax.pane_manager import PaneManager
 from openmax.session_runtime import anchor_payload
-from openmax.task_file import read_report, read_shared_context, report_path
+from openmax.task_file import read_report, read_shared_context, report_path, write_tool_output
 
 logger = logging.getLogger(__name__)
 
@@ -122,13 +122,100 @@ def _record_phase_anchor(phase: str, summary: str, completion_pct: int | None =
     _update_session_phase(normalized_phase)
 
 
-_TOOL_RESPONSE_MAX_CHARS = 500_000
+_TOOL_RESPONSE_MAX_CHARS = 100_000
+_TOOL_OUTPUT_SPILL_THRESHOLD = 12_000
+_TOOL_OUTPUT_PREVIEW_CHARS = 240
+
+
+def _runtime_cwd_or_fallback() -> str:
+    try:
+        return _runtime().cwd
+    except RuntimeError:
+        return str(Path.cwd())
+
+
+def _compact_preview(text: str, limit: int = _TOOL_OUTPUT_PREVIEW_CHARS) -> str:
+    preview = " ".join(text.split())
+    if len(preview) <= limit:
+        return preview
+    return preview[: limit - 3].rstrip() + "..."
+
+
+def _spill_large_text(
+    text: str,
+    *,
+    prefix: str,
+    ext: str = ".txt",
+    label: str = "output",
+) -> dict[str, Any]:
+    cwd = _runtime_cwd_or_fallback()
+    path = write_tool_output(cwd, prefix, text, ext=ext)
+    try:
+        rel_path = str(path.relative_to(cwd))
+    except ValueError:
+        rel_path = str(path)
+    return {
+        "spilled": True,
+        "label": label,
+        "path": rel_path,
+        "chars": len(text),
+        "preview": _compact_preview(text),
+    }
+
+
+def _spill_large_values(value: Any, *, prefix: str) -> Any:
+    if isinstance(value, str):
+        if len(value) <= _TOOL_OUTPUT_SPILL_THRESHOLD:
+            return value
+        return _spill_large_text(value, prefix=prefix, label="text")
+    if isinstance(value, dict):
+        result: dict[str, Any] = {}
+        for key, child in value.items():
+            result[key] = _spill_large_values(child, prefix=f"{prefix}-{key}")
+        return result
+    if isinstance(value, list):
+        return [
+            _spill_large_values(child, prefix=f"{prefix}-{idx}") for idx, child in enumerate(value)
+        ]
+    return value
+
+
+def _finalize_payload(payload: Any, max_chars: int) -> str:
+    if isinstance(payload, (dict, list)):
+        text = json.dumps(payload, ensure_ascii=False)
+    else:
+        text = str(payload)
+    if len(text) <= max_chars:
+        return text
+
+    ext = ".json" if isinstance(payload, (dict, list)) else ".txt"
+    spilled = _spill_large_text(
+        text,
+        prefix="tool-response",
+        ext=ext,
+        label="payload",
+    )
+    compact = {
+        "spilled": True,
+        "reason": "response_too_large",
+        "path": spilled["path"],
+        "chars": spilled["chars"],
+        "preview": spilled["preview"],
+    }
+    return json.dumps(compact, ensure_ascii=False)
 
 
 def _tool_response(data: Any, max_chars: int = _TOOL_RESPONSE_MAX_CHARS) -> dict[str, Any]:
-    text = json.dumps(data, ensure_ascii=False) if isinstance(data, (dict, list)) else str(data)
-    if len(text) > max_chars:
-        text = text[:max_chars] + "\n...[truncated]"
+    if isinstance(data, str) and len(data) > _TOOL_OUTPUT_SPILL_THRESHOLD:
+        spill = _spill_large_text(data, prefix="tool-response", label="text")
+        text = (
+            f"large output written to {spill['path']} "
+            f"({spill['chars']} chars). preview: {spill['preview']}"
+        )
+    elif isinstance(data, (dict, list)):
+        text = _finalize_payload(_spill_large_values(data, prefix="tool-response"), max_chars)
+    else:
+        text = _finalize_payload(data, max_chars)
     return {"content": [{"type": "text", "text": text}]}
 
 
@@ -274,6 +361,8 @@ async def _wait_for_pane_ready(
             text = ""
         if any(pat in text for pat in ready_patterns):
             return True
+        if not pane_mgr.is_pane_alive(pane_id):
+            return False
         lines = [ln for ln in text.strip().splitlines() if ln.strip()]
         if len(lines) >= 3 and text == prev_text:
             stable_count += 1
@@ -539,11 +628,12 @@ async def _wait_and_send_prompt(
 
     ready = True
     if cmd_spec.ready_patterns:
+        ready_timeout = max(min(cmd_spec.ready_delay_seconds * 4, 12.0), 5.0)
         ready = await _wait_for_pane_ready(
             runtime.pane_mgr,
             pane.pane_id,
             cmd_spec.ready_patterns,
-            timeout=max(cmd_spec.ready_delay_seconds * 4, 30.0),
+            timeout=ready_timeout,
         )
         if not ready:
             console.print(