sessiontools 0.3.0__tar.gz → 0.3.1__tar.gz

{sessiontools-0.3.0 → sessiontools-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sessiontools
-Version: 0.3.0
+Version: 0.3.1
 Summary: The harness layer: sessions, status and idle, one driver per harness - a library first
 Author: Mike Bailey
 Author-email: Mike Bailey <mike@sessionkit.ai>
@@ -68,6 +68,16 @@ eval "$(session completion bash)"
   whether a pin keeps it there. Off until you set `model.default`.
 - `session --help`: every verb.
 
+## Requirements
+
+- [x] macOS (tested on macOS 27, Apple silicon)
+- [ ] Linux
+- [ ] WSL
+- [ ] Windows
+
+What sessiontools depends on, what needs each one, and how to upgrade
+it: [dependencies][dependencies].
+
 ## Switching accounts
 
 `session account use NAME` moves this Mac to another Claude account from
@@ -243,6 +253,8 @@ and the kit's other packages keep their files in it too.
 - [The default model][default-model]: `session default-model`, opt-in,
   puts settings.json's `"model"` back when something rewrites it
 - [The Python library][library]: `from sessiontools import sessions`
+- [Dependencies][dependencies]: what sessiontools needs, what needs each
+  one, and how to upgrade it
 - [Building and testing][building]: make targets, specs, releases
 - [CHANGELOG][changelog]; licence AGPL-3.0-or-later ([LICENSE][license])
 
@@ -311,6 +323,7 @@ Follow one as it grows with `tail -F`, for example
 [default-model]: docs/default-model.md
 [library]: docs/python-library-api.md
 [building]: docs/building-and-testing.md
+[dependencies]: docs/dependencies.md
 [changelog]: CHANGELOG.md
 [license]: LICENSE
 [configuration]: docs/configuration.md

{sessiontools-0.3.0 → sessiontools-0.3.1}/README.md

@@ -52,6 +52,16 @@ eval "$(session completion bash)"
   whether a pin keeps it there. Off until you set `model.default`.
 - `session --help`: every verb.
 
+## Requirements
+
+- [x] macOS (tested on macOS 27, Apple silicon)
+- [ ] Linux
+- [ ] WSL
+- [ ] Windows
+
+What sessiontools depends on, what needs each one, and how to upgrade
+it: [dependencies][dependencies].
+
 ## Switching accounts
 
 `session account use NAME` moves this Mac to another Claude account from
@@ -227,6 +237,8 @@ and the kit's other packages keep their files in it too.
 - [The default model][default-model]: `session default-model`, opt-in,
   puts settings.json's `"model"` back when something rewrites it
 - [The Python library][library]: `from sessiontools import sessions`
+- [Dependencies][dependencies]: what sessiontools needs, what needs each
+  one, and how to upgrade it
 - [Building and testing][building]: make targets, specs, releases
 - [CHANGELOG][changelog]; licence AGPL-3.0-or-later ([LICENSE][license])
 
@@ -295,6 +307,7 @@ Follow one as it grows with `tail -F`, for example
 [default-model]: docs/default-model.md
 [library]: docs/python-library-api.md
 [building]: docs/building-and-testing.md
+[dependencies]: docs/dependencies.md
 [changelog]: CHANGELOG.md
 [license]: LICENSE
 [configuration]: docs/configuration.md

{sessiontools-0.3.0 → sessiontools-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sessiontools"
-version = "0.3.0"
+version = "0.3.1"
 description = "The harness layer: sessions, status and idle, one driver per harness - a library first"
 readme = "README.md"
 license = "AGPL-3.0-or-later"

{sessiontools-0.3.0 → sessiontools-0.3.1}/src/sessiontools/claude_code.py

@@ -72,7 +72,7 @@ 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
+    proc_start: str | None = None   # the process's start as written - liveness (procs.parse_start)
     started_at: float | None = None  # epoch seconds, when the session began
     version: str | None = None      # the harness's version
     #: Where the harness says it runs: `<tmux session>:@window.%pane`, e.g.

{sessiontools-0.3.0 → sessiontools-0.3.1}/src/sessiontools/cli.py

@@ -8,6 +8,7 @@ package code, well structured, in the right place - not copied.
     session get [PROP [SEAT]] [--json]
     session context [SEAT] [--peak] [--max N] [--parts [--tools] | --startup | --boot | --hooks] [--json]
     session start ...        launch a session from an agent file
+    session agent default    the default seat's name (the vendor's word), one line
     session sound landed|given --session SID [--ref ID] [--json]
     session sound engine build|on|off|status   the sound engine
     session operator         the operator and the privileged seats, as JSON
@@ -49,6 +50,7 @@ VERBS = (
     ("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"),
+    ("agent", "the default seat's name, for scripts (default)"),
     ("settings", "a session's settings, each key with the file that set it"),
     ("sound", "signal the busy sound (landed|given); `sound engine` switches the engine"),
     ("operator", "who seats ask, and who is privileged (one line of JSON)"),
@@ -708,6 +710,58 @@ def _park(argv: list[str]) -> int:
     return park.main(argv)
 
 
+AGENT_USAGE = """Usage: session agent default
+
+  default   print the default seat's name, the vendor's own word, and nothing
+            else: one line on stdout, nothing on stderr, exit 0. Safe in a
+            shell substitution: message setup --box "$(session agent default)"
+"""
+
+AGENT_DEFAULT_EPILOG = """\
+Reads no host state: no ps, no box, no lock, no settings. The word comes
+from the launcher's vendor table, so it always agrees with the name a bare
+`session start` gives its seat. Exit 0, or 2 for a usage error."""
+
+
+def _agent_default_parser() -> argparse.ArgumentParser:
+    """`session agent default`'s parser: no options."""
+    return argparse.ArgumentParser(prog="session agent default", epilog=AGENT_DEFAULT_EPILOG,
+                                   formatter_class=argparse.RawDescriptionHelpFormatter,
+                                   description="Print the default seat's name (the vendor's "
+                                               "own word) and a newline, and nothing else.")
+
+
+#: `session agent`: its one sub-verb is dispatched by hand, as statusline's
+#: are, so completion and the dispatcher read the same table.
+AGENT = Group(subs={"default": "sessiontools.cli:_agent_default_parser"})
+
+
+def _agent(argv: list[str]) -> int:
+    """`session agent default`: the default seat's word, for the readers that
+    cannot import sessiontools (phone, the kit's setup, the wake word). The
+    word is imported here and nowhere else: `sessiontools.start` loads
+    PyYAML, and `import sessiontools.cli` never may (tests/test_cli.py)."""
+    if argv[:1] and argv[0] in AGENT.subs:
+        _agent_default_parser().parse_args(argv[1:])
+        try:
+            from sessiontools.start.default_seat import word
+        except ImportError as e:
+            missing = "PyYAML" if e.name == "yaml" else (e.name or "a module")
+            print(f"session agent: broken install - {missing} will not import ({e}); "
+                  "reinstall sessiontools with its dependencies: "
+                  "uv tool install --editable --reinstall CHECKOUT", file=sys.stderr)
+            return 1
+        sys.stdout.write(f"{word()}\n")
+        return 0
+    if argv[:1] in (["-h"], ["--help"]):
+        sys.stdout.write(AGENT_USAGE)
+        return 0
+    if argv:
+        print(f"session agent: unknown subcommand {argv[0]!r}", file=sys.stderr)
+    sys.stderr.write(AGENT_USAGE)
+    return 2
+
+
 COMPLETION_EPILOG = """install, one line per shell:
   zsh, in ~/.zshrc after compinit:
     eval "$(session completion zsh)"
@@ -753,11 +807,12 @@ def _completion(argv: list[str]) -> int:
     return 0
 
 
-HANDLERS = {"list": _list, "get": _get, "context": _context, "start": _start,
+HANDLERS = {"list": _list, "get": _get, "context": _context, "start": _start, "agent": _agent,
             "settings": _settings, "sound": _sound, "operator": _operator,
             "statusline": _statusline, "pane-state": _pane_state,
             "default-model": _default_model, "ledger": _ledger,
-            "account": _account, "reap": _reap, "park": _park, "completion": _completion}
+            "account": _account, "reap": _reap, "park": _park,
+            "completion": _completion}
 
 #: Each verb's parser, as a `sessiontools.verbs` reference: a builder, or a
 #: `Group` for a verb whose first word is dispatched by hand. Each handler
@@ -768,6 +823,7 @@ PARSERS = {"list": "sessiontools.cli:_list_parser",
            "get": "sessiontools.cli:_get_parser",
            "context": "sessiontools.cli:_context_parser",
            "start": "sessiontools.start.args:build_parser",
+           "agent": "sessiontools.cli:AGENT",
            "settings": "sessiontools.cli:_settings_parser",
            "sound": "sessiontools.cli:SOUND",
            "operator": "sessiontools.cli:_operator_parser",

{sessiontools-0.3.0 → sessiontools-0.3.1}/src/sessiontools/context_parts/hooks.py

@@ -13,7 +13,7 @@ carried context, else the hook's event name. Per command:
   window holds it again:
   - EXACT: the same text;
   - TEMPLATED: the same once every digit run is one `#` (DIGITS), and not
-    exact: `[clock] 13:07 AEDT` then `[clock] 13:08 AEDT`.
+    exact: `[clock] 13:07 UTC` then `[clock] 13:08 UTC`.
   The first copy of a line is never a repeat. IN-BATCH is the part of those
   repeats whose earlier copy came in the SAME batch: a PostToolUse hook
   firing once per tool call of one batch (the prototype's `dup` + `templ`).

{sessiontools-0.3.0 → sessiontools-0.3.1}/src/sessiontools/park.py

@@ -1065,7 +1065,7 @@ again with no work since keeps it, so parking buys no time. Nothing here
 computes a deadline, kills, mails or writes config.
 
 --keep-until T --why R records a request to be kept until T, an absolute
-ISO 8601 time with an offset (2030-06-09T17:00:00+11:00, or Z). Nothing
+ISO 8601 time with an offset (2030-06-09T17:00:00+00:00, or Z). Nothing
 acts on it here. A park without it clears it.
 
 --check [SEAT] writes nothing. It reads the record and runs tree, work,

{sessiontools-0.3.0 → sessiontools-0.3.1}/src/sessiontools/procs.py

@@ -4,7 +4,10 @@ Liveness is one rule, the one `session list` always used (and sessionmail's
 doorbell uses since 2030-06-09): a sidecar's session is live when its pid is
 running AND that process started within SAME_PROCESS_SECONDS of the
 sidecar's `procStart`. A pid the OS has handed to something else is not the
-session. `ps` is asked in UTC because `procStart` is UTC ctime.
+session. `procStart` comes in two encodings (`parse_start`): on macOS it is
+`ps lstart` in UTC ctime, so `ps` is asked in UTC; on Linux it is the
+process's start in clock ticks since boot, which becomes a wall-clock time
+by the rule `ps` itself uses for `lstart`.
 
 `table(commands=True)` adds each process's command line: the pane
 signal sorts a seat's tool shells by what runs under them. Callers that do
@@ -35,6 +38,60 @@ def parse_ctime(text: str | None) -> float | None:
     return when.timestamp()
 
 
+#: Linux's kernel statistics, whose `btime` line is the boot time in epoch
+#: seconds. A module constant so a test can point it at a file of its own.
+PROC_STAT = "/proc/stat"
+
+#: Clock ticks per second when the system cannot say. Linux reports process
+#: start times in USER_HZ, 100 on every mainstream architecture.
+DEFAULT_CLOCK_TICKS = 100
+
+
+def boot_time() -> int | None:
+    """The `btime` line of PROC_STAT: when the system booted, in epoch
+    seconds. None where there is no such file (macOS) or no such line."""
+    try:
+        with open(PROC_STAT, encoding="ascii", errors="replace") as f:
+            for line in f:
+                name, _, value = line.partition(" ")
+                if name == "btime":
+                    return int(value) if value.strip().isdigit() else None
+    except OSError:
+        return None
+    return None
+
+
+def clock_ticks() -> int:
+    """Clock ticks per second (`SC_CLK_TCK`), DEFAULT_CLOCK_TICKS when the
+    system cannot say."""
+    try:
+        hz = os.sysconf("SC_CLK_TCK")
+    except (AttributeError, ValueError, OSError):
+        return DEFAULT_CLOCK_TICKS
+    return hz if hz > 0 else DEFAULT_CLOCK_TICKS
+
+
+def parse_start(text: str | None) -> float | None:
+    """A sidecar's `procStart` -> epoch seconds; None when it is not one.
+
+    Two encodings, told apart by their shape, never by the platform:
+    - UTC ctime (`Sun Jun  9 17:00:00 2030`), what Claude Code writes on
+      macOS: `parse_ctime`.
+    - Bare digits (`88300`), what it writes on Linux: the process's start
+      in clock ticks since boot (field 22 of `/proc/<pid>/stat`). It
+      becomes `btime + ticks // HZ`, the rule procps uses to print
+      `lstart`, so it lands on the second the process table shows. With no
+      boot time to add (no PROC_STAT) it is None: not provably live.
+      The kernel prints starttime as an unsigned 64-bit number, at most 20
+      digits; a longer run of digits is not one, and is None too."""
+    if text and text.isascii() and text.isdigit():
+        if len(text) > 20:
+            return None
+        boot = boot_time()
+        return None if boot is None else float(boot + int(text) // clock_ticks())
+    return parse_ctime(text)
+
+
 @dataclass(frozen=True)
 class Proc:
     pid: int
@@ -103,7 +160,7 @@ def same_process(pid: int | None, proc_start: str | None, procs: dict[int, Proc]
     proc = procs.get(pid) if pid is not None else None
     if proc is None or proc.started is None:
         return False
-    claimed = parse_ctime(proc_start)
+    claimed = parse_start(proc_start)
     return claimed is not None and abs(proc.started - claimed) <= SAME_PROCESS_SECONDS