openreflex 0.2.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openreflex
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -128,6 +128,17 @@ OpenReflex installs per project with `openreflex install <agent>`, or as a plugi
 With a plugin install, enable each project with `openreflex approve`. Claude Code and Codex are verified in live
 sessions; the Cursor and OpenCode integrations follow each agent's documented hook protocol.
 
+## See it work
+
+A real Claude Code session in a repository where OpenReflex has seen one similar task before. The
+`UserPromptSubmit` line shows the past experience found and the context added; the `Stop` line shows the verified
+outcome, the path taken and the cost.
+
+![Claude Code session with OpenReflex](https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session-2.png)
+
+The full walkthrough, with both sessions, the exact context the model received and the CLI output, is in
+[docs/walkthrough.md](docs/walkthrough.md).
+
 ## How it works
 
 Hooks send lifecycle events (prompt, tool start, tool end, compaction, stop) to the OpenReflex engine, which
@@ -157,21 +168,31 @@ Execution -caused-> Outcome -caused-> Experience -caused-> Lesson
   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.
 
+Every recommendation is stored as a decision snapshot with a **Reflex Score** (0-100): how strong the
+recommendation is, which is separate from the estimated chance that the task succeeds. `openreflex why` explains
+the latest decision and `openreflex trace` shows the timeline. In Claude Code, a short recap appears when a task
+starts, when OpenReflex recommends a pivot or stop or detects trouble, and when the task completes.
+
 Set optional limits for every task with `OPENREFLEX_BUDGET`, for example `calls=40,minutes=20,tokens=60000`.
+Routing, scoring, budget and recap settings come from a versioned policy: the packaged defaults, overridden by
+`~/.openreflex/config.toml` and then by `.openreflex.toml` in the project.
 
 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`.
+`max_tool_calls`, `max_minutes`, `max_context_tokens`), `choose_path`, `check_progress`, `explain_decision`,
+`get_execution_trace`, `get_reflex_score`, `record_outcome`, `search_experience`, `explain_node`,
+`get_project_insights`, `approve_project`, and `forget_experience` (deletes one past task's memory, only when the user asks).
 
 ## CLI
 
 | Command | Purpose |
 |---|---|
 | `install <agent> [--dry-run]` | Write project hooks and MCP config, and enable the project |
+| `uninstall <agent> [--dry-run]` | Remove OpenReflex's project hooks and MCP config; captured memory is kept |
 | `approve` / `revoke` | Enable or disable capture for the current project |
 | `context "<task>"` | Preview the Execution Context a task would receive |
 | `status [--json]` | What has been captured, reused, and learned |
-| `doctor` | Installation checks and recent hook errors |
+| `why` / `trace` | Explain the latest recommendation, or show the decision timeline |
+| `doctor` | Installation, project resolution, and recent hook activity checks |
 | `forget --yes` | Delete the project's data |
 | `benchmark` | Run the simulated benchmark |
 | `hook <agent> <event>` / `mcp` | Used by agent configs |

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

@@ -96,6 +96,17 @@ OpenReflex installs per project with `openreflex install <agent>`, or as a plugi
 With a plugin install, enable each project with `openreflex approve`. Claude Code and Codex are verified in live
 sessions; the Cursor and OpenCode integrations follow each agent's documented hook protocol.
 
+## See it work
+
+A real Claude Code session in a repository where OpenReflex has seen one similar task before. The
+`UserPromptSubmit` line shows the past experience found and the context added; the `Stop` line shows the verified
+outcome, the path taken and the cost.
+
+![Claude Code session with OpenReflex](https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session-2.png)
+
+The full walkthrough, with both sessions, the exact context the model received and the CLI output, is in
+[docs/walkthrough.md](docs/walkthrough.md).
+
 ## How it works
 
 Hooks send lifecycle events (prompt, tool start, tool end, compaction, stop) to the OpenReflex engine, which
@@ -125,21 +136,31 @@ Execution -caused-> Outcome -caused-> Experience -caused-> Lesson
   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.
 
+Every recommendation is stored as a decision snapshot with a **Reflex Score** (0-100): how strong the
+recommendation is, which is separate from the estimated chance that the task succeeds. `openreflex why` explains
+the latest decision and `openreflex trace` shows the timeline. In Claude Code, a short recap appears when a task
+starts, when OpenReflex recommends a pivot or stop or detects trouble, and when the task completes.
+
 Set optional limits for every task with `OPENREFLEX_BUDGET`, for example `calls=40,minutes=20,tokens=60000`.
+Routing, scoring, budget and recap settings come from a versioned policy: the packaged defaults, overridden by
+`~/.openreflex/config.toml` and then by `.openreflex.toml` in the project.
 
 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`.
+`max_tool_calls`, `max_minutes`, `max_context_tokens`), `choose_path`, `check_progress`, `explain_decision`,
+`get_execution_trace`, `get_reflex_score`, `record_outcome`, `search_experience`, `explain_node`,
+`get_project_insights`, `approve_project`, and `forget_experience` (deletes one past task's memory, only when the user asks).
 
 ## CLI
 
 | Command | Purpose |
 |---|---|
 | `install <agent> [--dry-run]` | Write project hooks and MCP config, and enable the project |
+| `uninstall <agent> [--dry-run]` | Remove OpenReflex's project hooks and MCP config; captured memory is kept |
 | `approve` / `revoke` | Enable or disable capture for the current project |
 | `context "<task>"` | Preview the Execution Context a task would receive |
 | `status [--json]` | What has been captured, reused, and learned |
-| `doctor` | Installation checks and recent hook errors |
+| `why` / `trace` | Explain the latest recommendation, or show the decision timeline |
+| `doctor` | Installation, project resolution, and recent hook activity checks |
 | `forget --yes` | Delete the project's data |
 | `benchmark` | Run the simulated benchmark |
 | `hook <agent> <event>` / `mcp` | Used by agent configs |

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openreflex"
-version = "0.2.0"
+version = "0.3.1"
 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"
@@ -41,7 +41,7 @@ openreflex = "openreflex.cli:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-openreflex = ["integrations/*.ts"]
+openreflex = ["integrations/*.ts", "policies/*.toml"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

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

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

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

@@ -6,13 +6,12 @@ import time
 from pathlib import Path
 
 from . import __version__
-from .project import approval, approve, home, project_root, revoke
+from .project import approval, approve, home, project_resolution, project_root, revoke
 
 AGENT_CHOICES = ["claude-code", "codex", "cursor", "opencode"]
 
 
 def _project(value: str | None) -> Path:
-    # An unexpanded ${VAR} placeholder from an agent config means "not provided".
     return project_root(None if not value or "${" in value else value)
 
 
@@ -32,7 +31,7 @@ def cmd_hook(args) -> int:
     if output:
         sys.stdout.write(output)
         sys.stdout.flush()
-    return 0  # never block the agent
+    return 0
 
 
 def cmd_mcp(args) -> int:
@@ -60,17 +59,46 @@ def cmd_install(args) -> int:
 
     project = _project(args.project)
     changes = install(args.agent, project, dry_run=args.dry_run)
-    verb = "Would write" if args.dry_run else "Wrote"
-    for change in changes:
-        print(f"{verb} {change}")
-    if not changes:
-        print("Already installed; nothing to change.")
+    verb = "would update" if args.dry_run else "updated"
+    print("OPENREFLEX / CONNECT")
+    print(f"  agent       {args.agent}")
+    print(f"  project     {project}")
+    if changes:
+        print(f"  config      {verb} {len(changes)} file{'s' if len(changes) != 1 else ''}")
+        for change in changes:
+            print(f"              {change}")
+    else:
+        print("  config      already connected")
     if not args.dry_run:
-        print(f"Enabled for {project}.")
+        print("  memory      enabled")
+        print("  storage     local")
+        print("\n  [ok] reflex active")
         if args.agent == "codex":
-            print("Codex asks you to trust new hooks once: open /hooks in Codex and approve the OpenReflex entries.")
+            print("\nCodex requires one trust step: open /hooks and approve the OpenReflex entries.")
     if shutil.which("openreflex") is None:
-        print("Warning: `openreflex` is not on PATH; hooks will not run. Install with `uv tool install .` or `pipx install .`.")
+        print("\nWarning: `openreflex` is not on PATH; hooks will not run. Install with `uv tool install .` or `pipx install .`.")
+    return 0
+
+
+def cmd_uninstall(args) -> int:
+    from .install import uninstall
+
+    project = _project(args.project)
+    changes = uninstall(args.agent, project, dry_run=args.dry_run)
+    verb = "would remove" if args.dry_run else "removed"
+    print("OPENREFLEX / DISCONNECT")
+    print(f"  agent       {args.agent}")
+    print(f"  project     {project}")
+    if changes:
+        print(f"  config      {verb} OpenReflex entries from {len(changes)} file{'s' if len(changes) != 1 else ''}")
+        for change in changes:
+            print(f"              {change}")
+    else:
+        print("  config      no project integration found")
+    print("  memory      preserved")
+    if not args.dry_run:
+        print("\n  [ok] disconnected")
+        print("\nRun `openreflex forget --yes` separately if you also want to delete local experience data.")
     return 0
 
 
@@ -118,22 +146,91 @@ def cmd_context(args) -> int:
     return 0
 
 
+def cmd_why(args) -> int:
+    from .engine import Engine
+
+    engine = Engine(_project(args.project))
+    try:
+        print(engine.why())
+    finally:
+        engine.close()
+    return 0
+
+
+def cmd_trace(args) -> int:
+    from .engine import Engine
+
+    engine = Engine(_project(args.project))
+    try:
+        print(engine.trace())
+    finally:
+        engine.close()
+    return 0
+
+
+def _json(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        return value if isinstance(value, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _claude_plugin_enabled() -> bool:
+    settings = _json(Path.home() / ".claude" / "settings.json")
+    enabled = settings.get("enabledPlugins")
+    if isinstance(enabled, dict):
+        return any("openreflex" in str(name).lower() and value is not False for name, value in enabled.items())
+    if isinstance(enabled, list):
+        return any("openreflex" in str(name).lower() for name in enabled)
+    return False
+
+
+def _recent_hook_trace(project: Path) -> str | None:
+    path = home() / "logs" / "hooks.log"
+    try:
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()[-100:]
+    except OSError:
+        return None
+    target = str(project)
+    for line in reversed(lines):
+        if target in line:
+            return line
+    return lines[-1] if lines else None
+
+
 def cmd_doctor(args) -> int:
     from .store import database_path
 
     project = _project(args.project)
+    resolution = project_resolution(args.project)
+    claude_project = "openreflex hook" in _read(project / ".claude" / "settings.json")
+    claude_plugin = _claude_plugin_enabled()
+    trace = _recent_hook_trace(project)
     checks = [
         ("openreflex on PATH", shutil.which("openreflex") is not None),
         ("project enabled", approval(project) is not None),
         ("database exists", database_path(project).exists()),
-        ("Claude Code hooks (project)", "openreflex hook" in _read(project / ".claude" / "settings.json")),
+        ("Claude Code integration", claude_project or claude_plugin),
         ("Codex hooks (project)", "openreflex hook" in _read(project / ".codex" / "hooks.json")),
         ("Cursor hooks (project)", "openreflex hook" in _read(project / ".cursor" / "hooks.json")),
         ("OpenCode plugin (project)", (project / ".opencode" / "plugins" / "openreflex.ts").exists()),
+        ("hook activity observed", trace is not None),
     ]
-    print(f"Project: {project}\nData:    {database_path(project)}")
+    print("OPENREFLEX / DOCTOR")
+    print(f"  project     {project}")
+    print(f"  resolution  {resolution['source']}")
+    if resolution.get("cwd"):
+        print(f"  hook cwd    {resolution['cwd']}")
+    if resolution.get("agent_hint"):
+        print(f"  agent hint  {resolution['agent_hint']}")
+    print(f"  data        {database_path(project)}")
+    if claude_plugin and not claude_project:
+        print("  Claude      plugin/global install detected")
     for name, ok in checks:
         print(f"  [{'ok' if ok else '--'}] {name}")
+    if trace:
+        print(f"Last hook trace:\n  {trace}")
     log = home() / "logs" / "errors.log"
     if log.exists():
         tail = log.read_text(encoding="utf-8", errors="replace").splitlines()[-5:]
@@ -178,7 +275,6 @@ def build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", required=True)
 
     hook = sub.add_parser("hook", help="Handle a lifecycle hook (JSON on stdin); used by agent configs")
-    # No `choices`: argparse exits 2 on bad input, and exit code 2 means "block" to Claude Code and Codex.
     hook.add_argument("agent", help=", ".join(AGENT_CHOICES))
     hook.add_argument("event", nargs="?")
     hook.set_defaults(func=cmd_hook)
@@ -189,16 +285,20 @@ def build_parser() -> argparse.ArgumentParser:
 
     for name, func, text in (("approve", cmd_approve, "Enable capture for a project"),
                              ("revoke", cmd_revoke, "Disable capture for a project"),
-                             ("doctor", cmd_doctor, "Check installation and recent hook errors")):
+                             ("doctor", cmd_doctor, "Check installation, project resolution, and recent hook activity"),
+                             ("why", cmd_why, "Explain the latest OpenReflex execution decision"),
+                             ("trace", cmd_trace, "Show the latest execution decision timeline")):
         command = sub.add_parser(name, help=text)
         command.add_argument("--project")
         command.set_defaults(func=func)
 
-    install = sub.add_parser("install", help="Write project hook + MCP config for an agent and enable the project")
-    install.add_argument("agent", choices=AGENT_CHOICES)
-    install.add_argument("--project")
-    install.add_argument("--dry-run", action="store_true")
-    install.set_defaults(func=cmd_install)
+    for name, func, text in (("install", cmd_install, "Connect OpenReflex hooks + MCP for an agent"),
+                             ("uninstall", cmd_uninstall, "Disconnect OpenReflex hooks + MCP while preserving memory")):
+        command = sub.add_parser(name, help=text)
+        command.add_argument("agent", choices=AGENT_CHOICES)
+        command.add_argument("--project")
+        command.add_argument("--dry-run", action="store_true")
+        command.set_defaults(func=func)
 
     status = sub.add_parser("status", help="Show capture, reuse, regret, and routing metrics")
     status.add_argument("--project")
@@ -227,7 +327,6 @@ def main(argv: list[str] | None = None) -> int:
     _utf8_stdio()
     argv = sys.argv[1:] if argv is None else argv
     if argv[:1] == ["hook"]:
-        # Hook invocations must never fail loudly or return a blocking exit code, whatever the arguments.
         try:
             return cmd_hook(argparse.Namespace(agent=argv[1] if len(argv) > 1 else "", event=argv[2] if len(argv) > 2 else ""))
         except BaseException:  # noqa: BLE001

openreflex-0.3.1/src/openreflex/control.py

@@ -0,0 +1,108 @@
+"""Budget-aware execution control driven by the versioned OpenReflex policy."""
+
+import math
+from dataclasses import dataclass
+
+from .models import CandidatePath, Execution, ToolCall
+from .policy import Policy, load_policy
+from .privacy import PROGRESS
+from .routing import Budget, dominates, marginal_cost
+
+
+@dataclass(frozen=True)
+class Verdict:
+    action: str
+    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, epsilon: float) -> float:
+    probability = min(max(probability, epsilon), 1 - epsilon)
+    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(), policy: Policy | None = None) -> Verdict:
+    cfg = policy or load_policy()
+    values = cfg.table("control")
+    success_value = float(values["success_value"])
+    idle_likelihood = float(values["idle_likelihood_ratio"])
+    failure_likelihood = float(values["failure_likelihood_ratio"])
+    shared_failure_likelihood = float(values["shared_failure_likelihood_ratio"])
+    pivot_reuse = float(values["pivot_reuse"])
+    pivot_margin = float(values["pivot_margin"])
+    minimum_remaining = float(values["minimum_remaining"])
+    epsilon = float(values["probability_epsilon"])
+
+    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 float(values["fallback_success_probability"])
+    estimate = _update(prior, idle_likelihood ** idle * failure_likelihood ** failures, epsilon)
+    expected_calls = current.tool_calls if current else cfg.number("routing.budget.minimum_tool_calls")
+    remaining = max(expected_calls - len(calls), minimum_remaining * expected_calls) / max(expected_calls, 1.0)
+    value_continue = success_value * estimate - overrun * marginal_cost(
+        (current.time_seconds if current else cfg.number("routing.budget.minimum_seconds")) * remaining,
+        expected_calls * remaining,
+        (current.context_tokens if current else cfg.number("routing.budget.minimum_context_tokens")) * remaining,
+        cfg,
+    )
+
+    total_failures = sum(c.status == "failure" for c in finished)
+    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, cfg) for other in pool if other is not path):
+            continue
+        path_estimate = _update(path.success_probability, shared_failure_likelihood ** total_failures, epsilon)
+        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, cfg)
+        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]]:
+    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:
+    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