cc-session-control 0.4.0__py3-none-any.whl

cc_session_control/data/registry.py

@@ -0,0 +1,155 @@
+"""Read Claude Code's session/agent registries — pure parse, ~5s TTL cache.
+
+Two on-disk registers Claude Code maintains itself:
+  - `sessions/<pid>.json`  → one per local runtime (a sid can have several)
+  - `jobs/<short>/state.json` → one per background agent (NO pid inside)
+
+Both readers swallow errors and return `[]` so the TUI never crashes on a
+malformed/absent register. Results are cached for ~5s (mirrors
+`liveness.alive_map`) so the shared world snapshot can reuse them; pass
+`max_age=0.0` to force a fresh read (used by tests that swap `cfg` paths).
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import time
+
+from ..config import cfg
+from ..models import AgentJob, SessionProc
+
+_sessions_cache: list[SessionProc] | None = None
+_sessions_time: float = 0.0
+_jobs_cache: list[AgentJob] | None = None
+_jobs_time: float = 0.0
+
+
+def invalidate_cache() -> None:
+    """Drop both cached reads (next call re-scans disk)."""
+    global _sessions_cache, _jobs_cache
+    _sessions_cache = None
+    _jobs_cache = None
+
+
+def _suffix(bridge: str | None) -> str:
+    """Namespace suffix of a bridge id (`cse_abc` -> `abc`), or ""."""
+    if not bridge or "_" not in bridge:
+        return ""
+    return bridge.split("_", 1)[1]
+
+
+def _parse_session_proc(path: str) -> SessionProc | None:
+    try:
+        with open(path, errors="ignore") as fh:
+            d = json.load(fh)
+    except Exception:
+        return None
+    sid = d.get("sessionId")
+    pid = d.get("pid")
+    if not sid or not pid:
+        return None
+    try:
+        pid_int = int(pid)
+    except (TypeError, ValueError):
+        return None
+    return SessionProc(
+        pid=pid_int,
+        sid=str(sid),
+        cwd=d.get("cwd", "") or "",
+        kind=d.get("kind", "") or "",
+        entrypoint=d.get("entrypoint", "") or "",
+        status=d.get("status", "") or "",
+        proc_start=str(d.get("procStart", "") or ""),
+        bridge=d.get("bridgeSessionId"),
+    )
+
+
+def read_session_procs(max_age: float = 5.0) -> list[SessionProc]:
+    """All parseable `sessions/<pid>.json` entries. Cached for `max_age` secs."""
+    global _sessions_cache, _sessions_time
+    now = time.monotonic()
+    if _sessions_cache is not None and (now - _sessions_time) < max_age:
+        return _sessions_cache
+    rows: list[SessionProc] = []
+    try:
+        for path in glob.glob(os.path.join(str(cfg.sessions_dir), "*.json")):
+            row = _parse_session_proc(path)
+            if row is not None:
+                rows.append(row)
+    except Exception:
+        rows = []
+    _sessions_cache = rows
+    _sessions_time = now
+    return rows
+
+
+def _parse_agent_job(state_path: str) -> AgentJob | None:
+    short = os.path.basename(os.path.dirname(state_path))
+    if not short:
+        return None
+    try:
+        with open(state_path, errors="ignore") as fh:
+            d = json.load(fh)
+    except Exception:
+        return None
+    sid = str(d.get("sessionId") or "")
+    flags = d.get("respawnFlags")
+    if not isinstance(flags, list):
+        flags = []
+    return AgentJob(
+        short=short,
+        sid=sid,
+        resume_sid=str(d.get("resumeSessionId") or sid or ""),
+        state=d.get("state", "") or "",
+        tempo=d.get("tempo", "") or "",
+        cwd=d.get("cwd", "") or "",
+        name=d.get("name", "") or "",
+        env_suffix=_suffix(d.get("bridgeSessionId")),
+        respawn_flags=[str(x) for x in flags],
+    )
+
+
+def read_agent_jobs(max_age: float = 5.0) -> list[AgentJob]:
+    """All parseable `jobs/<short>/state.json` records. Cached for `max_age`."""
+    global _jobs_cache, _jobs_time
+    now = time.monotonic()
+    if _jobs_cache is not None and (now - _jobs_time) < max_age:
+        return _jobs_cache
+    rows: list[AgentJob] = []
+    try:
+        pattern = os.path.join(str(cfg.jobs_dir), "*", "state.json")
+        for state_path in glob.glob(pattern):
+            row = _parse_agent_job(state_path)
+            if row is not None:
+                rows.append(row)
+    except Exception:
+        rows = []
+    _jobs_cache = rows
+    _jobs_time = now
+    return rows
+
+
+def host_pid_for_sid(
+    sid: str, session_procs: list[SessionProc]
+) -> tuple[int | None, bool]:
+    """Join a sid to its host pid via the registry session files — PURE.
+
+    `jobs/<short>/state.json` carries NO pid, so a background/agent worker's host
+    pid is the `sessions/<pid>.json` entry sharing the sid. Prefers a proc-alive
+    match (so `alive=True` is trustworthy and defeats pid reuse); falls back to
+    the first sid match with `alive=False`. Relies on each `SessionProc.proc_alive`
+    already being injected by the caller (no IO here). Returns `(None, False)`
+    when no sessions file references the sid (that live worker is unstoppable).
+
+    The single host-pid join shared by `snapshot._enrich_jobs`,
+    `actions.agent_ops.job_host`, and `cleanup.remove_session` (M3 guard).
+    """
+    procs = [sp for sp in session_procs if sp.sid == sid]
+    if not procs:
+        return None, False
+    for sp in procs:
+        if sp.proc_alive:
+            return sp.pid, True
+    return procs[0].pid, False

cc_session_control/data/sessions.py

@@ -0,0 +1,188 @@
+"""Session scanning — scan Claude Code transcripts and determine status."""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+from dataclasses import replace
+
+from ..config import cfg
+from ..models import LiveInfo, Session
+from . import registry
+from .liveness import _is_rc_exposed, alive_map, live_index
+from .proc import ancestor_pids as _ancestor_pids  # /proc walk moved to proc.py
+from .proc import pid_alive
+
+_NOISE = (
+    "<command-message>", "<command-name>", "<command-args>",
+    "<local-command-caveat>", "<local-command-stdout>", "<local-command-stderr>",
+    "<system-reminder>", "caveat:",
+)
+
+
+def _is_noise(t: str) -> bool:
+    t = t.strip().lower()
+    return (not t) or any(t.startswith(n) for n in _NOISE)
+
+
+def _clean_text(t: str) -> str:
+    t = " ".join(t.split())
+    for marker in ("<system-reminder", "<command-message", "<command-name",
+                   "<command-args", "<local-command-"):
+        i = t.find(marker)
+        if i != -1:
+            t = t[:i]
+    return t.strip()
+
+
+def _parse_transcript(
+    path: str,
+    idx: dict[str, LiveInfo],
+    cur: set[int],
+    job_shorts: set[str],
+) -> Session | None:
+    """Parse one transcript .jsonl into a Session, or None if it has no cwd.
+
+    `idx` is the joined live index (sid -> LiveInfo from `live_index()`), `cur`
+    the ancestor-pid set, and `job_shorts` the set of background-agent short ids
+    (`sid[:8]`); all injected so this stays unit-testable. The substring
+    pre-check before json.loads is kept intact for performance.
+    """
+    sid = os.path.basename(path)[:-6]
+    try:
+        st = os.stat(path)
+    except OSError:
+        return None
+
+    cwd = title = last_prompt = first_prompt = ""
+    hidden: set[str] = set()
+    prompts = 0
+
+    try:
+        with open(path, "r", errors="ignore") as fh:
+            for line in fh:
+                if '"sdk-ts"' in line:
+                    hidden.add("sdk")
+                if '"bridge-session"' in line:
+                    hidden.add("bridge")
+                if not cwd and '"cwd"' in line:
+                    try:
+                        cwd = json.loads(line).get("cwd", "") or cwd
+                    except Exception:
+                        pass
+                if '"aiTitle"' in line:
+                    try:
+                        title = json.loads(line).get("aiTitle", title) or title
+                    except Exception:
+                        pass
+                if '"lastPrompt"' in line:
+                    try:
+                        last_prompt = json.loads(line).get("lastPrompt", last_prompt) or last_prompt
+                    except Exception:
+                        pass
+                if '"type":"user"' in line:
+                    try:
+                        o = json.loads(line)
+                    except Exception:
+                        continue
+                    if o.get("type") != "user":
+                        continue
+                    c = (o.get("message") or {}).get("content")
+                    if isinstance(c, str):
+                        texts = [c]
+                    elif isinstance(c, list):
+                        texts = [b.get("text", "") for b in c
+                                 if isinstance(b, dict) and b.get("type") == "text"]
+                    else:
+                        texts = []
+                    texts = [t for t in texts if t.strip()]
+                    if texts:
+                        prompts += 1
+                        if not first_prompt:
+                            for t in texts:
+                                if _is_noise(t):
+                                    continue
+                                ct = _clean_text(t)
+                                if ct:
+                                    first_prompt = ct
+                                    break
+    except Exception:
+        pass
+
+    if not cwd:
+        return None
+
+    lp = "" if _is_noise(last_prompt) else last_prompt
+    label = title or first_prompt or lp or "(untitled)"
+
+    # Join the merged liveness/identity for this sid. Missing => dead, no
+    # registry data (transcript-only): liveness stays False and the registry-
+    # derived fields stay empty.
+    info = idx.get(sid)
+    if info is not None:
+        pid = info.pid
+        alive = info.alive
+        kind = info.kind
+        entrypoint = info.entrypoint
+        source = info.source
+        status = info.status
+        bridge = info.bridge
+        # "current" must protect ANY of the sid's alive pids: a resumed session
+        # has several pids and csctl may have been launched by an older one that
+        # is NOT the newest `pid` chosen for display. Fall back to the single
+        # chosen pid for hand-constructed LiveInfo with no `pids` list.
+        cand = info.pids if info.pids else ([pid] if pid else [])
+        current = any(p in cur for p in cand)
+        proc_alive = info.proc_alive
+    else:
+        pid = None
+        alive = False
+        kind = entrypoint = source = status = ""
+        bridge = None
+        current = False
+        proc_alive = False
+
+    rc_exposed = _is_rc_exposed(bridge, proc_alive)
+
+    return Session(
+        sid=sid, cwd=cwd, label=label, mtime=st.st_mtime,
+        prompts=prompts, pid=pid,
+        alive=alive,
+        current=current,
+        hidden=hidden, file=path,
+        kind=kind, entrypoint=entrypoint, source=source,
+        rc_exposed=rc_exposed,
+        env_id=bridge if rc_exposed else None,
+        agent_short=sid[:8] if sid[:8] in job_shorts else None,
+        status=status,
+    )
+
+
+def scan() -> list[Session]:
+    """Unified transcript-driven session scan.
+
+    Merges the three liveness/identity sources once per scan — registry
+    `sessions/<pid>.json`, `claude agents --json`, and `jobs/*/state.json` — then
+    projects each transcript through `live_index()` to fill source/liveness/
+    rc-exposure. Scan stays transcript-driven: an agent-only sid (present in the
+    live index but with no transcript) is surfaced by the Agents tab, not here.
+    """
+    root = str(cfg.projects_root)
+    session_procs = [
+        replace(sp, proc_alive=pid_alive(sp.pid, sp.proc_start))
+        for sp in registry.read_session_procs()
+    ]
+    agents = alive_map()
+    idx = live_index(session_procs, agents)
+    job_shorts = {j.short for j in registry.read_agent_jobs()}
+    cur = _ancestor_pids()
+    rows: list[Session] = []
+
+    for f in glob.glob(os.path.join(root, "*", "*.jsonl")):
+        row = _parse_transcript(f, idx, cur, job_shorts)
+        if row is not None:
+            rows.append(row)
+
+    rows.sort(key=lambda r: r.mtime, reverse=True)
+    return rows

cc_session_control/data/snapshot.py

@@ -0,0 +1,115 @@
+"""Shared world snapshot — ONE scan per refresh cycle (R11 / D8).
+
+The async refresh used to call `fetch_pending()` on every view, so three tabs
+each re-scanned `/proc`, the transcripts, and the registries. `build_world_snapshot`
+computes that world ONCE on the worker thread; `App` then hands the same
+immutable snapshot to each view's `fetch_pending(snapshot)` so they only project
+it (no per-view IO). Views stay back-compatible: `fetch_pending(None)` self-fetches.
+
+This is the TOP of the data layer — it composes `sessions` / `rc` / `registry` /
+`environments` / `proc`. Nothing in `data/` imports it (only `app`/`views` do),
+so there is no cycle. Errors are swallowed by the callees; `App` additionally
+guards `build_world_snapshot` so a failed build degrades to per-view self-fetch.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+from ..models import AgentJob, EnvRecord, RCProject, RCServer, Session, SessionProc
+from . import environments, liveness, proc, rc, registry, sessions
+
+
+@dataclass
+class WorldSnapshot:
+    """One cycle's shared view of the machine (read-only data for the views).
+
+    `sessions` is the full transcript-driven scan (SessionsView), `agent_jobs`
+    the background jobs enriched with host liveness (AgentsView), and
+    `rc_projects`/`rc_servers` the Remote Control world (RCView). The two env
+    sets are the bridge-environment ledger's two tiers (R6):
+      - `observed_envs` — ALIVE-GATED (`observe_live`): the CURRENT/bound display.
+      - `file_referenced_envs` — bridge-truthy (`observe`): ledger MEMBERSHIP, and
+        the set orphans are computed against (`orphan = ledger − file-referenced`).
+
+    `session_procs` (with `/proc` liveness already injected), `agents_map`
+    (`claude agents --json`) and `cur` (the ancestor-pid set) are the raw liveness
+    inputs `build_world_snapshot` already computes for the scan; they are exposed
+    here so the Sessions cleanup submenu can feed `cleanup_classified` /
+    `select_zombie_pids` WITHOUT a second scan (R11/D8).
+    """
+    sessions: list[Session] = field(default_factory=list)
+    agent_jobs: list[AgentJob] = field(default_factory=list)
+    rc_projects: list[RCProject] = field(default_factory=list)
+    rc_servers: list[RCServer] = field(default_factory=list)
+    observed_envs: list[EnvRecord] = field(default_factory=list)
+    file_referenced_envs: list[EnvRecord] = field(default_factory=list)
+    session_procs: list[SessionProc] = field(default_factory=list)
+    agents_map: dict[str, int | None] = field(default_factory=dict)
+    cur: set[int] = field(default_factory=set)
+
+
+def _enrich_jobs(
+    jobs: list[AgentJob], session_procs: list[SessionProc]
+) -> list[AgentJob]:
+    """Fill each job's `host_pid`/`host_alive` by joining sid -> sessions/<pid>.
+
+    `state.json` carries no pid, so a live worker's host pid is the proc-alive
+    `sessions/<pid>.json` for the job's sid (falling back to the first match when
+    none is alive). Uses the single `registry.host_pid_for_sid` join (shared with
+    `agent_ops.job_host`) and returns fresh copies so the cached registry objects
+    are never mutated. `session_procs` must already carry injected `proc_alive`
+    (build_world_snapshot does this).
+    """
+    out: list[AgentJob] = []
+    for job in jobs:
+        pid, alive = registry.host_pid_for_sid(job.sid, session_procs)
+        out.append(replace(job, host_pid=pid, host_alive=alive))
+    return out
+
+
+def build_world_snapshot() -> WorldSnapshot:
+    """Compute the shared per-cycle world once (worker thread, R11/D8).
+
+    Heavy scans (transcript glob via `sessions.scan`, `/proc` walk via
+    `rc.scan_servers`) run exactly once here instead of once per tab. The
+    registry reads are ~5s-TTL cached so the few repeat reads inside `scan()`
+    hit the cache. Each callee swallows its own errors and returns safe empties.
+    """
+    session_procs = [
+        replace(sp, proc_alive=proc.pid_alive(sp.pid, sp.proc_start))
+        for sp in registry.read_session_procs()
+    ]
+    all_sessions = sessions.scan()
+    agent_jobs = _enrich_jobs(registry.read_agent_jobs(), session_procs)
+    # Cheap, cached/inexpensive liveness inputs surfaced for the cleanup submenu
+    # (the registry read above + scan() already warmed alive_map's 5s cache).
+    agents_map = liveness.alive_map()
+    cur = proc.ancestor_pids()
+    rc_projects = rc.scan()
+    rc_servers = rc.scan_servers()
+    # R6 ledger persistence (the whole point of the ledger): record EVERY env an
+    # on-disk file references THIS cycle — session_* + cse_* + the env_* captured
+    # from rc servers — using the bridge-truthy (NOT alive-gated) set for
+    # membership. When one of these later toggles away (RC turned off / job
+    # removed / server stopped) it stays in the ledger but drops out of the
+    # file-referenced set, surfacing as an orphan / manual-delete candidate. Cheap
+    # and safe on the worker thread: the ledger is write-on-change + flock +
+    # compacted, so re-observing the same set is a no-op rewrite.
+    file_referenced_envs = environments.observe(session_procs, agent_jobs, rc_servers)
+    environments.upsert(file_referenced_envs)
+    # CURRENT must be alive-gated (R3/R6): pass the already-liveness-resolved
+    # session_procs + host-enriched agent_jobs + running servers so a zombie's
+    # stale bridge is NOT counted as a bound (current) environment.
+    observed_envs = environments.observe_live(session_procs, agent_jobs, rc_servers)
+    return WorldSnapshot(
+        sessions=all_sessions,
+        agent_jobs=agent_jobs,
+        rc_projects=rc_projects,
+        rc_servers=rc_servers,
+        observed_envs=observed_envs,
+        file_referenced_envs=file_referenced_envs,
+        session_procs=session_procs,
+        agents_map=agents_map,
+        cur=cur,
+    )

cc_session_control/models.py

@@ -0,0 +1,170 @@
+"""Data models for cc-session-control."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+# Single source of truth for RC status values. The Chinese display labels
+# (views/rc.py) and the CLI icons (cli.py) are presentation-only maps keyed
+# off this vocabulary.
+Status = Literal["running", "dead", "stopped"]
+
+
+@dataclass
+class Session:
+    sid: str
+    cwd: str
+    label: str
+    mtime: float
+    prompts: int
+    pid: int | None
+    alive: bool
+    current: bool
+    hidden: set[str] = field(default_factory=set)
+    file: str = ""
+    # Unified-workbench fields (all default so existing construction stays valid).
+    kind: str = ""              # registry `kind` (e.g. interactive / bg)
+    entrypoint: str = ""        # registry `entrypoint` (cli / claude-vscode / sdk-ts)
+    source: str = ""            # coarse bucket: cli / vscode / sdk / bg
+    rc_exposed: bool = False    # session remote control currently exposed
+    env_id: str | None = None   # bound bridge environment id, if any
+    agent_short: str | None = None  # linked background-agent short id, if any
+    status: str = ""            # registry `status` (busy / idle)
+
+    @property
+    def bridge_or_sdk(self) -> bool:
+        """D9: union of the transcript `hidden` tags and registry source==sdk.
+
+        The 桥接/SDK hide filter (Phase 7) keys off this so the badge and the
+        `h` toggle stay consistent whether the SDK signal arrived from the
+        transcript marker (`hidden`) or the registry entrypoint (`source`).
+        Kept here so the two signals never contradict at the model level.
+        """
+        return bool(self.hidden) or self.source == "sdk"
+
+
+@dataclass
+class SessionProc:
+    """One `sessions/<pid>.json` registry entry (a session's local runtime).
+
+    A single sessionId may have several of these — resume keeps the sid but
+    mints a new pid. `proc_start` defeats pid reuse (compared to /proc stat).
+    """
+    pid: int
+    sid: str
+    cwd: str = ""
+    kind: str = ""
+    entrypoint: str = ""
+    status: str = ""
+    proc_start: str = ""        # registry `procStart` (kernel starttime, as str)
+    proc_alive: bool = False    # injected /proc liveness, never parsed from JSON
+    bridge: str | None = None   # `bridgeSessionId` (session_* namespace)
+
+
+@dataclass
+class AgentJob:
+    """One `jobs/<short>/state.json` background-agent record.
+
+    state.json carries NO pid; `host_pid`/`host_alive` are filled later by
+    joining `sid -> sessions/<pid>.json` (see Phase 6).
+    """
+    short: str
+    sid: str
+    resume_sid: str
+    state: str = ""
+    tempo: str = ""
+    cwd: str = ""
+    name: str = ""
+    env_suffix: str = ""        # suffix of the cse_* bridge id
+    respawn_flags: list[str] = field(default_factory=list)
+    host_pid: int | None = None
+    host_alive: bool = False
+
+
+@dataclass
+class LiveInfo:
+    """Merged liveness/identity for one sessionId (output of live_index)."""
+    sid: str
+    pid: int | None = None
+    proc_start: str = ""
+    status: str = ""
+    kind: str = ""
+    entrypoint: str = ""
+    bridge: str | None = None
+    source: str = ""
+    alive: bool = False
+    proc_alive: bool = False
+    # All proc-confirmed alive pids for this sid (resume mints new pids while
+    # keeping the sid). `pid` is the chosen one for display; `pids` is the full
+    # candidate set so "current" detection protects ANY ancestor pid, not just
+    # the newest (multi-pid under-protection fix).
+    pids: list[int] = field(default_factory=list)
+
+
+@dataclass
+class RCProject:
+    name: str
+    directory: str
+    trusted: bool
+    in_list: bool
+    status: Status
+    auto_start: bool
+    rc_at_startup: bool | None = None  # per-project remoteControlAtStartup override
+    spawn_mode: str | None = None      # per-project remoteControlSpawnMode (None=unset)
+
+
+@dataclass
+class RCServer:
+    """A project RC server process (`claude remote-control --name`) — R5/D5.
+
+    Discovered from tmux (managed) and/or `/proc` (external). `managed` is True
+    when the pid belongs to a csctl-managed tmux pane; otherwise the server was
+    started outside csctl and is READ-ONLY (no takeover/restart — review gate).
+    `env_id` is the full cloud bridge id (`env_*`) captured from a managed
+    server's pane output, or None when unknown / external.
+    """
+    name: str
+    cwd: str = ""
+    managed: bool = False
+    pid: int | None = None
+    env_id: str | None = None
+    status: Status = "stopped"
+
+
+@dataclass(frozen=True)
+class EnvRecord:
+    """One live observation of a bridge environment (R6, D4).
+
+    `prefix` is the namespace (`session` / `cse` / `env`); `key` is the suffix
+    that is the canonical environment id WITHIN that namespace. `bound_sid` is
+    the session this observation is bound to (None for namespaces with no sid).
+    Frozen so it is hashable for set membership when splitting current/orphan.
+    Built by `environments.observe()` (registry) and, in Phase 5, pushed in by
+    `rc` for the `env_*` namespace — environments never imports rc.
+    """
+    prefix: str
+    key: str
+    bound_sid: str | None = None
+
+
+@dataclass
+class BridgeEnv:
+    """A ledger entry for one bridge environment (R6, D4).
+
+    `status` is NOT persisted — it is recomputed against the current observation
+    by `current_envs`/`orphan_envs` (an orphan is a manual-delete candidate on
+    claude.ai/code; there is no local deregister). `first_seen`/`last_seen` are
+    epoch seconds. The full namespaced id is `prefix_key`.
+    """
+    prefix: str
+    key: str
+    bound_sid: str | None = None
+    first_seen: float = 0.0
+    last_seen: float = 0.0
+    status: Literal["current", "orphan"] = "orphan"
+
+    @property
+    def env_id(self) -> str:
+        """Full namespaced id (`cse_<key>` / `session_<key>` / `env_<key>`)."""
+        return f"{self.prefix}_{self.key}"