agent-mcts 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_mcts/__init__.py +3 -0
- agent_mcts/adapters/__init__.py +12 -0
- agent_mcts/adapters/base.py +54 -0
- agent_mcts/adapters/claude_code.py +164 -0
- agent_mcts/cli.py +223 -0
- agent_mcts/core/__init__.py +20 -0
- agent_mcts/core/engine.py +196 -0
- agent_mcts/core/journal.py +66 -0
- agent_mcts/core/model.py +109 -0
- agent_mcts/core/prompts.py +68 -0
- agent_mcts/core/value.py +76 -0
- agent_mcts/core/worktree.py +94 -0
- agent_mcts/project.py +110 -0
- agent_mcts/py.typed +0 -0
- agent_mcts/tui.py +88 -0
- agent_mcts-0.1.0.dist-info/METADATA +157 -0
- agent_mcts-0.1.0.dist-info/RECORD +20 -0
- agent_mcts-0.1.0.dist-info/WHEEL +4 -0
- agent_mcts-0.1.0.dist-info/entry_points.txt +2 -0
- agent_mcts-0.1.0.dist-info/licenses/LICENSE +21 -0
agent_mcts/__init__.py
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
"""Agent adapters: thin backends that let the search core drive a specific coding agent CLI."""
|
|
2
|
+
|
|
3
|
+
from agent_mcts.adapters.base import AdapterError, AgentBackend, EpisodeResult
|
|
4
|
+
from agent_mcts.adapters.claude_code import ClaudeCodeAdapter, find_claude_binary
|
|
5
|
+
|
|
6
|
+
__all__ = [
|
|
7
|
+
"AdapterError",
|
|
8
|
+
"AgentBackend",
|
|
9
|
+
"ClaudeCodeAdapter",
|
|
10
|
+
"EpisodeResult",
|
|
11
|
+
"find_claude_binary",
|
|
12
|
+
]
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
"""The contract between the search engine and any coding-agent CLI.
|
|
2
|
+
|
|
3
|
+
Implementing this protocol for a new agent is the primary way to extend agent-mcts:
|
|
4
|
+
the search core never imports a concrete adapter.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import Any, Protocol
|
|
11
|
+
|
|
12
|
+
from pydantic import BaseModel, Field
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class AdapterError(RuntimeError):
|
|
16
|
+
"""Infrastructure failure: binary missing, timeout, unparseable output.
|
|
17
|
+
|
|
18
|
+
Distinct from the *agent* reporting an error, which is a valid episode
|
|
19
|
+
result (`EpisodeResult.is_error`) — the engine scores those branches low
|
|
20
|
+
instead of crashing the run.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class EpisodeResult(BaseModel):
|
|
25
|
+
"""Outcome of one agent episode (one node expansion)."""
|
|
26
|
+
|
|
27
|
+
session_id: str
|
|
28
|
+
summary: str # the agent's final message
|
|
29
|
+
cost_usd: float = 0.0
|
|
30
|
+
duration_s: float = 0.0
|
|
31
|
+
is_error: bool = False
|
|
32
|
+
raw: dict[str, Any] = Field(default_factory=dict) # full agent-native payload
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class AgentBackend(Protocol):
|
|
36
|
+
"""A coding agent that can run one episode in a directory, optionally forking a session."""
|
|
37
|
+
|
|
38
|
+
@property
|
|
39
|
+
def name(self) -> str: ...
|
|
40
|
+
|
|
41
|
+
async def run_episode(
|
|
42
|
+
self,
|
|
43
|
+
prompt: str,
|
|
44
|
+
workdir: Path,
|
|
45
|
+
*,
|
|
46
|
+
resume_session: str | None = None,
|
|
47
|
+
) -> EpisodeResult:
|
|
48
|
+
"""Run the agent on `prompt` with `workdir` as its working tree.
|
|
49
|
+
|
|
50
|
+
`resume_session` forks the given session so the episode inherits its
|
|
51
|
+
conversation without mutating it. Raises `AdapterError` on
|
|
52
|
+
infrastructure failure.
|
|
53
|
+
"""
|
|
54
|
+
...
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
"""Claude Code adapter.
|
|
2
|
+
|
|
3
|
+
Mechanics validated in docs/spikes/2026-08-02-session-fork-worktree.md:
|
|
4
|
+
one episode = one `claude -p` call; forking = `--resume <id> --fork-session`,
|
|
5
|
+
which works from any cwd and at any depth.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import asyncio
|
|
11
|
+
import json
|
|
12
|
+
import os
|
|
13
|
+
import shutil
|
|
14
|
+
import subprocess
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
from typing import Any, cast
|
|
17
|
+
|
|
18
|
+
from agent_mcts.adapters.base import AdapterError, EpisodeResult
|
|
19
|
+
|
|
20
|
+
ENV_BINARY_OVERRIDE = "AGENT_MCTS_CLAUDE_BIN"
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _executes(binary: Path) -> bool:
|
|
24
|
+
"""A candidate counts only if `--version` actually runs — broken npm shims exist
|
|
25
|
+
in the wild (postinstall never ran) that are present but exit non-zero."""
|
|
26
|
+
try:
|
|
27
|
+
proc = subprocess.run(
|
|
28
|
+
[str(binary), "--version"], capture_output=True, timeout=20, check=False
|
|
29
|
+
)
|
|
30
|
+
except (OSError, subprocess.TimeoutExpired):
|
|
31
|
+
return False
|
|
32
|
+
return proc.returncode == 0
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _bundle_version_key(path: Path) -> tuple[int, ...]:
|
|
36
|
+
try:
|
|
37
|
+
return tuple(int(part) for part in path.name.split("."))
|
|
38
|
+
except ValueError:
|
|
39
|
+
return (0,)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def find_claude_binary() -> str:
|
|
43
|
+
"""Probe candidates in order and return the first that verifiably executes."""
|
|
44
|
+
candidates: list[Path] = []
|
|
45
|
+
override = os.environ.get(ENV_BINARY_OVERRIDE)
|
|
46
|
+
if override:
|
|
47
|
+
candidates.append(Path(override))
|
|
48
|
+
on_path = shutil.which("claude")
|
|
49
|
+
if on_path:
|
|
50
|
+
candidates.append(Path(on_path))
|
|
51
|
+
candidates.append(Path.home() / ".claude" / "local" / "claude")
|
|
52
|
+
bundle_root = Path.home() / "Library" / "Application Support" / "Claude" / "claude-code"
|
|
53
|
+
if bundle_root.is_dir():
|
|
54
|
+
for version_dir in sorted(bundle_root.iterdir(), key=_bundle_version_key, reverse=True):
|
|
55
|
+
candidates.append(version_dir / "claude.app" / "Contents" / "MacOS" / "claude")
|
|
56
|
+
|
|
57
|
+
for candidate in candidates:
|
|
58
|
+
if candidate.is_file() and _executes(candidate):
|
|
59
|
+
return str(candidate)
|
|
60
|
+
|
|
61
|
+
raise AdapterError(
|
|
62
|
+
"No working `claude` binary found. Install Claude Code "
|
|
63
|
+
"(https://claude.com/claude-code) or point "
|
|
64
|
+
f"{ENV_BINARY_OVERRIDE} at the binary. Note: a `claude` on PATH that "
|
|
65
|
+
"cannot run `claude --version` (e.g. an npm install whose postinstall "
|
|
66
|
+
"never ran) is skipped."
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
class ClaudeCodeAdapter:
|
|
71
|
+
"""Drives Claude Code headlessly; one `run_episode` call = one node expansion."""
|
|
72
|
+
|
|
73
|
+
def __init__(
|
|
74
|
+
self,
|
|
75
|
+
binary: str | None = None,
|
|
76
|
+
*,
|
|
77
|
+
model: str | None = None,
|
|
78
|
+
permission_mode: str = "acceptEdits",
|
|
79
|
+
timeout_s: float = 600.0,
|
|
80
|
+
) -> None:
|
|
81
|
+
self._binary = binary or find_claude_binary()
|
|
82
|
+
self.model = model
|
|
83
|
+
self.permission_mode = permission_mode
|
|
84
|
+
self.timeout_s = timeout_s
|
|
85
|
+
|
|
86
|
+
@property
|
|
87
|
+
def name(self) -> str:
|
|
88
|
+
return "claude"
|
|
89
|
+
|
|
90
|
+
async def run_episode(
|
|
91
|
+
self,
|
|
92
|
+
prompt: str,
|
|
93
|
+
workdir: Path,
|
|
94
|
+
*,
|
|
95
|
+
resume_session: str | None = None,
|
|
96
|
+
) -> EpisodeResult:
|
|
97
|
+
cmd = [
|
|
98
|
+
self._binary,
|
|
99
|
+
"-p",
|
|
100
|
+
"--output-format",
|
|
101
|
+
"json",
|
|
102
|
+
"--permission-mode",
|
|
103
|
+
self.permission_mode,
|
|
104
|
+
]
|
|
105
|
+
if self.model:
|
|
106
|
+
cmd += ["--model", self.model]
|
|
107
|
+
if resume_session:
|
|
108
|
+
cmd += ["--resume", resume_session, "--fork-session"]
|
|
109
|
+
cmd.append(prompt)
|
|
110
|
+
|
|
111
|
+
proc = await asyncio.create_subprocess_exec(
|
|
112
|
+
*cmd,
|
|
113
|
+
cwd=workdir,
|
|
114
|
+
stdout=asyncio.subprocess.PIPE,
|
|
115
|
+
stderr=asyncio.subprocess.PIPE,
|
|
116
|
+
)
|
|
117
|
+
try:
|
|
118
|
+
stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=self.timeout_s)
|
|
119
|
+
except TimeoutError:
|
|
120
|
+
proc.kill()
|
|
121
|
+
await proc.wait()
|
|
122
|
+
raise AdapterError(
|
|
123
|
+
f"claude episode timed out after {self.timeout_s:.0f}s in {workdir}"
|
|
124
|
+
) from None
|
|
125
|
+
|
|
126
|
+
payload = self._parse_payload(stdout)
|
|
127
|
+
if payload is None:
|
|
128
|
+
detail = (
|
|
129
|
+
stderr.decode(errors="replace").strip() or stdout.decode(errors="replace").strip()
|
|
130
|
+
)
|
|
131
|
+
raise AdapterError(
|
|
132
|
+
f"claude exited with code {proc.returncode} and no JSON payload: {detail[-2000:]}"
|
|
133
|
+
)
|
|
134
|
+
return self._to_result(payload, exit_code=proc.returncode)
|
|
135
|
+
|
|
136
|
+
@staticmethod
|
|
137
|
+
def _parse_payload(stdout: bytes) -> dict[str, Any] | None:
|
|
138
|
+
text = stdout.decode(errors="replace").strip()
|
|
139
|
+
if not text:
|
|
140
|
+
return None
|
|
141
|
+
try:
|
|
142
|
+
payload: Any = json.loads(text)
|
|
143
|
+
except json.JSONDecodeError:
|
|
144
|
+
return None
|
|
145
|
+
if not isinstance(payload, dict):
|
|
146
|
+
return None
|
|
147
|
+
return cast(dict[str, Any], payload)
|
|
148
|
+
|
|
149
|
+
@staticmethod
|
|
150
|
+
def _to_result(payload: dict[str, Any], *, exit_code: int | None) -> EpisodeResult:
|
|
151
|
+
session_id = payload.get("session_id")
|
|
152
|
+
if not isinstance(session_id, str) or not session_id:
|
|
153
|
+
raise AdapterError(f"claude payload has no session_id: {str(payload)[:500]}")
|
|
154
|
+
summary = payload.get("result")
|
|
155
|
+
cost = payload.get("total_cost_usd")
|
|
156
|
+
duration_ms = payload.get("duration_ms")
|
|
157
|
+
return EpisodeResult(
|
|
158
|
+
session_id=session_id,
|
|
159
|
+
summary=summary if isinstance(summary, str) else "",
|
|
160
|
+
cost_usd=float(cost) if isinstance(cost, int | float) else 0.0,
|
|
161
|
+
duration_s=float(duration_ms) / 1000.0 if isinstance(duration_ms, int | float) else 0.0,
|
|
162
|
+
is_error=bool(payload.get("is_error")) or exit_code != 0,
|
|
163
|
+
raw=payload,
|
|
164
|
+
)
|
agent_mcts/cli.py
ADDED
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
"""Command-line entry point: run / show / apply."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import subprocess
|
|
7
|
+
from datetime import datetime
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Annotated, NoReturn
|
|
10
|
+
|
|
11
|
+
import typer
|
|
12
|
+
from rich.console import Console
|
|
13
|
+
|
|
14
|
+
from agent_mcts import __version__, project, tui
|
|
15
|
+
from agent_mcts.adapters import AdapterError, ClaudeCodeAdapter
|
|
16
|
+
from agent_mcts.core import journal
|
|
17
|
+
from agent_mcts.core.engine import SearchEngine
|
|
18
|
+
from agent_mcts.core.model import RunMeta, Tree
|
|
19
|
+
from agent_mcts.core.value import CommandValueFunction
|
|
20
|
+
from agent_mcts.core.worktree import WorktreeManager
|
|
21
|
+
|
|
22
|
+
app = typer.Typer(
|
|
23
|
+
help="Turn any coding agent into a tree-searching agent.",
|
|
24
|
+
no_args_is_help=True,
|
|
25
|
+
)
|
|
26
|
+
console = Console()
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _fail(message: str) -> NoReturn:
|
|
30
|
+
console.print(f"[red]error:[/] {message}")
|
|
31
|
+
raise typer.Exit(code=1)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _version_callback(value: bool) -> None:
|
|
35
|
+
if value:
|
|
36
|
+
typer.echo(f"agent-mcts {__version__}")
|
|
37
|
+
raise typer.Exit()
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@app.callback()
|
|
41
|
+
def main(
|
|
42
|
+
version: Annotated[
|
|
43
|
+
bool,
|
|
44
|
+
typer.Option(
|
|
45
|
+
"--version",
|
|
46
|
+
callback=_version_callback,
|
|
47
|
+
is_eager=True,
|
|
48
|
+
help="Show version and exit.",
|
|
49
|
+
),
|
|
50
|
+
] = False,
|
|
51
|
+
) -> None:
|
|
52
|
+
"""agent-mcts — MCTS test-time search for coding agents."""
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@app.command()
|
|
56
|
+
def run(
|
|
57
|
+
task: Annotated[str, typer.Argument(help="The task to search a solution for.")],
|
|
58
|
+
max_nodes: Annotated[
|
|
59
|
+
int | None, typer.Option("-n", "--max-nodes", help="Episode budget.")
|
|
60
|
+
] = None,
|
|
61
|
+
max_cost: Annotated[
|
|
62
|
+
float | None, typer.Option("--max-cost", help="Cost ceiling in USD.")
|
|
63
|
+
] = None,
|
|
64
|
+
value: Annotated[
|
|
65
|
+
str | None,
|
|
66
|
+
typer.Option("--value", help="Value command (defaults to auto-detected tests)."),
|
|
67
|
+
] = None,
|
|
68
|
+
model: Annotated[str | None, typer.Option("--model", help="Agent model override.")] = None,
|
|
69
|
+
yes: Annotated[bool, typer.Option("-y", "--yes", help="Skip confirmations.")] = False,
|
|
70
|
+
) -> None:
|
|
71
|
+
"""Search for a solution to TASK with your coding agent."""
|
|
72
|
+
try:
|
|
73
|
+
repo = project.find_repo_root(Path.cwd())
|
|
74
|
+
cfg = project.load_project_config(repo)
|
|
75
|
+
except project.ProjectError as exc:
|
|
76
|
+
_fail(str(exc))
|
|
77
|
+
if max_nodes is not None:
|
|
78
|
+
cfg.search.max_nodes = max_nodes
|
|
79
|
+
if max_cost is not None:
|
|
80
|
+
cfg.search.max_cost_usd = max_cost
|
|
81
|
+
|
|
82
|
+
value_command = value or cfg.value.command or project.detect_value_command(repo)
|
|
83
|
+
if value_command is None:
|
|
84
|
+
_fail(
|
|
85
|
+
"could not detect a test command to use as the value function. "
|
|
86
|
+
f"Pass --value '<command>' or set [value].command in {project.CONFIG_FILENAME}."
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
try:
|
|
90
|
+
adapter = ClaudeCodeAdapter(model=model or cfg.model)
|
|
91
|
+
except AdapterError as exc:
|
|
92
|
+
_fail(str(exc))
|
|
93
|
+
|
|
94
|
+
if project.is_dirty(repo):
|
|
95
|
+
console.print(
|
|
96
|
+
"[yellow]warning:[/] uncommitted changes detected — the search branches "
|
|
97
|
+
"from HEAD and will not see them."
|
|
98
|
+
)
|
|
99
|
+
console.print(
|
|
100
|
+
f"Agent: [bold]{cfg.agent}[/] · Value: [bold]{value_command}[/] · "
|
|
101
|
+
f"Budget: [bold]{cfg.search.max_nodes}[/] nodes / ${cfg.search.max_cost_usd:.2f}"
|
|
102
|
+
)
|
|
103
|
+
if not yes:
|
|
104
|
+
typer.confirm("Proceed?", abort=True)
|
|
105
|
+
|
|
106
|
+
run_id = datetime.now().strftime("%Y%m%d-%H%M%S")
|
|
107
|
+
tree = Tree(
|
|
108
|
+
RunMeta(
|
|
109
|
+
run_id=run_id,
|
|
110
|
+
task=task,
|
|
111
|
+
agent=cfg.agent,
|
|
112
|
+
repo_root=str(repo),
|
|
113
|
+
base_commit=project.head_commit(repo),
|
|
114
|
+
)
|
|
115
|
+
)
|
|
116
|
+
worktrees = WorktreeManager(repo, run_id)
|
|
117
|
+
engine = SearchEngine(
|
|
118
|
+
tree=tree,
|
|
119
|
+
adapter=adapter,
|
|
120
|
+
value_fn=CommandValueFunction(value_command),
|
|
121
|
+
worktrees=worktrees,
|
|
122
|
+
journal_path=project.journal_path(repo, run_id),
|
|
123
|
+
config=cfg.search,
|
|
124
|
+
)
|
|
125
|
+
view = tui.LiveSearchView(engine, console)
|
|
126
|
+
engine.on_change = view.refresh
|
|
127
|
+
try:
|
|
128
|
+
with view:
|
|
129
|
+
asyncio.run(engine.run())
|
|
130
|
+
except KeyboardInterrupt:
|
|
131
|
+
console.print("\n[yellow]Interrupted[/] — the partial tree is saved and usable.")
|
|
132
|
+
finally:
|
|
133
|
+
worktrees.cleanup()
|
|
134
|
+
|
|
135
|
+
console.print(
|
|
136
|
+
f"\nSearch finished: {engine.episodes} episodes, "
|
|
137
|
+
f"${engine.total_cost_usd:.2f} · run {run_id}"
|
|
138
|
+
)
|
|
139
|
+
best = tree.best()
|
|
140
|
+
if best is None or best.parent_id is None:
|
|
141
|
+
console.print("No attempt beat the baseline. Inspect with: [bold]agent-mcts show[/]")
|
|
142
|
+
else:
|
|
143
|
+
reward = best.reward if best.reward is not None else 0.0
|
|
144
|
+
summary = best.summary.splitlines()[0][:80] if best.summary else ""
|
|
145
|
+
console.print(f"Best: [bold]{best.id}[/] reward={reward:.2f} {summary}")
|
|
146
|
+
console.print("Next: [bold]agent-mcts show[/] · [bold]agent-mcts apply[/]")
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _load_tree(run_id: str | None) -> Tree:
|
|
150
|
+
try:
|
|
151
|
+
repo = project.find_repo_root(Path.cwd())
|
|
152
|
+
except project.ProjectError as exc:
|
|
153
|
+
_fail(str(exc))
|
|
154
|
+
resolved = run_id or project.latest_run_id(repo)
|
|
155
|
+
if resolved is None:
|
|
156
|
+
_fail('no runs found. Start one with: agent-mcts run "<task>"')
|
|
157
|
+
path = project.journal_path(repo, resolved)
|
|
158
|
+
if not path.exists():
|
|
159
|
+
_fail(f"run {resolved} has no journal at {path}")
|
|
160
|
+
return journal.load(path)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
@app.command()
|
|
164
|
+
def show(
|
|
165
|
+
node: Annotated[str | None, typer.Argument(help="Node id for details (e.g. n3).")] = None,
|
|
166
|
+
run_id: Annotated[str | None, typer.Option("--run", help="Run id (default: latest).")] = None,
|
|
167
|
+
) -> None:
|
|
168
|
+
"""Show the search tree of a run, or one node's full details."""
|
|
169
|
+
tree = _load_tree(run_id)
|
|
170
|
+
if node is None:
|
|
171
|
+
console.print(f"task: {tree.meta.task} · run {tree.meta.run_id}")
|
|
172
|
+
console.print(tui.render_tree(tree))
|
|
173
|
+
return
|
|
174
|
+
found = tree.nodes.get(node)
|
|
175
|
+
if found is None:
|
|
176
|
+
_fail(f"no node {node} in run {tree.meta.run_id}")
|
|
177
|
+
status = f"{found.status.value} reward={found.reward} Q={found.q:.2f} N={found.visits}"
|
|
178
|
+
for title, body in (
|
|
179
|
+
("status", status),
|
|
180
|
+
("branch", found.branch or "-"),
|
|
181
|
+
("session", found.session_id or "-"),
|
|
182
|
+
("cost", f"${found.cost_usd:.2f} in {found.duration_s:.0f}s"),
|
|
183
|
+
("prompt", found.prompt or "-"),
|
|
184
|
+
("summary", found.summary or "-"),
|
|
185
|
+
("evaluation", found.eval_detail or "-"),
|
|
186
|
+
):
|
|
187
|
+
console.print(f"[bold]{title}[/]: {body}")
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
@app.command()
|
|
191
|
+
def apply(
|
|
192
|
+
node: Annotated[
|
|
193
|
+
str | None, typer.Argument(help="Node id to apply (default: the best node).")
|
|
194
|
+
] = None,
|
|
195
|
+
run_id: Annotated[str | None, typer.Option("--run", help="Run id (default: latest).")] = None,
|
|
196
|
+
) -> None:
|
|
197
|
+
"""Stage a node's changes onto your working tree (squash merge — you commit)."""
|
|
198
|
+
tree = _load_tree(run_id)
|
|
199
|
+
target = tree.nodes.get(node) if node is not None else tree.best()
|
|
200
|
+
if target is None:
|
|
201
|
+
_fail(f"no node {node} in run {tree.meta.run_id}" if node else "run has no scored nodes")
|
|
202
|
+
if target.parent_id is None:
|
|
203
|
+
_fail("the best node is the untouched baseline — nothing to apply")
|
|
204
|
+
if target.branch is None:
|
|
205
|
+
_fail(f"node {target.id} has no snapshot branch (it failed before committing)")
|
|
206
|
+
|
|
207
|
+
repo = Path(tree.meta.repo_root)
|
|
208
|
+
if project.is_dirty(repo):
|
|
209
|
+
_fail("your working tree has uncommitted changes; commit or stash before applying")
|
|
210
|
+
proc = subprocess.run(
|
|
211
|
+
["git", "merge", "--squash", target.branch],
|
|
212
|
+
cwd=repo,
|
|
213
|
+
capture_output=True,
|
|
214
|
+
text=True,
|
|
215
|
+
check=False,
|
|
216
|
+
)
|
|
217
|
+
if proc.returncode != 0:
|
|
218
|
+
_fail(f"squash merge of {target.branch} failed:\n{proc.stdout}{proc.stderr}")
|
|
219
|
+
reward = target.reward if target.reward is not None else 0.0
|
|
220
|
+
console.print(
|
|
221
|
+
f"Staged [bold]{target.id}[/] (reward={reward:.2f}) from {target.branch}.\n"
|
|
222
|
+
"Review with [bold]git diff --cached[/] and commit when happy."
|
|
223
|
+
)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""Agent-agnostic search core: data model, journal, worktrees, value functions, UCT engine."""
|
|
2
|
+
|
|
3
|
+
from agent_mcts.core.engine import SearchConfig, SearchEngine
|
|
4
|
+
from agent_mcts.core.model import Node, NodeStatus, RunMeta, Tree
|
|
5
|
+
from agent_mcts.core.value import CommandValueFunction, Evaluation, ValueFunction
|
|
6
|
+
from agent_mcts.core.worktree import GitError, WorktreeManager
|
|
7
|
+
|
|
8
|
+
__all__ = [
|
|
9
|
+
"CommandValueFunction",
|
|
10
|
+
"Evaluation",
|
|
11
|
+
"GitError",
|
|
12
|
+
"Node",
|
|
13
|
+
"NodeStatus",
|
|
14
|
+
"RunMeta",
|
|
15
|
+
"SearchConfig",
|
|
16
|
+
"SearchEngine",
|
|
17
|
+
"Tree",
|
|
18
|
+
"ValueFunction",
|
|
19
|
+
"WorktreeManager",
|
|
20
|
+
]
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
"""The UCT search loop: wires an agent adapter, worktrees, a value function, and the journal.
|
|
2
|
+
|
|
3
|
+
Policy summary (see docs/design.md):
|
|
4
|
+
- one node expansion = one complete agent episode over an isolated worktree
|
|
5
|
+
- expand-first with fixed widths (root_width diverse attempts, refine_width revisions)
|
|
6
|
+
- UCT descent with c = sqrt(2) by default; failed episodes back up 0
|
|
7
|
+
- anytime: every state change is journaled, so Ctrl-C leaves a valid tree
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import math
|
|
13
|
+
from collections.abc import Callable
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
|
|
16
|
+
from pydantic import BaseModel
|
|
17
|
+
|
|
18
|
+
from agent_mcts.adapters.base import AdapterError, AgentBackend
|
|
19
|
+
from agent_mcts.core import journal, prompts
|
|
20
|
+
from agent_mcts.core.model import Node, NodeStatus, Tree
|
|
21
|
+
from agent_mcts.core.value import ValueFunction
|
|
22
|
+
from agent_mcts.core.worktree import WorktreeManager
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class SearchConfig(BaseModel):
|
|
26
|
+
max_nodes: int = 12 # episode budget (the root baseline is not an episode)
|
|
27
|
+
max_cost_usd: float = 10.0
|
|
28
|
+
c_uct: float = 1.414 # sqrt(2), the classic UCT exploration constant
|
|
29
|
+
root_width: int = 3 # diverse first attempts under the root
|
|
30
|
+
refine_width: int = 2 # revision children per non-root node
|
|
31
|
+
max_depth: int = 3 # root is depth 0
|
|
32
|
+
success_threshold: float = 0.999 # stop as soon as a node scores this high
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class SearchEngine:
|
|
36
|
+
"""Runs one search. Sequential in v0.1; parallel expansion is roadmapped."""
|
|
37
|
+
|
|
38
|
+
def __init__(
|
|
39
|
+
self,
|
|
40
|
+
*,
|
|
41
|
+
tree: Tree,
|
|
42
|
+
adapter: AgentBackend,
|
|
43
|
+
value_fn: ValueFunction,
|
|
44
|
+
worktrees: WorktreeManager,
|
|
45
|
+
journal_path: Path,
|
|
46
|
+
config: SearchConfig | None = None,
|
|
47
|
+
on_change: Callable[[], None] | None = None,
|
|
48
|
+
) -> None:
|
|
49
|
+
self.tree = tree
|
|
50
|
+
self.adapter = adapter
|
|
51
|
+
self.value_fn = value_fn
|
|
52
|
+
self.worktrees = worktrees
|
|
53
|
+
self.journal_path = journal_path
|
|
54
|
+
self.config = config or SearchConfig()
|
|
55
|
+
self.on_change = on_change # reassignable: the live TUI attaches itself here
|
|
56
|
+
|
|
57
|
+
@property
|
|
58
|
+
def total_cost_usd(self) -> float:
|
|
59
|
+
return sum(n.cost_usd for n in self.tree.nodes.values())
|
|
60
|
+
|
|
61
|
+
@property
|
|
62
|
+
def episodes(self) -> int:
|
|
63
|
+
return max(0, len(self.tree.nodes) - 1)
|
|
64
|
+
|
|
65
|
+
async def run(self) -> Tree:
|
|
66
|
+
if self.tree.root is None:
|
|
67
|
+
await self._init_root()
|
|
68
|
+
while self._within_budget():
|
|
69
|
+
parent = self._select()
|
|
70
|
+
if parent is None:
|
|
71
|
+
break # every node is at width/depth capacity
|
|
72
|
+
node = await self._expand(parent)
|
|
73
|
+
if (
|
|
74
|
+
node.status is NodeStatus.EVALUATED
|
|
75
|
+
and (node.reward or 0.0) >= self.config.success_threshold
|
|
76
|
+
):
|
|
77
|
+
break
|
|
78
|
+
return self.tree
|
|
79
|
+
|
|
80
|
+
# -- setup ---------------------------------------------------------------
|
|
81
|
+
|
|
82
|
+
async def _init_root(self) -> None:
|
|
83
|
+
journal.append_meta(self.journal_path, self.tree.meta)
|
|
84
|
+
root = self.tree.add(Node(id=self.tree.next_id(), status=NodeStatus.RUNNING))
|
|
85
|
+
self._journal([root])
|
|
86
|
+
|
|
87
|
+
self.worktrees.create(root.id)
|
|
88
|
+
root.branch = self.worktrees.branch_name(root.id)
|
|
89
|
+
evaluation = await self.value_fn.evaluate(self.worktrees.worktree_path(root.id))
|
|
90
|
+
root.reward = evaluation.score
|
|
91
|
+
root.eval_detail = evaluation.detail
|
|
92
|
+
root.status = NodeStatus.EVALUATED
|
|
93
|
+
self.tree.backup(root.id, evaluation.score)
|
|
94
|
+
self._journal([root])
|
|
95
|
+
|
|
96
|
+
# -- selection -----------------------------------------------------------
|
|
97
|
+
|
|
98
|
+
def _width(self, node: Node) -> int:
|
|
99
|
+
return self.config.root_width if node.parent_id is None else self.config.refine_width
|
|
100
|
+
|
|
101
|
+
def _depth(self, node: Node) -> int:
|
|
102
|
+
return len(self.tree.path(node.id)) - 1
|
|
103
|
+
|
|
104
|
+
def _can_expand(self, node: Node) -> bool:
|
|
105
|
+
return (
|
|
106
|
+
node.status is NodeStatus.EVALUATED
|
|
107
|
+
and self._depth(node) < self.config.max_depth
|
|
108
|
+
and len(self.tree.children(node.id)) < self._width(node)
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
def _subtree_has_capacity(self, node: Node) -> bool:
|
|
112
|
+
if self._can_expand(node):
|
|
113
|
+
return True
|
|
114
|
+
return any(self._subtree_has_capacity(c) for c in self.tree.children(node.id))
|
|
115
|
+
|
|
116
|
+
def _uct(self, parent: Node, child: Node) -> float:
|
|
117
|
+
explore = math.sqrt(math.log(max(parent.visits, 1)) / child.visits)
|
|
118
|
+
return child.q + self.config.c_uct * explore
|
|
119
|
+
|
|
120
|
+
def _select(self) -> Node | None:
|
|
121
|
+
"""Descend from the root; expand at the first node with spare width."""
|
|
122
|
+
root = self.tree.root
|
|
123
|
+
if root is None:
|
|
124
|
+
return None
|
|
125
|
+
node: Node = root
|
|
126
|
+
while True:
|
|
127
|
+
if self._can_expand(node):
|
|
128
|
+
return node
|
|
129
|
+
viable = [c for c in self.tree.children(node.id) if self._subtree_has_capacity(c)]
|
|
130
|
+
if not viable:
|
|
131
|
+
return None
|
|
132
|
+
parent = node
|
|
133
|
+
node = max(viable, key=lambda c: self._uct(parent, c))
|
|
134
|
+
|
|
135
|
+
# -- expansion -----------------------------------------------------------
|
|
136
|
+
|
|
137
|
+
async def _expand(self, parent: Node) -> Node:
|
|
138
|
+
siblings = [c.summary for c in self.tree.children(parent.id)]
|
|
139
|
+
if parent.parent_id is None:
|
|
140
|
+
prompt = prompts.root_attempt_prompt(self.tree.meta.task, parent.eval_detail, siblings)
|
|
141
|
+
else:
|
|
142
|
+
prompt = prompts.revision_prompt(
|
|
143
|
+
self.tree.meta.task, parent.reward or 0.0, parent.eval_detail, siblings
|
|
144
|
+
)
|
|
145
|
+
|
|
146
|
+
node = self.tree.add(
|
|
147
|
+
Node(
|
|
148
|
+
id=self.tree.next_id(),
|
|
149
|
+
parent_id=parent.id,
|
|
150
|
+
status=NodeStatus.RUNNING,
|
|
151
|
+
prompt=prompt,
|
|
152
|
+
)
|
|
153
|
+
)
|
|
154
|
+
self._journal([node])
|
|
155
|
+
|
|
156
|
+
workdir = self.worktrees.create(node.id, base=parent.branch)
|
|
157
|
+
try:
|
|
158
|
+
result = await self.adapter.run_episode(
|
|
159
|
+
prompt, workdir, resume_session=parent.session_id
|
|
160
|
+
)
|
|
161
|
+
node.session_id = result.session_id
|
|
162
|
+
node.summary = result.summary
|
|
163
|
+
node.cost_usd = result.cost_usd
|
|
164
|
+
node.duration_s = result.duration_s
|
|
165
|
+
if result.is_error:
|
|
166
|
+
node.status = NodeStatus.FAILED
|
|
167
|
+
node.reward = 0.0
|
|
168
|
+
node.eval_detail = f"agent reported an error: {result.summary}"
|
|
169
|
+
else:
|
|
170
|
+
self.worktrees.commit_all(node.id)
|
|
171
|
+
node.branch = self.worktrees.branch_name(node.id)
|
|
172
|
+
evaluation = await self.value_fn.evaluate(workdir)
|
|
173
|
+
node.reward = evaluation.score
|
|
174
|
+
node.eval_detail = evaluation.detail
|
|
175
|
+
node.status = NodeStatus.EVALUATED
|
|
176
|
+
except AdapterError as exc:
|
|
177
|
+
node.status = NodeStatus.FAILED
|
|
178
|
+
node.reward = 0.0
|
|
179
|
+
node.eval_detail = str(exc)
|
|
180
|
+
|
|
181
|
+
updated = self.tree.backup(node.id, node.reward or 0.0)
|
|
182
|
+
self._journal(updated)
|
|
183
|
+
return node
|
|
184
|
+
|
|
185
|
+
# -- bookkeeping ----------------------------------------------------------
|
|
186
|
+
|
|
187
|
+
def _within_budget(self) -> bool:
|
|
188
|
+
return (
|
|
189
|
+
self.episodes < self.config.max_nodes and self.total_cost_usd < self.config.max_cost_usd
|
|
190
|
+
)
|
|
191
|
+
|
|
192
|
+
def _journal(self, nodes: list[Node]) -> None:
|
|
193
|
+
for node in nodes:
|
|
194
|
+
journal.append_node(self.journal_path, node)
|
|
195
|
+
if self.on_change is not None:
|
|
196
|
+
self.on_change()
|