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 ADDED
@@ -0,0 +1,3 @@
1
+ """agent-mcts — turn any coding agent into a tree-searching agent."""
2
+
3
+ __version__ = "0.1.0"
@@ -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()