4top 0.2.0a1__py3-none-any.whl

4top-0.2.0a1.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: 4top
+Version: 0.2.0a1
+Summary: Your coding agents, one terminal. Find, search and resume native sessions, locally or over SSH.
+Author: 4ier
+License-Expression: MIT
+Project-URL: Repository, https://github.com/4ier/4top
+Project-URL: Issues, https://github.com/4ier/4top/issues
+Keywords: coding-agents,terminal,session-history,claude,codex,pi,ssh
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console :: Curses
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: session-ls<0.3,>=0.2.0
+Requires-Dist: textual<9,>=8.2.8
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=0.23; extra == "dev"
+Requires-Dist: pexpect<5,>=4.9; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Dynamic: license-file
+
+# 4top
+
+**Your coding agents, one terminal.**
+
+Find your work. Resume an exact native session. Reach your other machines over SSH.
+A keyboard-first terminal dashboard built on **session-ls**, with no extra 4top
+daemon, account, model calls, or telemetry.
+
+[中文](README.zh-CN.md) · [Compatibility](docs/compatibility.md) · [Remote hosts](docs/remote-design.md) · [Acceptance](docs/validation/README.md)
+
+![4top synthetic demo — no real user history](docs/demo/demo.svg)
+
+> **0.2.0a1 — alpha.** The current development line owns no process and drives no
+> multiplexer of its own. Codex **0.155.1** passed an authenticated exact-resume
+> smoke check against an earlier build;
+> Claude Code, Pi and other native versions are not certified.
+> [Evidence](docs/validation/macos-0.1.0a2.md). This release is not on PyPI.
+
+## Install from this checkout
+
+macOS or Linux; **Python 3.11+**. No multiplexer is required. Current validation
+records, rather than this minimum target, determine which versions were tested.
+Windows users need a Linux environment such as WSL; native Windows is unsupported.
+
+```sh
+git clone https://github.com/4ier/4top.git
+cd 4top
+python3 -m venv .venv
+.venv/bin/python -m pip install ./packages/session-ls .
+.venv/bin/4top --demo
+```
+
+Both local packages are intentionally supplied to pip: `session-ls 0.2.0` is not
+assumed to exist on a package registry. The root wheel contains only `fourtop`;
+the independent `session-ls` package retains its small, stdlib-only CLI.
+
+```sh
+. .venv/bin/activate
+4top                       # browse every session on this machine
+4top new codex             # start an agent here, in this terminal
+4top --host build-box      # view another machine over ssh
+```
+
+4top never installs or authenticates agents for you. Install the original Claude
+Code, Codex, or Pi CLI separately and keep its existing authentication flow.
+The panel also reads Cursor transcripts, but does not launch or resume Cursor.
+
+## The daily loop
+
+Open `4top` and you get every session on the machine, most recent first. Select a
+row and press **Enter**: 4top asks for confirmation and then runs the native CLI
+in this terminal to resume that exact session. Leave the agent and you are back in
+the panel. **`q` closes only the panel.**
+
+A plain terminal or any multiplexer you already run is equally fine: 4top starts
+the agent in the terminal it was launched from and never allocates a terminal of
+its own. If you want a session to survive closing your laptop, run 4top inside the
+multiplexer you already use.
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓`, `Enter` | Select and resume |
+| `H` | Switch the panel between this machine and a configured host |
+| `/`, `Enter`, `Esc` | Search metadata, return to table, clear/cancel |
+| `Ctrl-F` | Explicit literal full-content search; `Esc` cancels |
+| `Space`, `i` | Read-only preview, details |
+| `n`, `r`, `?` | New agent, refresh, help |
+| `q`, `Ctrl-C` | Close only the panel |
+
+Search supports case-insensitive words and quoted phrases; all terms must match.
+Full search decodes JSON text, including Chinese escaped as `\u....`. It reads
+only configured sources, reports partial scans, and never executes transcript
+content. The UI renders titles and previews as plain, sanitized text.
+
+## Sessions, not processes
+
+A native agent is a file. `pi --session <path>`, `claude --resume <id>` and
+`codex resume <id>` all work from the transcript alone, so the transcript is the
+thing 4top tracks, and the process is the ephemeral part.
+
+**Resume** starts a new native process from an exact ID or source path. It cannot
+restore lost memory, network connections, shell children, or a destroyed machine.
+Resume uses the CLI's **current native configuration**; 4top does not replay the
+original launch flags. Review native permissions before sending another task.
+
+Because 4top owns no process it claims nothing about liveness either: a row is a
+session you can resume, and that is all it says. Failed queries are reported as
+issues and never rendered as an empty machine.
+
+Two consequences worth knowing. A resumed agent is a **new** process; two agents in
+one directory still have **no code/worktree isolation**. And `4top new` runs the
+agent in the foreground of the terminal you launched it from: outside a multiplexer
+it ends with that terminal.
+
+## Remote hosts over SSH
+
+Point 4top at any machine you can already `ssh` into. There is no daemon to
+install, no port to open, and no credential store: the remote side is the same
+CLI, and the local 4top only runs it.
+
+```toml
+# ~/.config/4top/config.toml
+[hosts.build-box]
+ssh = "me@build-box"                 # any ssh destination, including a tailnet name
+# command = "/opt/4top/bin/4top"     # if a non-login PATH does not include 4top
+# refresh_seconds = 15.0               # slower than local: each tick is a round trip
+# timeout_seconds = 10.0
+```
+
+```sh
+4top --host build-box              # the whole panel, scoped to that host
+4top --host build-box list --json
+4top --host me@10.0.0.4 doctor     # an unconfigured target works too
+```
+
+Views stay isolated: the default scope is this machine, and a host replaces it
+rather than merging machines into one table. `H` switches the panel between them
+without leaving it; `--host NAME` starts the panel already scoped. Anything that starts a process runs
+**on that host** through `ssh -t`, so the resumed agent lives where its history
+lives; the remote CLI does the work and the local side only hands over the
+terminal. Connection reuse (`ControlMaster`) keeps refreshes cheap, `BatchMode`
+means a missing key fails fast instead of prompting, and a remote that speaks a
+different row schema is refused instead of partially parsed.
+
+Before it hands over the terminal, the panel asks the host that owns the session
+whether the resume can work there (`4top check`). A host without that agent
+installed, or a session whose directory is gone, is reported in the panel instead
+of failing during the hand-over, where the message would be painted over. The ssh
+connection also keeps a liveness probe, so a link that dies becomes an error rather
+than a hang, and the session stays in its transcript to be resumed again.
+
+## Command line
+
+```sh
+4top list --json                          # one JSON object per row
+4top list --agent pi --project 4top
+4top search 'retry "database timeout"'    # metadata match
+4top search '中文' --full                  # decoded full-content search
+4top preview h_<key>                      # one bounded read-only page
+4top check h_<key> --json                 # would a resume work here, and why not
+4top new codex -- --model MODEL           # native arguments after --
+4top resume h_<key> --yes                 # restore this process as the agent
+4top doctor --json
+```
+
+`doctor` also reports `revision`, and `4top --host NAME doctor` reports it for both
+sides, so a remote running older code is visible instead of failing later. Bring a
+remote forward with `scripts/remote_update.py NAME`; it uses the host's own egress
+first and falls back to a tunnel from this machine.
+
+`--config`, `--host` and `--no-color` work before or after the subcommand.
+`check` exits 0 when the session can resume here and 3 when it cannot. Keys
+may be shortened only when their prefixes are unambiguous (at least four
+characters). Row numbers are never execution targets. `list --json` rows carry
+`schema_version`, `key`, `agent`, `host`, `cwd`, `title`, `started`, `last`,
+`source`, `status` and `can_resume`.
+
+## Configuration and privacy
+
+Optional configuration: `$XDG_CONFIG_HOME/4top/config.toml` (default
+`~/.config/4top/config.toml`). No setup file is needed for standard stores.
+
+```toml
+[ui]
+refresh_seconds = 1.0
+history_refresh_seconds = 5.0
+color = "auto"                         # or "none"; NO_COLOR is also supported
+
+[history]
+metadata_max_bytes = 2097152
+metadata_max_lines = 2000
+preview_max_lines = 200
+
+[agents.codex]
+# root = "/absolute/path/to/codex-home"
+# executable = "/absolute/path/to/a-real-wrapper"
+```
+
+Agent store roots respect `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, and
+`PI_CODING_AGENT_DIR`; an explicit configured root wins. Selected history and
+launch profile must agree. Local state is private: `$XDG_STATE_HOME/4top` holds a
+local identity and your last selection, and `$XDG_CACHE_HOME/4top` holds
+rebuildable metadata. No environment values, prompt text, or transcripts are
+retained. The only network access is the ssh you configured.
+
+[Privacy](docs/privacy.md) · [Troubleshooting](docs/troubleshooting.md) · [Design](docs/design.md)
+
+## Develop and contribute
+
+```sh
+.venv/bin/python -m pip install -e ./packages/session-ls -e '.[dev]'
+.venv/bin/python -m pytest
+.venv/bin/python -m ruff check .
+uv tool install --force --editable .   # optional: `4top` runs this checkout
+```
+
+Tests use private temporary HOME/state directories and synthetic agents; the ssh
+tests use a fake `ssh` on `PATH`. No account credentials, network access or model
+calls are required. Record your OS, Python and native CLI versions when reporting
+compatibility. **Never post raw transcripts or tokens.**
+
+For fresh installation, CI, reproducible demo export, native smoke testing, and
+release gates, see [CONTRIBUTING](CONTRIBUTING.md) and the [acceptance guide](docs/validation/README.md).
+
+4top builds on 4ier's `session-ls` parsers and uses Textual. It is not affiliated
+with the vendors of the supported coding agents. **MIT licensed.**

4top-0.2.0a1.dist-info/RECORD

@@ -0,0 +1,18 @@
+4top-0.2.0a1.dist-info/licenses/LICENSE,sha256=cYZ3LVkc_-w5u7NQqO4QjWZ6Z9daosrMOOrb5IOXdeI,1061
+fourtop/__init__.py,sha256=FRTmk3XpzLxsNjuDlaL88OncrVEG6MFy1nVQh0sCSPw,84
+fourtop/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+fourtop/agents.py,sha256=hieUJ-LpIQR3Mmy-GqYuwhw9WqVqFyAUy7N_zZ4no3Y,7302
+fourtop/app.py,sha256=6kSrPjwhidox7rwipOkzWFY9V_iRkkGL7Y1Dd1-yJnE,35575
+fourtop/cli.py,sha256=VtbihQvWxY4tdl-LS2aD2Jf2Tf6qxwul0oPgV_245u8,11798
+fourtop/config.py,sha256=VebU1P-y0cIHC13PNiReM0GK02nHEa-TTJzqY4fpwGw,8190
+fourtop/doctor.py,sha256=g3fuBcwT3UVMJ-FMXt3Ci4tH3a9FxcyEQaneW_UlIyc,4341
+fourtop/errors.py,sha256=u10_hiP9bNlfoBRAafumcWCH8uVs512MTSabof3TNsg,642
+fourtop/hosts.py,sha256=RyIXxdn6aA2kC7oCT6jsMx6MJXTM459N0ngUdTV7oX8,7525
+fourtop/models.py,sha256=AJCs3GkHmwEqoIY7jKzBsCAgki-RCKhVqLJZKXAfsnE,2094
+fourtop/services.py,sha256=_90mGp_a_ofuLPg64EK7ozSOi-Fo2iyQ-CaTAkGarbo,11686
+fourtop/state.py,sha256=SKC3_U53feXhZGItOiTVMEyHJc74HJUe0MxjOsdopDw,2033
+4top-0.2.0a1.dist-info/METADATA,sha256=sYv642XMA75RNwb5ejDkmESQI0pl3-K1AoYjsT2mBHY,10475
+4top-0.2.0a1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+4top-0.2.0a1.dist-info/entry_points.txt,sha256=TREhJAejvlOwHehlUj6meVh7JQjWrwuKASdTKp1I3NA,42
+4top-0.2.0a1.dist-info/top_level.txt,sha256=-A1z8S-VOyAvinHumQEZKDjfomX0kl7H2LxzibJulPg,8
+4top-0.2.0a1.dist-info/RECORD,,

4top-0.2.0a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

4top-0.2.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+4top = fourtop.cli:main

4top-0.2.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4ier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

4top-0.2.0a1.dist-info/top_level.txt

@@ -0,0 +1 @@
+fourtop

fourtop/__init__.py

@@ -0,0 +1,3 @@
+"""4top: a terminal workspace for native coding agents."""
+
+__version__ = "0.2.0a1"

fourtop/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

fourtop/agents.py

@@ -0,0 +1,150 @@
+"""Native CLI plans. Capability probes do not authenticate or call a model."""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+from session_ls.api import HistoryRecord, history_key, is_uuid, open_source
+
+from .config import Config
+from .errors import Dependency, FourtopError, Missing
+from .models import LaunchPlan
+
+RESERVED = {
+    "claude": {"--resume", "-r", "--continue", "-c", "--session-id", "--fork-session",
+               "--no-session-persistence", "--print", "-p", "--input-format", "--output-format"},
+    "codex": {"--cd", "-C", "--ephemeral", "--resume", "--session-id"},
+    "pi": {"--resume", "-r", "--continue", "-c", "--session", "--session-id", "--session-dir",
+           "--no-session", "--print", "-p", "--mode"},
+}
+
+# Capability probes are local `--help` / `--version` calls; they never authenticate.
+PROBE_SECONDS = 5.0
+
+
+@dataclass(frozen=True)
+class Capability:
+    executable: str
+    help_ok: bool
+    allocate_id: bool
+    resume: bool
+    version: str
+
+
+def validate_extra(agent: str, extra: tuple[str, ...]) -> None:
+    for item in extra:
+        if "\x00" in item:
+            raise FourtopError("NUL is not allowed in command arguments", 2)
+        flag = item.split("=", 1)[0]
+        if flag in RESERVED[agent]:
+            raise FourtopError(f"{flag} changes runtime identity or mode; use a dedicated 4top command", 2)
+        # Native parsers accept compact short options such as -rUUID and -C/path.
+        if len(item) > 2 and not item.startswith("--"):
+            if item[:2] in RESERVED[agent]:
+                raise FourtopError(f"{item[:2]} conflicts with 4top's launch plan", 2)
+    # CLI subcommands are allowed after global flags by native parsers. Reject them
+    # anywhere, rather than letting --model X resume silently escape new semantics.
+    if agent == "codex" and any(item in {"resume", "fork", "exec", "e", "app-server", "mcp-server",
+                                      "login", "logout", "mcp", "app", "sandbox", "debug",
+                                      "apply", "cloud", "features", "completion", "help"}
+                                for item in extra):
+        raise FourtopError("Use the native interactive command; subcommands are not accepted by new", 2)
+
+
+class Drivers:
+    def __init__(self, config: Config, host_id: str):
+        self.config = config
+        self.host_id = host_id
+        self._probes = {}
+
+    def executable(self, agent: str) -> str:
+        if agent not in RESERVED:
+            raise Dependency(f"{agent} is read-only or unsupported for runtime operations")
+        configured = self.config.executables[agent]
+        found = shutil.which(configured, path=self.config.environment.get("PATH", os.defpath))
+        if not found:
+            raise Dependency(f"{agent} executable not found; install it or configure a real wrapper path")
+        return os.path.abspath(found)
+
+    def probe(self, agent: str) -> Capability:
+        executable = self.executable(agent)
+        st = os.stat(executable)
+        key = (executable, st.st_mtime_ns, st.st_size)
+        if key in self._probes:
+            return self._probes[key]
+        try:
+            result = subprocess.run([executable, "--help"], capture_output=True, text=True,
+                                    errors="replace", timeout=PROBE_SECONDS,
+                                    env=self.config.environment, cwd="/")
+            help_text = result.stdout + result.stderr
+            ok = result.returncode == 0
+            version_result = subprocess.run([executable, "--version"], capture_output=True, text=True,
+                                            errors="replace", timeout=PROBE_SECONDS,
+                                            env=self.config.environment, cwd="/")
+            version = version_result.stdout.strip()[:160] if version_result.returncode == 0 else "unknown"
+        except (OSError, subprocess.TimeoutExpired):
+            ok, help_text, version = False, "", "unavailable"
+        resume_token = "resume" if agent == "codex" else "--resume" if agent == "claude" else "--session"
+        value = Capability(executable, ok, ok and agent != "codex" and "--session-id" in help_text,
+                           ok and resume_token in help_text, version)
+        self._probes[key] = value
+        return value
+
+    @staticmethod
+    def cwd(value: str) -> str:
+        if not value or "\x00" in value:
+            raise Missing("A working directory is required")
+        path = Path(value).expanduser()
+        if not path.is_absolute():
+            path = Path.cwd() / path
+        if not path.is_dir() or not os.access(path, os.R_OK | os.X_OK):
+            raise Missing(f"Directory does not exist or is not accessible: {path}")
+        return str(path.resolve())
+
+    def plan_new(self, agent: str, cwd: str, extra: tuple[str, ...] = ()) -> LaunchPlan:
+        executable = self.executable(agent)
+        validate_extra(agent, extra)
+        cwd = self.cwd(cwd)
+        capability = self.probe(agent)
+        native_id = str(uuid.uuid4()) if capability.allocate_id else None
+        root = self.config.root(agent).path
+        args = [executable]
+        if native_id:
+            args.extend(["--session-id", native_id])
+        args.extend(extra)
+        env = dict(self.config.environment)
+        key = history_key(self.host_id, agent, root, native_id) if native_id else None
+        return LaunchPlan(agent, executable, tuple(args), cwd, env, root, native_id, key)
+
+    def plan_resume(self, record: HistoryRecord, cwd: str | None = None) -> LaunchPlan:
+        if record.agent not in RESERVED:
+            raise Dependency("This history adapter is read-only; native resume is not supported")
+        if record.root != self.config.root(record.agent).path:
+            raise Dependency("History root differs from the selected agent profile")
+        if not cwd and record.cwd_quality != "native":
+            raise Missing("Historical directory is inferred or missing; provide --cwd explicitly")
+        cwd = self.cwd(cwd or record.cwd)
+        # Reopen the exact approved source immediately before planning an executable action.
+        try:
+            with open_source(record.file, record.root):
+                pass
+        except (OSError, ValueError):
+            raise Missing("The selected history file is missing or not trusted") from None
+        capability = self.probe(record.agent)
+        if not capability.resume:
+            raise Dependency("Installed CLI did not advertise a supported resume interface (--help)")
+        if record.agent in ("claude", "codex") and not is_uuid(record.native_id):
+            raise Dependency("An exact UUID is required; 4top will not guess the latest session")
+        if record.agent == "claude":
+            args = (capability.executable, "--resume", record.native_id)
+        elif record.agent == "codex":
+            args = (capability.executable, "resume", record.native_id)
+        else:
+            args = (capability.executable, "--session", record.file)
+        env = dict(self.config.environment)
+        return LaunchPlan(record.agent, capability.executable, args, cwd, env, record.root,
+                          record.native_id, record.key)