rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/agents/prompts.py

@@ -0,0 +1,156 @@
+"""What each agent is told about its kernel, its sub-agents and its limits."""
+
+from __future__ import annotations
+
+import json
+
+from rlmagent.agents.tree import AgentNode
+
+KERNEL_GUIDE = """## Your kernel
+The python tool runs code in one kernel that stays alive for the whole task: \
+variables, imports and functions you define remain available in later calls. \
+Its working directory is the project root. Run shell commands with a leading `!` \
+or with subprocess. Print summaries (lengths, counts, a few lines) rather than \
+whole files or large objects; long output is cut to its start and end."""
+
+SANDBOX_GUIDE = """## Your kernel
+The python tool runs code in one sandboxed kernel (Python compiled to WebAssembly) that stays alive for the whole task: variables, imports and functions you define remain available in later calls. The sandbox has its own empty filesystem; `open()` does not see the project.{network} Reach the project only through these functions (await them):
+
+    text  = await read_file("src/app.py")
+    part  = await read_file("src/app.py", 100, 160)   # only lines 100 to 160
+    paths = await list_files("**/*.py")
+    hits  = await search_files(r"def main", glob="*.py")  # [{"path", "line", "text"}]
+    await write_file("src/app.py", text)          # asks the user first
+    await edit_file("src/app.py", old, new)       # old must occur exactly once
+    await apply_patch(unified_diff)               # several edits or files, all or none; asks first
+    r = await run("python -m pytest -q")          # {"exit": 0, "output": "..."}; asks first
+    answer = await ask_user("Which one?", ["a", "b"])  # only when you truly cannot decide
+
+Paths are relative to the project root. Run tests, builds and installs with run(); it executes on the user's machine. A refused write or command raises RuntimeError: tell the user what you wanted to do instead of retrying. Print summaries rather than whole files; long output is cut to its start and end."""
+
+DELEGATION_GUIDE = """## Sub-agents
+Inside the kernel you can hand work to sub-agents, which are agents like you \
+with their own kernel and the same tools:
+
+    answer  = await rlm("task for the sub-agent", context)
+    answers = await gather_rlm([("task A", data_a), ("task B", data_b)])
+
+- `context` can be any JSON-compatible value. The sub-agent receives it as the \
+variable CONTEXT in its own kernel, so large data never has to pass through a \
+message. Slice or filter it first: send each sub-agent only what its task needs. \
+If you hand on most of your own context barely reduced, the sub-agent is asked to \
+check the hand-off first and may refuse to start; then narrow the data and try again.
+- Each call returns the value the sub-agent passed to FINAL, as a normal Python \
+object you can keep working with.
+- Delegate when pieces are independent (the same check across many files, \
+several separate questions) or when reading everything yourself would crowd \
+out the rest of the task. Do small things yourself; a sub-agent costs a full \
+agent run.
+- If the user asks you to use sub-agents, you must call rlm, gather_rlm or spawn; \
+do not do the work yourself instead.
+- gather_rlm runs its jobs at the same time and returns results in order. If \
+one fails, the others are stopped and the call raises.
+
+To keep working while a sub-agent runs, start it in the background:
+
+    h = await spawn("run the test suite and report failures", data)
+    ...                       # carry on with other cells
+    report = await h.result() # waits; h.result(timeout=10) raises TimeoutError if not done
+    await h.status()          # starting, running, idle, done, failed or cancelled
+    await h.cancel()          # stops it and everything it started
+    await h.messages()        # notes it left for you
+    hs = await children()     # every sub-agent you started
+    await name_child(h, "reviewer")  # name a child under this parent
+    h = await find_child("reviewer") # look up its handle
+    info = await child_info(h)       # status and recorded usage
+    await steer_child(h, "check login first")  # guide its next model request
+
+- Use spawn for long work you do not need yet or may want to stop; use \
+gather_rlm for independent pieces you need all of now.
+- spawn(task, data, keep=True) keeps the sub-agent after its FINAL, idle, so \
+h.send("next instruction") can give it more work; h.result() then returns its \
+newest FINAL.
+- rlm and spawn take model=, e.g. model="cli:codex" or "cli:claude-code?model=sonnet", \
+to run that sub-agent on another model; only when the user asks for one.
+- When you finish, sub-agents you started are stopped; collect what you need \
+first."""
+
+LEAF_NOTE = "Sub-agents are not available to you: rlm, gather_rlm and spawn are not defined in your kernel. Do this task yourself."
+
+CHILD_ROLE = """## Your role
+You were started by another agent to do one task. Its data, if any, is in the \
+variable CONTEXT in your kernel. When you are done, call FINAL(value) in the \
+python tool with the result it asked for; that value is returned to it directly. \
+Call FINAL exactly once. To report progress before then, await tell_parent("note")."""
+
+RESUMED_NOTICE = (
+    "This session was resumed. The kernel is new: variables, imports and functions "
+    "from earlier in the conversation are gone. Rebuild anything you still need."
+)
+
+COMPACTION_NOTE = "The kernel is still running: variables defined before this summary are still available."
+
+
+PLAYBOOK_GUIDE = """## Playbook
+You keep a playbook of rules, memories, skills and sub-agent roles across \
+sessions. When something is worth keeping (a correction from the user, a \
+mistake you repeated, a procedure you did twice, a lasting fact), call \
+`await improve("what to keep")` in the python tool; the playbook is updated \
+when the turn ends. Without `shared=True` it is kept for this session only; \
+pass `shared=True` when the user says to remember it always, in every future \
+session, or for every project. `await playbook()` lists entries."""
+
+
+ONLINE = (" It can reach the internet: use httpx (async, `async with httpx.AsyncClient()`) "
+          "or `pyodide.http.pyfetch`; requests does not work here. Install pure-Python packages "
+          "with `await micropip.install(...)`; numpy, pandas and other compiled packages with "
+          "`await pyodide_js.loadPackage(...)`.")
+OFFLINE = " It has no network and no pip."
+
+
+def kernel_guide(sandboxed: bool, network: bool = False) -> str:
+    if not sandboxed:
+        return KERNEL_GUIDE
+    return SANDBOX_GUIDE.replace("{network}", ONLINE if network else OFFLINE)
+
+
+def root_system(base: str, can_delegate: bool, playbook: bool = False,
+                sandboxed: bool = False, network: bool = False) -> str:
+    guide = kernel_guide(sandboxed, network)
+    parts = [base, guide, DELEGATION_GUIDE if can_delegate else LEAF_NOTE]
+    if playbook:
+        parts.append(PLAYBOOK_GUIDE)
+    return "\n\n".join(parts)
+
+
+def child_system(base: str, node: AgentNode, can_delegate: bool, sandboxed: bool = False,
+                 network: bool = False) -> str:
+    guide = kernel_guide(sandboxed, network)
+    parts = [base, guide, CHILD_ROLE, DELEGATION_GUIDE if can_delegate else LEAF_NOTE]
+    return "\n\n".join(parts)
+
+
+def context_preview(value: object, limit: int = 600) -> str:
+    if value is None:
+        return "CONTEXT is None (no data was passed)."
+    if isinstance(value, str):
+        kind = f"a string of {len(value):,} characters"
+    elif isinstance(value, (list, tuple)):
+        kind = f"a list of {len(value):,} items"
+    elif isinstance(value, dict):
+        kind = f"a dict with keys {list(value)[:20]}"
+    else:
+        kind = f"a {type(value).__name__}"
+    text = value if isinstance(value, str) else json.dumps(value, default=repr)
+    head = text[:limit] + (" ..." if len(text) > limit else "")
+    return f"CONTEXT is {kind}. It begins:\n{head}"
+
+
+RETURN_REMINDER = (
+    "Deliver your answer by calling FINAL(value) in the python tool. "
+    "A plain text reply is not returned to the agent that asked."
+)
+
+
+def child_first_message(node: AgentNode) -> str:
+    return f"{node.task}\n\n{context_preview(node.context)}\n\n{RETURN_REMINDER}"

rlmagent/agents/trace.py

@@ -0,0 +1,290 @@
+"""A record of every model call in an agent tree, and how the calls relate."""
+
+from __future__ import annotations
+
+import json
+import math
+import time
+import uuid
+from contextvars import ContextVar
+from pathlib import Path
+
+from rlmagent.agents.budget import REFUSED
+from rlmagent.harness.provider.wire import StreamCloseEvent, StreamFaultEvent
+
+request_id: ContextVar[str | None] = ContextVar("model_request_id", default=None)
+attempt_observer: ContextVar[object] = ContextVar("model_attempt_observer", default=None)
+
+
+def model_attempt(**fields):
+    observer = attempt_observer.get()
+    if observer is not None:
+        observer(**fields)
+
+
+def correlate_headers(headers: dict[str, str]) -> dict[str, str]:
+    call = request_id.get()
+    if call is None:
+        return headers
+    result = {key: value for key, value in headers.items()
+              if key.lower() != "x-rlmagent-request-id"}
+    result["X-Rlmagent-Request-Id"] = call
+    return result
+
+
+async def correlated(stream, call: str | None, tracer=None):
+    """Give each provider read the same ID without leaking it to other streams."""
+    iterator = aiter(stream)
+    try:
+        while True:
+            token = request_id.set(call)
+            observer = attempt_observer.set(
+                (lambda **fields: tracer._write("model_attempt", request=call, **fields))
+                if tracer is not None else None)
+            try:
+                event = await anext(iterator)
+            except StopAsyncIteration:
+                return
+            finally:
+                request_id.reset(token)
+                attempt_observer.reset(observer)
+            yield event
+    finally:
+        if close := getattr(iterator, "aclose", None):
+            await close()
+
+
+class Tracer:
+    def __init__(self, path: Path | str | None = None, contract: dict | None = None) -> None:
+        self.path = Path(path) if path else None
+        self.records: list[dict] = []
+        self._last: dict[str, str] = {}
+        self._pending: dict[str, list[tuple[str, str]]] = {}
+        self._compacted: set[str] = set()
+        self._returned: set[str] = set()
+        self._totals: dict[str, dict] = {}
+        self._open: dict[str, tuple] = {}
+        self._historical_calls: dict[str, dict] = {}
+        self._child_calls: dict[str, str] = {}
+        if self.path is not None:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text("", encoding="utf-8")
+        self._write("run", contract=contract, started=time.time())
+
+    def _write(self, kind: str, **fields) -> None:
+        record = {"kind": kind, **fields}
+        self.records.append(record)
+        if self.path is not None:
+            with self.path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(record, default=str) + "\n")
+
+    def persist(self, path: Path) -> None:
+        """Append this runtime's request ledger to the saved session."""
+        if self.path is not None:
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.exists():
+            for line in path.read_text(encoding="utf-8").splitlines():
+                if line.strip():
+                    record = json.loads(line)
+                    if not isinstance(record, dict):
+                        raise ValueError("Saved request ledger contains an invalid record")
+                    if record.get("kind") == "call":
+                        self._remember_call(self._historical_calls, record)
+        with path.open("a", encoding="utf-8") as output:
+            for record in self.records:
+                output.write(json.dumps(record, default=str) + "\n")
+        self.path = path
+
+    @staticmethod
+    def _remember_call(calls, record):
+        identity = record.get("id")
+        if not isinstance(identity, str) or not identity:
+            raise ValueError("Saved request ledger has a call without an identity")
+        if identity in calls and calls[identity] != record:
+            raise ValueError("Saved request ledger has conflicting records for one call")
+        calls[identity] = record
+
+    def lifetime_usage(self):
+        """Idempotent persisted-plus-current usage, separate from admission counters."""
+        calls = dict(self._historical_calls)
+        for record in self.records:
+            if record.get("kind") == "call":
+                self._remember_call(calls, record)
+        fields = ("input", "output", "cache_read", "cache_write", "reasoning", "cost")
+        agents, incomplete, unreported, unpriced = {}, 0, 0, 0
+        for record in calls.values():
+            agent = record.get("agent")
+            if not isinstance(agent, str):
+                raise ValueError("Saved request ledger has an invalid agent")
+            totals = agents.setdefault(agent, dict.fromkeys(("calls", *fields), 0))
+            totals["calls"] += 1
+            incomplete += any(field not in record for field in fields)
+            unreported += not record.get("usage_reported", False)
+            unpriced += record.get("cost", 0) == 0
+            for field in fields:
+                value = record.get(field, 0)
+                if type(value) not in (int, float) or not math.isfinite(value) or value < 0:
+                    raise ValueError("Saved request ledger has invalid usage")
+                totals[field] += value
+        return {
+            "agents": agents,
+            "totals": {field: sum(agent[field] for agent in agents.values())
+                       for field in ("calls", *fields)},
+            "coverage": {"incompleteUsageRecords": incomplete,
+                         "unreportedUsageRecords": unreported, "unpricedRecords": unpriced},
+        }
+
+    def child_usage(self, child: str, *, compatibility: bool = False) -> dict:
+        fields = ("input", "output", "cache_read", "cache_write", "reasoning", "cost")
+        calls = {} if compatibility else dict(self._historical_calls)
+        for record in self.records:
+            if record.get("kind") == "call":
+                self._remember_call(calls, record)
+        selected = [record for record in calls.values()
+                    if record.get("agent" if compatibility else "child") == child]
+        return {"calls": len(selected),
+                "unreported": sum(not record.get("usage_reported") for record in selected),
+                "unpriced": sum(record.get("cost", 0) == 0 for record in selected),
+                **{field: sum(record.get(field, 0) for record in selected) for field in fields}}
+
+    def begin(self, agent: str, model: str, *, child: str | None = None) -> str:
+        call = uuid.uuid4().hex
+        if child is not None:
+            self._child_calls[call] = child
+        previous = self._last.get(agent)
+        compacted = agent in self._compacted
+        pending = self._pending.pop(agent, [])
+        links = [(source, how) for source, how in pending]
+        if previous is not None:
+            links.insert(0, (previous, "compact" if compacted else "next"))
+        self._compacted.discard(agent)
+        self._last[agent] = call
+        self._open[call] = (agent, model, time.time(), previous, pending, compacted, links)
+        return call
+
+    def drop(self, call: str) -> None:
+        """Forget a call that was never sent (refused by the budget)."""
+        self._child_calls.pop(call, None)
+        agent, _, _, previous, pending, compacted, _ = self._open.pop(call)
+        if previous is None:
+            self._last.pop(agent, None)
+        else:
+            self._last[agent] = previous
+        if pending:
+            self._pending.setdefault(agent, [])[:0] = pending
+        if compacted:
+            self._compacted.add(agent)
+
+    def end(self, call: str, usage, stop: str | None) -> None:
+        agent, model, started, _, _, _, links = self._open.pop(call)
+        child = self._child_calls.pop(call, None)
+        for source, how in links:
+            self._write("link", **{"from": source, "to": call, "how": how})
+        self._totals.setdefault(agent, {"calls": 0, "cost": 0.0, "input": 0, "output": 0})
+        cost = usage.cost.total if usage is not None else 0.0
+        tokens_in = usage.input if usage is not None else 0
+        tokens_out = usage.output if usage is not None else 0
+        t = self._totals[agent]
+        t["calls"] += 1
+        t["cost"] += cost
+        t["input"] += tokens_in
+        t["output"] += tokens_out
+        for name in ("cache_read", "cache_write", "reasoning"):
+            t[name] = t.get(name, 0) + ((getattr(usage, name, 0) or 0) if usage is not None else 0)
+        self._write("call", id=call, agent=agent, model=model, stop=stop, cost=cost,
+                    input=tokens_in, output=tokens_out, usage_reported=usage is not None,
+                    cache_read=(usage.cache_read or 0) if usage is not None else 0,
+                    cache_write=(usage.cache_write or 0) if usage is not None else 0,
+                    reasoning=(usage.reasoning or 0) if usage is not None else 0,
+                    seconds=round(time.time() - started, 3),
+                    **({"child": child} if child is not None else {}))
+
+    def spawned(self, parent: str, child: str) -> None:
+        if parent in self._last:
+            self._pending.setdefault(child, []).append((self._last[parent], "spawn"))
+
+    def returned(self, parent: str, child: str) -> None:
+        last = self._last.get(child)
+        if last is not None and last not in self._returned:
+            self._returned.add(last)
+            self._pending.setdefault(parent, []).append((last, "return"))
+
+    def compacted(self, agent: str) -> None:
+        self._compacted.add(agent)
+
+    def finish(self, agents: list[dict], stopped_by: str | None, complete: bool = True) -> dict:
+        for agent in agents:
+            self._write("agent", **agent)
+        summary = {
+            "calls": sum(t["calls"] for t in self._totals.values()),
+            "cost": sum(t["cost"] for t in self._totals.values()),
+            "input": sum(t["input"] for t in self._totals.values()),
+            "output": sum(t["output"] for t in self._totals.values()),
+            "agents": self._totals,
+            "agents_started": max(len(agents) - 1, 0),
+            "stopped_by": stopped_by,
+            "complete": complete,
+        }
+        self._write("summary", **summary)
+        return summary
+
+
+class TracedProvider:
+    """One agent's view of the tree's provider: every call is traced as that agent's."""
+
+    follows_tree = True
+
+    def __init__(self, tree, agent: str) -> None:
+        self._tree = tree
+        self._agent = agent
+
+    def __getattr__(self, name):
+        return getattr(self._tree.provider, name)
+
+    async def stream_response(self, *, model, **kwargs):
+        limit = getattr(getattr(self._tree, "policy", None), "agent_max_tokens", None)
+        if limit is not None and self._tree.tracer._totals.get(self._agent, {}).get("output", 0) >= limit:
+            from rlmagent.harness.contracts.transcript import ModelEntry
+
+            yield StreamFaultEvent(reason="error", error=ModelEntry(model=model, stop_reason="error",
+                error_message=f"agent {self._agent} reached its limit of {limit} completion tokens"))
+            return
+        refinement = getattr(self._tree, "refinement", None)
+        if refinement is not None:
+            kwargs["system"] = refinement.filter_system(kwargs["system"])
+        tracer = self._tree.tracer
+        call = tracer.begin(self._agent, model)
+        session = getattr(self._tree, "session", None)
+        if session is None:
+            session = getattr(self._tree, "_session_of", {}).get(self._agent)
+        ledger = getattr(session, "steering", None)
+        pending = []
+        if ledger is not None:
+            from rlmagent.harness.contracts.transcript import HumanEntry
+
+            text, pending = ledger.context(self._agent, root=self._agent == self._tree.root_id())
+            if text:
+                kwargs["messages"] = [*kwargs["messages"], HumanEntry(content="Steering instructions:\n" + text)]
+        usage, stop, refused = None, None, False
+        from rlmagent.model.deadline import bounded_stream
+        try:
+            async for event in correlated(
+                bounded_stream(self._tree.provider.stream_response(model=model, **kwargs),
+                               model, getattr(self._tree, "request_timeout", 300.0)), call, tracer
+            ):
+                if isinstance(event, StreamCloseEvent):
+                    usage, stop = event.message.usage, event.reason
+                    if ledger is not None:
+                        ledger.consumed(pending, self._agent, call)
+                        if pending:
+                            tracer._write("steering", agent=self._agent, request=call, messages=pending)
+                elif isinstance(event, StreamFaultEvent):
+                    usage, stop = event.error.usage, event.reason
+                    refused = (event.error.error_message or "").startswith(REFUSED)
+                yield event
+        finally:
+            if refused:
+                tracer.drop(call)
+            else:
+                tracer.end(call, usage, stop)