sessiontools 0.0.3__tar.gz → 0.0.4__tar.gz

{sessiontools-0.0.3 → sessiontools-0.0.4}/PKG-INFO

@@ -1,7 +1,9 @@
 Metadata-Version: 2.3
 Name: sessiontools
-Version: 0.0.3
+Version: 0.0.4
 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-Dist: pyyaml>=6
+Requires-Dist: jsonschema>=4
 Requires-Python: >=3.11

sessiontools-0.0.4/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "sessiontools"
+version = "0.0.4"
+description = "The harness layer: sessions, status and idle, one driver per harness - a library first"
+authors = [
+    { name = "Cora 7", email = "ai-cora@failmode.com" }
+]
+# >=3.11, not the recipe's >=3.13: sessionmail (the first consumer) declares
+# >=3.11, and uv resolves for EVERY version a project allows, so a stricter
+# floor here made sessionmail's `uv sync` unsatisfiable (Pip, 13:02 Thu
+# 2026-09-17). Measured: the suite passes on 3.11, 3.12 and 3.13; nothing in
+# the tree needs 3.13.
+requires-python = ">=3.11"
+# ONE runtime dependency, and only for `session start`: agent front matter
+# is YAML (the same YAML Claude Code reads itself). Mike, voice 00:12 Tue
+# 2026-09-29, asked "Can start pull in the YAML library, just for itself?":
+# "Um, yes." So PyYAML is declared here and imported by exactly one module,
+# `sessiontools.start.agentfile`; `import sessiontools` (the library
+# sessionmail depends on) still imports nothing outside the standard library.
+# tests/test_cli.py pins both halves.
+# The SECOND: jsonschema, for `session settings` alone - each tool ships a
+# JSON Schema and the reader checks the merged result against it. No
+# configuration library for the layering (Mike, voice 19:15 Sat 2026-10-03,
+# Cora /RULINGS 4600); imported inside `sessiontools.settings.check_schema`,
+# so `import sessiontools` still reaches nothing outside the standard library.
+dependencies = ["PyYAML>=6", "jsonschema>=4"]
+
+# THE `session` COMMAND - ruled at the cutover. Mike, voice 23:25-23:28 Mon
+# 2026-09-28, the session repo just moved aside: sessiontools provides it
+# ("Ah, yes, it should"), same verbs, ported as package code ("port it
+# nicely"), superseding his 12:18 Thu 2026-09-17 "not on our path today".
+# Exactly one package owns `session` on the PATH; from here it is this one.
+# argparse and the library; PyYAML for `session start` alone (above).
+[project.scripts]
+session = "sessiontools.cli:main"
+
+[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"]
+# The oracle tests run the old launcher (tests/oracle/session-start) beside
+# the port. They are manual: `make oracle` (Mike, voice 11:34 Tue 2026-09-29).
+addopts = "--strict-markers -m 'not oracle'"
+markers = [
+    "oracle: runs the old launcher as the byte-equal oracle; manual, `make oracle`",
+]

{sessiontools-0.0.3 → sessiontools-0.0.4}/src/sessiontools/__init__.py

@@ -1,11 +1,12 @@
 """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.
+Import it, or use the command it ships: `session` (Mike, voice 23:25-23:28
+Mon 2026-09-28, when the session repo was retired). `session list` and
+`session get` are built on the functions below; `session start` is its own
+package, `sessiontools.start`; `session send` is disabled (2026-09-29).
 
-    from sessiontools import sessions, find, idle_seconds
+    from sessiontools import sessions, live, find, idle_seconds
     from sessiontools import session_id, current, SESSION_ID_VARS
 
 Every function speaks OUR words - busy, not busy, unknown - never a
@@ -24,6 +25,7 @@ from sessiontools.claude_code import (
     current,
     find,
     idle_seconds,
+    live,
     session_id,
     sessions,
     sidecar_dir,
@@ -42,6 +44,7 @@ __all__ = [
     "current",
     "find",
     "idle_seconds",
+    "live",
     "session_id",
     "sessions",
     "sidecar_dir",

{sessiontools-0.0.3 → sessiontools-0.0.4}/src/sessiontools/claude_code.py

@@ -48,6 +48,10 @@ class Session:
     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
+    proc_start: str | None = None   # the process's start, UTC ctime - liveness
+    started_at: float | None = None  # epoch seconds, when the session began
+    version: str | None = None      # the harness's version
+    tmux: str | None = None         # where the harness says it runs: `sock:@win.%pane`
 
     def idle_seconds(self, now: float | None = None) -> float:
         """0 while busy; else seconds since the status last changed."""
@@ -86,9 +90,20 @@ def _read(path: Path) -> Session | None:
         agent=data.get("agent") if isinstance(data.get("agent"), str) else None,
         raw_status=status if isinstance(status, str) else None,
         path=path,
+        proc_start=data.get("procStart") if isinstance(data.get("procStart"), str) else None,
+        started_at=_ms(data.get("startedAt")),
+        version=data.get("version") if isinstance(data.get("version"), str) else None,
+        tmux=data.get("tmux") if isinstance(data.get("tmux"), str) else None,
     )
 
 
+def _ms(value: object) -> float | None:
+    """Epoch milliseconds -> seconds; None when it is not a number."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value) / 1000.0
+
+
 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
@@ -101,6 +116,16 @@ def sessions(env: dict[str, str] | None = None) -> list[Session]:
     return sorted(found, key=lambda s: s.updated_at, reverse=True)
 
 
+def live(env: dict[str, str] | None = None,
+         procs: dict | None = None) -> list[Session]:
+    """The sessions whose process is running NOW - `sessions()` minus every
+    sidecar a crash left behind or whose pid was reused (`procs.same_process`,
+    the rule `session list` always used). Newest status first."""
+    from sessiontools import procs as _procs
+    table = _procs.table() if procs is None else procs
+    return [s for s in sessions(env) if _procs.same_process(s.pid, s.proc_start, table)]
+
+
 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):

sessiontools-0.0.4/src/sessiontools/cli.py

@@ -0,0 +1,311 @@
+"""`session`: the fleet's session command, owned by sessiontools.
+
+Mike ruled the cutover at 23:25-23:28 Mon 2026-09-28, the session repo just
+moved aside as `session-20260928`: sessiontools provides `session` ("Ah,
+yes, it should"), same verbs, and the verbs are PORTED - package code, "well
+structured, in the right place" - not copied. See
+`openspec/changes/the-session-command`.
+
+    session list [--json] [--no-recap] [--no-context] [--pane NAME]
+    session get [PROP [SEAT]] [--json]
+    session context [SEAT] [--peak] [--max N] [--json]
+    session start ...        launch a session from an agent file
+    session mail ...         (retired: says where each verb went)
+
+One runtime dependency, PyYAML, imported by `session start` alone (Mike,
+00:12 Tue 2026-09-29); the rest is argparse and the library underneath.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+MAIL_MOVED = """session mail: retired with the session repo (2026-09-28). Its verbs live in sessionmail:
+  session mail ls|tree|cat|run PATH  ->  memory ls|tree|cat|run PATH
+  session mail send ...              ->  message send ...
+  session mail arm / wait            ->  pager listen"""
+
+VERBS = (
+    ("list", "the live sessions and their tmux panes"),
+    ("get", "read one property of a live seat"),
+    ("context", "how full a seat's context window is"),
+    ("start", "launch a session from an agent file"),
+    ("settings", "a session's settings, each key with the file that set it"),
+)
+
+
+def usage() -> str:
+    rows = "\n".join(f"  {v:14} {d}" for v, d in VERBS)
+    return (f"Usage: session <verb> [args...]\n\nVerbs:\n{rows}\n\n"
+            "Run `session <verb> --help` for that verb's options.\n")
+
+
+def _list(argv: list[str]) -> int:
+    from sessiontools import listing
+    p = argparse.ArgumentParser(prog="session list",
+                                description="The live sessions and their tmux panes.")
+    p.add_argument("--json", action="store_true", help="machine-readable")
+    p.add_argument("--no-recap", action="store_true", help="accepted; recaps are not ported yet")
+    p.add_argument("--no-context", action="store_true",
+                   help="skip CONTEXT (a transcript read per seat): '-' cells, null keys")
+    p.add_argument("--pane", metavar="NAME", help="print the pane id of the session matching NAME")
+    a = p.parse_args(argv)
+    found = listing.rows()
+    if a.pane is not None:
+        row = listing.match(found, a.pane)
+        if row is None or not row.tmux_pane:
+            print(f"session list: no live session with a pane matches {a.pane!r}", file=sys.stderr)
+            return 1
+        print(row.tmux_pane)
+        return 0
+    if not a.no_context:
+        found = listing.with_context(found)
+    print(listing.render_json(found) if a.json else listing.render_table(found))
+    return 0
+
+
+def _get(argv: list[str]) -> int:
+    from sessiontools import get as _g
+    from sessiontools import listing
+    p = argparse.ArgumentParser(prog="session get", description="Read one property of a live seat.")
+    p.add_argument("prop", nargs="?")
+    p.add_argument("seat", nargs="?")
+    p.add_argument("--json", action="store_true")
+    a = p.parse_args(argv)
+    if a.prop is None:
+        print(_g.table())
+        return 0
+    try:
+        print(_g.get(listing.rows(), a.prop, a.seat, a.json))
+    except _g.GetError as e:
+        print(e, file=sys.stderr)
+        return e.code
+    return 0
+
+
+def _send(argv: list[str]) -> int:
+    from sessiontools import listing
+    from sessiontools import send as _s
+    # Parsed by hand, not argparse: everything after NAME is TEXT, verbatim,
+    # dashes included - except a lone `-v`, the voice-mode trigger
+    # (sessionview's `speak` runs `session send "$name" -v`).
+    if argv[:1] == ["--list"]:
+        return _list([])
+    if not argv or argv[0] in ("-h", "--help"):
+        print(SEND_USAGE)
+        return 0 if argv else 2
+    name, rest = argv[0], argv[1:]
+    text = "v" if rest == ["-v"] else " ".join(rest)
+    if not text:
+        print(SEND_USAGE, file=sys.stderr)
+        return 2
+    found = listing.rows()
+    row = listing.match(found, name)
+    if row is None:
+        print(f"No session matching '{name}'", file=sys.stderr)
+        if found:
+            print("Available sessions:", file=sys.stderr)
+            for r in found:
+                print(f"  {r.name:30} ({r.repo})", file=sys.stderr)
+        return 1
+    if not row.tmux_pane or not row.tmux_socket:
+        print(f"Session '{row.name}' found but has no tmux pane", file=sys.stderr)
+        return 1
+    if not _s.still_belongs(row.tmux_socket, row.tmux_pane, row.session.pid):
+        print(f"Pane {row.tmux_pane} no longer belongs to session '{row.name}' "
+              "(stale/recycled pane) - refusing to send", file=sys.stderr)
+        return 1
+    if _s.send_keys(row.tmux_socket, row.tmux_pane, text):
+        print(f"Sent to {row.name} (pane {row.tmux_pane}): {text}")
+        return 0
+    print(f"Failed to send to pane {row.tmux_pane}", file=sys.stderr)
+    return 1
+
+
+CONTEXT_EPILOG = """\
+Unlike the old session-context (retired 2026-09-28):
+  - the window is the model's; unknown or exceeded prints '?' and the JSON
+    carries max/pct/free as null (the old CLI assumed 1M, the confidently
+    wrong number). $CONTEXT_MAX still tightens a known window; it is no
+    longer --max's default.
+  - a transcript with no usage rows is exit 1, not '0 / 1.00M (0%)'.
+  - a <synthetic> zero reading on a seat that reached its peak is '?', as in
+    session list's CONTEXT; --peak shows the peak.
+  - --dir is gone: with no SEAT and no session in the environment, the newest
+    transcript of the current directory's project is read.
+  - SEAT is a live seat's id prefix, then the `session get` name rule, then
+    any session id prefix among the transcripts."""
+
+
+def _context(argv: list[str]) -> int:
+    """The old `session-context` report, on sessiontools.window: the window
+    is the MODEL's (never a guessed 1M), or --max N when you assert one."""
+    from pathlib import Path
+
+    from sessiontools import listing, window
+    from sessiontools.claude_code import session_id
+    p = argparse.ArgumentParser(prog="session context", epilog=CONTEXT_EPILOG,
+                                formatter_class=argparse.RawDescriptionHelpFormatter,
+                                description="How full a seat's context window is: the "
+                                            "tokens in it now, of the model's window.")
+    p.add_argument("seat", nargs="?", metavar="SEAT",
+                   help="a live seat or a session id / prefix; default: this session")
+    p.add_argument("--peak", action="store_true", help="the session's high-water mark, not now")
+    p.add_argument("--max", type=int, metavar="N", help="assert the window size (tokens, > 0)")
+    p.add_argument("--json", action="store_true", help="machine-readable")
+    a = p.parse_args(argv)
+    if a.max is not None and a.max <= 0:
+        p.error(f"--max must be a positive number of tokens, not {a.max}")
+    ident = a.seat or session_id()
+    live = listing.rows() if ident else []
+    row = listing.match_id_first(live, ident) if ident else None
+    if row is not None:
+        path = window.transcript_path(row.session.cwd, row.session.id)
+    elif ident:
+        path = window.transcript_path(None, ident)
+    else:
+        path = window.newest_transcript(str(Path.cwd()))
+    if path is None:
+        print(f"session context: no transcript for {ident or 'this directory'!r} "
+              f"(under {window.projects_dir()})", file=sys.stderr)
+        return 1
+    u = window.scan(path)
+    if u.usage_rows == 0:
+        print(f"session context: {path.name} has no usage rows yet", file=sys.stderr)
+        return 1
+    used = u.peak if a.peak else u.used
+    size = a.max if a.max else window.resolve_window(u.model, used)
+    zero_tail = not a.peak and u.used == 0 and u.peak > 0
+    pct = used * 100 // size if size and not zero_tail else None
+    free = size - used if size and not zero_tail else None
+    if a.json:
+        print(json.dumps({"used": used, "peak": u.peak, "max": size, "pct": pct,
+                          "free": free, "session": path.stem, "model": u.model}))
+        return 0
+    tag = " [peak]" if a.peak else ""
+    fmt = window.fmt_tokens
+    if zero_tail:
+        print(f"Context: ? - the last reading is a <synthetic> zero; the peak was "
+              f"{fmt(u.peak)} (--peak)")
+    elif size is None:
+        print(f"Context: {fmt(used)} / ? - {window.why_unknown(u.model, used)} "
+              f"(--max N asserts one){tag}")
+    else:
+        print(f"Context: {fmt(used)} / {fmt(size)} ({pct}%) · {fmt(free)} free{tag}")
+    return 0
+
+
+def _start(argv: list[str]) -> int:
+    try:
+        from sessiontools.start import main as start_main  # Cora's port
+    except ImportError as e:
+        # The port has landed, so a failed import here is a broken install,
+        # never an unported verb. PyYAML is start's one runtime dependency
+        # and the likeliest thing missing. Exit 1: the launch failed (2 is
+        # usage or a refusal, and this is neither).
+        missing = "PyYAML" if e.name == "yaml" else (e.name or "a module")
+        print(f"session start: broken install - {missing} will not import ({e}); "
+              "reinstall sessiontools with its dependencies: "
+              "uv tool install --editable --reinstall CHECKOUT", file=sys.stderr)
+        return 1
+    return start_main(argv)
+
+
+SEND_USAGE = """Usage:
+  session send NAME TEXT...   type TEXT into the session matching NAME, then Enter
+  session send NAME -v        send 'v' + Enter (the voice-mode trigger)
+  session send --list         the live sessions (session list)
+
+NAME matches part of a session's name or repo, or a prefix of its id; the
+first match wins. TEXT is joined with spaces and typed literally."""
+
+
+#: `session send` is DISABLED - Mike, voice 00:32 Tue 2026-09-29: "I
+#: accidentally ran session send, and then it wrote something into your pane
+#: ... we should disable it ... keep it somewhere in case I want it back ...
+#: so it's not in the help and it's not available as a command ... it's too
+#: tempting. If it's there, it's too inviting." So it is in neither the help
+#: nor HANDLERS; `_send` and send.py stay, unwired. Bringing it back: delete
+#: its DISABLED entry (checked FIRST in main, so it wins), add "send": _send
+#: to HANDLERS, and restore its VERBS row.
+DISABLED = {
+    "send": ("session send: disabled (Mike, 2026-09-29: it typed into an agent's pane "
+             "by accident). To reach an agent, mail it: message send ADDRESS -s SUBJECT --no-body"),
+}
+
+def _settings(argv: list[str]) -> int:
+    """`session settings <sid> [tool]`: the cascade computed, never on disk
+    (openspec/changes/session-settings). New paths only: a tool that has not
+    moved reads "not moved"."""
+    from sessiontools import settings
+    p = argparse.ArgumentParser(prog="session settings",
+                                description="A session's settings, merged down the cascade "
+                                            "(template, host, agent, seat, session), each key "
+                                            "with the file that set it.")
+    p.add_argument("sid", nargs="?", metavar="SID", help="a session id; default: this session")
+    p.add_argument("tool", nargs="?", metavar="TOOL", help="one tool (mail, session, ears, mouth); default: every tool found")
+    p.add_argument("--agent", metavar="NAME", help="the agent layer to read; default: the session's own record")
+    p.add_argument("--seat", metavar="NAME", help="the seat layer to read; default: the session's own record")
+    p.add_argument("--json", action="store_true", help="machine-readable: values, origins, locked, problems per tool")
+    a = p.parse_args(argv)
+    sid = a.sid
+    if not sid:
+        from sessiontools.claude_code import session_id
+        sid = session_id()
+    if not sid:
+        p.error("no session id: name one, or run inside a session")
+    agent, seat = settings.identity(sid)
+    agent = a.agent or agent
+    seat = a.seat or seat
+    names = [a.tool] if a.tool else settings.tools(sid, agent, seat)
+    rc = 0
+    out: dict[str, dict] = {}
+    for name in names:
+        try:
+            res = settings.resolve(name, sid, agent, seat)
+        except settings.SettingsError as e:
+            print(f"session settings: refused: {e}", file=sys.stderr)
+            return 2
+        if res.problems:
+            rc = 2
+        if a.json:
+            out[name] = {"moved": res.moved, "values": res.values, "origins": res.origins,
+                         "locked": res.locked, "problems": res.problems,
+                         "sources": [{"layer": s.layer, "path": str(s.path)} for s in res.sources]}
+        else:
+            sys.stdout.write(settings.report(res))
+    if a.json:
+        print(json.dumps({"session": sid, "agent": agent, "seat": seat, "tools": out}, indent=1))
+    elif not names:
+        print(f"no settings at any new path for session {sid}")
+    return rc
+
+
+HANDLERS = {"list": _list, "get": _get, "context": _context, "start": _start,
+            "settings": _settings}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    verb = args.pop(0) if args else ""
+    if verb in ("", "-h", "--help"):
+        sys.stdout.write(usage())
+        return 0
+    if verb == "mail":
+        print(MAIL_MOVED, file=sys.stderr)
+        return 2
+    if verb in DISABLED:
+        print(DISABLED[verb], file=sys.stderr)
+        return 2
+    handler = HANDLERS.get(verb)
+    if handler is None:
+        print(f"session: unknown verb {verb!r}\n", file=sys.stderr)
+        sys.stderr.write(usage())
+        return 2
+    return handler(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

sessiontools-0.0.4/src/sessiontools/get.py

@@ -0,0 +1,89 @@
+"""`session get`: read one property of a live seat.
+
+The properties and output are the session repo's `session-get` (retired
+2026-09-28). `model` reads the transcript (`sessiontools.window`: the last
+real model id, never `<synthetic>`); the rest come from `session list`.
+Exit codes: 0 found; 1 unknown PROP; 2 no such seat, or no value for PROP.
+(argparse usage errors are 2.) A SEAT is matched by the `session send`
+rule; no SEAT means this session, from the environment.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+from sessiontools import window
+from sessiontools.claude_code import session_id
+from sessiontools.listing import Row, match
+
+#: (prop, source) in the order `session get` lists them.
+PROPS = (
+    ("id", "session list"),
+    ("short", "session list"),
+    ("pid", "session list"),
+    ("name", "session list"),
+    ("agent", "session list"),
+    ("cwd", "session list"),
+    ("status", "session list"),
+    ("idle", "session list: 0 while status is busy, else seconds since it changed"),
+    ("version", "session list"),
+    ("pane", "session list"),
+    ("model", "the transcript: the last real model id"),
+)
+
+
+class GetError(Exception):
+    def __init__(self, message: str, code: int):
+        super().__init__(message)
+        self.code = code
+
+
+def table() -> str:
+    lines = [f"{'PROP':8} {'SETTABLE':9} SOURCE"]
+    lines += [f"{p:8} {'no':9} {src}" for p, src in PROPS]
+    return "\n".join(lines)
+
+
+def value(row: Row, prop: str, now: float | None = None) -> object:
+    s = row.session
+    if prop == "model":           # a transcript read: only when asked for
+        return window.of(s.id, s.cwd).model
+    now = time.time() if now is None else now
+    return {
+        "id": s.id, "short": row.short, "pid": s.pid, "name": row.name,
+        "agent": s.agent, "cwd": s.cwd, "status": s.raw_status,
+        "idle": int(s.idle_seconds(now)), "version": s.version, "pane": row.tmux_pane,
+    }[prop]
+
+
+def resolve(found: list[Row], seat: str | None, env: dict[str, str] | None = None) -> Row:
+    if seat:
+        row = match(found, seat)
+        if row is None:
+            raise GetError(f"session get: no live seat matches {seat!r} "
+                           f"({len(found)} live; see `session list`)", 2)
+        return row
+    sid = session_id(env)
+    for row in found:
+        if sid and row.session.id == sid:
+            return row
+    raise GetError("session get: no SEAT given and this session is not a live one "
+                   "(no CLAUDE_CODE_SESSION_ID, or no sidecar for it)", 2)
+
+
+def get(found: list[Row], prop: str, seat: str | None, as_json: bool,
+        env: dict[str, str] | None = None) -> str:
+    if prop not in dict(PROPS):
+        raise GetError(f"session get: unknown PROP {prop!r}; one of: "
+                       + ", ".join(p for p, _ in PROPS), 1)
+    row = resolve(found, seat, env)
+    v = value(row, prop)
+    if v is None:
+        raise GetError(f"session get: no {prop} known for {row.name}", 2)
+    if not as_json:
+        return str(v)
+    out = {"session_id": row.session.id, "name": row.name, prop: v}
+    if prop == "idle":
+        out["status"] = row.session.raw_status
+    return json.dumps(out)