polyrob 0.5.0__py3-none-any.whl

agents/task/agent/autonomy_state.py

@@ -0,0 +1,275 @@
+"""Restart-durable autonomy state.
+
+Two registries used to be volatile process memory, making autonomy turn-durable
+but not restart-durable:
+
+- ``AsyncDelegationRegistry`` (UP-12) — a background delegation dispatched and
+  then lost to a restart silently evaporated: the parent session was promised a
+  ``delegation_result`` that never arrived.
+- ``ReentryBudget`` (W1) — a forged-wake storm mid-ping-pong got a free depth
+  reset by crashing.
+
+``AutonomyStateStore`` persists both on the standard WAL+jitter sidecar pattern
+(``core/sqlite_util``, same as goals.db/cron.db) in ``autonomy_state.db`` under
+the data root (registered in ``core/db_manifest.py`` so backup/rollback snapshot
+it). Recovery is HONEST, never magic: a delegation still ``running`` at process
+start was crash-interrupted — :func:`recover_interrupted_delegations` marks it
+``interrupted`` and surfaces that back to the originating session via the
+self-wake rail (or leaves the durable row as the record when the wake is
+dropped/disabled). The child coroutine itself is never resumed.
+
+Everything here is fail-open: a store error degrades the registries to their
+legacy in-memory behavior, never blocks a dispatch or a wake.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from typing import Any, List, Optional
+
+from core.sqlite_util import execute_retry
+
+logger = logging.getLogger(__name__)
+
+_RESULT_TEXT_CAP = 4000
+# Budget rows older than this are dropped on hydrate — a wake recorded days ago
+# should not still be spacing/backing-off a fresh process.
+STALE_BUDGET_SEC = 7 * 86400
+
+
+def default_autonomy_state_db() -> str:
+    """Resolve autonomy_state.db NEXT TO its sibling autonomy DBs.
+
+    cron.db/goals.db/memory.db live under the container config's ``data_dir``
+    (server: ``{POLYROB_DATA_DIR}/data``; CLI: reconciled to the ``.polyrob``
+    root by build_cli_container) — prefer that, so ops tooling that assumes
+    co-location never misses this DB. Fall back to ``get_data_root()`` (the CLI
+    resolution) when no container config is available.
+    """
+    try:
+        from core.container import DependencyContainer
+        cfg = DependencyContainer.get_instance().get_service("config")
+        data_dir = getattr(cfg, "data_dir", None)
+        if data_dir:
+            return os.path.join(str(data_dir), "autonomy_state.db")
+    except Exception:
+        pass
+    from core.runtime_config import get_data_root
+    return os.path.join(get_data_root(), "autonomy_state.db")
+
+
+class AutonomyStateStore:
+    """WAL-backed store for delegations + reentry budgets (one per data root)."""
+
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        os.makedirs(os.path.dirname(db_path) or ".", exist_ok=True)
+        execute_retry(
+            db_path,
+            """CREATE TABLE IF NOT EXISTS delegations (
+                   session_id TEXT NOT NULL,
+                   delegation_id TEXT NOT NULL,
+                   user_id TEXT NOT NULL DEFAULT '',
+                   goal TEXT,
+                   profile TEXT,
+                   parent_agent_id TEXT,
+                   status TEXT NOT NULL DEFAULT 'running',
+                   dispatched_at REAL,
+                   completed_at REAL,
+                   result_text TEXT,
+                   PRIMARY KEY (session_id, delegation_id)
+               )""",
+        )
+        execute_retry(
+            db_path,
+            "CREATE INDEX IF NOT EXISTS idx_delegations_status ON delegations(status)",
+        )
+        execute_retry(
+            db_path,
+            """CREATE TABLE IF NOT EXISTS reentry_budget (
+                   session_id TEXT PRIMARY KEY,
+                   user_id TEXT NOT NULL DEFAULT '',
+                   count INTEGER NOT NULL DEFAULT 0,
+                   last_wake_at REAL NOT NULL DEFAULT 0
+               )""",
+        )
+
+    # -- delegations -----------------------------------------------------------
+
+    def record_dispatched(self, *, session_id: str, user_id: str, delegation_id: str,
+                          goal: str, profile: str, parent_agent_id: Optional[str],
+                          dispatched_at: float) -> None:
+        execute_retry(
+            self.db_path,
+            """INSERT OR REPLACE INTO delegations
+               (session_id, delegation_id, user_id, goal, profile, parent_agent_id,
+                status, dispatched_at)
+               VALUES (?,?,?,?,?,?,'running',?)""",
+            (session_id, delegation_id, user_id, goal, profile,
+             parent_agent_id, dispatched_at),
+        )
+
+    def record_terminal(self, session_id: str, delegation_id: str, *, status: str,
+                        completed_at: float, result_text: str = "") -> None:
+        execute_retry(
+            self.db_path,
+            """UPDATE delegations SET status=?, completed_at=?, result_text=?
+               WHERE session_id=? AND delegation_id=?""",
+            (status, completed_at, (result_text or "")[:_RESULT_TEXT_CAP],
+             session_id, delegation_id),
+        )
+
+    def get(self, session_id: str, delegation_id: str) -> Optional[dict]:
+        row = execute_retry(
+            self.db_path,
+            "SELECT * FROM delegations WHERE session_id=? AND delegation_id=?",
+            (session_id, delegation_id), fetch="one",
+        )
+        return dict(row) if row else None
+
+    def list_running(self) -> List[dict]:
+        rows = execute_retry(
+            self.db_path, "SELECT * FROM delegations WHERE status='running'",
+            fetch="all",
+        )
+        return [dict(r) for r in (rows or [])]
+
+    def max_counter(self, session_id: str) -> int:
+        """Highest numeric suffix of this session's deleg_NNNN ids — seeds the
+        in-memory counter so a restarted session never reissues an id."""
+        rows = execute_retry(
+            self.db_path,
+            "SELECT delegation_id FROM delegations WHERE session_id=?",
+            (session_id,), fetch="all",
+        )
+        best = 0
+        for r in rows or []:
+            did = r["delegation_id"] or ""
+            if did.startswith("deleg_"):
+                try:
+                    best = max(best, int(did.split("_", 1)[1]))
+                except ValueError:
+                    continue
+        return best
+
+    # -- reentry budget ----------------------------------------------------------
+
+    def get_budget(self, session_id: str) -> Optional[dict]:
+        row = execute_retry(
+            self.db_path,
+            "SELECT count, last_wake_at FROM reentry_budget WHERE session_id=?",
+            (session_id,), fetch="one",
+        )
+        return dict(row) if row else None
+
+    def put_budget(self, session_id: str, user_id: str, *, count: int,
+                   last_wake_at: float) -> None:
+        execute_retry(
+            self.db_path,
+            """INSERT INTO reentry_budget (session_id, user_id, count, last_wake_at)
+               VALUES (?,?,?,?)
+               ON CONFLICT(session_id) DO UPDATE SET
+                   count=excluded.count, last_wake_at=excluded.last_wake_at""",
+            (session_id, user_id, count, last_wake_at),
+        )
+
+    def delete_budget(self, session_id: str) -> None:
+        execute_retry(
+            self.db_path, "DELETE FROM reentry_budget WHERE session_id=?",
+            (session_id,),
+        )
+
+
+_STORE_LOCK = threading.Lock()
+_STORE_CACHE: dict = {}
+
+
+def get_autonomy_state_store() -> Optional[AutonomyStateStore]:
+    """The store at the default path, or None when durability is off or the
+    store cannot be opened (fail-open to legacy in-memory behavior).
+
+    Memoized per resolved path — orchestrators are constructed per session and
+    the store's schema init is blocking sqlite I/O; it must run once per
+    process, not once per session.
+    """
+    try:
+        from agents.task.constants import AutonomyConfig
+        if not AutonomyConfig.autonomy_state_durable():
+            return None
+        path = default_autonomy_state_db()
+        with _STORE_LOCK:
+            store = _STORE_CACHE.get(path)
+            if store is None:
+                store = AutonomyStateStore(path)
+                _STORE_CACHE[path] = store
+            return store
+    except Exception:
+        logger.warning("autonomy_state store unavailable — running in-memory only",
+                       exc_info=True)
+        return None
+
+
+def reset_autonomy_state_store_cache() -> None:
+    """Test seam: drop memoized stores so path/env changes take effect."""
+    with _STORE_LOCK:
+        _STORE_CACHE.clear()
+
+
+async def recover_interrupted_delegations(task_agent: Any, db_path: str) -> int:
+    """Startup sweep: mark crash-interrupted delegations and surface them.
+
+    Returns the number of rows recovered. The self-wake delivery is best-effort
+    (SELF_WAKE_ENABLED off / non-resident session / budget exhausted → the wake
+    is dropped, but the durable ``interrupted`` row remains the honest record).
+    """
+    if not os.path.exists(db_path):
+        return 0
+    try:
+        store = AutonomyStateStore(db_path)
+        rows = store.list_running()
+    except Exception:
+        logger.warning("delegation recovery sweep failed to read store", exc_info=True)
+        return 0
+    recovered = 0
+    for row in rows:
+        session_id, delegation_id = row["session_id"], row["delegation_id"]
+        try:
+            store.record_terminal(
+                session_id, delegation_id, status="interrupted",
+                completed_at=time.time(),
+                result_text="Process restarted while this delegation was running.",
+            )
+            recovered += 1
+        except Exception:
+            logger.warning("could not mark delegation %s/%s interrupted",
+                           session_id, delegation_id, exc_info=True)
+            continue
+        try:
+            from agents.task.telemetry.event_log import get_event_log, event_log_enabled
+            if event_log_enabled():
+                get_event_log().record(
+                    "delegation_interrupted", user_id=row.get("user_id", ""),
+                    session_id=session_id, source="autonomy_state",
+                    attrs={"delegation_id": delegation_id,
+                           "goal": (row.get("goal") or "")[:200]},
+                )
+        except Exception:
+            pass
+        try:
+            deliver = getattr(task_agent, "deliver_self_wake", None)
+            if deliver is not None:
+                await deliver(
+                    session_id, row.get("user_id", ""),
+                    (f"Background delegation {delegation_id} "
+                     f"({(row.get('goal') or '')[:200]}) was interrupted by a process "
+                     "restart and did NOT complete. Re-dispatch it if the work is "
+                     "still needed."),
+                    metadata={"delegation_id": delegation_id,
+                              "recovery": "interrupted_delegation"},
+                )
+        except Exception:
+            logger.warning("interrupted-delegation wake for %s failed (row remains "
+                           "the durable record)", session_id, exc_info=True)
+    return recovered

agents/task/agent/conversation.py

@@ -0,0 +1,75 @@
+"""First-class multi-turn conversation over the existing agent loop (R4).
+
+A Conversation owns ordered Turns and drives the agent one turn at a time with a
+small per-turn step budget, returning the answer synchronously — instead of the
+HITL resume FSM (which re-enters a 100-step task loop per reply). Server task
+sessions are unaffected; this is opt-in via Conversation.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Iterable, List
+
+
+def extract_answer(history: Any) -> str:
+    """The agent's reply for a turn = the last is_done result's extracted_content.
+
+    Accepts either a flat iterable of ActionResults or the AgentHistoryList that
+    Agent.run() actually returns. AgentHistoryList is a pydantic model: iterating
+    it yields (field, value) tuples, not results, so unwrap via action_results()
+    when available before scanning for the terminal is_done result.
+    """
+    results: Iterable[Any]
+    if hasattr(history, "action_results") and callable(history.action_results):
+        results = history.action_results()
+    else:
+        results = history
+    answer = ""
+    for result in results:
+        if getattr(result, "is_done", False) and getattr(result, "extracted_content", None):
+            answer = result.extracted_content
+    return answer
+
+
+DEFAULT_TURN_BUDGET = 20  # interactive turns; raise for big asks, autonomous tasks use run()
+
+
+def _reset_turn_state(agent: Any) -> None:
+    """Clear transient failure state so a NEW user turn gets a fresh attempt.
+
+    Agent.run() resets n_steps but not consecutive_failures / _cancelled. Without
+    this, once a turn hits max consecutive failures (e.g. an LLM quota error), the
+    agent stays wedged and every later respond() returns 'failed | -1 steps' — the
+    REPL is dead until restart. A fresh user message should start clean.
+    """
+    state = getattr(agent, "state", None)
+    if state is not None and hasattr(state, "consecutive_failures"):
+        state.consecutive_failures = 0
+    if getattr(agent, "_cancelled", False):
+        agent._cancelled = False
+
+
+@dataclass
+class Turn:
+    user: str
+    assistant: str = ""
+
+
+@dataclass
+class Conversation:
+    agent: Any
+    turns: List[Turn] = field(default_factory=list)
+
+    async def respond(self, text: str, max_steps: int = DEFAULT_TURN_BUDGET) -> str:
+        """Run exactly one conversational turn and return the agent's reply.
+
+        After the first turn we pass _continue_session=True so run() skips the
+        once-per-session preamble (session-start telemetry + H-MEM create/load),
+        which would otherwise re-fire on every REPL line.
+        """
+        _reset_turn_state(self.agent)                # recover from a prior failed turn
+        self.agent.set_turn_input(text)              # append-as-turn (Task 7)
+        history = await self.agent.run(
+            max_steps=max_steps, _continue_session=bool(self.turns))
+        answer = extract_answer(history)
+        self.turns.append(Turn(user=text, assistant=answer))
+        return answer

agents/task/agent/core/__init__.py

@@ -0,0 +1,6 @@
+"""Agent core mixins.
+
+Pure code-motion extraction of internal method-groups from
+``agents/task/agent/service.py`` (class ``Agent``). The mixins here are composed
+back into ``Agent`` via inheritance; method bodies are verbatim.
+"""

agents/task/agent/core/aux_metering.py

@@ -0,0 +1,61 @@
+"""Meter auxiliary LLM calls (compaction, judge, reflection) through the single
+usage/deduction path. These calls were unbilled — only the main step
+(next_action_internal.py:388) recorded usage — so long-context compaction on the
+flagship model was free. Per operator decision aux calls DEDUCT like main calls, but
+this helper FAILS OPEN on any error (including InsufficientCreditsError): aux calls are
+internal maintenance and must never hard-halt a session. The deduction still happens
+whenever the balance covers it.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _llm_identity(llm: Any, response: Any = None) -> tuple[str, str]:
+    """Derive (model, provider) from the llm object, falling back to detecting
+    the provider from the model name via ``detect_llm_provider`` (which takes a
+    RESPONSE + optional model name — the response param is unused by that
+    function but kept for signature compatibility; the model name is what it
+    actually looks up in the model registry).
+    """
+    model = (getattr(llm, "model_name", None) or getattr(llm, "model", None)
+             or getattr(llm, "model_type", None) or "unknown")
+    provider = (getattr(llm, "llm_provider", None) or getattr(llm, "provider_name", None))
+    if not provider:
+        try:
+            from agents.task.utils import detect_llm_provider
+            provider = detect_llm_provider(response, model) or "unknown"
+        except Exception:
+            provider = "unknown"
+    return str(model), str(provider)
+
+
+async def meter_aux_llm(*, usage_tracker, user_id: Optional[str], session_id: str,
+                        agent_id: str, llm: Any, response: Any, duration_seconds: float,
+                        component: str, purpose: str) -> None:
+    """Record usage for an auxiliary (non-main-step) LLM call.
+
+    Fail-open: no-ops silently when there's no tracker/user_id (e.g. anonymous
+    local sessions), and swallows ANY exception from token extraction or
+    ``record_llm_usage`` itself (including InsufficientCreditsError) — an aux
+    call is internal maintenance and must never abort the caller.
+    """
+    if not (usage_tracker and user_id):
+        return
+    try:
+        from agents.task.utils import extract_token_usage
+        model, provider = _llm_identity(llm, response)
+        usage = extract_token_usage(response, provider) or {}
+        await usage_tracker.record_llm_usage(
+            user_id=user_id, session_id=session_id, agent_id=agent_id,
+            model=model, provider=provider,
+            input_tokens=usage.get("prompt_tokens") or 0,
+            output_tokens=usage.get("completion_tokens") or 0,
+            cached_tokens=usage.get("cached_tokens") or 0,
+            duration_seconds=duration_seconds, component=component, purpose=purpose, success=True,
+        )
+    except Exception as e:  # fail-open (incl. InsufficientCreditsError): never break the aux op
+        logger.warning(f"aux metering skipped ({component}/{purpose}): {type(e).__name__}: {e}")

agents/task/agent/core/background_review.py

@@ -0,0 +1,157 @@
+"""Post-turn background-review fork (W2-C, Reference-parity self-improvement loop).
+
+After a run of productive turns, the agent forks a cheap, fire-and-forget sub-agent
+that reviews what just happened and — when it finds a durable, reusable procedure —
+authors a skill (via the W2 ``skill_manage`` tool, which quarantines it for review).
+This is the "learning" loop: experience → distilled skill → available next session.
+
+Design:
+- **Non-blocking** — ``asyncio.create_task`` so the run loop returns immediately; a
+  review never delays the user-facing turn.
+- **Cheap** — runs on the aux/judge model (``_provision_aux_llm("judge")``) and
+  inherits the cached system prefix → prefix-cache hit (Reference's ~26% saving).
+- **Least-privilege** — spawned through ``SubAgentManager.run_subtask`` as a depth-1
+  LEAF (UP-05 child controller: no code-exec/cron, cannot re-delegate).
+- **Bounded** — at most ``BG_REVIEW_MAX_STEPS`` steps; exempt for sub-agents (a
+  reviewer never forks its own reviewer).
+- **Fail-open** — any error is swallowed; the loop must never break on a review.
+
+Gated ``BACKGROUND_REVIEW_ENABLED`` (default OFF). Authored skills are quarantined
+(``created_by="background_review"`` → always ``.pending/``), so even a compromised
+review cannot self-activate a skill.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__)
+
+_REVIEW_PROMPT = (
+    "You are a background reviewer for an AI agent. The agent just finished a run of "
+    "work in this session. Review the recent conversation/work and decide whether a "
+    "DURABLE, REUSABLE procedure emerged that would help in future sessions.\n\n"
+    "If yes: call skill_manage(action='create', skill_id=<short-kebab-id>, "
+    "content=<a concise SKILL.md: a '# Title' heading then when-to-use + steps>). "
+    "Keep it general (no secrets, no session-specific data). Author at most ONE skill.\n"
+    "If nothing is worth saving: call done() with a one-line reason. Do not do any "
+    "other work, browse, or message the user."
+)
+
+# polyrob Phase E: the "learns over time" engine. The reviewer already runs as a
+# LEAF sub-agent, so a self_context_manage write resolves to background provenance →
+# ALWAYS .pending, NEVER auto-active and NEVER promotable by this forged turn. So we
+# can safely invite it to ALSO propose a consolidated SELF-context refinement; the
+# owner promotes it later. Only offered when SELF_CONTEXT_WRITABLE is on.
+_SELF_CONTEXT_REVIEW_ADDENDUM = (
+    "\n\nSEPARATELY: if you learned something durable about how to work with THIS user "
+    "(a stable preference, convention, or fact worth remembering), you may also call "
+    "self_context_manage(action='update', content=<a consolidated self.md, ≤2200 "
+    "chars — MERGE with what's already there via action='read' first; do not sprawl>). "
+    "This proposes a refinement to your evolving SELF context; it is QUARANTINED for "
+    "owner review and applies next session. Keep it about working-style/preferences, "
+    "never your core identity or boundaries (those are operator-owned)."
+)
+
+
+def build_review_prompt() -> str:
+    """The reviewer task. Adds the SELF-context-refinement invitation only when the
+    SELF_CONTEXT_WRITABLE tool is actually available (else the legacy skills-only
+    prompt, byte-identical)."""
+    try:
+        from agents.task.constants import AutonomyConfig
+        if AutonomyConfig.self_context_writable():
+            return _REVIEW_PROMPT + _SELF_CONTEXT_REVIEW_ADDENDUM
+    except Exception:
+        pass
+    return _REVIEW_PROMPT
+
+
+class BackgroundReviewMixin:
+    """Fire a post-turn self-improvement reviewer. Composed into Agent."""
+
+    def _bg_review_should_fire(self, turn_was_productive: bool) -> bool:
+        """Pure decision: increment the productive-turn counter and report whether the
+        interval has elapsed. Resets the counter when it fires."""
+        from agents.task.constants import AutonomyConfig
+        if not AutonomyConfig.background_review_enabled():
+            return False
+        if not AutonomyConfig.skills_writable():
+            # SK-F8: the reviewer's whole output rail is skill_manage(create) —
+            # firing it while skills are read-only just burns an aux-model run
+            # that is guaranteed to fail at the tool layer.
+            return False
+        if getattr(self, "_is_sub_agent", False):
+            return False  # a reviewer never forks a reviewer
+        if not turn_was_productive:
+            return False
+        interval = max(1, AutonomyConfig.bg_review_interval())
+        n = getattr(self, "_bg_review_productive_turns", 0) + 1
+        if n >= interval:
+            self._bg_review_productive_turns = 0
+            return True
+        self._bg_review_productive_turns = n
+        return False
+
+    def _maybe_spawn_background_review(self, *, turn_was_productive: bool) -> None:
+        """Fire-and-forget the reviewer if the cadence says so. Never blocks/raises."""
+        try:
+            if not self._bg_review_should_fire(turn_was_productive):
+                return
+            task = asyncio.create_task(self._run_background_review())
+            # M5: keep a strong reference so CPython can't GC the task mid-run (a task no
+            # one references may be collected before it completes), and so it's cancelled
+            # at session teardown. Mirrors _stall_check_task; self-removes when done.
+            _tasks = getattr(self.orchestrator, "_execution_tasks", None)
+            if isinstance(_tasks, list):
+                _tasks.append(task)
+                task.add_done_callback(lambda t, _l=_tasks: (_l.remove(t) if t in _l else None))
+            logger.info("🪞 spawned background-review fork (session %s)",
+                        getattr(self.orchestrator, "session_id", "?"))
+        except Exception as e:
+            logger.debug("background-review spawn skipped: %s", e)
+
+    async def _run_background_review(self) -> None:
+        """Run the reviewer sub-agent on the aux model. Fail-open."""
+        try:
+            from agents.task.constants import AutonomyConfig
+            manager = self.orchestrator.get_sub_agent_manager() if self.orchestrator else None
+            if manager is None:
+                return
+            # P2-8: reuse the agent's cached judge client instead of building a fresh
+            # isolated client (with its own httpx pool) on every fire — the old code
+            # leaked one pool per background review. Cached on self._judge_llm (the same
+            # slot _validate_output uses) and closed once at session cleanup (M2).
+            aux = getattr(self, "_judge_llm", None)
+            if aux is None:
+                try:
+                    # P2-9: async provisioning — don't block the loop building the client.
+                    aux = await self._provision_aux_llm_async("judge")
+                    if aux is not None:
+                        self._judge_llm = aux
+                except Exception:
+                    aux = None
+            # P2-10: make the reviewer's model cost VISIBLE. The cheap-aux map has no
+            # openrouter/nvidia key, so on the default OpenRouter deploy `aux` is None and
+            # this PROACTIVE loop (fires every BG_REVIEW_INTERVAL turns without any user
+            # ask) runs up to bg_review_max_steps on the FLAGSHIP main model. Log at INFO
+            # which model it will use so the cost isn't silent (add an openrouter/nvidia
+            # cheap-map entry or set AUX_MODEL_JUDGE to route it cheap).
+            _review_llm = aux or self.llm
+            if aux is None:
+                logger.info(
+                    "background review running on the MAIN model %r (no cheap aux "
+                    "resolved) — set AUX_MODEL_JUDGE or add a provider cheap-map entry "
+                    "to route it to a cheaper model",
+                    getattr(self.llm, "model_name", getattr(self.llm, "model_type", "?")),
+                )
+            await manager.run_subtask(
+                task=build_review_prompt(),
+                parent_agent_id=self.agent_id,
+                profile_id="executor",
+                max_steps=AutonomyConfig.bg_review_max_steps(),
+                parent_llm=_review_llm,
+                skip_complexity_check=True,
+            )
+        except Exception as e:
+            logger.debug("background-review run failed (ignored): %s", e)