sessiontools 0.0.1__tar.gz

sessiontools-0.0.1/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.3
+Name: sessiontools
+Version: 0.0.1
+Summary: The harness layer: sessions, status and idle, one driver per harness - a library first
+Author: Cora 7
+Author-email: Cora 7 <ai-cora@failmode.com>
+Requires-Python: >=3.13

sessiontools-0.0.1/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "sessiontools"
+version = "0.0.1"
+description = "The harness layer: sessions, status and idle, one driver per harness - a library first"
+authors = [
+    { name = "Cora 7", email = "ai-cora@failmode.com" }
+]
+requires-python = ">=3.13"
+# ZERO runtime dependencies, on purpose: sessionmail (click + mcp) will
+# depend on this, and a stranger installing sessionmail must be happy to
+# pull it. A library first.
+dependencies = []
+
+# NO [project.scripts] - by ruling. Mike, voice 12:18 Thu 2026-09-17: "if
+# sessionmail only consumes it via the library, then we don't need to put
+# the session command from sessiontools on our path today. We can put that
+# on when we've migrated all the other commands across." The moment a
+# console script is declared here, every install puts it on the PATH, so
+# the way to keep it off is to not declare it. tests/test_library.py pins
+# this.
+
+[build-system]
+requires = ["uv_build>=0.11.9,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sessiontools-0.0.1/src/sessiontools/__init__.py

@@ -0,0 +1,41 @@
+"""sessiontools - the harness layer: sessions, their status, and how long
+they have been idle - one driver per harness, a library first.
+
+Import it; do not look for a command. There is no console script until the
+cutover (Mike, voice 12:18 Thu 2026-09-17), and the one that arrives then
+is `session`, whose verbs the fleet's callers are already written to.
+
+    from sessiontools import sessions, find, idle_seconds
+
+Every function speaks OUR words - busy, not busy, unknown - never a
+harness's. The first driver is `claude_code`; the day a harness changes a
+status word, that driver changes and nothing above it does.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from sessiontools.claude_code import (
+    SIDECAR_DIR_ENV,
+    Session,
+    find,
+    idle_seconds,
+    sessions,
+    sidecar_dir,
+)
+
+try:
+    __version__ = version("sessiontools")
+except PackageNotFoundError:   # a checkout that is not installed
+    __version__ = "0+unknown"
+
+__all__ = [
+    "SIDECAR_DIR_ENV",
+    "Session",
+    "__version__",
+    "find",
+    "idle_seconds",
+    "sessions",
+    "sidecar_dir",
+]

sessiontools-0.0.1/src/sessiontools/claude_code.py

@@ -0,0 +1,118 @@
+"""Claude Code - the first driver.
+
+Claude Code writes one sidecar per live session, `<dir>/<pid>.json`, and
+keeps its `status` and `updatedAt` current as the session works. Three of
+our tools each grew a private reader of that file (sessionmail's
+`_seat._sidecar_idle`, taskmaster's `agents/discovery.py`, `session get
+idle`); this is the one copy they share.
+
+The words are the harness's, not ours. Claude Code says `busy`, `shell`,
+`idle`, `waiting`; a driver translates: busy is busy, anything else is
+not, and no sidecar is unknown. Nothing above this module should ever
+see a harness's vocabulary (Cora, by mail 11:50 Thu 2026-09-17: "the API
+must not speak Claude Code's vocabulary ... the day a status word
+changes, one driver changes and nothing else does").
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+HARNESS = "claude-code"
+
+#: Where the sidecars live. The same rule every reader already used:
+#: `SESSION_SIDECAR_DIR`, else `~/.claude/sessions`.
+SIDECAR_DIR_ENV = "SESSION_SIDECAR_DIR"
+
+
+def sidecar_dir(env: dict[str, str] | None = None) -> Path:
+    env = os.environ if env is None else env
+    return Path(env.get(SIDECAR_DIR_ENV) or (Path.home() / ".claude" / "sessions"))
+
+
+@dataclass(frozen=True)
+class Session:
+    """One live session as the harness reports it, in our words."""
+
+    id: str
+    harness: str
+    busy: bool
+    updated_at: float          # epoch seconds, when status last changed
+    pid: int | None = None
+    cwd: str | None = None
+    name: str | None = None
+    agent: str | None = None
+    raw_status: str | None = None   # the harness's own word, for the curious
+    path: Path | None = None        # the sidecar it came from
+
+    def idle_seconds(self, now: float | None = None) -> float:
+        """0 while busy; else seconds since the status last changed."""
+        if self.busy:
+            return 0.0
+        now = time.time() if now is None else now
+        return max(0.0, now - self.updated_at)
+
+
+def _read(path: Path) -> Session | None:
+    """One sidecar -> one Session, or None when it is not one: unreadable,
+    not JSON, not a dict, or missing the two fields a verdict needs."""
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    sid = data.get("sessionId")
+    status = data.get("status")
+    updated = data.get("updatedAt")
+    if not isinstance(sid, str) or not status or updated is None:
+        return None
+    try:
+        updated_at = float(updated) / 1000.0
+    except (TypeError, ValueError):
+        return None
+    return Session(
+        id=sid,
+        harness=HARNESS,
+        busy=(status == "busy"),
+        updated_at=updated_at,
+        pid=data.get("pid") if isinstance(data.get("pid"), int) else None,
+        cwd=data.get("cwd") if isinstance(data.get("cwd"), str) else None,
+        name=data.get("name") if isinstance(data.get("name"), str) else None,
+        agent=data.get("agent") if isinstance(data.get("agent"), str) else None,
+        raw_status=status if isinstance(status, str) else None,
+        path=path,
+    )
+
+
+def sessions(env: dict[str, str] | None = None) -> list[Session]:
+    """Every session with a readable sidecar, newest status first. A
+    directory that is missing or unreadable is an empty list, not an
+    error: no harness here is a fact, not a fault."""
+    try:
+        paths = sorted(sidecar_dir(env).glob("*.json"))
+    except OSError:
+        return []
+    found = [s for s in (_read(p) for p in paths) if s is not None]
+    return sorted(found, key=lambda s: s.updated_at, reverse=True)
+
+
+def find(session_id: str, env: dict[str, str] | None = None) -> Session | None:
+    """The session with this id, or None when no sidecar names it."""
+    for s in sessions(env):
+        if s.id == session_id:
+            return s
+    return None
+
+
+def idle_seconds(session_id: str, now: float | None = None,
+                 env: dict[str, str] | None = None) -> float | None:
+    """The one number the pager wants: 0 while busy, else seconds since
+    the status last changed; None when nothing can be said. Same rule as
+    every reader it replaces."""
+    s = find(session_id, env)
+    return None if s is None else s.idle_seconds(now)

sessiontools-0.0.1/src/sessiontools/cli.py

@@ -0,0 +1,14 @@
+"""The `session` command - NOT YET, by ruling.
+
+Mike, voice 12:18 Thu 2026-09-17: *"if sessionmail only consumes it via the
+library, then we don't need to put the session command from sessiontools on
+our path today. We can put that on when we've migrated all the other
+commands across."*
+
+So this module is a placeholder on purpose: no click, no `main`, nothing
+`pyproject.toml` points at. When the cutover comes, the command is
+`session` - `session list`, `session get idle` - the verbs the fleet's
+callers (sessionview, voicemode, the shell aliases) are already written to,
+and exactly one package owns it on the PATH. See
+`openspec/changes/the-session-command`.
+"""