ramure 0.0.1__py3-none-any.whl

ramure/__init__.py

@@ -0,0 +1,49 @@
+from ramure.agent import Agent
+from ramure.log import Log, LogEntry
+from ramure.machines import Image, LocalImage, LocalMachine, Machine
+from ramure.process import (
+    ProcessHandle,
+    ProcessScope,
+    agent,
+    agent_process,
+    connect,
+    current_runtime,
+    done,
+    emit,
+    expose,
+    fail,
+    machine,
+    spawn,
+    wait,
+)
+from ramure.runtime import Runtime
+from ramure.stream import Event, Stream
+from ramure.types import ExecResult, ExecutionFailed
+
+__all__ = [
+    "Agent",
+    "Event",
+    "ExecResult",
+    "ExecutionFailed",
+    "Image",
+    "LocalImage",
+    "LocalMachine",
+    "Log",
+    "LogEntry",
+    "Machine",
+    "ProcessHandle",
+    "ProcessScope",
+    "Runtime",
+    "Stream",
+    "agent",
+    "agent_process",
+    "connect",
+    "current_runtime",
+    "done",
+    "emit",
+    "expose",
+    "fail",
+    "machine",
+    "spawn",
+    "wait",
+]

ramure/agent.py

@@ -0,0 +1,68 @@
+"""The ``Agent`` type.
+
+An Agent owns its own state: a replicated ``Log``, a dict of tool
+handlers, a registration ``Event``, and a handle to the process scope
+that created it. It is the single source of truth for that agent inside
+the runtime; nothing else shadows its fields.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
+
+from ramure.helpers.schema import build_tool_definition
+from ramure.log import Log
+from ramure.machines import Machine
+from ramure.stream import Stream
+from ramure.types import ExecResult
+
+if TYPE_CHECKING:
+    from ramure.process import ProcessScope
+
+
+Handler = Callable[..., Awaitable[Any]]
+
+
+@dataclass
+class Agent:
+    name: str
+    machine: Machine
+    log: Log
+    system_prompt: str | None = None
+    handlers: dict[str, Handler] = field(default_factory=dict)
+    registered: asyncio.Event = field(default_factory=asyncio.Event)
+    scope: "ProcessScope | None" = field(default=None, repr=False)
+
+    @property
+    def events(self) -> Stream:
+        """Async-iterable stream of this agent's events (no replication metadata)."""
+        return self.log.stream
+
+    def on(self, tool_name: str) -> Callable[[Handler], Handler]:
+        """Register an async tool handler for this agent."""
+
+        def decorator(fn: Handler) -> Handler:
+            if not inspect.iscoroutinefunction(fn):
+                raise TypeError("Tool handlers must be async")
+            self.register_handler(tool_name, fn)
+            return fn
+
+        return decorator
+
+    def register_handler(self, name: str, fn: Handler) -> None:
+        """Install a tool handler. If the agent is already live, announce it."""
+        self.handlers[name] = fn
+        if self.registered.is_set():
+            self.log.emit("tool_registered", build_tool_definition(name, fn))
+
+    async def send(self, text: str) -> None:
+        """Deliver a user-style message to this agent."""
+        self.log.emit("message", {"text": text})
+
+    async def exec(
+        self, command: str, *, user: str = "agent", timeout: int | None = None
+    ) -> ExecResult:
+        return await self.machine.exec(command, user=user, timeout=timeout)

ramure/cli.py

@@ -0,0 +1,168 @@
+"""Ramure CLI.
+
+Commands talk to a live runtime over its Unix socket at
+``~/.ramure/runtimes/{execution_id}.sock``. Finished runs have no
+socket; their logs stay in ``~/.ramure/logs/{execution_id}/``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import socket
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from ramure.control import SOCKET_DIR, socket_path
+
+
+app = typer.Typer(
+    name="ramure",
+    help="Inspect and interact with ramure executions.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+ID_OPT = typer.Option(None, "--id", "-i", help="Execution id or prefix (default: the only live run).")
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+
+def _live_ids() -> list[str]:
+    if not SOCKET_DIR.exists():
+        return []
+    return sorted(p.stem for p in SOCKET_DIR.glob("*.sock"))
+
+
+def pick(prefix: str | None) -> str:
+    """Resolve a live run id by prefix, or the only live run if omitted."""
+    ids = [i for i in _live_ids() if prefix is None or i.startswith(prefix)]
+    if not ids:
+        die(f"No live run matches '{prefix}'." if prefix else "No live runs.")
+    if len(ids) > 1:
+        label = "Ambiguous prefix" if prefix else "Multiple live runs; pass --id"
+        die(f"{label}:\n" + "\n".join(f"  {i[:8]}" for i in ids))
+    return ids[0]
+
+
+# ---------------------------------------------------------------------------
+# Socket RPC
+# ---------------------------------------------------------------------------
+
+
+def call(execution_id: str, request: dict[str, Any]) -> dict[str, Any]:
+    """Send one request to the runtime's control socket, return the reply."""
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
+            s.connect(str(socket_path(execution_id)))
+            s.sendall((json.dumps(request) + "\n").encode())
+            reply = _recv_line(s)
+    except (FileNotFoundError, ConnectionRefusedError) as exc:
+        die(f"Runtime unreachable: {exc}")
+    if not reply:
+        die("empty reply from runtime")
+    data = json.loads(reply)
+    if "error" in data:
+        die(data["error"])
+    return data
+
+
+def _recv_line(s: socket.socket) -> str:
+    buf = bytearray()
+    while True:
+        chunk = s.recv(4096)
+        if not chunk:
+            break
+        buf.extend(chunk)
+        if b"\n" in chunk:
+            break
+    return buf.decode().rstrip("\n")
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+@app.command("ls")
+def cmd_ls() -> None:
+    """List live runs."""
+    ids = _live_ids()
+    if not ids:
+        typer.echo("No live runs.")
+        return
+    for i in ids:
+        reply = call(i, {"cmd": "status"})
+        typer.echo(f"{i[:8]}  {reply.get('program', '?')}")
+
+
+@app.command("status")
+def cmd_status(id_: str = ID_OPT) -> None:
+    """Show structure of a live run: agents, machines, connections."""
+    s = call(pick(id_), {"cmd": "status"})
+
+    typer.echo(f"Execution: {s['execution_id']}")
+    typer.echo(f"Program:   {s.get('program', '?')}")
+    typer.echo(f"PID:       {s.get('pid', '?')}")
+    typer.echo(f"Server:    {s.get('server_url', '?')}")
+
+    if s.get("agents"):
+        typer.echo("\nAgents:")
+        for ag in s["agents"]:
+            m = ag["machine"]
+            bits = [m.get("kind", "?")]
+            if "workdir" in m:
+                bits.append(f"workdir={m['workdir']}")
+            tmux = f"  tmux={ag['tmux_session']}" if ag.get("tmux_session") else ""
+            typer.echo(f"  {ag['name']}  [{' '.join(bits)}]{tmux}")
+
+    if s.get("connections"):
+        typer.echo("\nConnections:")
+        for c in s["connections"]:
+            typer.echo(f"  {c['a']} -> {c['b']}")
+
+
+@app.command("send")
+def cmd_send(
+    agent: str = typer.Argument(..., help="Agent name."),
+    message: str = typer.Argument(..., help="Message text."),
+    id_: str = ID_OPT,
+) -> None:
+    """Send a message to an agent."""
+    call(pick(id_), {"cmd": "send", "agent": agent, "text": message})
+    typer.echo(f"Sent to {agent}.")
+
+
+@app.command("connect")
+def cmd_connect(agent: str = typer.Argument(...), id_: str = ID_OPT) -> None:
+    """Attach to an agent's tmux session."""
+    eid = pick(id_)
+    info = call(eid, {"cmd": "agent", "name": agent})
+    session = info.get("tmux_session") or f"ramure-{eid}-{agent}"
+    os.execvp("tmux", ["tmux", "attach-session", "-t", session])
+
+
+@app.command("ssh")
+def cmd_ssh(agent: str = typer.Argument(...), id_: str = ID_OPT) -> None:
+    """Open a shell on an agent's machine."""
+    info = call(pick(id_), {"cmd": "agent", "name": agent})
+    m = info["machine"]
+    if m.get("kind") != "LocalMachine":
+        die(f"ssh not supported for machine kind '{m.get('kind')}' yet.")
+    shell = os.environ.get("SHELL", "/bin/bash")
+    os.execvp(shell, [shell, "-c", f"cd {shlex.quote(m.get('workdir', os.getcwd()))} && exec {shell}"])
+
+
+def die(msg: str) -> None:
+    typer.echo(msg, err=True)
+    raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()

ramure/context.py

@@ -0,0 +1,18 @@
+"""Context variables shared across the runtime and process modules.
+
+Extracted so ``ramure.runtime`` doesn't need a lazy import of
+``ramure.process`` to reach the active process scope.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ramure.process import ProcessScope
+
+
+_current_process: ContextVar["ProcessScope | None"] = ContextVar(
+    "ramure_current_process", default=None
+)

ramure/control.py

@@ -0,0 +1,139 @@
+"""Unix-socket control server for CLI interaction.
+
+The runtime listens on ``~/.ramure/runtimes/{execution_id}.sock``.
+The CLI connects, sends one line of JSON, reads one line back, closes.
+
+Commands:
+
+- ``{"cmd":"status"}`` -> ``{agents, connections, program, pid, started_at}``
+- ``{"cmd":"agent", "name":<str>}`` -> ``{name, machine, tmux_session}``
+- ``{"cmd":"send", "agent":<str>, "text":<str>}`` -> ``{"ok":true}``
+
+Errors come back as ``{"error":<msg>}``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ramure.helpers import agent_session_name
+
+if TYPE_CHECKING:
+    from ramure.runtime import Runtime
+
+
+SOCKET_DIR = Path.home() / ".ramure" / "runtimes"
+
+
+def socket_path(execution_id: str) -> Path:
+    return SOCKET_DIR / f"{execution_id}.sock"
+
+
+class ControlServer:
+    def __init__(self, runtime: Runtime) -> None:
+        self.runtime = runtime
+        self._server: asyncio.base_events.Server | None = None
+        self._path: Path | None = None
+
+    async def start(self) -> None:
+        assert self.runtime.execution_id
+        SOCKET_DIR.mkdir(parents=True, exist_ok=True)
+        self._path = socket_path(self.runtime.execution_id)
+        # Clean up a stale socket from a crashed previous run.
+        try:
+            self._path.unlink()
+        except FileNotFoundError:
+            pass
+        self._server = await asyncio.start_unix_server(self._handle, path=str(self._path))
+
+    async def stop(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+        if self._path is not None:
+            try:
+                self._path.unlink()
+            except FileNotFoundError:
+                pass
+            self._path = None
+
+    async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            line = await reader.readline()
+            if not line:
+                return
+            try:
+                msg = json.loads(line)
+            except json.JSONDecodeError:
+                reply = {"error": "invalid json"}
+            else:
+                reply = await self._dispatch(msg)
+            writer.write((json.dumps(reply) + "\n").encode())
+            await writer.drain()
+        finally:
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    async def _dispatch(self, msg: dict[str, Any]) -> dict[str, Any]:
+        cmd = msg.get("cmd")
+        if cmd == "status":
+            return self._cmd_status()
+        if cmd == "agent":
+            return self._cmd_agent(msg.get("name", ""))
+        if cmd == "send":
+            return await self._cmd_send(msg.get("agent", ""), msg.get("text", ""))
+        return {"error": f"unknown cmd '{cmd}'"}
+
+    # -- handlers --
+
+    def _cmd_status(self) -> dict[str, Any]:
+        rt = self.runtime
+        return {
+            "execution_id": rt.execution_id,
+            "pid": os.getpid(),
+            "program": _program_name(),
+            "started_at": rt.started_at,
+            "server_url": rt.server_url,
+            "agents": [self._agent_info(ag.name) for ag in rt.agents.values()],
+            "connections": [
+                {"a": a, "b": b} for (a, b) in sorted(rt.edges)
+            ],
+        }
+
+    def _cmd_agent(self, name: str) -> dict[str, Any]:
+        if name not in self.runtime.agents:
+            return {"error": f"unknown agent '{name}'"}
+        return self._agent_info(name)
+
+    async def _cmd_send(self, name: str, text: str) -> dict[str, Any]:
+        ag = self.runtime.agents.get(name)
+        if ag is None:
+            return {"error": f"unknown agent '{name}'"}
+        if not text:
+            return {"error": "missing text"}
+        await ag.send(text)
+        return {"ok": True}
+
+    def _agent_info(self, name: str) -> dict[str, Any]:
+        ag = self.runtime.agents[name]
+        return {
+            "name": name,
+            "machine": ag.machine.describe(),
+            "tmux_session": agent_session_name(self.runtime.execution_id or "", name),
+        }
+
+
+def _program_name() -> str:
+    argv0 = sys.argv[0] if sys.argv else ""
+    if argv0 and Path(argv0).exists():
+        return str(Path(argv0).resolve())
+    return argv0 or "<unknown>"

ramure/extension.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def extension_source() -> str:
+    path = Path(__file__).with_name("extension.ts")
+    if not path.exists():
+        raise FileNotFoundError(f"Bundled extension not found: {path}")
+    return path.read_text()