televibe 0.1.0__py3-none-any.whl

televibe/__init__.py

@@ -0,0 +1,23 @@
+"""Run headless coding agents one turn at a time, as resumable sessions with a typed event stream."""
+
+import sys
+
+if sys.platform == "win32":
+    raise ImportError(
+        "televibe supports Linux and macOS only: it kills an agent by its process group, "
+        "which Windows does not have"
+    )
+
+from televibe.access import Access
+from televibe.account import Account
+from televibe.engine import Engine, Stranded
+from televibe.errors import TelevibeError
+from televibe.events import Done, Failed, FailReason, Message, Queued, Started, ToolUse, Warning
+from televibe.providers import ClaudeCode, Codex
+from televibe.session import Session
+from televibe.turn import Turn
+
+__all__ = [
+    "Access", "Account", "ClaudeCode", "Codex", "Done", "Engine", "FailReason", "Failed", "Message",
+    "Queued", "Session", "Started", "Stranded", "TelevibeError", "ToolUse", "Turn", "Warning",
+]

televibe/access.py

@@ -0,0 +1,11 @@
+"""How much an agent may change (section 9)."""
+
+import enum
+
+
+class Access(enum.Enum):
+    """The same name does not give the same guarantee across providers (see SPEC.md section 9)."""
+
+    READ_ONLY = "read_only"
+    WORKSPACE_WRITE = "workspace_write"
+    FULL = "full"

televibe/account.py

@@ -0,0 +1,26 @@
+"""An agent account: one directory with its login, settings and transcripts (section 3)."""
+
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from types import MappingProxyType
+
+from televibe.env import check_credentials
+from televibe.errors import TelevibeError
+
+
+class Account:
+    __slots__ = ("_credentials", "home")
+
+    def __init__(self, home: str | os.PathLike[str], credentials: Mapping[str, str] | None = None) -> None:
+        if home is None:
+            raise TelevibeError("Account needs a home directory; televibe never falls back to ~/.claude or ~/.codex")
+        self.home = Path(home).expanduser().resolve()
+        self._credentials = check_credentials(credentials or {})
+
+    @property
+    def credentials(self) -> Mapping[str, str]:
+        return MappingProxyType(self._credentials)
+
+    def __repr__(self) -> str:
+        return f"Account(home={str(self.home)!r}, credentials=<{len(self._credentials)} hidden>)"

televibe/engine.py

@@ -0,0 +1,177 @@
+"""The Engine: ordering, recovery, and the factory for turns."""
+
+from __future__ import annotations
+
+import asyncio
+import fcntl
+import json
+import logging
+import math
+import os
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+from televibe.access import Access
+from televibe.env import check_turn_env
+from televibe.errors import TelevibeError
+from televibe.markers import Markers
+from televibe.procinfo import kill_group, start_time
+from televibe.providers.base import TurnOptions
+from televibe.scheduler import Scheduler
+from televibe.session import Session, unbound
+from televibe.turn import Runner, Turn, TurnSpec
+
+log = logging.getLogger("televibe")
+
+_EMPTY: Mapping[str, Any] = MappingProxyType({})
+_TURN_ID = re.compile(r"[0-9a-f]{32}")
+
+
+@dataclass(frozen=True, slots=True)
+class Stranded:
+    """A turn an earlier process left in flight (REQ-STATE-3).
+
+    `session` is not bound to a provider; run it again with
+    `provider.load_session(stranded.session.dump())`.
+    """
+
+    turn_id: str
+    tag: dict[str, Any]
+    session: Session
+    started_at: datetime
+    killed: bool
+
+
+def _kill_if_same(pgid: object, recorded: object) -> bool:
+    """Kill the group only if its leader exists and started when recorded (REQ-STATE-4)."""
+    if not isinstance(pgid, int) or not isinstance(recorded, str):
+        return False
+    if start_time(pgid) != recorded:
+        return False
+    kill_group(pgid)
+    return True
+
+
+class Engine:
+    def __init__(self, state_dir: str | os.PathLike[str], max_concurrent: int = 1) -> None:
+        if isinstance(max_concurrent, bool) or not isinstance(max_concurrent, int) or max_concurrent < 1:
+            raise TelevibeError("max_concurrent must be a positive int")
+        self._markers = Markers(Path(state_dir).expanduser())
+        self._scheduler = Scheduler(max_concurrent)
+        self._runners: dict[str, Runner] = {}
+        self._state = "new"
+        self._lock_fd: int | None = None
+
+    async def __aenter__(self) -> Engine:
+        if self._state != "new":
+            raise TelevibeError("an Engine is entered once")
+        self._markers.open()
+        self._lock()
+        self._state = "open"
+        return self
+
+    def _lock(self) -> None:
+        """One engine per state_dir, so stranded() never sees another engine's live turn (REQ-STATE-3)."""
+        state_dir = self._markers.dir.parent
+        fd = os.open(state_dir / "lock", os.O_RDWR | os.O_CREAT, 0o600)
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            os.close(fd)
+            raise TelevibeError(f"state_dir {state_dir} is in use by another Engine") from None
+        self._lock_fd = fd
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        self._state = "closed"
+        runners = list(self._runners.values())
+        for runner in runners:
+            runner.cancel("engine closed")  # REQ-CANCEL-7
+        await asyncio.gather(*(runner.wait_ended() for runner in runners), return_exceptions=True)
+        if self._lock_fd is not None:
+            os.close(self._lock_fd)  # closing the descriptor releases the lock
+            self._lock_fd = None
+
+    def _require_open(self) -> None:
+        if self._state != "open":
+            raise TelevibeError("the Engine is not open: use it inside `async with Engine(...)`")
+
+    def turn(
+        self,
+        prompt: str,
+        *,
+        session: Session,
+        access: Access = Access.READ_ONLY,
+        lane: str | None = None,
+        model: str | None = None,
+        instructions: str | None = None,
+        env: Mapping[str, str] = _EMPTY,
+        add_dirs: Sequence[str | os.PathLike[str]] = (),
+        timeout_s: float = 900,
+        tag: Mapping[str, Any] = _EMPTY,
+    ) -> Turn:
+        self._require_open()
+        if not isinstance(prompt, str) or not prompt:
+            raise TelevibeError("prompt must be a non-empty str")
+        try:
+            prompt.encode()
+        except UnicodeEncodeError:
+            raise TelevibeError("prompt must be text that encodes to UTF-8 (it holds a lone surrogate)") from None
+        if not isinstance(session, Session):
+            raise TelevibeError(f"session must be a Session, got {type(session).__name__}")
+        provider = session._bound
+        if provider is None:
+            raise TelevibeError("this session is not bound to a provider; use provider.load_session(session.dump())")
+        if not isinstance(access, Access):
+            raise TelevibeError(f"access must be an Access, got {access!r}")
+        provider.check_access(access)
+        for name, value in (("lane", lane), ("model", model), ("instructions", instructions)):
+            if value is not None and not isinstance(value, str):
+                raise TelevibeError(f"{name} must be a str or None")
+            if value is not None and "\0" in value:
+                raise TelevibeError(f"{name} must not contain a NUL character")
+        if isinstance(timeout_s, bool) or not isinstance(timeout_s, (int, float)) or not math.isfinite(timeout_s) or timeout_s <= 0:
+            raise TelevibeError("timeout_s must be a positive, finite number of seconds")
+        if isinstance(add_dirs, (str, bytes, os.PathLike)):
+            raise TelevibeError("add_dirs must be a sequence of paths, not one path")
+        if any("\0" in os.fspath(d) for d in add_dirs if isinstance(d, (str, os.PathLike))):
+            raise TelevibeError("add_dirs must not contain a NUL character")
+        dirs = tuple(Path(d).expanduser().resolve() for d in add_dirs)
+        turn_env = check_turn_env(env)
+        try:
+            tag_copy = json.loads(json.dumps(dict(tag)))
+        except (TypeError, ValueError) as exc:
+            raise TelevibeError(f"tag must be a JSON-serializable mapping: {exc}") from None
+        spec = TurnSpec(prompt, TurnOptions(access, model, instructions, dirs), lane, turn_env, float(timeout_s), tag_copy)
+        return Turn(Runner(self, provider, provider.prepare(session), spec))
+
+    async def stranded(self) -> list[Stranded]:
+        """Every marker an earlier process left; kills its agent if still alive (REQ-STATE-3, REQ-STATE-4)."""
+        self._require_open()
+        found = []
+        for marker in self._markers.all():
+            turn_id = marker.get("turn_id")
+            if not isinstance(turn_id, str) or turn_id in self._runners:
+                continue
+            try:
+                session = unbound(marker["session"])
+                started_at = datetime.fromisoformat(marker["started_at"])
+            except (KeyError, TypeError, ValueError, TelevibeError):
+                log.warning("televibe: marker %s is malformed; skipping it", turn_id)
+                continue
+            killed = await asyncio.to_thread(_kill_if_same, marker.get("pgid"), marker.get("proc_start"))
+            found.append(Stranded(turn_id, dict(marker.get("tag") or {}), session, started_at, killed))
+        return found
+
+    def forget(self, turn_id: str) -> None:
+        """Remove a stranded marker (REQ-STATE-5)."""
+        self._require_open()
+        if not isinstance(turn_id, str) or not _TURN_ID.fullmatch(turn_id):
+            raise TelevibeError(f"not a turn id: {turn_id!r}")
+        if turn_id in self._runners:
+            raise TelevibeError(f"turn {turn_id} is live in this engine, not stranded")
+        self._markers.remove(turn_id)

televibe/env.py

@@ -0,0 +1,69 @@
+"""The child process environment (REQ-ENV-1..3)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from typing import TYPE_CHECKING
+
+from televibe.errors import TelevibeError
+
+if TYPE_CHECKING:
+    from televibe.account import Account
+
+INHERITED = frozenset({"PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "TERM", "TMPDIR", "TZ"})
+API_KEYS = frozenset({"ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "OPENAI_API_KEY"})
+ACCOUNT_VARS = frozenset({"CLAUDE_CONFIG_DIR", "CODEX_HOME"})
+
+
+def _check_str_map(env: Mapping[str, str], where: str) -> dict[str, str]:
+    if not isinstance(env, Mapping):
+        raise TelevibeError(f"{where} must be a mapping of str to str")
+    for key, value in env.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+            raise TelevibeError(f"{where} must map str to str; {key!r} does not")
+        if not key or "=" in key or "\0" in key or "\0" in value:
+            raise TelevibeError(f"{where}: {key!r} is not a name and value a process environment can hold")
+    return dict(env)
+
+
+def refuse_account_vars(names: Iterable[str], where: str) -> None:
+    found = sorted(ACCOUNT_VARS.intersection(names))
+    if found:
+        raise TelevibeError(f"{', '.join(found)} refused in {where}: choose the account through Account")
+
+
+def refuse_api_keys(names: Iterable[str], where: str) -> None:
+    found = sorted(API_KEYS.intersection(names))
+    if found:
+        raise TelevibeError(
+            f"{', '.join(found)} refused in {where}: televibe v1 runs agents on subscriptions only, "
+            "and an API key would bill the API"
+        )
+
+
+def check_credentials(credentials: Mapping[str, str]) -> dict[str, str]:
+    checked = _check_str_map(credentials, "credentials")
+    refuse_api_keys(checked, "credentials")
+    refuse_account_vars(checked, "credentials")
+    return checked
+
+
+def check_turn_env(env: Mapping[str, str]) -> dict[str, str]:
+    checked = _check_str_map(env, "a turn's env")
+    refuse_api_keys(checked, "a turn's env")
+    refuse_account_vars(checked, "a turn's env")
+    return checked
+
+
+def child_env(
+    account_var: str,
+    account: Account,
+    turn_env: Mapping[str, str],
+    parent: Mapping[str, str] = os.environ,
+) -> dict[str, str]:
+    env = {name: value for name, value in parent.items() if name in INHERITED or name.startswith("LC_")}
+    env[account_var] = str(account.home)
+    env.update(account.credentials)
+    env.update(turn_env)
+    return env

televibe/errors.py

@@ -0,0 +1,5 @@
+"""The one exception televibe raises at a call site."""
+
+
+class TelevibeError(Exception):
+    """A misuse caught before any agent process starts (REQ-API-2)."""

televibe/events.py

@@ -0,0 +1,76 @@
+"""The events a turn yields (section 5)."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from televibe.session import Session
+
+
+class FailReason(enum.StrEnum):
+    TIMEOUT = "timeout"
+    CANCELLED = "cancelled"
+    SESSION_LOST = "session_lost"
+    PROVIDER_ERROR = "provider_error"
+    SPAWN_ERROR = "spawn_error"
+
+
+@dataclass(frozen=True, slots=True)
+class Queued:
+    """The turn is waiting for a free slot, lane or session."""
+
+
+@dataclass(frozen=True, slots=True)
+class Started:
+    """The agent process is running and reported its session id."""
+
+    session: Session
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    """One complete assistant message."""
+
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class ToolUse:
+    """The agent started a tool (a command, an edit, a search)."""
+
+    name: str
+    detail: str
+
+
+@dataclass(frozen=True, slots=True)
+class Warning:  # noqa: A001 - the spec's name; it shadows the builtin only inside this module
+    """The agent reported a problem that did not end the turn."""
+
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class Done:
+    """Terminal: the turn finished. `text` is the final answer."""
+
+    session: Session
+    text: str
+    usage: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class Failed:
+    """Terminal: the turn did not finish."""
+
+    reason: FailReason
+    session: Session | None
+    detail: str
+    partial: str
+
+
+type Event = Queued | Started | Message | ToolUse | Warning | Done | Failed
+
+TERMINAL = (Done, Failed)

televibe/lines.py

@@ -0,0 +1,44 @@
+"""JSON records from an agent's stdout, one per line (REQ-RUN-3)."""
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+LINE_LIMIT = 8 * 1024 * 1024
+_CHUNK = 64 * 1024
+
+
+def _decode(line: bytes) -> dict[str, Any] | None:
+    line = line.strip()
+    if not line:
+        return None
+    try:
+        value = json.loads(line)
+    except ValueError:  # includes UnicodeDecodeError
+        return None
+    return value if isinstance(value, dict) else None
+
+
+async def json_records(stream: asyncio.StreamReader, limit: int = LINE_LIMIT) -> AsyncIterator[dict[str, Any]]:
+    """Yield each line that is a JSON object; skip everything else, including lines over `limit` bytes."""
+    buf = bytearray()
+    skipping = False  # inside a line that already went over the limit
+    while chunk := await stream.read(_CHUNK):
+        start = 0
+        while (newline := chunk.find(b"\n", start)) >= 0:
+            if skipping:
+                skipping = False
+            else:
+                buf += chunk[start:newline]
+                if len(buf) <= limit and (record := _decode(bytes(buf))) is not None:
+                    yield record
+            buf.clear()
+            start = newline + 1
+        if not skipping:
+            buf += chunk[start:]
+            if len(buf) > limit:
+                buf.clear()
+                skipping = True
+    if buf and not skipping and (record := _decode(bytes(buf))) is not None:
+        yield record

televibe/markers.py

@@ -0,0 +1,41 @@
+"""One marker file per in-flight turn (section 11)."""
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger("televibe")
+
+
+class Markers:
+    def __init__(self, state_dir: Path) -> None:
+        self.dir = state_dir / "turns"
+
+    def open(self) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def write(self, turn_id: str, data: dict[str, Any]) -> None:
+        path = self.dir / f"{turn_id}.json"
+        tmp = self.dir / f".{turn_id}.json.tmp"
+        with open(tmp, "w") as f:
+            json.dump(data, f)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+
+    def remove(self, turn_id: str) -> None:
+        (self.dir / f"{turn_id}.json").unlink(missing_ok=True)
+
+    def all(self) -> list[dict[str, Any]]:
+        found = []
+        for path in sorted(self.dir.glob("*.json")):
+            try:
+                data = json.loads(path.read_text())
+            except (OSError, ValueError):
+                log.warning("televibe: skipping unreadable marker %s", path)
+                continue
+            if isinstance(data, dict):
+                found.append(data)
+        return found

televibe/procinfo.py

@@ -0,0 +1,50 @@
+"""Process facts televibe needs: a start time to recognize a pid, and a group kill."""
+
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+
+def start_time(pid: int) -> str | None:
+    """An opaque start time for `pid`, or None if there is no such process.
+
+    Comparing it with a recorded value tells a live agent from a recycled pid (REQ-STATE-4).
+    """
+    if sys.platform.startswith("linux"):
+        try:
+            stat = Path(f"/proc/{pid}/stat").read_text()
+        except OSError:
+            return None
+        return stat.rsplit(")", 1)[1].split()[19]  # field 22, starttime
+    try:
+        result = subprocess.run(
+            ["ps", "-o", "lstart=", "-p", str(pid)],
+            capture_output=True,
+            text=True,
+            env={"PATH": "/bin:/usr/bin", "LC_ALL": "C"},
+            check=False,
+        )
+    except OSError:
+        return None
+    value = result.stdout.strip()
+    return value if result.returncode == 0 and value else None
+
+
+def kill_group(pgid: int) -> None:
+    """SIGKILL the whole process group; silent if it is already gone (REQ-CANCEL-1)."""
+    try:
+        os.killpg(pgid, signal.SIGKILL)
+    except (ProcessLookupError, PermissionError):
+        pass
+
+
+def group_alive(pgid: int) -> bool:
+    try:
+        os.killpg(pgid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True

televibe/providers/__init__.py

@@ -0,0 +1,6 @@
+"""Agent providers."""
+
+from televibe.providers.claude import ClaudeCode
+from televibe.providers.codex import Codex
+
+__all__ = ["ClaudeCode", "Codex"]

televibe/providers/base.py

@@ -0,0 +1,101 @@
+"""What every provider supplies: sessions, a command line, and a stream parser."""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+from televibe.access import Access
+from televibe.account import Account
+from televibe.errors import TelevibeError
+from televibe.events import Done, Event, FailReason
+from televibe.session import Session, parse_dump
+
+
+@dataclass(frozen=True, slots=True)
+class TurnOptions:
+    access: Access
+    model: str | None
+    instructions: str | None
+    add_dirs: tuple[Path, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class Failure:
+    """How a provider says a turn failed; the runner turns it into `Failed`."""
+
+    reason: FailReason
+    detail: str
+
+
+class Parser(ABC):
+    """Reads one turn's records. `session` gains its id once the agent reports it."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+        self.terminal: Done | Failure | None = None
+
+    @abstractmethod
+    def feed(self, record: dict[str, Any]) -> list[Event]:
+        """Non-terminal events for one record; sets `terminal` on a terminal record."""
+
+    @abstractmethod
+    def finish(self, returncode: int, stderr_tail: str) -> Done | Failure:
+        """The turn's outcome once the process has exited."""
+
+
+class Provider(ABC):
+    kind: ClassVar[str]
+    binary: ClassVar[str]
+    account_var: ClassVar[str]
+    access_levels: ClassVar[frozenset[Access]]
+    fixed_ids: ClassVar[bool]
+
+    def __init__(self, account: Account) -> None:
+        if not isinstance(account, Account):
+            raise TelevibeError(f"{type(self).__name__} needs an Account, got {type(account).__name__}")
+        self.account = account
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(account={self.account!r})"
+
+    def new_session(self, cwd: str | os.PathLike[str], id: str | None = None) -> Session:
+        if id is not None and not self.fixed_ids:
+            raise TelevibeError(f"{self.kind} names its own sessions; new_session takes no id")
+        if id is not None and (not isinstance(id, str) or not id):
+            raise TelevibeError("a fixed session id must be a non-empty str")
+        return self._session(cwd, id, started=False)
+
+    def resume_session(self, cwd: str | os.PathLike[str], id: str) -> Session:
+        if not isinstance(id, str) or not id:
+            raise TelevibeError("resume_session needs the session's non-empty id")
+        return self._session(cwd, id, started=True)
+
+    def load_session(self, text: str) -> Session:
+        data = parse_dump(text)
+        if data["provider"] != self.kind:
+            raise TelevibeError(f"this session belongs to {data['provider']!r}, not {self.kind!r}")
+        if Path(data["home"]) != self.account.home:
+            raise TelevibeError(f"this session belongs to account home {data['home']}, not {self.account.home}")
+        return Session(self.kind, self.account.home, Path(data["cwd"]), data["id"], data["started"], _bound=self)
+
+    def _session(self, cwd: str | os.PathLike[str], id: str | None, *, started: bool) -> Session:
+        return Session(self.kind, self.account.home, Path(cwd).expanduser().resolve(), id, started, _bound=self)
+
+    def check_access(self, access: Access) -> None:
+        if access not in self.access_levels:
+            supported = ", ".join(sorted(level.name for level in self.access_levels))
+            raise TelevibeError(f"{self.kind} does not support Access.{access.name}; it supports {supported}")
+
+    def prepare(self, session: Session) -> Session:
+        """The session as the turn will run it."""
+        return session
+
+    @abstractmethod
+    def argv(self, session: Session, options: TurnOptions) -> list[str]: ...
+
+    @abstractmethod
+    def parser(self, session: Session) -> Parser: ...