ctlrm 0.1.0__py3-none-any.whl

ctlrm/__init__.py

@@ -0,0 +1,3 @@
+"""Top-level package metadata for ctlrm."""
+
+from ctlrm.version import __version__ as __version__

ctlrm/__main__.py

@@ -0,0 +1,307 @@
+"""Typer command-line interface for filesystem-backed ctlrm rooms."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable, Sequence
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Annotated, TypeVar
+from uuid import uuid4
+
+import typer
+import yaml
+from pydantic import ValidationError
+
+from ctlrm.runtime.manifest import RoleAssignment, RoomManifest
+from ctlrm.runtime.messages import MailboxMessage
+from ctlrm.runtime.room import RoomRuntime
+
+from ctlrm.managed.cli import session_app, supervisor_app
+
+from ctlrm.managed.workflow_cli import workflow_app
+from ctlrm.managed.project_cli import project_app, job_app
+
+app = typer.Typer(no_args_is_help=True, pretty_exceptions_enable=False)
+app.add_typer(session_app, name="session")
+app.add_typer(workflow_app, name="workflow")
+app.add_typer(project_app, name="project")
+app.add_typer(job_app, name="job")
+app.add_typer(supervisor_app, name="supervisor")
+_Result = TypeVar("_Result")
+
+
+def _now() -> str:
+    """Return the current UTC time in an interoperable representation."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _read_text(value: str | None, path: Path | None) -> str:
+    """Resolve text supplied inline, from a file, or through standard input."""
+    if value is not None:
+        return value
+    if path is not None:
+        return path.read_text(encoding="utf-8")
+    if stdin_buffer := getattr(sys.stdin, "buffer", None):
+        return stdin_buffer.read().decode("utf-8")
+    return sys.stdin.read()
+
+
+def _run(action: Callable[[], _Result]) -> _Result:
+    """Convert expected domain failures into stable command exit codes."""
+    try:
+        return action()
+    except typer.Exit:
+        raise
+    except FileExistsError as exc:
+        typer.echo(f"conflict: {exc.filename or exc}", err=True)
+        raise typer.Exit(3) from exc
+    except FileNotFoundError as exc:
+        typer.echo(f"not found: {exc.filename or exc}", err=True)
+        raise typer.Exit(4) from exc
+    except (ValidationError, ValueError, yaml.YAMLError) as exc:
+        typer.echo(f"invalid: {exc}", err=True)
+        raise typer.Exit(2) from exc
+    except (OSError, RuntimeError) as exc:
+        typer.echo(f"room error: {exc}", err=True)
+        raise typer.Exit(5) from exc
+
+
+def _parse_assignments(values: list[str]) -> list[RoleAssignment]:
+    """Parse repeated PARTICIPANT=ROLE assignment options."""
+    assignments = []
+    for value in values:
+        participant, separator, role = value.partition("=")
+        if not separator:
+            raise ValueError(f"assignment must be PARTICIPANT=ROLE: {value!r}")
+        assignments.append(RoleAssignment(participant=participant, role=role))
+    return assignments
+
+
+def _runtime(ctx: typer.Context) -> RoomRuntime:
+    """Return the room runtime stored by the root callback."""
+    assert isinstance(ctx.obj, RoomRuntime)
+    return ctx.obj
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    root_path: Annotated[
+        Path | None,
+        typer.Option("--root", help="Project root containing the .ctlrm room."),
+    ] = None,
+) -> None:
+    """Coordinate agents through a project-local shared directory."""
+    ctx.obj = RoomRuntime((root_path or Path.cwd()).resolve())
+
+
+@app.command()
+def serve(
+    port: Annotated[int, typer.Option(min=1024, max=65535)] = 8766,
+    data: Annotated[
+        Path | None, typer.Option(help="Override the central user data directory.")
+    ] = None,
+) -> None:
+    """Open a local browser workbench for managed projects and agent terminals."""
+    import uvicorn
+    from ctlrm.managed.projects import ProjectStore
+    from ctlrm.web.app import create_app
+
+    web = create_app(ProjectStore(data), port=port)
+    typer.echo(f"Control room: http://127.0.0.1:{port}/#token={web.state.token}")
+    uvicorn.run(
+        web, host="127.0.0.1", port=port, access_log=False, ws_max_size=65536, ws_max_queue=8
+    )
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    participant_id: Annotated[str, typer.Option("--id", help="Room author's participant ID.")],
+    name: Annotated[str, typer.Option(help="Display name for the room author.")],
+    assign: Annotated[
+        list[str],
+        typer.Option(help="Role assignment as PARTICIPANT=ROLE; repeat for the full roster."),
+    ],
+    prompt: Annotated[
+        str | None, typer.Option(help="Room prompt; defaults to standard input.")
+    ] = None,
+    prompt_file: Annotated[
+        Path | None,
+        typer.Option("--prompt-file", help="Read the room prompt from a UTF-8 file."),
+    ] = None,
+    kind: Annotated[str, typer.Option(help="Participant kind.")] = "agent",
+    provider: Annotated[str | None, typer.Option(help="Agent provider, if applicable.")] = None,
+    restart_command: Annotated[
+        str | None,
+        typer.Option("--restart-command", help="Command to restart this session; stored only."),
+    ] = None,
+    capability: Annotated[list[str], typer.Option(help="Author capability; may be repeated.")] = [],
+) -> None:
+    """Create the prompt and role roster, then register their author."""
+    if prompt is not None and prompt_file is not None:
+        raise typer.BadParameter("use either --prompt or --prompt-file, not both")
+
+    def initialize() -> None:
+        room = RoomManifest(
+            id=f"room-{uuid4().hex}",
+            author=participant_id,
+            created_at=_now(),
+            assignments=_parse_assignments(assign),
+            prompt=_read_text(prompt, prompt_file),
+        )
+        result = _runtime(ctx).initialize(
+            room,
+            name=name,
+            kind=kind,
+            provider=provider,
+            restart_command=restart_command,
+            capabilities=capability,
+            joined_at=_now(),
+        )
+        typer.echo(result.room_path)
+        typer.echo(result.signature_path)
+        if not result.created:
+            typer.echo("room already initialized; author registration recovered", err=True)
+
+    _run(initialize)
+
+
+@app.command()
+def join(
+    ctx: typer.Context,
+    participant_id: Annotated[str, typer.Option("--id", help="Assigned participant ID.")],
+    name: Annotated[str, typer.Option(help="Participant display name.")],
+    kind: Annotated[str, typer.Option(help="Participant kind.")] = "agent",
+    provider: Annotated[str | None, typer.Option(help="Agent provider, if applicable.")] = None,
+    restart_command: Annotated[
+        str | None,
+        typer.Option("--restart-command", help="Command to restart this session; stored only."),
+    ] = None,
+    capability: Annotated[
+        list[str], typer.Option(help="Participant capability; may be repeated.")
+    ] = [],
+) -> None:
+    """Accept the role assigned in the room roster and write a signature."""
+
+    def register() -> None:
+        path = _runtime(ctx).join_participant(
+            participant_id=participant_id,
+            name=name,
+            kind=kind,
+            provider=provider,
+            capabilities=capability,
+            restart_command=restart_command,
+            joined_at=_now(),
+        )
+        typer.echo(path)
+
+    _run(register)
+
+
+@app.command()
+def send(
+    ctx: typer.Context,
+    sender: Annotated[str, typer.Option("--from", help="Registered sender ID.")],
+    recipient: Annotated[str, typer.Option("--to", help="Registered recipient ID.")],
+    title: Annotated[str, typer.Option(help="Short message title.")],
+    kind: Annotated[str, typer.Option(help="Message kind.")] = "message",
+    body: Annotated[
+        str | None, typer.Option(help="Message body; defaults to standard input.")
+    ] = None,
+    body_file: Annotated[
+        Path | None,
+        typer.Option("--body-file", help="Read the body from a UTF-8 file."),
+    ] = None,
+    file: Annotated[list[str], typer.Option(help="Related file path; may be repeated.")] = [],
+    message_id: Annotated[str | None, typer.Option("--id", help="Explicit message ID.")] = None,
+    execution_id: Annotated[str | None, typer.Option(help="Owning workflow execution ID.")] = None,
+) -> None:
+    """Deliver an immutable message between registered participants."""
+    if body is not None and body_file is not None:
+        raise typer.BadParameter("use either --body or --body-file, not both")
+
+    def deliver() -> None:
+        identifier = (
+            message_id or f"msg-{datetime.now(timezone.utc):%Y%m%dT%H%M%S}-{uuid4().hex[:8]}"
+        )
+        message = MailboxMessage(
+            id=identifier,
+            from_=sender,
+            to=recipient,
+            kind=kind,
+            title=title,
+            status="new",
+            created_at=_now(),
+            files=file,
+            body=_read_text(body, body_file),
+        )
+        runtime = _runtime(ctx)
+        if (runtime.root / "area.yaml").exists():
+            from ctlrm.managed.area import Area
+            from ctlrm.managed.workflows import WorkflowService
+
+            area = Area.load(runtime.project_root)
+            if area.data["mode"] == "workflow":
+                if not execution_id:
+                    raise ValueError("workflow messages require --execution-id from the assignment")
+                typer.echo(WorkflowService(area).send_message(message, execution_id))
+                return
+        if execution_id:
+            raise ValueError("execution IDs require a managed workflow")
+        typer.echo(runtime.send_message(message))
+
+    _run(deliver)
+
+
+@app.command()
+def inbox(
+    ctx: typer.Context,
+    participant: Annotated[str, typer.Option(help="Participant whose inbox should be listed.")],
+) -> None:
+    """List messages in one participant inbox."""
+
+    def show() -> None:
+        """List valid items and diagnose malformed neighbors."""
+        errors: list[tuple[Path, Exception]] = []
+        for message in _runtime(ctx).read_inbox(
+            participant, on_error=lambda path, exc: errors.append((path, exc))
+        ):
+            typer.echo(f"{message.id}\t{message.from_}\t{message.kind}\t{message.title}")
+        _report_invalid_files(errors)
+
+    _run(show)
+
+
+@app.command()
+def participants(ctx: typer.Context) -> None:
+    """List participant signatures and their assigned roles."""
+
+    def show() -> None:
+        """List valid identities and diagnose malformed neighbors."""
+        errors: list[tuple[Path, Exception]] = []
+        for signature in _runtime(ctx).list_signatures(
+            on_error=lambda path, exc: errors.append((path, exc))
+        ):
+            typer.echo(f"{signature.id}\t{signature.role}\t{signature.kind}\t{signature.name}")
+        _report_invalid_files(errors)
+
+    _run(show)
+
+
+def _report_invalid_files(errors: list[tuple[Path, Exception]]) -> None:
+    """Report all invalid files after rendering the valid entries."""
+    for path, error in errors:
+        typer.echo(f"invalid: {path}: {error}", err=True)
+    if errors:
+        raise typer.Exit(2)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run the ctlrm command-line application."""
+    app(args=list(argv) if argv is not None else None, prog_name="ctlrm")
+
+
+if __name__ == "__main__":
+    main()

ctlrm/communication/__init__.py

@@ -0,0 +1 @@
+"""Modules for inter-agent communication."""

ctlrm/communication/terminal.py

@@ -0,0 +1,292 @@
+"""Owned terminal management through libtmux, with process identity checks."""
+
+from pathlib import Path
+from functools import wraps
+import os
+import shutil
+import subprocess
+import shlex
+import signal
+import time
+import sys
+from typing import Protocol
+
+import libtmux
+
+from ctlrm.runtime.location import runtime_path
+from ctlrm.managed.storage import read_record
+
+
+class StopPending(RuntimeError):
+    """An owned process has been signaled but has not exited yet."""
+
+
+def _translate_errors(method):
+    """Keep library-specific exceptions inside the terminal adapter."""
+
+    @wraps(method)
+    def call(*args, **kwargs):
+        """Translate a failed tmux operation into the service error contract."""
+        try:
+            return method(*args, **kwargs)
+        except libtmux.exc.LibTmuxException as error:
+            raise RuntimeError(f"tmux operation failed: {error}") from error
+
+    return call
+
+
+def process_identity(pid: int) -> str | None:
+    """Return an OS start identity, treating dead/zombie processes as absent."""
+    try:
+        value = Path(f"/proc/{pid}/stat").read_text().rsplit(")", 1)[1].split()
+        if value[0] == "Z":
+            return None
+        boot = Path("/proc/sys/kernel/random/boot_id").read_text().strip()
+        return f"{boot}:{pid}:{value[19]}"
+    except FileNotFoundError:
+        return None
+
+
+def children(pid: int) -> list[int]:
+    """Read direct provider children of the stable host process on Linux."""
+    try:
+        text = Path(f"/proc/{pid}/task/{pid}/children").read_text()
+        return [int(value) for value in text.split() if process_identity(int(value))]
+    except FileNotFoundError:
+        return []
+
+
+class Terminal(Protocol):
+    """Boundary faked by deterministic supervisor tests."""
+
+    def exists(self, spec: dict) -> bool:
+        """Return whether the deterministic terminal name is occupied."""
+        ...
+
+    def ensure(self, spec: dict) -> dict:
+        """Create or reconcile a verified owned terminal."""
+        ...
+
+    def adopt(self, spec: dict) -> dict:
+        """Verify an existing launch without creating one if it disappeared."""
+        ...
+
+    def health(self, spec: dict, identity: dict) -> str:
+        """Return running, exited, or missing; mismatched ownership raises."""
+        ...
+
+    def wake(self, spec: dict, identity: dict, reference: str) -> None:
+        """Deliver a bounded literal mailbox reference to a verified provider."""
+        ...
+
+    def stop(self, spec: dict, identity: dict) -> None:
+        """Stop only the verified session and its provider processes."""
+        ...
+
+
+class TmuxTerminal:
+    """One isolated server namespace per coordination area."""
+
+    def __init__(self, area_id: str) -> None:
+        """Use a dedicated socket and ignore user tmux configuration."""
+        self.socket = f"ctlrm-{area_id}"
+        self.server = libtmux.Server(socket_name=self.socket, config_file="/dev/null")
+
+    def _session(self, spec: dict):
+        """Find one exact session name without selecting user terminals."""
+        return self.server.sessions.get(session_name=spec["terminal_name"], default=None)
+
+    @_translate_errors
+    def exists(self, spec: dict) -> bool:
+        """Return whether this generation's terminal name is occupied."""
+        return self._session(spec) is not None
+
+    def _identity(self, spec: dict, session) -> dict:
+        """Verify creation-time environment, host command, root, and process identity."""
+        panes = list(session.panes)
+        if len(panes) != 1:
+            raise ValueError("owned session has an unexpected pane layout")
+        pane = panes[0]
+        token = session.cmd("show-environment", "CTLRM_LAUNCH_TOKEN").stdout
+        if token != [f"CTLRM_LAUNCH_TOKEN={spec['token']}"]:
+            raise ValueError("terminal ownership token mismatch")
+        host_pid = int(pane.pane_pid)
+        expected = [
+            sys.executable,
+            "-m",
+            "ctlrm.managed.host",
+            spec["root"],
+            spec["id"],
+            str(spec["generation"]),
+        ]
+        try:
+            command = Path(f"/proc/{host_pid}/cmdline").read_bytes().split(b"\0")
+            actual = [part.decode() for part in command if part]
+            cwd = Path(f"/proc/{host_pid}/cwd").resolve(strict=True)
+        except FileNotFoundError as error:
+            raise ValueError("terminal host disappeared during identity validation") from error
+        if actual != expected or cwd != Path(spec["root"]):
+            raise ValueError(
+                "terminal host command or worktree mismatch; inspect before reconciliation"
+            )
+        server_pid = int(pane.cmd("display-message", "-p", "#{pid}").stdout[0])
+        host_start, server_start = process_identity(host_pid), process_identity(server_pid)
+        if not host_start or not server_start:
+            raise ValueError("terminal process identity is unavailable")
+        return {
+            "socket": self.socket,
+            "socket_path": pane.cmd("display-message", "-p", "#{socket_path}").stdout[0],
+            "server": server_start,
+            "host": host_start,
+            "pane": pane.pane_id,
+            "host_pid": host_pid,
+            "session": session.session_id,
+        }
+
+    @_translate_errors
+    def ensure(self, spec: dict) -> dict:
+        """Create a stable host or adopt only an exact creation-time identity match."""
+        session = self._session(spec)
+        if session is None:
+            command = [
+                sys.executable,
+                "-m",
+                "ctlrm.managed.host",
+                spec["root"],
+                spec["id"],
+                str(spec["generation"]),
+            ]
+            session = self.server.new_session(
+                session_name=spec["terminal_name"],
+                start_directory=spec["root"],
+                window_command="exec " + shlex.join(command),
+                environment={"CTLRM_LAUNCH_TOKEN": spec["token"]},
+                x=120,
+                y=40,
+            )
+        deadline = time.monotonic() + 2
+        while True:
+            try:
+                identity = self._identity(spec, session)
+                break
+            except ValueError:
+                if time.monotonic() >= deadline:
+                    raise
+                time.sleep(0.02)
+        session.set_option("@ctlrm-area", spec["area_id"])
+        session.set_option("@ctlrm-session", spec["id"])
+        session.set_option("@ctlrm-generation", str(spec["generation"]))
+        return identity
+
+    @_translate_errors
+    def adopt(self, spec: dict) -> dict:
+        """Reconcile an existing launch without starting a process on a race."""
+        session = self._session(spec)
+        if session is None:
+            raise ValueError("launch disappeared before readiness reconciliation")
+        return self._identity(spec, session)
+
+    def _verified(self, spec: dict, identity: dict):
+        """Resolve a recorded terminal and reject server restart/PID reuse."""
+        session = self._session(spec)
+        if session is None:
+            return None
+        try:
+            observed = self._identity(spec, session)
+        except (libtmux.exc.LibTmuxException, ValueError, OSError):
+            # A session can disappear after lookup. Only confirmed absence permits recovery.
+            if (
+                self._session(spec) is None
+                and process_identity(identity["host_pid"]) != identity["host"]
+            ):
+                return None
+            raise
+        if observed != identity:
+            raise ValueError("terminal identity changed; refusing to adopt or stop it")
+        return session
+
+    @_translate_errors
+    def health(self, spec: dict, identity: dict) -> str:
+        """A live host with no provider child is an exited agent, not a healthy pane."""
+        session = self._verified(spec, identity)
+        if session is None:
+            return "missing"
+        if children(identity["host_pid"]):
+            return "running"
+        exit_path = (
+            runtime_path(Path(spec["root"]))
+            / "sessions"
+            / spec["id"]
+            / f"exit-{spec['generation']}.json"
+        )
+        if exit_path.exists():
+            if read_record(exit_path).get("token") != spec["token"]:
+                raise ValueError("provider exit observation has a mismatched launch token")
+            return "exited"
+        return "starting"
+
+    @_translate_errors
+    def wake(self, spec: dict, identity: dict, reference: str) -> None:
+        """Type only a bounded ASCII reference, never a user's multiline prompt."""
+        if (
+            not reference.isascii()
+            or len(reference.encode()) > 256
+            or "\n" in reference
+            or "\r" in reference
+        ):
+            raise ValueError("terminal references must be a single ASCII line of at most 256 bytes")
+        session = self._verified(spec, identity)
+        if session is None or self.health(spec, identity) != "running":
+            raise ValueError("provider is not running")
+        session.panes[0].send_keys(reference, literal=True)
+
+    @_translate_errors
+    def stop(self, spec: dict, identity: dict) -> None:
+        """Kill only the verified dedicated session, propagating terminal hangup."""
+        session = self._verified(spec, identity)
+        if session is not None:
+            host_pid = identity["host_pid"]
+            group = os.getpgid(host_pid)
+            if group != host_pid:
+                raise ValueError("terminal host does not own its process group")
+            os.killpg(group, signal.SIGKILL)
+            # Killing the dedicated process group also closes the pane/session.
+            deadline = time.monotonic() + 2
+            while process_identity(host_pid) == identity["host"] and time.monotonic() < deadline:
+                time.sleep(0.02)
+        if process_identity(identity["host_pid"]) == identity["host"]:
+            raise StopPending("terminal stop is pending; host process still exists")
+
+    @_translate_errors
+    def capture(self, spec: dict, identity: dict) -> str:
+        """Capture bounded recent output from a verified owned terminal."""
+        session = self._verified(spec, identity)
+        if session is None:
+            return "[terminal is missing]"
+        return "\n".join(session.panes[0].capture_pane(start=-200) or [])
+
+    @_translate_errors
+    def attach_command(self, spec: dict, identity: dict, *, readonly: bool = False) -> list[str]:
+        """Build an interactive client command only after verifying the owned generation."""
+        session = self._verified(spec, identity)
+        if session is None:
+            raise ValueError("terminal is missing")
+        # libtmux captures stdio; native attachment needs a caller-owned terminal or PTY.
+        binary = self.server.tmux_bin or shutil.which("tmux")
+        if not binary:
+            raise RuntimeError("tmux executable is missing")
+        return [
+            binary,
+            "-S",
+            identity["socket_path"],
+            "attach-session",
+            *(["-f", "read-only"] if readonly else []),
+            "-t",
+            session.session_id,
+        ]
+
+    def attach(self, spec: dict, identity: dict) -> None:
+        """Attach the interactive client through a verified libtmux session."""
+        result = subprocess.run(self.attach_command(spec, identity))
+        if result.returncode:
+            raise RuntimeError(f"interactive tmux client exited with status {result.returncode}")

ctlrm/managed/__init__.py

@@ -0,0 +1 @@
+"""Managed worktree sessions and durable workflow services."""