openreflex 0.1.3__tar.gz → 0.2.0__tar.gz

{openreflex-0.1.3/src/openreflex.egg-info → openreflex-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openreflex
-Version: 0.1.3
+Version: 0.2.0
 Summary: Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live
 Author: vishnu-77
 License-Expression: MIT
@@ -140,16 +140,28 @@ Execution -failed_with-> ToolCall -resolved_by-> ToolCall
 Execution -caused-> Outcome -caused-> Experience -caused-> Lesson
 ```
 
-- **Before a task:** similar experiences are retrieved, three strategies (`inspect-first`, `test-first`,
-  `incremental`) are scored on success probability, time, tool calls, context cost, risk, uncertainty, and
-  reversibility, and a context of at most 1,400 characters is injected. Nothing is injected without relevant
-  experience.
-- **During a task:** each alert fires at most once per task with a cooldown, and names a concrete alternative.
+- **Before a task:** similar experiences are retrieved and three strategies (`inspect-first`, `test-first`,
+  `incremental`) are estimated on success probability, time, tool calls, context cost, risk, uncertainty,
+  reversibility, and expected regret. Strategies that another one beats on every measure are dropped as
+  dominated (Pareto efficiency), the rest are ranked by utility within any limits you set, and the chosen path
+  gets an execution budget for time, tool calls, and context. A context of at most 1,400 characters is
+  injected; nothing is injected without relevant experience.
+- **During a task:** when a detector finds a failure loop, repeated calls, stalled progress, context growth,
+  or work past the budget, OpenReflex estimates the marginal value of more work. The current path's success
+  estimate is updated with each call that makes no progress or fails, and compared with the cost of the work
+  left and with the best untried alternative. The alert ends with a recommendation to **continue**, **pivot**
+  to another strategy, or **stop** and ask the user. Each problem, pivot, or stop is raised once, with a cooldown
+  between messages.
 - **After a task:** outcome and chosen path come from the agent's `record_outcome` / `choose_path` MCP calls when
-  available, and are otherwise inferred from tool activity. Execution Regret is withheld when the outcome is unknown.
+  available, and are otherwise inferred from tool activity. Execution Regret compares the path taken with the
+  best plausible alternative; it is withheld when the outcome is unknown, and feeds back into how strategies
+  are ranked next time, along with success, cost, and how often a strategy ran into trouble.
 
-Agents can also query OpenReflex directly through its MCP server: `get_execution_context`, `choose_path`,
-`record_outcome`, `search_experience`, `explain_node`, `project_insights`, and `approve_project`.
+Set optional limits for every task with `OPENREFLEX_BUDGET`, for example `calls=40,minutes=20,tokens=60000`.
+
+Agents can also query OpenReflex directly through its MCP server: `get_execution_context` (optionally with
+`max_tool_calls`, `max_minutes`, `max_context_tokens`), `choose_path`, `check_progress`, `record_outcome`,
+`search_experience`, `explain_node`, `project_insights`, and `approve_project`.
 
 ## CLI
 

{openreflex-0.1.3 → openreflex-0.2.0}/README.md

@@ -108,16 +108,28 @@ Execution -failed_with-> ToolCall -resolved_by-> ToolCall
 Execution -caused-> Outcome -caused-> Experience -caused-> Lesson
 ```
 
-- **Before a task:** similar experiences are retrieved, three strategies (`inspect-first`, `test-first`,
-  `incremental`) are scored on success probability, time, tool calls, context cost, risk, uncertainty, and
-  reversibility, and a context of at most 1,400 characters is injected. Nothing is injected without relevant
-  experience.
-- **During a task:** each alert fires at most once per task with a cooldown, and names a concrete alternative.
+- **Before a task:** similar experiences are retrieved and three strategies (`inspect-first`, `test-first`,
+  `incremental`) are estimated on success probability, time, tool calls, context cost, risk, uncertainty,
+  reversibility, and expected regret. Strategies that another one beats on every measure are dropped as
+  dominated (Pareto efficiency), the rest are ranked by utility within any limits you set, and the chosen path
+  gets an execution budget for time, tool calls, and context. A context of at most 1,400 characters is
+  injected; nothing is injected without relevant experience.
+- **During a task:** when a detector finds a failure loop, repeated calls, stalled progress, context growth,
+  or work past the budget, OpenReflex estimates the marginal value of more work. The current path's success
+  estimate is updated with each call that makes no progress or fails, and compared with the cost of the work
+  left and with the best untried alternative. The alert ends with a recommendation to **continue**, **pivot**
+  to another strategy, or **stop** and ask the user. Each problem, pivot, or stop is raised once, with a cooldown
+  between messages.
 - **After a task:** outcome and chosen path come from the agent's `record_outcome` / `choose_path` MCP calls when
-  available, and are otherwise inferred from tool activity. Execution Regret is withheld when the outcome is unknown.
+  available, and are otherwise inferred from tool activity. Execution Regret compares the path taken with the
+  best plausible alternative; it is withheld when the outcome is unknown, and feeds back into how strategies
+  are ranked next time, along with success, cost, and how often a strategy ran into trouble.
 
-Agents can also query OpenReflex directly through its MCP server: `get_execution_context`, `choose_path`,
-`record_outcome`, `search_experience`, `explain_node`, `project_insights`, and `approve_project`.
+Set optional limits for every task with `OPENREFLEX_BUDGET`, for example `calls=40,minutes=20,tokens=60000`.
+
+Agents can also query OpenReflex directly through its MCP server: `get_execution_context` (optionally with
+`max_tool_calls`, `max_minutes`, `max_context_tokens`), `choose_path`, `check_progress`, `record_outcome`,
+`search_experience`, `explain_node`, `project_insights`, and `approve_project`.
 
 ## CLI
 

{openreflex-0.1.3 → openreflex-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openreflex"
-version = "0.1.3"
+version = "0.2.0"
 description = "Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live"
 readme = "README.md"
 license = "MIT"

{openreflex-0.1.3 → openreflex-0.2.0}/src/openreflex/__init__.py

@@ -1,3 +1,3 @@
 """Ambient, local execution intelligence."""
 
-__version__ = "0.1.3"
+__version__ = "0.2.0"

{openreflex-0.1.3 → openreflex-0.2.0}/src/openreflex/cli.py

@@ -102,6 +102,8 @@ def cmd_status(args) -> int:
           f"{eff['without_prior_experience']['tool_calls']} (observational)")
     print(f"  mean execution regret: {regret['mean']}   routing agreement: {routing['agreement']}")
     print(f"  live alerts: {data['live_alerts'] or '-'}")
+    control = data["execution_control"]
+    print(f"  verdicts: {control['verdicts'] or '-'}   tasks within tool-call budget: {control['tasks_within_tool_call_budget']}")
     return 0
 
 

openreflex-0.2.0/src/openreflex/control.py

@@ -0,0 +1,119 @@
+"""Budget-aware execution control: is more computation on the current path still worth it?
+
+The current path's success estimate starts from its planned probability and is updated with Bayes' rule as
+the task runs. A tool call that makes no progress, and more so a failure, is likelier on a path that will not
+work than on one that will, so each lowers the odds. Failures also weigh, more lightly, on the alternatives,
+since some causes (a broken environment, a wrong assumption about the task) defeat any approach.
+
+The marginal value of continuing is the success the path can still deliver minus the cost of the work it is
+expected to need; pivoting is valued the same way for the best untried alternative that no other untried one
+dominates, charged
+the part of its work a fresh start repeats; stopping is the zero point. Work past the budget costs more per
+unit. A verdict other than "continue" is only acted on when a detector has already found trouble.
+"""
+
+import math
+from dataclasses import dataclass
+
+from .models import CandidatePath, Execution, ToolCall
+from .privacy import PROGRESS
+from .routing import Budget, dominates, marginal_cost
+
+SUCCESS_VALUE = 0.55        # utility weight of success, as in routing.utility
+IDLE_LIKELIHOOD = 0.85      # P(call without progress | path will succeed) / P(... | path will not)
+FAILURE_LIKELIHOOD = 0.6    # the same ratio for a failed call
+SHARED_FAILURE_LIKELIHOOD = 0.85  # how much each failure also counts against the alternatives
+PIVOT_REUSE = 0.3           # most of an alternative's work that exploration so far can already cover
+PIVOT_MARGIN = 0.03         # a pivot must beat continuing by this much utility
+MIN_REMAINING = 0.3         # continuing always needs at least this share of the path's expected work
+
+
+@dataclass(frozen=True)
+class Verdict:
+    action: str                     # "continue", "pivot" or "stop"
+    current: str | None
+    success_estimate: float
+    value_continue: float
+    alternative: CandidatePath | None
+    alternative_estimate: float | None
+    value_pivot: float | None
+    budget_used: float
+
+    def summary(self) -> str:
+        parts = [f"success estimate ~{self.success_estimate:.0%} on {self.current or 'the current path'}"]
+        if self.alternative is not None and self.alternative_estimate is not None:
+            parts.append(f"~{self.alternative_estimate:.0%} for {self.alternative.strategy}")
+        parts.append(f"budget {self.budget_used:.0%} used")
+        return ", ".join(parts)
+
+
+def _update(probability: float, likelihood_ratio: float) -> float:
+    probability = min(max(probability, 1e-6), 1 - 1e-6)
+    odds = probability / (1 - probability) * likelihood_ratio
+    return odds / (1 + odds)
+
+
+def assess(execution: Execution, calls: list[ToolCall], current: CandidatePath | None,
+           alternatives: list[CandidatePath], budget: Budget, active_seconds: float, since: float,
+           tried: set[str] = frozenset()) -> Verdict:
+    """Verdict for the execution so far. `since` is when evidence against the current path starts counting:
+    the last progress, or the moment the path was switched to. `tried` strategies are not offered again."""
+    finished = [c for c in calls if c.status != "running"]
+    recent = [c for c in finished if c.started_at > since]
+    failures = sum(c.status == "failure" for c in recent)
+    idle = sum(c.status == "success" and c.category not in PROGRESS for c in recent)
+    used = budget.usage(active_seconds, len(calls), execution.output_tokens_estimate)
+    overrun = max(1.0, used)
+
+    prior = current.success_probability if current else 0.5
+    estimate = _update(prior, IDLE_LIKELIHOOD ** idle * FAILURE_LIKELIHOOD ** failures)
+    expected_calls = current.tool_calls if current else 20.0
+    remaining = max(expected_calls - len(calls), MIN_REMAINING * expected_calls) / max(expected_calls, 1.0)
+    value_continue = SUCCESS_VALUE * estimate - overrun * marginal_cost(
+        (current.time_seconds if current else 600) * remaining, expected_calls * remaining,
+        (current.context_tokens if current else 6000) * remaining)
+
+    total_failures = sum(c.status == "failure" for c in finished)
+    # Pivot options are compared with each other, not with the current path: its planning-time estimates are
+    # exactly what the evidence in this task is overturning.
+    pool = [p for p in alternatives if p.within_limits and p.strategy not in tried
+            and not (current and p.strategy == current.strategy)]
+    best, best_estimate, best_value = None, None, None
+    for path in pool:
+        if any(dominates(other, path) for other in pool if other is not path):
+            continue
+        path_estimate = _update(path.success_probability, SHARED_FAILURE_LIKELIHOOD ** total_failures)
+        repeat = 1 - min(PIVOT_REUSE, len(calls) / max(path.tool_calls, 1.0))
+        value = SUCCESS_VALUE * path_estimate - overrun * marginal_cost(
+            path.time_seconds * repeat, path.tool_calls * repeat, path.context_tokens * repeat)
+        if best_value is None or value > best_value:
+            best, best_estimate, best_value = path, path_estimate, value
+
+    if best_value is not None and best_value > value_continue + PIVOT_MARGIN and best_value > 0:
+        action = "pivot"
+    elif value_continue <= 0 and (best_value is None or best_value <= 0) and used >= 1:
+        action = "stop"
+    else:
+        action = "continue"
+    return Verdict(action, current.strategy if current else None, round(estimate, 4), round(value_continue, 4),
+                   best, None if best_estimate is None else round(best_estimate, 4),
+                   None if best_value is None else round(best_value, 4), round(used, 3))
+
+
+def pivots(execution: Execution) -> list[tuple[str, str, int]]:
+    """(from, to, call count) for each pivot recommended so far; verdicts read "pivot:<from>><to>@<calls>"."""
+    found = []
+    for verdict in execution.verdicts:
+        head, _, count = verdict.rpartition("@")
+        if head.startswith("pivot:") and ">" in head and count.isdigit():
+            source, _, target = head[len("pivot:"):].partition(">")
+            found.append((source, target, int(count)))
+    return found
+
+
+def switch_time(execution: Execution, calls: list[ToolCall]) -> float:
+    """When the path last changed: the call at which the latest pivot was recommended."""
+    history = pivots(execution)
+    if not history or not calls:
+        return -math.inf
+    return calls[max(1, min(history[-1][2], len(calls))) - 1].started_at

{openreflex-0.1.3 → openreflex-0.2.0}/src/openreflex/detect.py

@@ -7,15 +7,15 @@ interrupted when replanning is justified by evidence rather than by a single slo
 
 from dataclasses import dataclass
 
-from .models import CandidatePath, Execution, ToolCall
+from .models import Execution, ToolCall
 from .privacy import PROGRESS
+from .routing import Budget
 
 COOLDOWN_SECONDS = 180
 REPEAT_THRESHOLD = 3
 FAILURE_LOOP_THRESHOLD = 3
 STAGNATION_CALLS = 15
 STAGNATION_SECONDS = 600
-CONTEXT_FLOOR_TOKENS = 30000
 
 
 @dataclass(frozen=True)
@@ -25,7 +25,7 @@ class Alert:
     detail: str
 
 
-def detect(execution: Execution, calls: list[ToolCall], recommended: CandidatePath | None, now: float) -> list[Alert]:
+def detect(execution: Execution, calls: list[ToolCall], budget: Budget, now: float, active_seconds: float = 0) -> list[Alert]:
     alerts: list[Alert] = []
     finished = [c for c in calls if c.status != "running"]
 
@@ -61,15 +61,17 @@ def detect(execution: Execution, calls: list[ToolCall], recommended: CandidatePa
         alerts.append(Alert("stagnation", 0.7, f"{len(since_progress)} calls over {idle / 60:.0f} min without a "
                                                f"successful edit or check (only {', '.join(kinds)})"))
 
-    budget = max(CONTEXT_FLOOR_TOKENS, 2 * (recommended.context_tokens if recommended else 8000))
-    if execution.output_tokens_estimate > budget or execution.compactions:
+    if execution.output_tokens_estimate > budget.context_tokens or execution.compactions:
         reason = "context was compacted" if execution.compactions else \
-            f"~{execution.output_tokens_estimate // 1000}k tokens of tool output (budget ~{int(budget) // 1000}k)"
+            f"~{execution.output_tokens_estimate // 1000}k tokens of tool output (budget ~{int(budget.context_tokens) // 1000}k)"
         alerts.append(Alert("context_growth", 0.5, reason))
 
-    if recommended and len(calls) > max(30, 2.5 * recommended.tool_calls) and not any(
-            c.category in PROGRESS and c.status == "success" for c in calls[-8:]):
-        alerts.append(Alert("over_budget", 0.5, f"{len(calls)} tool calls vs ~{recommended.tool_calls:.0f} expected"))
+    recent_progress = any(c.category in PROGRESS and c.status == "success" for c in calls[-8:])
+    # The time budget, like stagnation, only applies once implementation has begun: reading can take a while.
+    if not recent_progress and (len(calls) > budget.tool_calls or (implementing and active_seconds > budget.seconds)):
+        detail = (f"{len(calls)} tool calls (budget ~{budget.tool_calls:.0f})" if len(calls) > budget.tool_calls
+                  else f"{active_seconds / 60:.0f} min of work (budget ~{budget.seconds / 60:.0f} min)")
+        alerts.append(Alert("over_budget", 0.5, detail))
     return alerts
 
 

{openreflex-0.1.3 → openreflex-0.2.0}/src/openreflex/engine.py

@@ -14,10 +14,10 @@ import time
 from collections import Counter
 from pathlib import Path
 
-from . import detect, learning
+from . import control, detect, learning
 from .models import CandidatePath, Context, Execution, Experience, Lesson, Outcome, Status, Task, ToolCall, uid
 from .privacy import PROGRESS, categorize, error_signature, file_paths, fingerprint, redact
-from .routing import candidates, classify, embed, similarity
+from .routing import Budget, Limits, budget_for, candidates, classify, embed, limits_from_env, similarity
 from .store import Store, database_path
 
 FOLLOW_UP = re.compile(r"^\s*(yes|no|ok(ay)?|thanks|thank you|continue|go on|go ahead|proceed|sure|lgtm|do it|"
@@ -155,18 +155,32 @@ class Engine:
         recent = [e for e in self.store.list("Execution", limit=50) if now - e.started_at < max_age]
         return max(recent, key=lambda e: (e.ended_at is None, e.started_at), default=None)
 
-    def context_for(self, description: str, agent: str = "mcp", session: str | None = None) -> tuple[Execution, Context]:
-        """Explicit request for an Execution Context; always returns the full text, even without experience."""
+    def context_for(self, description: str, agent: str = "mcp", session: str | None = None,
+                    limits: Limits | None = None) -> tuple[Execution, Context]:
+        """Explicit request for an Execution Context; always returns the full text, even without experience.
+        Limits, when given, re-plan the current task so its path and budget fit them."""
         now = self.clock()
         with self.store.transaction():
             current = self.current_execution(agent if session else None, session, max_age=1800)
             if current is not None and current.ended_at is None:
                 task = self._task(current)
-                if task.description == UNTRACKED or not task.substantial:
-                    self._describe(current, description, now)
+                if task.description == UNTRACKED or not task.substantial or limits is not None:
+                    keep = task.description if task.description != UNTRACKED and task.substantial else description
+                    self._describe(current, keep, now, limits)
                 context = self.store.list("Context", "task_id", current.task_id, limit=1)[0]
                 return current, context
-            return self._start(agent, session or f"mcp-{int(now)}", description, now, substantial=True)
+            return self._start(agent, session or f"mcp-{int(now)}", description, now, substantial=True, limits=limits)
+
+    def progress(self, agent: str | None = None, session: str | None = None):
+        """Explicit progress check: (execution, verdict, detected problems, budget). Records nothing."""
+        with self.store.transaction():
+            execution = self.current_execution(agent if session else None, session)
+            if execution is None:
+                raise ValueError("No current execution; request an execution context first")
+            calls, now = self._calls(execution.id), self.clock()
+            budget, active = self._budget(execution), learning.active_seconds(execution, calls, now)
+            problems = detect.detect(execution, calls, budget, now, active)
+            return execution, self._verdict(execution, calls, budget, active), problems, budget
 
     def choose_path(self, strategy: str, steps: list[str] | None = None, execution_id: str | None = None) -> CandidatePath:
         with self.store.transaction():
@@ -182,6 +196,9 @@ class Engine:
                     "steps": [redact(s, 200) for s in (steps or [])][:8], "evidence_count": 0, "uncertainty": 1.0})
                 self.store.put(path)
             execution.chosen_path_id, execution.chosen_inferred = path.id, False
+            limit = self._budget(execution) if execution.budget_source == "limit" else None
+            self._set_budget(execution, budget_for(path, Limits(limit.seconds, limit.tool_calls, limit.context_tokens)
+                                                   if limit else limits_from_env()))
             self.store.put(execution)
             self.store.link(execution.id, "used", path.id)
             return path
@@ -198,8 +215,9 @@ class Engine:
         task = Task(description=redact(description, 1000), task_class=classify(description), session_id="preview",
                     agent="preview", started_at=self.clock())
         retrieved = self.retrieve(task.description, task.task_class)
-        paths = candidates(task.id, task.task_class, self._evidence(task.task_class, task.description))
-        return render_context(task, paths, retrieved, self.lessons([x for x, _ in retrieved]))
+        limits = limits_from_env()
+        paths = candidates(task.id, task.task_class, self._evidence(task.task_class, task.description), limits)
+        return render_context(task, paths, retrieved, self.lessons([x for x, _ in retrieved]), budget_for(paths[0], limits))
 
     def retrieve(self, description: str, task_class: str | None = None, k: int = 5) -> list[tuple[Experience, float]]:
         query = embed(description)
@@ -265,47 +283,52 @@ class Engine:
         return similar if len(similar) >= 3 else same
 
     def _start(self, agent: str, session: str, description: str, now: float,
-               substantial: bool) -> tuple[Execution, Context]:
+               substantial: bool, limits: Limits | None = None) -> tuple[Execution, Context]:
         task = Task(description=redact(description, 1000), task_class=classify(description), session_id=session,
                     agent=agent, started_at=now, substantial=substantial)
-        paths = candidates(task.id, task.task_class, self._evidence(task.task_class, task.description))
+        limits = limits or limits_from_env()
+        paths = candidates(task.id, task.task_class, self._evidence(task.task_class, task.description), limits)
         execution = Execution(task_id=task.id, agent=agent, session_id=session, recommended_path_id=paths[0].id,
                               started_at=now, last_progress_at=now)
+        self._set_budget(execution, budget_for(paths[0], limits))
         self.store.put(task)
         for path in paths:
             self.store.put(path)
             self.store.link(path.id, "recommended_for", task.id)
         self.store.put(execution)
         self.store.link(task.id, "caused", execution.id)
-        context = self._write_context(task, paths)
+        context = self._write_context(task, paths, self._budget(execution))
         self.store.link(execution.id, "used", context.id)
         self.store.bind_session(agent, session, execution.id)
         return execution, context
 
-    def _describe(self, execution: Execution, description: str, now: float) -> Context:
-        """Attach a real description to a task that began without one, and re-plan it."""
+    def _describe(self, execution: Execution, description: str, now: float, limits: Limits | None = None) -> Context:
+        """Attach a real description to a task that began without one (or new limits), and re-plan it."""
         task = self._task(execution)
         task.description, task.task_class = redact(description, 1000), classify(description)
         task.substantial = is_substantial(description) or task.substantial
         self.store.put(task)
         for node in self.store.list("CandidatePath", "task_id", task.id) + self.store.list("Context", "task_id", task.id):
             self.store.delete(node.id)
-        paths = candidates(task.id, task.task_class, self._evidence(task.task_class, task.description))
+        limits = limits or limits_from_env()
+        paths = candidates(task.id, task.task_class, self._evidence(task.task_class, task.description), limits)
         for path in paths:
             self.store.put(path)
             self.store.link(path.id, "recommended_for", task.id)
         execution.recommended_path_id = paths[0].id
-        execution.chosen_path_id = None if execution.chosen_inferred else execution.chosen_path_id
+        # A declared path was deleted with the old plan above; re-planning starts from the new recommendation.
+        execution.chosen_path_id, execution.chosen_inferred = None, False
+        self._set_budget(execution, budget_for(paths[0], limits))
         self.store.put(execution)
-        context = self._write_context(task, paths)
+        context = self._write_context(task, paths, self._budget(execution))
         self.store.link(execution.id, "used", context.id)
         return context
 
-    def _write_context(self, task: Task, paths: list[CandidatePath]) -> Context:
+    def _write_context(self, task: Task, paths: list[CandidatePath], budget: Budget | None = None) -> Context:
         retrieved = self.retrieve(task.description, task.task_class) if task.substantial else []
         experiences = [e for e, _ in retrieved]
         lessons = self.lessons(experiences)
-        text = render_context(task, paths, retrieved, lessons)
+        text = render_context(task, paths, retrieved, lessons, budget)
         context = Context(task_id=task.id, text=text, experience_ids=[e.id for e in experiences],
                           lesson_ids=[lesson.id for lesson, _, _ in lessons],
                           injected=task.substantial and bool(experiences))
@@ -330,27 +353,70 @@ class Engine:
                     f"\"{signature}\". Change the input or approach before retrying.")
         return None
 
-    def _alert(self, execution: Execution, calls: list[ToolCall], now: float) -> str | None:
+    def _set_budget(self, execution: Execution, budget: Budget) -> None:
+        execution.budget_seconds, execution.budget_tool_calls = round(budget.seconds, 1), round(budget.tool_calls, 1)
+        execution.budget_tokens, execution.budget_source = round(budget.context_tokens), budget.source
+
+    def _budget(self, execution: Execution) -> Budget:
+        if execution.budget_tool_calls is not None:
+            return Budget(execution.budget_seconds, execution.budget_tool_calls, execution.budget_tokens,
+                          execution.budget_source or "estimated")
         recommended = self.store.get(execution.recommended_path_id) if self.store.exists(execution.recommended_path_id) else None
-        alert = detect.select(execution, detect.detect(execution, calls, recommended, now), now)
-        if alert is None:
+        return budget_for(recommended) if recommended else Budget(1200.0, 30.0, 30000.0, "estimated")
+
+    def _verdict(self, execution: Execution, calls: list[ToolCall], budget: Budget, active: float) -> control.Verdict:
+        paths = self.store.list("CandidatePath", "task_id", execution.task_id)
+        by_strategy = {p.strategy: p for p in paths}
+        history = control.pivots(execution)
+        declared = self.store.get(execution.chosen_path_id) if execution.chosen_path_id and not execution.chosen_inferred \
+            and self.store.exists(execution.chosen_path_id) else None
+        recommended = next((p for p in paths if p.id == execution.recommended_path_id), None)
+        # Mid-task, running checks before any edit is already test-first, even though no edit confirms it yet.
+        inferred = learning.infer_strategy(calls) or ("test-first" if any(c.category == "test" for c in calls) else "")
+        current = (by_strategy.get(history[-1][1]) if history else None) or declared or \
+            by_strategy.get(inferred) or recommended
+        tried = {name for source, target, _ in history for name in (source, target)}
+        since = max(execution.last_progress_at, control.switch_time(execution, calls))
+        return control.assess(execution, calls, current, paths, budget, active, since, tried)
+
+    def _alert(self, execution: Execution, calls: list[ToolCall], now: float) -> str | None:
+        """At most one message per cooldown: a newly detected problem, or a new pivot/stop verdict when a
+        problem persists after its alert was already given."""
+        if now - execution.last_alert_at < detect.COOLDOWN_SECONDS:
+            return None
+        budget, active = self._budget(execution), learning.active_seconds(execution, calls, now)
+        problems = detect.detect(execution, calls, budget, now, active)
+        if not problems:
             return None
-        execution.alerts.append(alert.kind)
+        verdict = self._verdict(execution, calls, budget, active)
+        key = {"pivot": f"pivot:{verdict.current or 'unplanned'}>{verdict.alternative.strategy}" if verdict.alternative else None,
+               "stop": "stop"}.get(verdict.action)
+        fresh_verdict = key is not None and key not in {v.rpartition("@")[0] for v in execution.verdicts}
+        alert = detect.select(execution, problems, now)
+        if alert is None and not fresh_verdict:
+            return None
+        if alert is not None:
+            execution.alerts.append(alert.kind)
+        alert = alert or max(problems, key=lambda a: a.severity)
         execution.last_alert_at = now
-        task = self._task(execution)
-        paths = sorted(self.store.list("CandidatePath", "task_id", task.id), key=lambda p: -p.score)
-        current = learning.infer_strategy(calls) or (recommended.strategy if recommended else None)
-        alternative = next((p for p in paths if p.strategy != current), None)
+        execution.verdicts.append(f"{key or verdict.action}@{len(calls)}")
         advice = {
-            "failure_loop": "Stop retrying the same fix: re-read the error and question the assumption behind it",
+            "failure_loop": "Don't retry the same fix: re-read the error and question the assumption behind it",
             "repeated_action": "Reuse the earlier result instead of re-running the same call",
             "stagnation": "Progress has stalled; re-plan before continuing",
             "context_growth": "Prefer targeted reads (line ranges, filtered or tail'ed command output) over full dumps",
-            "over_budget": "This is well past the expected effort; re-scope or re-plan",
+            "over_budget": "This is past the execution budget; re-scope or re-plan",
         }[alert.kind]
-        parts = [f"OpenReflex: {alert.detail}. {advice}."]
-        if alternative and alert.kind in {"failure_loop", "stagnation", "over_budget"}:
-            parts.append(f"Alternative path - {alternative.strategy}: {' -> '.join(alternative.steps)}.")
+        parts = [f"OpenReflex: {alert.detail}."]
+        if verdict.action == "stop":
+            parts.append(f"Recommendation: stop. More work is unlikely to pay off ({verdict.summary()}). "
+                         "Summarize what was tried and what failed, and ask the user how to proceed.")
+        elif verdict.action == "pivot":
+            path = verdict.alternative
+            parts.append(f"{advice}. Recommendation: pivot to {path.strategy} - {' -> '.join(path.steps)} "
+                         f"({verdict.summary()}).")
+        else:
+            parts.append(f"{advice}. Recommendation: continue on this path ({verdict.summary()}).")
         signature = next((c.error_signature for c in reversed(calls) if c.status == "failure"), None)
         if signature and alert.kind == "failure_loop":
             known = [item for item in self.store.list("Lesson", "kind", "resolution", limit=500) if signature in item.text]
@@ -407,6 +473,7 @@ class Engine:
             strategy=outcome.chosen_strategy, status=status, elapsed_seconds=outcome.elapsed_seconds,
             tool_calls=outcome.tool_calls, output_tokens_estimate=outcome.output_tokens_estimate, files=files[:20],
             benefited=bool(context and context.experience_ids), estimated_regret=outcome.estimated_regret,
+            alerts=[a for a in execution.alerts if not a.startswith("retry:")], verdicts=list(execution.verdicts),
             embedding=embed(task.description), created_at=now)
         self.store.put(experience)
         self.store.link(outcome.id, "caused", experience.id)
@@ -422,7 +489,7 @@ class Engine:
 
 
 def render_context(task: Task, paths: list[CandidatePath], retrieved: list[tuple[Experience, float]],
-                   lessons: list[tuple[Lesson, float, int]]) -> str:
+                   lessons: list[tuple[Lesson, float, int]], budget: Budget | None = None) -> str:
     """Compact Execution Context. Budgeted in characters so it stays a small, predictable token cost."""
     experiences = [e for e, _ in retrieved]
     succeeded = sum(e.status == "success" for e in experiences)
@@ -432,7 +499,15 @@ def render_context(task: Task, paths: list[CandidatePath], retrieved: list[tuple
     lines.append(f"Suggested path: {best.strategy} - {' -> '.join(best.steps)} "
                  f"(success~{best.success_probability:.0%}, ~{best.tool_calls:.0f} tool calls, {basis}).")
     if rest:
-        lines.append("Alternatives: " + ", ".join(f"{p.strategy} ({p.score:+.2f} vs {best.score:+.2f})" for p in rest))
+        def label(p: CandidatePath) -> str:
+            if p.dominated_by:
+                return f"{p.strategy} (dominated by {p.dominated_by})"
+            return f"{p.strategy} ({'over your limit' if not p.within_limits else f'{p.score:+.2f} vs {best.score:+.2f}'})"
+        lines.append("Alternatives: " + ", ".join(label(p) for p in rest))
+    if budget is not None:
+        lines.append(f"Budget: ~{budget.tool_calls:.0f} tool calls, ~{budget.seconds / 60:.0f} min, "
+                     f"~{budget.context_tokens / 1000:.0f}k tokens of tool output"
+                     + (" (your limit)." if budget.source == "limit" else "."))
     files = Counter(f for e in experiences if e.status == "success" for f in e.files[:6])
     if files:
         lines.append("Likely relevant files: " + ", ".join(f for f, _ in files.most_common(6)))

{openreflex-0.1.3 → openreflex-0.2.0}/src/openreflex/mcp_server.py

@@ -9,11 +9,13 @@ from mcp.server.fastmcp import FastMCP
 from . import metrics
 from .engine import Engine
 from .project import approval, approve, project_root
+from .routing import Limits
 
 INSTRUCTIONS = """OpenReflex is local execution memory for this project. Hooks capture work automatically.
 Use get_execution_context before a substantial task if no [OpenReflex] context was already provided.
-Call choose_path if you deliberately take a different approach than suggested, and record_outcome once the
-result is verified (tests pass, user confirmed). Never call approve_project unless the user asked for it."""
+Call choose_path if you deliberately take a different approach than suggested, check_progress when unsure
+whether more work is paying off, and record_outcome once the result is verified (tests pass, user confirmed).
+Never call approve_project unless the user asked for it."""
 
 
 def build_server(project: Path) -> FastMCP:
@@ -38,17 +40,52 @@ def build_server(project: Path) -> FastMCP:
             instance.close()
 
     @server.tool()
-    def get_execution_context(task: str) -> str:
-        """Retrieve relevant past experience for a task, with 2-3 scored candidate strategies, likely files, and
-        lessons. Call before substantial work when no [OpenReflex] context was injected."""
+    def get_execution_context(task: str, max_tool_calls: int | None = None, max_minutes: float | None = None,
+                              max_context_tokens: int | None = None) -> str:
+        """Retrieve relevant past experience for a task: candidate strategies scored on success, time, tool calls,
+        context, risk, uncertainty and reversibility (dominated ones marked), an execution budget, likely files,
+        and lessons. Call before substantial work when no [OpenReflex] context was injected. Optional max_* limits
+        constrain the plan and budget."""
         def operation(e: Engine):
-            execution, context = e.context_for(task)
-            paths = sorted(e.store.list("CandidatePath", "task_id", execution.task_id), key=lambda p: -p.score)
+            given = [value for value in (max_tool_calls, max_minutes, max_context_tokens) if value is not None]
+            if any(value <= 0 for value in given):
+                raise ValueError("limits must be positive")
+            limits = Limits(max_minutes * 60 if max_minutes else None, max_tool_calls, max_context_tokens) if given else None
+            execution, context = e.context_for(task, limits=limits)
+            paths = e.store.list("CandidatePath", "task_id", execution.task_id)
+            order = [execution.recommended_path_id] + [p.id for p in sorted(paths, key=lambda p: -p.score)]
+            paths = sorted(paths, key=lambda p: order.index(p.id))
+
+            def status(p) -> str:
+                return (f"dominated by {p.dominated_by}" if p.dominated_by else
+                        "over the limits" if not p.within_limits else "Pareto-efficient")
             scored = "\n".join(
-                f"- {p.strategy}: score {p.score:+.3f}, success~{p.success_probability:.0%}, ~{p.tool_calls:.0f} calls, "
-                f"~{p.time_seconds / 60:.0f} min, risk {p.risk:.2f}, uncertainty {p.uncertainty:.2f}, "
-                f"reversibility {p.reversibility:.2f}, evidence n={p.evidence_count}" for p in paths)
-            return f"{context.text}\n\nCandidate scores:\n{scored}\n(execution {execution.id})"
+                f"- {p.strategy}: score {p.score:+.3f} ({status(p)}), success~{p.success_probability:.0%}, "
+                f"~{p.tool_calls:.0f} calls, ~{p.time_seconds / 60:.0f} min, ~{p.context_tokens / 1000:.1f}k tokens, "
+                f"risk {p.risk:.2f}, uncertainty {p.uncertainty:.2f}, reversibility {p.reversibility:.2f}, "
+                f"expected regret {p.expected_regret:.3f}, evidence n={p.evidence_count}" for p in paths)
+            return f"{context.text}\n\nCandidate paths:\n{scored}\n(execution {execution.id})"
+        return run(operation)
+
+    @server.tool()
+    def check_progress() -> str:
+        """Estimate whether more work on the current path is still worth it: continue, pivot to another strategy,
+        or stop and ask the user. Based on progress so far, failures and the execution budget. Records nothing."""
+        def operation(e: Engine):
+            execution, verdict, problems, budget = e.progress()
+            action = verdict.action if problems else "continue"
+            lines = [f"Recommendation: {action}" + ("" if problems else " (no signs of trouble)") + ".",
+                     f"Estimate: {verdict.summary()}.",
+                     f"Marginal value: continue {verdict.value_continue:+.3f}"
+                     + (f", pivot to {verdict.alternative.strategy} {verdict.value_pivot:+.3f}" if verdict.alternative else "")
+                     + ", stop +0.000.",
+                     f"Budget: ~{budget.tool_calls:.0f} tool calls, ~{budget.seconds / 60:.0f} min, "
+                     f"~{budget.context_tokens / 1000:.0f}k tokens of tool output ({budget.source})."]
+            if problems:
+                lines.append("Detected: " + "; ".join(p.detail for p in problems) + ".")
+            if action == "pivot":
+                lines.append(f"{verdict.alternative.strategy}: {' -> '.join(verdict.alternative.steps)}.")
+            return "\n".join(lines) + f"\n(execution {execution.id})"
         return run(operation)
 
     @server.tool()