pascal-agent 0.3.0__py3-none-any.whl

pascal/loop.py

@@ -0,0 +1,1037 @@
+"""Pascal main loop — tool-use loop architecture.
+
+Claude Code / Codex / ReAct inspired:
+  LLM → N tool_calls → execute sequentially → tool_results back to LLM → repeat
+
+No JSON serialization for tool_calls — Message.tool_calls is used directly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from pascal.actions import execute_action, _auto_postmortem, ActionContext
+from pascal.capability import TrustMap, compute_threshold, infer_domain
+from pascal.desk import Desk
+from pascal.effect import check_allowed, classify_command, effect_to_int, get_max_effect
+from pascal.mcp import MCPManager
+from pascal.prompt import SYSTEM_PROMPT
+from pascal.receipts import Ledger
+from pascal.sandbox import SandboxManager
+from pascal.state import PascalStore, _json_safe
+from pascal.tools import (
+    TOOL_EFFECTS,
+    cleanup_tools,
+    set_workspace,
+    get_approval_callback,
+    get_channel_bot,
+    get_owner_chat_id,
+)
+from pascal.types import ActionStatus, ContentBlock, LLMResponse, Message, Observation, Role, ToolCall
+
+logger = logging.getLogger(__name__)
+
+_MAX_PARSE_RETRIES = 3
+_DEFAULT_MAX_TOOL_ROUNDS = 10
+_MESSAGE_CHAR_BUDGET = 120_000
+_TOOL_RESULT_CHAR_BUDGET = 8_000
+_DESKTOP_PROMPT_START = "Desktop tools (Windows):\n"
+_DESKTOP_PROMPT_END = "External data handling:\n"
+
+TERMINAL_ACTIONS = frozenset({"wait", "escalate", "complete_task", "fail_task"})
+BATCH_BREAKERS = frozenset({
+    "plan", "delegate", "wait", "escalate",
+    "complete_task", "fail_task", "block_task",
+})
+
+
+def _strip_prompt_section(prompt: str, start_marker: str, end_marker: str) -> str:
+    """Remove a prompt section delimited by fixed start/end markers."""
+    before, found_start, tail = prompt.partition(start_marker)
+    if not found_start:
+        return prompt
+    _section, found_end, after = tail.partition(end_marker)
+    if not found_end:
+        return prompt
+    trimmed = f"{before}{found_end}{after}"
+    while "\n\n\n" in trimmed:
+        trimmed = trimmed.replace("\n\n\n", "\n\n")
+    return trimmed
+
+
+_SYSTEM_PROMPT_NO_DESKTOP = _strip_prompt_section(
+    SYSTEM_PROMPT,
+    _DESKTOP_PROMPT_START,
+    _DESKTOP_PROMPT_END,
+)
+
+
+# ── Loop State ─────────────────────────────────────────────
+
+@dataclass
+class LoopState:
+    """Mutable per-run state."""
+    actions_taken: list[dict[str, Any]] = field(default_factory=list)
+    consecutive_errors: int = 0
+    thought_buffer: list[str] = field(default_factory=list)
+    error_feedback: str = ""
+    has_unknown_step: bool = False
+    last_attachment: ContentBlock | None = None
+    skip_verification: bool = False
+    last_observation: Observation | None = None
+    action_step: int = 0
+    force_full_render: bool = True
+    cached_preset: str = ""
+
+
+@dataclass
+class ToolUseResult:
+    """Outcome of one inner tool-use loop pass."""
+    stop_reason: str = ""  # text_response / terminal_action / stagnation / max_errors / round_cap
+    terminal_action: str | None = None
+    terminal_decision: dict[str, Any] = field(default_factory=dict)
+    terminal_result: dict[str, Any] = field(default_factory=dict)
+    terminal_obs: Observation | None = None
+
+
+# ── Loop Runner ────────────────────────────────────────────
+
+class LoopRunner:
+    """Orchestrates the Pascal tool-use loop."""
+
+    def __init__(
+        self,
+        store: PascalStore,
+        llm,
+        *,
+        verifier_llm=None,
+        ledger: Ledger | None = None,
+        mcp_manager: MCPManager | None = None,
+        max_effect: str | None = None,
+        max_iterations: int = 50,
+        max_tool_rounds: int | None = None,
+        max_inner_turns: int = 1,  # deprecated alias for max_tool_rounds
+        on_action: Callable[[dict[str, Any]], None] | None = None,
+        execute_command: Callable[[str], str] | None = None,
+        workspace: str | None = None,
+        wake_event: "asyncio.Event | None" = None,
+    ):
+        self.store = store
+        self.llm = llm
+        self.verifier_llm = verifier_llm
+        self.ledger = ledger
+        self.mcp_manager = mcp_manager
+        self.max_effect = max_effect
+        self.on_action = on_action
+        self.execute_command = execute_command
+        self.wake_event = wake_event
+        self._iteration_limit = max_iterations if max_iterations > 0 else 999_999
+        # Priority: max_tool_rounds > max_inner_turns (deprecated alias) > default
+        if max_tool_rounds is not None:
+            self._max_tool_rounds = max(1, max_tool_rounds)
+        elif max_inner_turns > 1:
+            self._max_tool_rounds = max(1, max_inner_turns)
+        else:
+            self._max_tool_rounds = _DEFAULT_MAX_TOOL_ROUNDS
+        self.state = LoopState()
+        self.trust_map = TrustMap.load(store.connection)
+
+        import uuid as _uuid
+        self.run_id = f"run_{_uuid.uuid4().hex[:8]}"
+
+        self._locked = not store.acquire_lock(self.run_id)
+        if self._locked:
+            return
+
+        # Identity seed
+        if not store.get_context("identity"):
+            from datetime import datetime, timezone
+            store.set_context("identity", {
+                "name": "Pascal",
+                "companion_since": datetime.now(timezone.utc).strftime("%Y-%m-%d"),
+                "personality": "Calm, practical, opinionated when it matters. Minimal unnecessary talk.",
+            })
+
+        # MCP + skills + tool schemas
+        mcp_tool_specs = mcp_manager.all_tool_specs() if mcp_manager else []
+        skill_list = _load_skills()
+        self.desk = Desk(store, mcp_tools=mcp_tool_specs, skills=skill_list)
+
+        from pascal.schemas import build_tool_schemas
+        self._tool_schemas_cache = {
+            "minimal": build_tool_schemas(preset="minimal"),
+            "standard": build_tool_schemas(preset="standard"),
+            "full": build_tool_schemas(preset="full"),
+        }
+
+        ws = workspace or os.getcwd()
+        set_workspace(ws)
+        self.sandbox = SandboxManager(workspace=ws)
+
+        # Action context — single object for all handler calls
+        self.action_ctx = ActionContext(
+            store=store, llm=verifier_llm, max_effect=max_effect,
+            sandbox=self.sandbox, mcp_manager=mcp_manager,
+            execute_command=execute_command,
+            thought_buffer=self.state.thought_buffer,
+            ledger=ledger, notify_fn=_notify_channel,
+        )
+
+        # Resume context
+        self.resume_context, resumed_unknown = _compile_resume_context(store)
+        if resumed_unknown:
+            self.state.has_unknown_step = True
+
+        # Auto-pick sole actionable task
+        if not store.get_active_task():
+            actionable = _get_actionable_pending_tasks(store)
+            if len(actionable) == 1:
+                store.activate_task(actionable[0]["id"])
+                logger.info("Auto-picked sole actionable task: %s", actionable[0]["goal"][:80])
+
+    # ── Initial messages ──────────────────────────────────
+
+    def _render_system_prompt(self, preset: str) -> str:
+        """Render the system prompt variant for the active tool preset."""
+        base_prompt = SYSTEM_PROMPT if preset == "full" else _SYSTEM_PROMPT_NO_DESKTOP
+        static_prompt = self.desk.render_static()
+        if static_prompt:
+            return f"{base_prompt}\n\n{static_prompt}"
+        return base_prompt
+
+    def _build_initial_messages(self) -> list[Message]:
+        """Build the initial message list with full desk render."""
+        system_prompt = self._render_system_prompt(self._refresh_tool_preset())
+
+        desk_prompt = self.desk.render(
+            has_unknown_step=self.state.has_unknown_step,
+            include_static=False,
+        )
+        user_content = f"Your desk:\n\n{desk_prompt}"
+        if self.resume_context:
+            user_content += f"\n\n## Resume Context\n{self.resume_context}"
+        if self.state.error_feedback:
+            user_content += f"\n\n## ERROR from previous\n{self.state.error_feedback}"
+            self.state.error_feedback = ""
+        user_content += "\n\nDecide your next action."
+
+        messages = [Message(role=Role.SYSTEM, content=system_prompt)]
+        messages.append(Message(role=Role.USER, content=user_content))
+        return messages
+
+    # ── Tool preset selection ────────────────────────────
+
+    def _refresh_tool_preset(self) -> str:
+        """Recompute and cache the tool preset. Called once per outer iteration."""
+        if not self.store.get_active_task():
+            preset = "minimal"
+        elif self.mcp_manager and self.mcp_manager.connected_servers:
+            preset = "full"
+        else:
+            preset = "standard"
+        self.state.cached_preset = preset
+        return preset
+
+    def _select_tool_preset(self) -> str:
+        """Return cached preset (avoids DB query on every inner loop round)."""
+        return self.state.cached_preset or self._refresh_tool_preset()
+
+    # ── LLM call ──────────────────────────────────────────
+
+    async def _call_llm(self, messages: list[Message]) -> LLMResponse | None:
+        """Call LLM with tool schemas. Returns None on failure."""
+        try:
+            preset = self._select_tool_preset()
+            if messages and messages[0].role == Role.SYSTEM:
+                messages[0].content = self._render_system_prompt(preset)
+            response = await _llm_call_with_retry(
+                self.llm,
+                messages,
+                tools=self._tool_schemas_cache[preset],
+            )
+        except Exception as exc:
+            logger.error("LLM call failed after retries: %s", exc)
+            self.state.consecutive_errors += 1
+            if self.state.consecutive_errors >= _MAX_PARSE_RETRIES:
+                self.store.record("Loop stopped: repeated LLM failures")
+            return None
+        if not response.text and not response.tool_calls:
+            self.state.consecutive_errors += 1
+            if self.state.consecutive_errors >= _MAX_PARSE_RETRIES:
+                self.store.record("Loop stopped: repeated empty LLM responses")
+            return None
+        return response
+
+    # ── Safety checks (unchanged) ─────────────────────────
+
+    def _action_domain(self, action: str, decision: dict[str, Any]) -> str:
+        hint = str(
+            decision.get("tool")
+            or decision.get("command")
+            or decision.get("reply_text")
+            or decision.get("task")
+            or ""
+        ).strip()
+        return infer_domain(action, hint or None)
+
+    def _plan_effect_level(self, decision: dict[str, Any]) -> str:
+        max_level = "E1"
+        for step in _iter_plan_actions(decision):
+            step_action = str(step.get("action") or "").strip()
+            step_level = self._decision_effect_level(step_action, step)
+            if step_level is not None and effect_to_int(step_level) > effect_to_int(max_level):
+                max_level = step_level
+        return max_level
+
+    def _decision_effect_level(self, action: str, decision: dict[str, Any]) -> str | None:
+        if action == "plan":
+            return self._plan_effect_level(decision)
+        if action == "delegate":
+            return "E2"
+        if action == "handle_notification":
+            reply_text = str(decision.get("reply_text") or "").strip()
+            return "E2" if reply_text and reply_text.upper() != "NO_REPLY" else "E0"
+        if action != "execute":
+            return None
+        tool_name = str(decision.get("tool") or "").strip()
+        if tool_name:
+            tool_effect = TOOL_EFFECTS.get(tool_name)
+            if tool_effect is not None:
+                return tool_effect
+            if self.mcp_manager is not None and self.mcp_manager.has_tool(tool_name):
+                specs = [spec for spec in self.mcp_manager.all_tool_specs() if spec.name == tool_name]
+                return "E3" if (specs and specs[0].side_effects) else "E0"
+            return "E1"
+        command = str(decision.get("command") or "").strip()
+        if command:
+            return classify_command(command)
+        return None
+
+    def _record_trust_gate(self, *, action, decision, effect_level, domain, threshold, recent_errors):
+        active = self.store.get_active_task()
+        active_id = active["id"] if active else None
+        payload = {
+            "action": action, "effect_level": effect_level, "domain": domain,
+            "threshold": threshold, "recent_error_streak": recent_errors, "decision": decision,
+        }
+        self.store.record(
+            f"trust_gate: {threshold} {action} ({effect_level})",
+            task_id=active_id, details=payload,
+            action_status="error" if threshold == "block" else "unknown",
+        )
+        if self.ledger is not None:
+            self.ledger.record("governance", {"type": "trust_gate", **payload})
+
+    def _pre_execute_checks(self, action: str, decision: dict, iteration: int) -> str | None:
+        """Returns 'break' (stagnation=stop loop), 'continue' (block=skip), or None."""
+        if action == "think":
+            recent_thinks = sum(1 for a in reversed(self.state.actions_taken[-5:]) if a["action"] == "think")
+            if recent_thinks >= 4:
+                self.state.error_feedback = "You have been thinking too long. Execute an action now."
+
+        if action in ("execute", "plan"):
+            cmd = str(decision.get("command") or decision.get("tool") or "")
+            stag_kind = _detect_stagnation(self.store, cmd) if cmd else ""
+            if stag_kind:
+                stag_label = "same tool" if stag_kind == "tool" else "same command"
+                self.state.error_feedback = (
+                    f"Stagnation detected: {stag_label} repeated 3+ times ('{cmd}'). "
+                    "Try a completely different approach. "
+                    "Tool access priority: API > UIA > DOM(CDP) > Shell > Screenshot"
+                )
+                self.store.record(
+                    f"Stagnation: {stag_label} repeated 3+ times",
+                    task_id=(self.store.get_active_task() or {}).get("id"),
+                    details={"action": "escalate", "command": cmd, "reason": "stagnation_detected"},
+                    action_status="error",
+                )
+                active = self.store.get_active_task()
+                if active:
+                    _auto_postmortem(self.store, active, f"Stagnation: repeated '{cmd}'")
+                self.state.actions_taken.append({
+                    "iteration": iteration, "action": "escalate",
+                    "reason": "stagnation_detected", "result": {"stagnation": True},
+                })
+                return "break"
+
+        effect_level = self._decision_effect_level(action, decision)
+        if effect_level is None or effect_to_int(effect_level) == 0:
+            return None
+        if not check_allowed(effect_level, get_max_effect(self.max_effect)):
+            self.state.error_feedback = (
+                f"Effect level {effect_level} exceeds max allowed {get_max_effect(self.max_effect)}. "
+                "Choose a lower-effect action or escalate to a human."
+            )
+            return "continue"
+
+        recent_errors = _recent_error_streak(self.state.actions_taken)
+        domain = self._action_domain(action, decision)
+        threshold = compute_threshold(
+            effect_level, trust_map=self.trust_map, domain=domain,
+            recent_error_streak=recent_errors,
+        )
+        should_gate = threshold == "block"
+        if threshold == "caution" and (effect_to_int(effect_level) >= 4 or recent_errors >= 3):
+            should_gate = True
+        if not should_gate:
+            return None
+
+        self._record_trust_gate(
+            action=action, decision=decision, effect_level=effect_level,
+            domain=domain, threshold=threshold, recent_errors=recent_errors,
+        )
+        self.state.error_feedback = (
+            f"Trust gate {threshold}: {action} at {effect_level} in domain '{domain}' is not allowed. "
+            "Choose a lower-effect step, gather more evidence, or escalate."
+        )
+        return "continue"
+
+    # ── Observe + Record ──────────────────────────────────
+
+    def _observe_result(self, action: str, decision: dict, result: Any) -> Observation:
+        """Create Observation from raw result. Updates trust + state."""
+        obs = Observation.from_result(action, result)
+        self.state.last_observation = obs
+        domain = self._action_domain(action, decision)
+
+        if obs.status == ActionStatus.OK:
+            self.trust_map.update_on_success(domain)
+        elif obs.status == ActionStatus.ERROR:
+            self.trust_map.update_on_failure(domain, is_judgment_error=True)
+        elif obs.status == ActionStatus.UNKNOWN:
+            self.trust_map.update_on_failure(domain, is_judgment_error=False)
+            from pascal.capability import _clamp_score
+            if domain in self.trust_map.domains:
+                self.trust_map.domains[domain] = _clamp_score(self.trust_map.domains[domain] - 0.03)
+
+        if obs.status == ActionStatus.UNKNOWN:
+            self.state.has_unknown_step = True
+        elif obs.status == ActionStatus.OK and action == "execute":
+            self.state.has_unknown_step = False
+
+        # Vision: save attachment for next USER message
+        if obs.attachment:
+            self.state.last_attachment = obs.attachment
+
+        # Clear thought buffer after non-think
+        if action != "think":
+            self.state.thought_buffer.clear()
+
+        return obs
+
+    def _record_and_update(
+        self, obs: Observation, decision: dict,
+        reason: str, expected_evidence: str, stop_condition: str, iteration: int,
+    ) -> None:
+        """Record action to history + ledger. No control flow."""
+        action = obs.action_type
+        result = obs.raw_result
+
+        active = self.store.get_active_task()
+        active_id = active["id"] if active else None
+        # idem_key includes action_step to prevent collisions in multi-tool iterations
+        idem_key = f"{active_id or 'notask'}:{iteration}:{self.state.action_step}:{action}"
+
+        action_record = {
+            "iteration": iteration,
+            "action": action,
+            "reason": reason,
+            "result": result,
+        }
+        self.state.actions_taken.append(action_record)
+        if self.on_action:
+            self.on_action(action_record)
+        _broadcast_action(action_record)
+
+        self.store.record(
+            f"{action}: {reason}" if reason else action,
+            task_id=active_id,
+            details={"decision": decision, "result": result},
+            idem_key=idem_key,
+            action_status=obs.status,
+        )
+
+        if self.ledger is not None:
+            self.ledger.record_action(action, decision, result)
+
+        self.trust_map.save(self.store.connection)
+
+    # ── Stop conditions (unchanged) ───────────────────────
+
+    async def _check_stop(self, action: str, decision: dict, result: Any,
+                          obs: Observation, iteration: int) -> str | None:
+        """Returns 'break', 'continue', or None."""
+        if (
+            self.wake_event is None
+            and action == "complete_task"
+            and obs.status == ActionStatus.OK
+            and not _has_actionable_work(self.store)
+        ):
+            auto_wait = {
+                "iteration": iteration, "action": "wait",
+                "reason": "auto-idle after completion",
+                "result": {"waiting": True, "auto": True},
+            }
+            self.state.actions_taken.append(auto_wait)
+            if self.on_action:
+                self.on_action(auto_wait)
+            _broadcast_action(auto_wait)
+            self.store.record(
+                "wait: auto-idle after completion",
+                details={"decision": {"action": "wait", "auto": True}, "result": auto_wait["result"]},
+                action_status="ok",
+            )
+            return "break"
+
+        if action == "wait":
+            if self.wake_event is not None:
+                self.wake_event.clear()
+                while not self.wake_event.is_set():
+                    self.store.refresh_lock()
+                    try:
+                        await asyncio.wait_for(self.wake_event.wait(), timeout=60)
+                    except asyncio.TimeoutError:
+                        pass
+                return "continue"
+            else:
+                return "break"
+
+        if action == "escalate":
+            if self.wake_event is not None and get_approval_callback() is not None:
+                active = self.store.get_active_task()
+                if active:
+                    question = str(decision.get("question") or "Need human input")
+                    await get_approval_callback()(get_owner_chat_id(), active["id"], question)
+                    self.store.update_task(active["id"], status="blocked",
+                                          progress=f"Awaiting approval: {question}")
+                    return "continue"
+            return "break"
+
+        if isinstance(result, dict) and result.get("escalate"):
+            return "break"
+        return None
+
+    async def _cleanup(self) -> None:
+        self.trust_map.save(self.store.connection)
+        await cleanup_tools()
+        self.store.release_lock()
+
+    # ── Tool use loop (NEW — Claude Code / Codex pattern) ─
+
+    async def _tool_use_loop(self, messages: list[Message], iteration: int) -> ToolUseResult:
+        """Inner tool-use loop. No JSON serialization — Message.tool_calls directly."""
+
+        def _append_tool_error(tc_id: str, error: str) -> None:
+            messages.append(Message(
+                role=Role.TOOL, tool_call_id=tc_id,
+                content=json.dumps({"error": error}, ensure_ascii=False),
+            ))
+
+        def _close_remaining(tool_calls: list[ToolCall], start: int, error: str) -> None:
+            for skipped in tool_calls[start:]:
+                _append_tool_error(skipped.id, error)
+
+        for _round in range(self._max_tool_rounds):
+            # Vision: pending attachment → USER message
+            if self.state.last_attachment is not None:
+                messages.append(Message(
+                    role=Role.USER, content="[screenshot attached]",
+                    attachments=[self.state.last_attachment],
+                ))
+                self.state.last_attachment = None
+
+            # LLM call
+            response = await self._call_llm(messages)
+            if response is None:
+                if self.state.consecutive_errors >= _MAX_PARSE_RETRIES:
+                    return ToolUseResult(stop_reason="max_errors")
+                continue
+
+            # Extract tool_calls from function calling response
+            tool_calls = list(response.tool_calls or [])
+            self.state.consecutive_errors = 0
+
+            # No tool_calls = text response → done
+            if not tool_calls:
+                if response.text:
+                    messages.append(Message(role=Role.ASSISTANT, content=response.text))
+                return ToolUseResult(stop_reason="text_response")
+
+            # Assistant message — tool_calls directly, no JSON serialization
+            messages.append(Message(
+                role=Role.ASSISTANT,
+                content=response.text or "",
+                tool_calls=tool_calls,
+            ))
+
+            # Execute each tool_call sequentially
+            for idx, tc in enumerate(tool_calls):
+                action = tc.name.strip().lower()
+                decision = dict(tc.params) if tc.params else {}
+                decision["action"] = action
+                self.state.action_step += 1
+
+                # Safety check
+                signal = self._pre_execute_checks(action, decision, iteration)
+                if signal == "break":
+                    _append_tool_error(tc.id, "stagnation detected, loop terminated")
+                    _close_remaining(tool_calls, idx + 1,
+                                     "skipped: loop terminated after earlier stagnation")
+                    return ToolUseResult(stop_reason="stagnation")
+                if signal == "continue":
+                    _append_tool_error(tc.id, self.state.error_feedback or "blocked")
+                    _close_remaining(tool_calls, idx + 1,
+                                     "skipped: earlier tool call was blocked; replan required")
+                    break
+
+                # Execute — use ActionContext for uniform handler dispatch
+                self.action_ctx.skip_verification = self.state.skip_verification
+                result = await execute_action(
+                    self.store, decision, action, ctx=self.action_ctx,
+                )
+
+                # Observe + record immediately
+                obs = self._observe_result(action, decision, result)
+                reason = str(decision.get("reason") or decision.get("thought") or "")
+                self._record_and_update(obs, decision, reason, "", "", iteration)
+
+                # Tool result — raw_result, always valid JSON
+                result_content = json.dumps(result, ensure_ascii=False, default=_json_safe)
+                if len(result_content) > _TOOL_RESULT_CHAR_BUDGET:
+                    result_content = json.dumps(
+                        {"truncated": True, "preview": result_content[:_TOOL_RESULT_CHAR_BUDGET]},
+                        ensure_ascii=False,
+                    )
+                messages.append(Message(
+                    role=Role.TOOL, tool_call_id=tc.id, content=result_content,
+                ))
+
+                # Batch-breaker → stop batch, let LLM replan
+                if action in BATCH_BREAKERS:
+                    _close_remaining(tool_calls, idx + 1,
+                                     f"skipped: '{action}' ended the tool batch; replan required")
+                    if action in TERMINAL_ACTIONS:
+                        return ToolUseResult(
+                            stop_reason="terminal_action",
+                            terminal_action=action,
+                            terminal_decision=decision,
+                            terminal_result=result,
+                            terminal_obs=obs,
+                        )
+                    break
+
+                # Failure → stop batch
+                if obs.status != ActionStatus.OK:
+                    _close_remaining(tool_calls, idx + 1,
+                                     f"skipped: '{action}' failed; replan required")
+                    break
+
+        return ToolUseResult(stop_reason="round_cap")
+
+    # Text JSON fallback removed — all providers now support function calling.
+
+    # ── Context management ────────────────────────────────
+
+    def _messages_too_long(self, messages: list[Message]) -> bool:
+        return sum(len(m.content or "") for m in messages) > _MESSAGE_CHAR_BUDGET
+
+    def _compact_messages(self, messages: list[Message]) -> list[Message]:
+        """Trim messages while preserving assistant-tool batch integrity.
+
+        Dropped messages are saved to ~/.pascal/scratch/ so the agent can
+        recover context by reading the file if needed (filesystem-as-memory pattern).
+        """
+        if not messages:
+            return messages
+        system = messages[0]
+        tail = messages[1:]
+        recent = tail[-8:]
+
+        # Ensure no orphaned TOOL or partial batches
+        while recent:
+            first = recent[0]
+            if first.role == Role.TOOL:
+                idx = len(messages) - len(recent) - 1
+                while idx >= 1 and messages[idx].role == Role.TOOL:
+                    idx -= 1
+                if idx >= 1 and messages[idx].role == Role.ASSISTANT:
+                    recent = [messages[idx]] + recent
+                    continue
+                recent = recent[1:]
+                continue
+            if first.role == Role.ASSISTANT and first.tool_calls:
+                needed = len(first.tool_calls)
+                found = sum(1 for m in recent[1:1 + needed] if m.role == Role.TOOL)
+                if found < needed:
+                    recent = recent[1 + found:]
+                    continue
+            break
+
+        # Save dropped messages to scratch file (filesystem-as-memory)
+        dropped = tail[:-8] if len(tail) > 8 else []
+        scratch_ref = ""
+        if dropped:
+            scratch_ref = self._save_scratch(dropped)
+
+        delta_content = f"[context_refresh]\n{self.desk.render_delta(observation=self.state.last_observation)}"
+        if scratch_ref:
+            delta_content += f"\n\nPrevious context saved to: {scratch_ref} (use read_file if needed)"
+        delta = Message(role=Role.USER, content=delta_content)
+        return [system, delta, *recent]
+
+    def _save_scratch(self, messages: list[Message]) -> str:
+        """Save dropped messages to ~/.pascal/scratch/{run_id}.md. Returns path."""
+        from pathlib import Path as _Path
+        scratch_dir = _Path.home() / ".pascal" / "scratch"
+        scratch_dir.mkdir(parents=True, exist_ok=True)
+        path = scratch_dir / f"{self.run_id}_context.md"
+        lines = []
+        for msg in messages:
+            role = msg.role.value if hasattr(msg.role, "value") else str(msg.role)
+            content = (msg.content or "")[:500]
+            lines.append(f"## [{role}]\n{content}\n")
+        path.write_text("\n".join(lines), encoding="utf-8")
+        return str(path)
+
+    # ── Main loop ─────────────────────────────────────────
+
+    async def run(self) -> list[dict[str, Any]]:
+        """Run the tool-use loop. Returns action log."""
+        if self._locked:
+            return [{"action": "wait", "reason": "another run is active", "result": {"locked": True}}]
+
+        messages: list[Message] = self._build_initial_messages()
+        self.state.force_full_render = False  # consumed
+
+        try:
+            for iteration in range(self._iteration_limit):
+                self.store.refresh_lock()
+
+                # Desk sync for subsequent iterations
+                if iteration > 0:
+                    self._refresh_tool_preset()
+                    if self.state.force_full_render:
+                        messages = self._build_initial_messages()
+                        self.state.force_full_render = False
+                    else:
+                        delta = self.desk.render_delta(observation=self.state.last_observation)
+                        messages.append(Message(
+                            role=Role.USER,
+                            content=f"[desk update]\n{delta}\n\nDecide your next action.",
+                        ))
+
+                # Tool use loop
+                result = await self._tool_use_loop(messages, iteration)
+
+                # Checkpoint
+                active = self.store.get_active_task()
+                if active:
+                    self.store.save_checkpoint(active["id"], iteration, {
+                        "has_unknown_step": self.state.has_unknown_step,
+                    })
+                elif result.terminal_action in ("complete_task", "fail_task"):
+                    # Task is no longer active — find from recent history
+                    recent = self.store.get_recent_history(limit=3)
+                    for h in recent:
+                        if h.get("task_id"):
+                            self.store.save_checkpoint(h["task_id"], iteration, {
+                                "has_unknown_step": self.state.has_unknown_step,
+                            })
+                            break
+
+                # Terminal action → check stop
+                if result.terminal_action and result.terminal_obs is not None:
+                    stop = await self._check_stop(
+                        result.terminal_action, result.terminal_decision,
+                        result.terminal_result, result.terminal_obs, iteration,
+                    )
+                    if stop == "break":
+                        break
+                    if stop == "continue":
+                        self.state.force_full_render = True
+                        continue
+
+                # Non-terminal stops
+                if result.stop_reason in ("stagnation", "max_errors"):
+                    break
+
+                # Context management
+                if self._messages_too_long(messages):
+                    messages = self._compact_messages(messages)
+
+        finally:
+            await self._cleanup()
+
+        return self.state.actions_taken
+
+
+async def run_loop(
+    store: PascalStore,
+    llm,
+    *,
+    verifier_llm=None,
+    ledger: Ledger | None = None,
+    mcp_manager: MCPManager | None = None,
+    max_effect: str | None = None,
+    max_iterations: int = 50,
+    max_tool_rounds: int | None = None,
+    max_inner_turns: int = 1,  # deprecated alias for max_tool_rounds
+    on_action: Callable[[dict[str, Any]], None] | None = None,
+    execute_command: Callable[[str], str] | None = None,
+    workspace: str | None = None,
+    wake_event: "asyncio.Event | None" = None,
+) -> list[dict[str, Any]]:
+    """Run the Pascal loop. Returns the action log."""
+    runner = LoopRunner(
+        store, llm,
+        verifier_llm=verifier_llm, ledger=ledger, mcp_manager=mcp_manager,
+        max_effect=max_effect, max_iterations=max_iterations,
+        max_tool_rounds=max_tool_rounds, max_inner_turns=max_inner_turns,
+        on_action=on_action, execute_command=execute_command,
+        workspace=workspace, wake_event=wake_event,
+    )
+    return await runner.run()
+
+
+# ── Helpers ───────────────────────────────────────────────
+
+def _get_actionable_pending_tasks(store: PascalStore) -> list[dict[str, Any]]:
+    pending = store.get_pending_tasks()
+    if not pending:
+        return []
+    done_ids = {
+        r["id"] for r in store.connection.execute("SELECT id FROM tasks WHERE status = 'done'").fetchall()
+    }
+    actionable = []
+    for task in pending:
+        deps = []
+        if task.get("depends_on"):
+            try:
+                deps = json.loads(task["depends_on"])
+            except (json.JSONDecodeError, TypeError):
+                deps = []
+        if deps and not all(dep in done_ids for dep in deps):
+            continue
+        actionable.append(task)
+    actionable.sort(key=lambda t: (
+        {"urgent": 0, "normal": 1, "low": 2}.get(t.get("priority", "normal"), 1),
+        t.get("due_at") or "9999", t.get("created_at") or "",
+    ))
+    return actionable
+
+
+def _has_actionable_work(store: PascalStore) -> bool:
+    if store.get_active_task():
+        return True
+    if store.get_pending_notifications():
+        return True
+    return bool(_get_actionable_pending_tasks(store))
+
+
+def _recent_error_streak(actions_taken: list[dict[str, Any]]) -> int:
+    streak = 0
+    for rec in reversed(actions_taken):
+        result = rec.get("result")
+        if not isinstance(result, dict):
+            break
+        status = str(result.get("status") or "").strip().lower()
+        if status not in {"error", "unknown"}:
+            break
+        if rec.get("action") not in {"execute", "plan"}:
+            break
+        streak += 1
+    return streak
+
+
+def _iter_plan_actions(decision: dict[str, Any]):
+    steps = decision.get("steps")
+    if isinstance(steps, list):
+        for step in steps:
+            if isinstance(step, dict):
+                yield step
+    plan_tree = decision.get("plan_tree")
+    if not isinstance(plan_tree, dict):
+        return
+    stack = [plan_tree]
+    while stack:
+        node = stack.pop()
+        action = node.get("action")
+        if isinstance(action, dict):
+            yield action
+        children = node.get("children")
+        if isinstance(children, list):
+            for child in reversed(children):
+                if isinstance(child, dict):
+                    stack.append(child)
+
+
+def _load_skills() -> list[dict[str, str]]:
+    from pathlib import Path as _Path
+    skills_dir = _Path.home() / ".pascal" / "skills"
+    if not skills_dir.is_dir():
+        return []
+    skills = []
+    for path in sorted(skills_dir.glob("*.md")):
+        try:
+            text = path.read_text(encoding="utf-8")
+            if text.startswith("---"):
+                end = text.index("---", 3)
+                frontmatter = text[3:end].strip()
+                name = ""
+                description = ""
+                for line in frontmatter.split("\n"):
+                    if line.startswith("name:"):
+                        name = line.split(":", 1)[1].strip().strip('"\'')
+                    elif line.startswith("description:"):
+                        description = line.split(":", 1)[1].strip().strip('"\'')
+                if name:
+                    skills.append({"name": name, "description": description, "file": str(path)})
+        except Exception:
+            continue
+    return skills
+
+
+async def _llm_call_with_retry(llm, messages, max_retries: int = 3, tools: list | None = None) -> LLMResponse:
+    last_exc = None
+    for attempt in range(max_retries):
+        try:
+            return await llm.chat(messages, tools=tools or [])
+        except Exception as exc:
+            last_exc = exc
+            exc_str = str(exc).lower()
+            if any(kw in exc_str for kw in ("429", "rate", "timeout", "502", "503", "504", "connection")):
+                wait = min(2 ** attempt, 30)
+                logger.warning("LLM transient error (attempt %d/%d), retrying in %ds: %s",
+                               attempt + 1, max_retries, wait, exc)
+                await asyncio.sleep(wait)
+                continue
+            raise
+    assert last_exc is not None, "LLM retry loop exhausted with no exception"
+    raise last_exc
+
+
+async def _notify_channel(message: str) -> None:
+    from pascal.trust import scan as _trust_scan
+    if _trust_scan(message).verdict == "block":
+        logger.warning("Status message blocked by trust scanner")
+        return
+    try:
+        bot = get_channel_bot()
+        owner = get_owner_chat_id()
+        if bot is not None and owner:
+            await bot.send_message(chat_id=owner, text=message)
+            return
+    except Exception:
+        pass
+    try:
+        from pascal.scheduler import _send_webhook
+        import os as _os
+        for url_key in ("PASCAL_SLACK_WEBHOOK", "PASCAL_DISCORD_WEBHOOK"):
+            url = _os.environ.get(url_key, "")
+            if url:
+                _send_webhook(url, message)
+                return
+    except Exception:
+        pass
+
+
+_status_callbacks: list = []
+
+
+def add_status_callback(fn) -> None:
+    _status_callbacks.append(fn)
+
+
+def _broadcast_action(action_record: dict[str, Any]) -> None:
+    action = action_record.get("action", "?")
+    reason = action_record.get("reason", "")
+    result = action_record.get("result", {})
+    status = result.get("status", "") if isinstance(result, dict) else ""
+    icons = {"execute": ">", "think": "\U0001f4ad", "pick_task": "+", "complete_task": "\u2713",
+             "fail_task": "\u2717", "delegate": "\u2192", "plan": "\U0001f4cb", "wait": ".", "escalate": "?",
+             "handle_notification": "!", "memorize": "\U0001f4dd"}
+    icon = icons.get(action, " ")
+    summary = f"[{icon}] {action}: {reason}"
+    if status and status != "ok":
+        summary += f" ({status})"
+    for fn in _status_callbacks:
+        try:
+            fn(summary)
+        except Exception:
+            pass
+
+
+def _detect_stagnation(store: PascalStore, current_command: str, window: int = 3) -> str:
+    """Detect command/tool repetition stagnation.
+
+    Returns "" (no stagnation), "command" (same command repeated), or "tool" (same tool repeated).
+    """
+    recent = store.get_recent_history(window * 3)
+    execute_records: list[str] = []
+    tool_names: list[str] = []
+    for record in reversed(recent):
+        details = record.get("details") or {}
+        if isinstance(details, str):
+            try:
+                details = json.loads(details)
+            except (json.JSONDecodeError, TypeError):
+                details = {}
+        rec_decision = details.get("decision") or details
+        if rec_decision.get("action") in ("execute", "plan"):
+            command = str(rec_decision.get("command") or "").strip()
+            tool = str(rec_decision.get("tool") or "").strip()
+            if not command and not tool:
+                continue
+            execute_records.append(command or tool)
+            tool_names.append(tool)
+        if len(execute_records) >= window:
+            break
+    if len(execute_records) < window:
+        return ""
+    if all(cmd == current_command for cmd in execute_records):
+        return "command"
+    first_tool = tool_names[0]
+    if first_tool and all(t == first_tool for t in tool_names):
+        return "tool"
+    return ""
+
+
+def _compile_resume_context(store: PascalStore) -> tuple[str, bool]:
+    parts: list[str] = []
+    has_unknown = False
+    active = store.get_active_task()
+    if active:
+        cp = store.get_latest_checkpoint(active["id"])
+        if cp:
+            snap = cp.get("snapshot") or {}
+            parts.append(f"Resuming task: {active['goal']} (from checkpoint)")
+            has_unknown = bool(snap.get("has_unknown_step"))
+        if active.get("progress"):
+            parts.append(f"Last progress: {active['progress']}")
+        todos = store.get_todos(active["id"])
+        if todos:
+            done = sum(1 for t in todos if t["status"] == "done")
+            parts.append(f"TODOs: {done}/{len(todos)} completed")
+            next_todo = next((t for t in todos if t["status"] == "pending"), None)
+            if next_todo:
+                parts.append(f"Next step: {next_todo['title']}")
+
+    history = store.get_recent_history(limit=5)
+    if history:
+        parts.append("Recent actions:")
+        for h in history:
+            parts.append(f"  - {h['summary']}")
+
+    for channel in ("telegram", "discord"):
+        convos = store.get_recent_conversation(channel, limit=5)
+        if convos:
+            parts.append(f"Recent conversation ({channel}):")
+            for c in convos:
+                parts.append(f"  [{c['role']}] {c['content'][:80]}")
+
+    return "\n".join(parts), has_unknown