aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/runtime/tool_executor.py

@@ -0,0 +1,329 @@
+"""Tool execution layer for Aria Code runtimes."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, Mapping, Optional
+
+from .approval import ApprovalDecision, apply_approval_decision
+from .events import RuntimeTrace, ToolCallRecord
+
+ToolHandler = Callable[[dict], dict]
+RemoteExecutor = Callable[[str, dict], Awaitable[dict]]
+Hook = Callable[[str, str, dict, Optional[dict]], None]
+ExecutionContextProvider = Callable[[], Mapping[str, Any]]
+
+
+class ToolExecutor:
+    """Execute local/remote tools with hooks, policy injection, and trace records."""
+
+    def __init__(
+        self,
+        local_tools: Mapping[str, tuple],
+        *,
+        remote_executor: RemoteExecutor | None = None,
+        hook: Hook | None = None,
+        trace: RuntimeTrace | None = None,
+        config: Dict[str, Any] | None = None,
+        execution_context: ExecutionContextProvider | None = None,
+    ) -> None:
+        self.local_tools = local_tools
+        self.remote_executor = remote_executor
+        self.hook = hook
+        self.trace = trace or RuntimeTrace()
+        self.config = config or {}
+        self.execution_context = execution_context
+
+    def execute_local(
+        self, tool_name: str, params: dict, *, approval: ApprovalDecision | None = None
+    ) -> dict:
+        """Execute a local tool synchronously."""
+        if "_agent_allowed_tools" in self.config and tool_name not in self.config["_agent_allowed_tools"]:
+            return {"success": False, "error": "Tool is outside this agent role’s allowed capabilities."}
+        if self.config.get("_conversation_only"):
+            return {"success": False, "error": "This is a standalone conversational request. Reply directly without tools or file inspection."}
+        if tool_name not in self.local_tools:
+            return {"success": False, "error": f"Unknown local tool: {tool_name}"}
+        if approval is not None and not approval.approved:
+            reason = approval.reason or "Tool approval denied."
+            self.trace.emit("tool_denied", {"tool": tool_name, "reason": reason})
+            return {"success": False, "error": reason}
+        handler = self.local_tools[tool_name][0]
+        params = self._prepare_params(
+            tool_name,
+            params,
+            include_execution_context=True,
+            bind_research_context=True,
+            approval=approval,
+        )
+        context_error = params.pop("_execution_context_error", None)
+        if context_error:
+            result = {"success": False, "error": context_error}
+            self.trace.emit("tool_denied", {"tool": tool_name, "reason": context_error})
+            return result
+        return self._call_with_trace(tool_name, params, lambda: handler(params))
+
+    async def execute(self, tool_name: str, params: dict) -> dict:
+        """Execute a tool asynchronously, using remote executor when needed."""
+        if "_agent_allowed_tools" in self.config and tool_name not in self.config["_agent_allowed_tools"]:
+            return {"success": False, "error": "Tool is outside this agent role’s allowed capabilities."}
+        if self.config.get("_conversation_only"):
+            return {"success": False, "error": "This is a standalone conversational request. Reply directly without tools or file inspection."}
+        if tool_name in self.local_tools:
+            # Scheduler operations must remain on the active event loop. A worker
+            # thread cannot create a durable background coroutine on this loop.
+            if tool_name in {"spawn_task", "task_cancel", "task_status", "task_result", "task_list", "list_agents"}:
+                return self.execute_local(tool_name, params)
+            loop = asyncio.get_event_loop()
+            return await loop.run_in_executor(None, self.execute_local, tool_name, params)
+        if self.remote_executor is None:
+            return {"success": False, "error": f"Unknown tool: {tool_name}"}
+        params = self._prepare_params(tool_name, params, bind_research_context=True)
+        start = time.time()
+        self._run_hook("pre_tool", tool_name, params)
+        self.trace.emit("tool_call", {"tool": tool_name, "params": params})
+        try:
+            result = await self.remote_executor(tool_name, params)
+        except Exception as exc:
+            result = {"success": False, "error": str(exc)}
+        observable = {key: value for key, value in result.items() if key != "_vision_image"}
+        self._run_hook("post_tool", tool_name, params, observable)
+        end = time.time()
+        self.trace.add_tool_call(ToolCallRecord(
+            tool=tool_name,
+            params=params,
+            result=observable,
+            elapsed_ms=(end - start) * 1000,
+            started_at=start,
+            ended_at=end,
+        ))
+        return result
+
+    def _call_with_trace(self, tool_name: str, params: dict, fn: Callable[[], dict]) -> dict:
+        start = time.time()
+        self._run_hook("pre_tool", tool_name, params)
+        self.trace.emit("tool_call", {"tool": tool_name, "params": params})
+        try:
+            result = fn()
+        except Exception as exc:
+            result = {"success": False, "error": str(exc)}
+        observable = {key: value for key, value in result.items() if key != "_vision_image"}
+        self._run_hook("post_tool", tool_name, params, observable)
+        end = time.time()
+        self.trace.add_tool_call(ToolCallRecord(
+            tool=tool_name,
+            params=params,
+            result=observable,
+            elapsed_ms=(end - start) * 1000,
+            started_at=start,
+            ended_at=end,
+        ))
+        return result
+
+    def _prepare_params(
+        self,
+        tool_name: str,
+        params: dict,
+        *,
+        include_execution_context: bool = False,
+        bind_research_context: bool = False,
+        approval: ApprovalDecision | None = None,
+    ) -> dict:
+        prepared = dict(params or {})
+        # A model cannot grant itself directories or replace the host workspace.
+        for key in tuple(prepared):
+            if key.startswith("_"):
+                prepared.pop(key)
+        if tool_name == "analyze_financial_statements":
+            prepared["network_enabled"] = bool(self.config.get("network_enabled", True))
+        if tool_name == "run_command":
+            # Tool arguments come from the model. Only the host configuration and
+            # a typed approval decision may set execution controls.
+            for key in (
+                "policy", "permission_mode", "network_enabled",
+                "user_approved", "_upgrade_policy", "sandbox", "os_sandbox",
+            ):
+                prepared.pop(key, None)
+        workspace_tools = {"read_file", "write_file", "edit_file", "multi_edit", "list_files",
+                           "search_code", "glob", "analyze_file", "notebook_read", "notebook_edit",
+                           "apply_patch", "run_command", "github", "spawn_task", "list_task_context"}
+        context = {
+            "_workspace": self.config.get("_session_workspace_root") or self.config.get("workspace_root") or str(Path.cwd()),
+            "_allowed_read_roots": [*(self.config.get("read_roots") or ()), *(self.config.get("_session_read_roots") or ())],
+            "_allowed_write_roots": [*(self.config.get("write_roots") or ()), *(self.config.get("_session_write_roots") or ())],
+            "_permission_mode": self.config.get("permission_mode", "workspace-write"),
+        } if tool_name in workspace_tools else {}
+        if self.execution_context is not None and (
+            include_execution_context or bind_research_context
+        ):
+            try:
+                context.update(dict(self.execution_context() or {}))
+                if bind_research_context:
+                    self._bind_research_run(tool_name, prepared, context)
+            except Exception as exc:
+                if include_execution_context:
+                    prepared["_execution_context_error"] = (
+                        f"Execution context unavailable: {exc}"
+                    )
+        if include_execution_context:
+            for key, value in context.items():
+                if key.startswith("_") and value is not None:
+                    prepared[key] = value
+            self._bind_workspace(tool_name, prepared, context)
+            self._check_file_permission(tool_name, prepared)
+            if tool_name in {"write_file", "edit_file", "multi_edit", "notebook_edit"}:
+                if approval is not None and approval.approved:
+                    prepared["_skip_confirm"] = True
+        if tool_name in {"spawn_task", "list_task_context"}:
+            prepared["_task_context_enabled"] = bool(self.config.get("task_context_enabled", True))
+            prepared["_session_id"] = str(context.get("_session_id") or self.config.get("last_session_id") or "")
+        if tool_name == "spawn_task":
+            prepared["_parent_permission_mode"] = self.config.get("permission_mode", "workspace-write")
+        if tool_name == "warehouse_task":
+            # Tool arguments cannot select another conversation or permission mode.
+            session = context.get("_session_id") or self.config.get("last_session_id")
+            prepared["_warehouse_scope"] = str(session or "")
+            prepared["_warehouse_read_only"] = self.config.get("permission_mode") in {"read-only", "readonly", "read_only", "plan"}
+        if tool_name == "run_command":
+            prepared["policy"] = self.config.get("command_policy", "safe")
+            prepared["permission_mode"] = self.config.get("permission_mode", "workspace-write")
+            prepared["network_enabled"] = bool(self.config.get("network_enabled", True))
+            prepared["sandbox"] = bool(self.config.get("command_sandbox", False))
+            prepared["os_sandbox"] = self.config.get("os_sandbox", "auto")
+            if approval is not None and approval.approved:
+                apply_approval_decision(prepared, approval)
+        return prepared
+
+    def _check_file_permission(self, tool_name: str, prepared: dict) -> None:
+        if prepared.get("_execution_context_error"):
+            return
+        from aria_code.workspace.files import WorkspaceSecurity
+        write_tools = {"write_file", "edit_file", "multi_edit", "apply_patch", "notebook_edit"}
+        read_tools = {"read_file", "list_files", "search_code", "glob", "analyze_file", "notebook_read"}
+        canonical = tool_name.rsplit("__", 1)[-1]
+        mode = str(self.config.get("permission_mode", "workspace-write"))
+        if canonical in write_tools and mode in {"read-only", "readonly", "read_only", "plan"}:
+            prepared["_execution_context_error"] = "Writes are blocked in read-only mode."
+            return
+        if canonical not in write_tools | read_tools or mode == "full-access":
+            return
+        security = WorkspaceSecurity.from_tool_params(prepared)
+        try:
+            security.require_safe(
+                prepared.get("root" if canonical == "glob" else "path") or ".",
+                write=canonical in write_tools,
+            )
+        except PermissionError as exc:
+            prepared["_execution_context_error"] = (
+                f"{exc}. Add --add-dir for writes or --read-dir for reads."
+            )
+
+    @staticmethod
+    def _bind_research_run(
+        tool_name: str,
+        prepared: dict,
+        context: Mapping[str, Any],
+    ) -> None:
+        """Correlate an institutional research run with its upstream Aria run."""
+        canonical_name = str(tool_name).rsplit("__", 1)[-1]
+        if canonical_name != "research_run_create":
+            return
+        control_run_id = context.get("_run_id")
+        trace_id = context.get("_trace_id") or control_run_id
+        if control_run_id:
+            prepared.setdefault("control_run_id", str(control_run_id))
+        if trace_id:
+            prepared.setdefault("trace_id", str(trace_id))
+
+    @staticmethod
+    def _bind_workspace(tool_name: str, prepared: dict, context: Mapping[str, Any]) -> None:
+        workspace_value = context.get("_workspace")
+        if not workspace_value:
+            return
+        workspace = Path(str(workspace_value)).expanduser().resolve()
+        restricted = bool(context.get("_workspace_restricted", False))
+        # A task worktree stands in for the repository it was made from. The
+        # model still sees that repository's paths — in the project context,
+        # in earlier turns — so a path into it is taken to mean the same file
+        # in the worktree, and the user's own copy is never written.
+        origins = _origins(context.get("_workspace_origin"), workspace)
+        path_tools = {
+            "read_file",
+            "write_file",
+            "edit_file",
+            "multi_edit",
+            "list_files",
+            "search_code",
+            "glob",
+            "analyze_file",
+            "notebook_read",
+            "notebook_edit",
+        }
+        if tool_name in path_tools:
+            path_key = "root" if tool_name == "glob" else "path"
+            raw_path = str(prepared.get(path_key) or ".")
+            target = Path(raw_path).expanduser()
+            if not target.is_absolute():
+                target = workspace / target
+            target = _into_workspace(target.resolve(), origins, workspace)
+            if restricted and not target.is_relative_to(workspace):
+                prepared["_execution_context_error"] = (
+                    f"Tool path is outside the isolated workspace: {target}"
+                )
+                return
+            prepared[path_key] = str(target)
+        if tool_name in {"run_command", "github"}:
+            raw_cwd = str(prepared.get("cwd") or workspace)
+            cwd = Path(raw_cwd).expanduser()
+            if not cwd.is_absolute():
+                cwd = workspace / cwd
+            cwd = _into_workspace(cwd.resolve(), origins, workspace)
+            if origins and prepared.get("command"):
+                prepared["command"] = _rebase_command(str(prepared["command"]), origins, workspace)
+            if restricted and not cwd.is_relative_to(workspace):
+                prepared["_execution_context_error"] = (
+                    f"Command cwd is outside the isolated workspace: {cwd}"
+                )
+                return
+            prepared["cwd"] = str(cwd)
+
+    def _run_hook(self, hook_type: str, tool_name: str, params: dict, result: dict | None = None) -> None:
+        if self.hook is None:
+            return
+        try:
+            self.hook(hook_type, tool_name, params, result)
+        except Exception:
+            pass
+
+
+def _origins(value: Any, workspace: Path) -> tuple[Path, ...]:
+    """The origin repository as written and as resolved, unless it is the workspace."""
+    if not value:
+        return ()
+    raw = Path(str(value)).expanduser()
+    found = []
+    for candidate in (raw, raw.resolve()):
+        if candidate != workspace and candidate not in found:
+            found.append(candidate)
+    return tuple(found)
+
+
+def _into_workspace(target: Path, origins: tuple[Path, ...], workspace: Path) -> Path:
+    if target.is_relative_to(workspace):
+        return target
+    for origin in origins:
+        if target.is_relative_to(origin):
+            return workspace / target.relative_to(origin)
+    return target
+
+
+def _rebase_command(command: str, origins: tuple[Path, ...], workspace: Path) -> str:
+    """Point absolute paths into the origin at the worktree: ``cd /repo && …``."""
+    for origin in sorted(origins, key=lambda path: len(str(path)), reverse=True):
+        pattern = re.escape(str(origin)) + r"(?=[/\s'\"`;:)|&]|$)"
+        command = re.sub(pattern, lambda _match: str(workspace), command)
+    return command
+

aria_code/runtime/tool_policy.py

@@ -0,0 +1,107 @@
+"""Persistent per-tool execution policy: allowlist, denylist, ask-always.
+
+Stores policy in ~/.arthera/tool_policy.json.
+Checked in _confirm_tool_execution_decision() before any user prompt.
+
+Usage:
+    from runtime.tool_policy import check_tool_policy, add_to_policy
+
+    verdict = check_tool_policy("write_file")  # "allow" | "deny" | "ask" | "default"
+    add_to_policy("read_file", "allow")         # permanently auto-approve
+    add_to_policy("run_command", "deny")        # permanently block
+    add_to_policy("edit_file", "ask")           # always prompt
+    remove_from_policy("read_file")             # remove from all lists
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+from aria_code.packages.aria_core.paths import aria_home
+
+PolicyVerdict = Literal["allow", "deny", "ask", "default"]
+
+_DEFAULT_POLICY: dict = {
+    "allowed": [],     # auto-approve without prompt
+    "denied": [],      # always block, never execute
+    "ask_always": [],  # always prompt even for non-CONFIRM_TOOLS
+}
+
+
+def _policy_file() -> Path:
+    return aria_home() / "tool_policy.json"
+
+
+def load_tool_policy() -> dict:
+    """Load policy from disk; returns defaults if missing or corrupt."""
+    f = _policy_file()
+    if f.exists():
+        try:
+            raw = json.loads(f.read_text(encoding="utf-8"))
+            return {
+                "allowed":    list(raw.get("allowed", [])),
+                "denied":     list(raw.get("denied", [])),
+                "ask_always": list(raw.get("ask_always", [])),
+            }
+        except Exception:
+            pass
+    return {k: list(v) for k, v in _DEFAULT_POLICY.items()}
+
+
+def save_tool_policy(policy: dict) -> None:
+    f = _policy_file()
+    f.parent.mkdir(parents=True, exist_ok=True)
+    f.write_text(json.dumps(policy, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def check_tool_policy(tool_name: str) -> PolicyVerdict:
+    """Return the persistent verdict for *tool_name*.
+
+    "allow"   → auto-approve, skip confirmation prompt
+    "deny"    → block, never execute
+    "ask"     → always prompt (overrides session auto-allow)
+    "default" → no override, fall through to normal flow
+    """
+    policy = load_tool_policy()
+    if tool_name in policy.get("denied", []):
+        return "deny"
+    if tool_name in policy.get("allowed", []):
+        return "allow"
+    if tool_name in policy.get("ask_always", []):
+        return "ask"
+    return "default"
+
+
+def add_to_policy(tool_name: str, verdict: Literal["allow", "deny", "ask"]) -> None:
+    """Add *tool_name* to the given policy list, removing it from any other list first."""
+    policy = load_tool_policy()
+    for key in ("allowed", "denied", "ask_always"):
+        policy.setdefault(key, [])
+        if tool_name in policy[key]:
+            policy[key].remove(tool_name)
+    if verdict == "allow":
+        policy["allowed"].append(tool_name)
+    elif verdict == "deny":
+        policy["denied"].append(tool_name)
+    elif verdict == "ask":
+        policy["ask_always"].append(tool_name)
+    save_tool_policy(policy)
+
+
+def remove_from_policy(tool_name: str) -> bool:
+    """Remove *tool_name* from all lists. Returns True if it was present."""
+    policy = load_tool_policy()
+    changed = False
+    for key in ("allowed", "denied", "ask_always"):
+        if tool_name in policy.get(key, []):
+            policy[key].remove(tool_name)
+            changed = True
+    if changed:
+        save_tool_policy(policy)
+    return changed
+
+
+def policy_summary() -> dict:
+    """Return current policy as a human-readable dict."""
+    return load_tool_policy()

aria_code/runtime/transactions.py

@@ -0,0 +1,216 @@
+"""Transaction points: the whole session state before each turn.
+
+``/rewind`` used to restore files, and ``/rewind both`` then dropped the last
+exchange, so rewinding three turns of edits left the conversation one turn
+back and every approval granted since still in force. A transaction point
+records, before each turn, everything that turn could change:
+
+* the conversation, in full;
+* the task list the model was keeping;
+* the approvals in force (allow-all, per-tool, per-command-prefix);
+* the newest file checkpoint, so every edit after it can be undone;
+* whether the code at that point had passed its checks;
+* the open task worktree and its unapplied diff.
+
+Rewinding to a point undoes every file change recorded after it, then puts
+the rest back as it was. Points live in ``<root>/<session_id>.jsonl``, the
+newest ``keep_per_session`` kept, each storing only the messages its turn's
+predecessor did not have.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+TRANSACTION_SCHEMA = "aria.transaction_point.v1"
+DEFAULT_KEEP_PER_SESSION = 50
+DEFAULT_MAX_SNAPSHOT_BYTES = 2 * 1024 * 1024
+
+# What the code was known to be at a point: checks ran green, ran red, files
+# changed with nothing to check them, or nothing has changed yet.
+PASSED, FAILED, UNVERIFIED, UNCHANGED = "passed", "failed", "unverified", ""
+# Red, but only where it was red before the change (runtime/baseline.py).
+PREEXISTING = "preexisting"
+
+
+@dataclass
+class TransactionPoint:
+    point_id: str
+    session_id: str
+    turn: int
+    prompt: str                      # the message the turn after this point answered
+    created_at: float
+    messages: list = field(default_factory=list)
+    todos: list = field(default_factory=list)
+    approvals: dict = field(default_factory=dict)
+    checkpoint_sequence: int = 0
+    verdict: str = UNCHANGED
+    task: Optional[dict] = None      # {task_id, repository, path, patch}
+    truncated: bool = False
+
+    def to_dict(self) -> dict:
+        return {"schema": TRANSACTION_SCHEMA, **asdict(self)}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "TransactionPoint":
+        fields = cls.__dataclass_fields__
+        return cls(**{key: value for key, value in data.items() if key in fields})
+
+
+def verdict_from_acceptance(acceptance: Any, previous: str) -> str:
+    """The code's state after a turn, from the acceptance summary it carried.
+
+    A turn that changed nothing leaves the previous verdict standing.
+    """
+    if not isinstance(acceptance, dict) or not acceptance.get("paths"):
+        return previous
+    verified = acceptance.get("verified")
+    if verified is True:
+        return PASSED
+    if verified is False:
+        return PREEXISTING if acceptance.get("regressions") is False else FAILED
+    return UNVERIFIED
+
+
+class TransactionStore:
+    """Points per session, appended one line per turn.
+
+    Consecutive points usually share the conversation up to the newer one's
+    last few messages, so a point whose conversation extends the previous
+    one's stores only the messages added since (``delta``). A compaction or a
+    rewind breaks the chain and the next point is stored in full. The file is
+    rewritten only to drop old points, once it holds twice as many as kept.
+    """
+
+    def __init__(self, root: Path | str, *, keep_per_session: int = DEFAULT_KEEP_PER_SESSION,
+                 max_snapshot_bytes: int = DEFAULT_MAX_SNAPSHOT_BYTES) -> None:
+        self.root = Path(root).expanduser()
+        self.keep_per_session = max(1, int(keep_per_session))
+        self.max_snapshot_bytes = max(64 * 1024, int(max_snapshot_bytes))
+
+    def _path(self, session_id: str) -> Path:
+        safe = "".join(ch for ch in str(session_id) if ch.isalnum() or ch in "-_") or "default"
+        return self.root / f"{safe}.jsonl"
+
+    def _lines(self, session_id: str) -> list[dict]:
+        try:
+            raw = self._path(session_id).read_text(encoding="utf-8").splitlines()
+        except OSError:
+            return []
+        records = []
+        for line in raw:
+            try:
+                data = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(data, dict) and data.get("schema") == TRANSACTION_SCHEMA:
+                records.append(data)
+        return records
+
+    def _read(self, session_id: str) -> list[TransactionPoint]:
+        """Oldest first, each with its whole conversation."""
+        points: list[TransactionPoint] = []
+        for data in self._lines(session_id):
+            delta = data.pop("delta", None)
+            try:
+                point = TransactionPoint.from_dict(data)
+            except TypeError:
+                continue
+            if delta is not None:
+                if not points or points[-1].point_id != delta.get("base"):
+                    continue  # its base was dropped: unrecoverable, skip it
+                prefix = points[-1].messages[: int(delta.get("start") or 0)]
+                point.messages = prefix + list(delta.get("messages") or [])
+                point.truncated = point.truncated or points[-1].truncated
+            points.append(point)
+        return points
+
+    @staticmethod
+    def _encode(point: TransactionPoint, previous: Optional[TransactionPoint]) -> dict:
+        data = point.to_dict()
+        if previous is not None:
+            start = len(previous.messages)
+            if start and point.messages[:start] == previous.messages:
+                data.pop("messages")
+                data["delta"] = {"base": previous.point_id, "start": start,
+                                 "messages": point.messages[start:]}
+        return data
+
+    def _rewrite(self, session_id: str, points: list[TransactionPoint]) -> None:
+        path = self._path(session_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temp = path.with_suffix(".tmp")
+        previous = None
+        with temp.open("w", encoding="utf-8") as handle:
+            for point in points[-self.keep_per_session:]:
+                handle.write(json.dumps(self._encode(point, previous), ensure_ascii=False, default=str) + "\n")
+                previous = point
+        os.replace(temp, path)
+
+    def _fit(self, point: TransactionPoint) -> TransactionPoint:
+        """Drop the oldest messages until the snapshot is under the byte cap."""
+        messages = list(point.messages)
+        while messages and len(json.dumps(messages, ensure_ascii=False, default=str)) > self.max_snapshot_bytes:
+            messages.pop(0)
+            point.truncated = True
+        point.messages = messages
+        return point
+
+    def record(self, point: TransactionPoint) -> TransactionPoint:
+        # Round-trip through JSON so the stored and the compared forms agree.
+        point.messages = json.loads(json.dumps(point.messages, ensure_ascii=False, default=str))
+        point = self._fit(point)
+        points = self._read(point.session_id)
+        if len(points) + 1 > 2 * self.keep_per_session:
+            self._rewrite(point.session_id, points + [point])
+            return point
+        path = self._path(point.session_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        line = json.dumps(self._encode(point, points[-1] if points else None), ensure_ascii=False, default=str)
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(line + "\n")
+        return point
+
+    def list(self, session_id: str) -> list[TransactionPoint]:
+        """Newest first, at most ``keep_per_session``."""
+        return list(reversed(self._read(session_id)[-self.keep_per_session:]))
+
+    def find(self, session_id: str, ref: str) -> Optional[TransactionPoint]:
+        """By id (or its prefix), or by count: ``"1"`` is the point before the last turn."""
+        points = self.list(session_id)
+        ref = str(ref or "1").strip()
+        if ref.isdigit() and len(ref) <= 3:
+            index = int(ref) - 1
+            return points[index] if 0 <= index < len(points) else None
+        matches = [point for point in points if point.point_id.startswith(ref)]
+        return matches[0] if len(matches) == 1 else None
+
+    def latest_green(self, session_id: str) -> Optional[TransactionPoint]:
+        return next((point for point in self.list(session_id) if point.verdict == PASSED), None)
+
+    def drop_from(self, point: TransactionPoint) -> None:
+        """Forget ``point`` and every later one: after a rewind they are not history."""
+        kept = []
+        for candidate in self._read(point.session_id):
+            if candidate.point_id == point.point_id:
+                break
+            kept.append(candidate)
+        self._rewrite(point.session_id, kept)
+
+
+def new_point(*, session_id: str, turn: int, prompt: str, **state: Any) -> TransactionPoint:
+    return TransactionPoint(point_id=uuid.uuid4().hex[:10], session_id=session_id, turn=turn,
+                            prompt=" ".join(str(prompt or "").split())[:120],
+                            created_at=time.time(), **state)
+
+
+def default_transaction_store() -> TransactionStore:
+    from ..packages.aria_core.paths import aria_home
+
+    return TransactionStore(aria_home() / "transactions")