agmx 0.1.0__py3-none-any.whl

agmx/__init__.py

@@ -0,0 +1,7 @@
+"""``agmx`` -- chạy việc của AgentMatrix ngay trên máy bạn.
+
+Gói này cài trên máy NGƯỜI DÙNG: chỉ stdlib + httpx, không Postgres, không
+Redis, không config của server, và tuyệt đối không ``DATABASE_URL``.
+"""
+
+__version__ = "0.1.0"

agmx/__main__.py

@@ -0,0 +1,354 @@
+"""``agmx`` -- công cụ dòng lệnh chạy trên MÁY CỦA NGƯỜI DÙNG.
+
+Hai việc duy nhất:
+
+* ``agmx login``        -- đổi email/mật khẩu lấy token, cất vào ``~/.agmx``.
+* ``agmx runner start`` -- nhận việc từ server rồi thực thi ngay tại đây, bằng
+  phiên đăng nhập CLI của chính người dùng này.
+
+Điểm mấu chốt của thiết kế: **server không nói đường dẫn**. Nó chỉ nói
+``project_id``; máy này tự tra ra thư mục của mình từ danh sách ``--project``
+đã đăng ký. Một ``project_id`` lạ bị báo ``failed`` chứ không bao giờ được đoán
+thành một đường dẫn nào đó.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import socket
+import sys
+import time
+from pathlib import Path
+
+import httpx
+
+from . import config, executor
+from .client import DEFAULT_SERVER, Client
+
+DEFAULT_POLL_SECONDS = 5
+
+#: Mã lỗi server trả về -> câu người đọc hiểu được.
+_LOGIN_ERRORS = {
+    "invalid_credentials": "email hoặc mật khẩu không đúng.",
+    "locked": "tài khoản đang bị khoá (sai mật khẩu quá nhiều lần).",
+    "disabled": "tài khoản đã bị vô hiệu hoá.",
+    "invalid_request": "server từ chối yêu cầu (thiếu email hoặc mật khẩu).",
+}
+
+
+def _sleep(seconds: float) -> None:
+    """Chỗ duy nhất runner ngủ -- test thay nó để vòng lặp chạy tức thì."""
+    time.sleep(seconds)
+
+
+# --------------------------------------------------------------------------- #
+# agmx login
+# --------------------------------------------------------------------------- #
+
+def cmd_login(args: argparse.Namespace) -> int:
+    cfg = config.load()
+    server = args.server or cfg.get("server") or os.environ.get("AGMX_SERVER") or DEFAULT_SERVER
+
+    email = (args.email or input("Email: ")).strip()
+    if not email:
+        print("Chưa nhập email, dừng lại.", file=sys.stderr)
+        return 1
+    # Mật khẩu CHỈ đọc từ TTY: một cờ --password nằm lại trong lịch sử shell và
+    # trong argv của tiến trình, ai chạy `ps` cũng đọc được.
+    password = getpass.getpass("Mật khẩu: ")
+    if not password:
+        print("Chưa nhập mật khẩu, dừng lại.", file=sys.stderr)
+        return 1
+
+    try:
+        status, body = Client(server).login(email, password)
+    except httpx.HTTPError as exc:
+        print(f"Không gọi được server {server}: {exc}", file=sys.stderr)
+        return 1
+
+    if status != 200 or not body.get("ok") or not body.get("token"):
+        code = str(body.get("error") or f"HTTP {status}")
+        print(f"Đăng nhập thất bại: {_LOGIN_ERRORS.get(code, code)}", file=sys.stderr)
+        return 1
+
+    # Ghi cấu hình MỚI, không vá lên cái cũ: đăng nhập là một phiên khác, và
+    # runner_id của phiên trước có thể thuộc về người khác.
+    config.save({
+        "server": server,
+        "token": body["token"],
+        "expires_at": body.get("expires_at"),
+        "email": email,
+    })
+    name = (body.get("user") or {}).get("name") or email
+    print(f"Đã đăng nhập {name} <{email}> tại {server}.")
+    print(f"Token cất ở {config.credentials_path()} (quyền 0600).")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# agmx runner start
+# --------------------------------------------------------------------------- #
+
+def parse_projects(pairs: list[str]) -> dict[str, str]:
+    """``["agmx=/repo"]`` -> ``{"agmx": "/repo"}``. Đây là bản đồ duy nhất từ
+    ``project_id`` ra đường dẫn thật, và nó nằm ở phía máy người dùng."""
+    projects: dict[str, str] = {}
+    for raw in pairs:
+        project_id, separator, local_path = raw.partition("=")
+        project_id, local_path = project_id.strip(), local_path.strip()
+        if not separator or not project_id or not local_path:
+            raise ValueError(
+                f"--project phải có dạng PROJECT_ID=/đường/dẫn, nhận được: {raw!r}"
+            )
+        projects[project_id] = str(Path(local_path).expanduser().resolve())
+    return projects
+
+
+def _enroll(client: Client, projects: dict[str, str]) -> str | None:
+    """Đăng ký máy này với server. Trả ``runner_id``, hoặc ``None`` nếu hỏng."""
+    try:
+        status, body = client.enroll(socket.gethostname(), projects)
+    except httpx.HTTPError as exc:
+        print(f"Không đăng ký được runner với {client.server}: {exc}", file=sys.stderr)
+        return None
+    if status != 200 or not body.get("ok") or not body.get("runner_id"):
+        print(
+            f"Server từ chối đăng ký runner (HTTP {status}): {body.get('error') or body}",
+            file=sys.stderr,
+        )
+        return None
+
+    runner_id = str(body["runner_id"])
+    config.save({**config.load(), "runner_id": runner_id})
+    return runner_id
+
+
+def _report(client: Client, runner_id: str, run_id: str, status: str, **facts) -> None:
+    try:
+        code, body = client.result(runner_id, run_id, status, **facts)
+    except httpx.HTTPError as exc:
+        # Mất kết quả của một run thì tiếc, nhưng giết cả runner thì tệ hơn.
+        print(f"Không báo được kết quả run {run_id} về server: {exc}", file=sys.stderr)
+        return
+    if code != 200 or not body.get("ok"):
+        # Im lặng ở đây nghĩa là server vẫn nghĩ run đang chạy, còn máy này thì
+        # đã quên nó -- nói ra để người dùng còn biết mà tra.
+        print(
+            f"Server không nhận kết quả run {run_id} (HTTP {code}): "
+            f"{body.get('error') or body}",
+            file=sys.stderr,
+        )
+
+
+def _output_sink(client: Client, runner_id: str, run_id: str):
+    def send(seq: int, stream: str, content: str) -> None:
+        try:
+            client.output(runner_id, run_id, seq, stream, content)
+        except httpx.HTTPError as exc:
+            # Mất một mẻ log không phải lý do để bỏ dở việc đang chạy.
+            print(f"Không đẩy được output run {run_id} (mẻ {seq}): {exc}", file=sys.stderr)
+
+    return send
+
+
+def _handle_run(client: Client, runner_id: str, projects: dict[str, str], run: dict) -> None:
+    run_id = str(run.get("run_id") or "")
+    task_id = str(run.get("task_id") or "")
+    project_id = run.get("project_id")
+
+    local_path = projects.get(project_id)
+    if local_path is None:
+        known = ", ".join(sorted(projects)) or "(chưa đăng ký project nào)"
+        reason = (
+            f"project_id {project_id!r} chưa đăng ký trên máy này; "
+            f"runner chỉ nhận việc cho: {known}"
+        )
+        print(f"Bỏ qua run {run_id}: {reason}", file=sys.stderr)
+        _report(client, runner_id, run_id, "failed", error=reason)
+        return
+
+    print(f"Nhận run {run_id} (task {task_id}), project {project_id} -> {local_path}")
+    try:
+        outcome = executor.execute(
+            local_path=local_path,
+            run_id=run_id,
+            command=str(run.get("command") or ""),
+            timeout_seconds=float(run.get("timeout_seconds") or 900),
+            on_output=_output_sink(client, runner_id, run_id),
+        )
+    except Exception as exc:  # kể cả lỗi lạ: im lặng nuốt là mất hẳn một run
+        reason = f"thực thi thất bại: {type(exc).__name__}: {exc}"
+        print(f"Run {run_id} lỗi: {reason}", file=sys.stderr)
+        _report(client, runner_id, run_id, "failed", error=reason)
+        return
+
+    # ``status`` là bắt buộc trong hợp đồng, nên nó được nói lại một cách MÁY
+    # MÓC từ mã thoát: không đọc output, không suy diễn, không dựng result_ref.
+    # Sự việc thô đi kèm ngay bên cạnh để server tự phán.
+    if outcome["timed_out"]:
+        status = "timeout"
+    else:
+        status = "success" if outcome["exit_code"] == 0 else "failed"
+    print(f"Run {run_id} kết thúc: {status} (mã thoát {outcome['exit_code']}).")
+    _report(client, runner_id, run_id, status, **outcome)
+
+
+def poll_loop(
+    client: Client,
+    runner_id: str,
+    projects: dict[str, str],
+    poll_seconds: float = DEFAULT_POLL_SECONDS,
+    max_iterations: int | None = None,
+) -> None:
+    """Vòng heartbeat -> lease -> thực thi -> result, tới khi Ctrl-C.
+
+    ``max_iterations`` chỉ để test không chạy vô hạn.
+    """
+    iterations = 0
+    while max_iterations is None or iterations < max_iterations:
+        iterations += 1
+        try:
+            status, body = client.heartbeat(runner_id)
+            if status == 404 and body.get("error") == "unknown_runner":
+                # Server không còn biết runner này. Đăng ký lại, chứ poll mãi
+                # vào một id đã chết thì runner sống mà không nhận được việc.
+                print("Server không còn nhớ runner này, đăng ký lại.", file=sys.stderr)
+                new_id = _enroll(client, projects)
+                if new_id is None:
+                    _sleep(poll_seconds)
+                    continue
+                runner_id = new_id
+
+            status, body = client.lease(runner_id)
+            if status != 200 or not body.get("ok"):
+                print(
+                    f"Server từ chối cấp việc (HTTP {status}): {body.get('error') or body}",
+                    file=sys.stderr,
+                )
+                _sleep(poll_seconds)
+                continue
+
+            run = body.get("run")
+            if not run:
+                _sleep(poll_seconds)
+                continue
+        except httpx.HTTPError as exc:
+            # Máy người dùng rớt mạng là chuyện thường ngày, không phải lý do
+            # để runner chết.
+            print(f"Lỗi mạng: {exc}. Thử lại sau {poll_seconds}s.", file=sys.stderr)
+            _sleep(poll_seconds)
+            continue
+
+        _handle_run(client, runner_id, projects, run)
+        # Vừa có việc thì nhiều khả năng còn việc nữa: lease tiếp, đừng ngủ.
+
+
+def cmd_runner_start(args: argparse.Namespace) -> int:
+    cfg = config.load()
+    token = cfg.get("token")
+    if not token:
+        print("Chưa đăng nhập, chạy `agmx login` trước.", file=sys.stderr)
+        return 1
+    server = args.server or cfg.get("server") or DEFAULT_SERVER
+
+    try:
+        projects = parse_projects(args.project)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    for project_id, local_path in sorted(projects.items()):
+        if not Path(local_path).is_dir():
+            print(
+                f"Cảnh báo: {project_id} trỏ tới {local_path} nhưng đó không "
+                f"phải thư mục đang tồn tại.",
+                file=sys.stderr,
+            )
+
+    client = Client(server, token)
+    runner_id = _enroll(client, projects)
+    if runner_id is None:
+        return 1
+
+    print(
+        f"Runner {runner_id} chạy trên {socket.gethostname()}, "
+        f"hỏi việc {server} mỗi {args.poll_seconds}s. Ctrl-C để dừng."
+    )
+    poll_loop(client, runner_id, projects, args.poll_seconds)
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# Vào cửa
+# --------------------------------------------------------------------------- #
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agmx",
+        description=(
+            "agmx -- chạy việc của AgentMatrix ngay trên máy bạn, bằng phiên "
+            "đăng nhập CLI của chính bạn."
+        ),
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="LỆNH")
+
+    login = subparsers.add_parser(
+        "login",
+        help="đăng nhập vào server và cất token vào ~/.agmx/.credentials.json",
+        description="Đăng nhập. Mật khẩu chỉ nhập từ bàn phím, không có cờ --password.",
+    )
+    login.add_argument("--server", help=f"địa chỉ server (mặc định {DEFAULT_SERVER})")
+    login.add_argument("--email", help="email đăng nhập (bỏ trống thì sẽ hỏi)")
+    login.set_defaults(func=cmd_login)
+
+    runner = subparsers.add_parser(
+        "runner",
+        help="điều khiển runner trên máy này",
+        description="Runner: nhận việc từ server rồi chạy ngay tại máy này.",
+    )
+    runner_sub = runner.add_subparsers(dest="runner_command", metavar="LỆNH")
+    start = runner_sub.add_parser(
+        "start",
+        help="đăng ký máy này rồi nhận việc liên tục",
+        description=(
+            "Đăng ký máy này với server rồi lặp: xin việc, chạy, báo kết quả. "
+            "Server chỉ gửi project_id; đường dẫn thật do máy này quyết định."
+        ),
+    )
+    start.add_argument(
+        "--project",
+        action="append",
+        default=[],
+        required=True,
+        metavar="PROJECT_ID=/đường/dẫn",
+        help="project máy này nhận việc, lặp lại được nhiều lần",
+    )
+    start.add_argument(
+        "--poll-seconds",
+        type=float,
+        default=DEFAULT_POLL_SECONDS,
+        help=f"nghỉ bao lâu giữa hai lần hỏi việc (mặc định {DEFAULT_POLL_SECONDS})",
+    )
+    start.add_argument("--server", help="ghi đè địa chỉ server đã lưu khi đăng nhập")
+    start.set_defaults(func=cmd_runner_start)
+    runner.set_defaults(func=lambda _args: (runner.print_help(), 1)[1])
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 1
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        print("\nĐã dừng. Tạm biệt.")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agmx/client.py

@@ -0,0 +1,65 @@
+"""Các route HTTP máy này nói với control plane. Chỉ httpx, không gì khác."""
+
+from __future__ import annotations
+
+import httpx
+
+# Control plane công khai. HTTPS không phải trang trí: ``agmx login`` đặt mật
+# khẩu vào thân yêu cầu, http trần trên internet là đưa nó cho cả đường dây.
+DEFAULT_SERVER = "https://agmx.nothanagentic.vn"
+HTTP_TIMEOUT = 30.0
+
+
+class Client:
+    """Một phiên nói chuyện với server. ``token`` rỗng thì chỉ login được."""
+
+    def __init__(self, server: str | None, token: str | None = None, timeout: float = HTTP_TIMEOUT):
+        self.server = (server or DEFAULT_SERVER).rstrip("/")
+        self.token = token
+        self._http = httpx.Client(timeout=timeout)
+
+    def post(self, path: str, payload: dict) -> tuple[int, dict]:
+        """POST JSON, trả ``(status_code, body)``. Ném ``httpx.HTTPError`` khi mạng hỏng."""
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        response = self._http.post(self.server + path, json=payload, headers=headers)
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        return response.status_code, body if isinstance(body, dict) else {}
+
+    # -- 5 route -------------------------------------------------------- #
+
+    def login(self, email: str, password: str) -> tuple[int, dict]:
+        return self.post("/auth/login", {"email": email, "password": password})
+
+    def enroll(self, hostname: str, projects: dict[str, str]) -> tuple[int, dict]:
+        return self.post("/runner/enroll", {
+            "hostname": hostname,
+            "projects": [
+                {"project_id": project_id, "local_path": local_path}
+                for project_id, local_path in sorted(projects.items())
+            ],
+        })
+
+    def heartbeat(self, runner_id: str) -> tuple[int, dict]:
+        return self.post("/runner/heartbeat", {"runner_id": runner_id})
+
+    def lease(self, runner_id: str) -> tuple[int, dict]:
+        return self.post("/runner/lease", {"runner_id": runner_id})
+
+    def output(self, runner_id: str, run_id: str, seq: int, stream: str, content: str):
+        return self.post("/runner/output", {
+            "runner_id": runner_id,
+            "run_id": run_id,
+            "seq": seq,
+            "stream": stream,
+            "content": content,
+        })
+
+    def result(self, runner_id: str, run_id: str, status: str, **facts) -> tuple[int, dict]:
+        """Báo run đã kết thúc. ``facts``: exit_code, base_sha, head_sha,
+        timed_out, error -- những gì máy này QUAN SÁT được, không phải kết luận."""
+        payload = {"runner_id": runner_id, "run_id": run_id, "status": status}
+        payload.update(facts)
+        return self.post("/runner/result", payload)

agmx/config.py

@@ -0,0 +1,82 @@
+"""Cấu hình của ``agmx``: bí mật một nơi, phần còn lại một nơi khác.
+
+``~/.agmx/.credentials.json`` (0600) giữ token; ``~/.agmx/settings.json``
+(0644) giữ những thứ không phải bí mật (server, runner_id, email). Tách ra
+theo đúng cách ``~/.claude`` làm: settings là thứ người ta mở ra xem, sửa, dán
+vào issue; token thì không. Gộp chung một file nghĩa là mỗi lần khoe cấu hình
+là một lần lộ phiên đăng nhập.
+
+``config.json`` kiểu cũ vẫn đọc được, để máy đã cài không phải đăng nhập lại.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+#: Những khoá là BÍ MẬT. Chỉ chúng mới được vào file 0600, và mọi khoá khác
+#: đều ra file 0644 -- danh sách này là ranh giới, không phải gợi ý.
+SECRET_KEYS = ("token", "expires_at")
+
+
+def config_dir() -> Path:
+    """Thư mục config. ``AGMX_CONFIG_DIR`` đổi được (test không đụng ``~`` thật)."""
+    return Path(os.environ.get("AGMX_CONFIG_DIR") or (Path.home() / ".agmx"))
+
+
+def credentials_path() -> Path:
+    return config_dir() / ".credentials.json"
+
+
+def settings_path() -> Path:
+    return config_dir() / "settings.json"
+
+
+def legacy_path() -> Path:
+    """File một-cục của bản cũ. Chỉ còn được ĐỌC, không bao giờ được ghi nữa."""
+    return config_dir() / "config.json"
+
+
+def _read(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def load() -> dict:
+    """Cấu hình đã lưu: file cũ làm nền, file mới đè lên."""
+    merged = _read(legacy_path())
+    merged.update(_read(settings_path()))
+    merged.update(_read(credentials_path()))
+    return merged
+
+
+def _write(path: Path, data: dict, mode: int) -> None:
+    """Ghi với quyền đặt TRƯỚC khi có nội dung.
+
+    ``open()`` rồi ``chmod()`` để lại một khoảng thời gian token nằm trên đĩa
+    với quyền mặc định; ai đọc được trong khoảng đó thì đọc được phiên đăng
+    nhập. ``os.open`` mang sẵn mode, và ``fchmod`` ép đúng quyền kể cả khi file
+    đã tồn tại sẵn với quyền rộng hơn (``O_CREAT`` không sửa quyền file cũ) hay
+    khi umask của máy cắt bớt.
+    """
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
+    os.fchmod(fd, mode)
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+
+
+def save(data: dict) -> None:
+    """Cất cấu hình, tự tách bí mật ra khỏi phần còn lại."""
+    directory = config_dir()
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    os.chmod(directory, 0o700)  # mkdir(mode=) im lặng bỏ qua khi thư mục đã có
+
+    _write(credentials_path(), {k: data[k] for k in SECRET_KEYS if k in data}, 0o600)
+    _write(settings_path(), {k: v for k, v in data.items() if k not in SECRET_KEYS}, 0o644)
+    # Bỏ file cũ đi: token của nó không còn ai đọc nữa nhưng vẫn ai cũng đọc
+    # được. Một bản sao bí mật nằm lì trên đĩa là bí mật bị lộ, chỉ chậm hơn.
+    legacy_path().unlink(missing_ok=True)

agmx/executor.py

@@ -0,0 +1,272 @@
+"""Chạy MỘT run trên máy này: worktree riêng, spawn, đẩy output theo mẻ.
+
+Chỉ ``subprocess`` + ``git``. Không có gì của control plane ở đây.
+
+Và cố ý không có: **runner không phán xét**. Nó không quyết định run thành công
+hay thất bại, không dựng ``result_ref``, không đọc output để đoán ý người ta
+muốn gì. Nó trả về sự việc -- mã thoát, base, head, có quá giờ hay không -- rồi
+server phán. Logic phán xét bên server đã trả giá bằng nhiều sự cố thật; chép
+lại ở phía client là mua lại đúng bộ bug đó, lần này trên máy người lạ, nơi
+không ai vá được.
+"""
+
+from __future__ import annotations
+
+import os
+import queue
+import shutil
+import signal
+import subprocess
+import tempfile
+import threading
+import time
+from typing import Callable
+
+#: Biến git trỏ vào repo KHÁC. Không xoá khỏi môi trường con thì lệnh git của
+#: agent ghi thẳng vào repo chính dù ``cwd`` là worktree: GIT_DIR thắng cwd,
+#: luôn luôn. Đây là sự cố có thật của dự án (CTV2-1427).
+GIT_POINTER_VARS = (
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_COMMON_DIR",
+    "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "GIT_NAMESPACE",
+    "GIT_CEILING_DIRECTORIES",
+)
+
+#: Bao lâu thì đẩy một mẻ output đi, kể cả khi mẻ còn ngắn. Người ngồi xem một
+#: run 15 phút cần thấy nó đang nói gì, không phải đợi tới lúc nó im hẳn.
+FLUSH_SECONDS = 0.5
+#: Trần của MỘT mẻ, đếm bằng KÝ TỰ chứ không phải byte: server từ chối body quá
+#: 64KiB, và một ký tự UTF-8 dài nhất 4 byte, nên 16k ký tự luôn lọt.
+MAX_BATCH_CHARS = 16_000
+#: Chờ tiến trình chết tử tế bao lâu trước khi SIGKILL cả nhóm.
+KILL_GRACE_SECONDS = 3.0
+
+#: Nhận ``(seq, stream, content)``. ``seq`` đánh từ 0, tăng dần theo từng run.
+OutputSink = Callable[[int, str, str], None]
+
+
+def child_env() -> dict[str, str]:
+    """Môi trường cho tiến trình con: bản sao ĐẦY ĐỦ, đã bỏ con trỏ git.
+
+    Trả về cả môi trường chứ không phải lớp phủ. Xoá một khoá khỏi lớp phủ là
+    vô nghĩa -- ``Popen`` dựng môi trường con từ ``os.environ`` rồi mới đắp lớp
+    phủ lên, nên khoá đã xoá vẫn thừa kế nguyên vẹn (CTV2-1758).
+    """
+    env = dict(os.environ)
+    for name in GIT_POINTER_VARS:
+        env.pop(name, None)
+    return env
+
+
+def _git(cwd: str, *args: str, check: bool = True) -> subprocess.CompletedProcess:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        errors="replace",
+        env=child_env(),
+        check=False,
+    )
+    if check and result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        raise RuntimeError(f"`git {' '.join(args)}` hỏng: {detail}")
+    return result
+
+
+def branch_name(run_id: str) -> str:
+    return f"ct-run/{run_id}"
+
+
+def execute(
+    local_path: str,
+    run_id: str,
+    command: str,
+    timeout_seconds: float,
+    on_output: OutputSink | None = None,
+) -> dict:
+    """Chạy ``command`` trong worktree riêng của ``run_id``.
+
+    Trả về ``{exit_code, base_sha, head_sha, timed_out}`` -- dữ liệu thô, không
+    kèm lời phán nào. ``head_sha`` là ``None`` khi run không đổi gì cả.
+    """
+    base_sha = _git(local_path, "rev-parse", "HEAD").stdout.strip()
+    parent = tempfile.mkdtemp(prefix=f"agmx-{run_id}-")
+    worktree = os.path.join(parent, "worktree")
+    # ``-B`` chứ không ``-b``: cùng một run được giao lại (server restart, lease
+    # hết hạn) thì làm lại từ đầu, chứ không hỏng vĩnh viễn vì nhánh đã có.
+    _git(local_path, "worktree", "add", "-B", branch_name(run_id), worktree, base_sha)
+    try:
+        exit_code, timed_out = _spawn(command, worktree, timeout_seconds, on_output)
+        head_sha = _commit(worktree, run_id)
+    finally:
+        # Gỡ worktree nhưng GIỮ nhánh: worktree chỉ là thư mục, commit nằm
+        # trong object database dùng chung của repo chính và sống tiếp.
+        _git(local_path, "worktree", "remove", "--force", worktree, check=False)
+        shutil.rmtree(parent, ignore_errors=True)
+    return {
+        "exit_code": exit_code,
+        "base_sha": base_sha,
+        "head_sha": head_sha,
+        "timed_out": timed_out,
+    }
+
+
+def _commit(worktree: str, run_id: str) -> str | None:
+    """Commit những gì run để lại. ``None`` khi nó không để lại gì."""
+    _git(worktree, "add", "-A")
+    if _git(worktree, "diff", "--cached", "--quiet", check=False).returncode == 0:
+        return None
+
+    message = f"agmx run {run_id}"
+    done = _git(worktree, "commit", "-m", message, check=False)
+    if done.returncode != 0:
+        # Máy chưa khai user.name/user.email thì git từ chối commit. Danh tính
+        # thay thế chỉ dùng ở nước này, để commit của người dùng vẫn mang tên
+        # thật của họ khi họ có khai.
+        done = _git(
+            worktree,
+            "-c", "user.name=agmx runner",
+            "-c", "user.email=agmx@localhost",
+            "commit", "-m", message,
+            check=False,
+        )
+    if done.returncode != 0:
+        raise RuntimeError(f"commit hỏng: {(done.stderr or done.stdout).strip()}")
+    return _git(worktree, "rev-parse", "HEAD").stdout.strip()
+
+
+# --------------------------------------------------------------------------- #
+# Spawn + stream
+# --------------------------------------------------------------------------- #
+
+class _Batches:
+    """Gom dòng thành mẻ theo luồng, đánh ``seq`` tăng dần từ 0."""
+
+    def __init__(self, sink: OutputSink | None, max_chars: int = MAX_BATCH_CHARS):
+        self.sink = sink
+        self.max_chars = max_chars
+        self.seq = 0
+        self.pending: dict[str, list[str]] = {}
+
+    def add(self, stream: str, line: str) -> None:
+        batch = self.pending.setdefault(stream, [])
+        batch.append(line)
+        if sum(map(len, batch)) >= self.max_chars:
+            self.flush(stream)
+
+    def flush(self, stream: str | None = None) -> None:
+        for name in [stream] if stream else list(self.pending):
+            content = "".join(self.pending.pop(name, ()))
+            # Một dòng đơn lẻ cũng có thể vượt trần (log JSON nén một dòng);
+            # cắt ở đây chứ không để server trả 413 rồi mất cả mẻ.
+            for start in range(0, len(content), self.max_chars):
+                self._send(name, content[start:start + self.max_chars])
+
+    def _send(self, stream: str, content: str) -> None:
+        if not content:
+            return
+        if self.sink is not None:
+            self.sink(self.seq, stream, content)
+        self.seq += 1
+
+
+def _pump(pipe, stream: str, lines: queue.Queue) -> None:
+    """Đọc một ống theo DÒNG và đẩy sang hàng đợi, không chờ tiến trình xong."""
+    try:
+        for line in pipe:
+            lines.put((stream, line))
+    finally:
+        pipe.close()
+
+
+def _drain(lines: queue.Queue, batches: _Batches, timeout: float) -> None:
+    try:
+        batches.add(*lines.get(timeout=max(timeout, 0)))
+    except queue.Empty:
+        return
+    while True:
+        try:
+            batches.add(*lines.get_nowait())
+        except queue.Empty:
+            return
+
+
+def _kill_group(proc: subprocess.Popen, group: int) -> None:
+    """Giết CẢ NHÓM tiến trình, không chỉ tiến trình cha.
+
+    CLI hay đẻ con; giết mỗi cha thì con sống tiếp, và nó còn giữ nguyên đầu
+    ghi của ống stdout -- tiến trình này sẽ đọc một ống không bao giờ đóng.
+    SIGKILL gửi cho cả nhóm KỂ CẢ khi cha đã chết vì SIGTERM: thứ đáng sợ là
+    đứa con, và nó không chết theo cha.
+    """
+    _signal_group(group, signal.SIGTERM)
+    try:
+        proc.wait(timeout=KILL_GRACE_SECONDS)
+    except subprocess.TimeoutExpired:
+        pass
+    _signal_group(group, signal.SIGKILL)
+
+
+def _signal_group(group: int, sig: int) -> None:
+    try:
+        os.killpg(group, sig)
+    except (ProcessLookupError, PermissionError):
+        pass
+
+
+def _spawn(
+    command: str,
+    cwd: str,
+    timeout_seconds: float,
+    on_output: OutputSink | None,
+) -> tuple[int | None, bool]:
+    proc = subprocess.Popen(
+        command,
+        shell=True,
+        cwd=cwd,
+        env=child_env(),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        errors="replace",
+        bufsize=1,
+        # Nhóm tiến trình riêng: điều kiện để giết được cả đàn con ở trên.
+        start_new_session=True,
+    )
+    group = proc.pid  # setsid: pgid == pid, và đọc ngay bây giờ thì chắc chắn đúng
+    lines: queue.Queue = queue.Queue()
+    readers = [
+        threading.Thread(target=_pump, args=(pipe, stream, lines), daemon=True)
+        for pipe, stream in ((proc.stdout, "stdout"), (proc.stderr, "stderr"))
+    ]
+    for reader in readers:
+        reader.start()
+
+    batches = _Batches(on_output)
+    deadline = time.monotonic() + timeout_seconds
+    timed_out = False
+    while True:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            timed_out = True
+            _kill_group(proc, group)
+            break
+        _drain(lines, batches, min(remaining, FLUSH_SECONDS))
+        batches.flush()
+        if proc.poll() is not None and not any(r.is_alive() for r in readers):
+            break
+
+    for reader in readers:
+        reader.join(timeout=KILL_GRACE_SECONDS)
+    _drain(lines, batches, 0)
+    batches.flush()
+    try:
+        proc.wait(timeout=KILL_GRACE_SECONDS)
+    except subprocess.TimeoutExpired:
+        pass
+    return proc.returncode, timed_out

agmx-0.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: agmx
+Version: 0.1.0
+Summary: Chạy việc của AgentMatrix ngay trên máy bạn, bằng phiên đăng nhập CLI của chính bạn.
+Author: lupca
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lupca/AgentMatrix
+Project-URL: Source, https://github.com/lupca/AgentMatrix/tree/main/runner
+Keywords: agmx,agentmatrix,coding-agent,runner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+
+# agmx
+
+Chạy việc của AgentMatrix ngay trên **máy bạn**, bằng phiên đăng nhập CLI của
+chính bạn. Gói này chỉ cần Python và `httpx`: không Postgres, không Redis,
+không `DATABASE_URL` của control plane.
+
+## Cài
+
+```bash
+pipx install ./runner          # hoặc: pipx install agmx
+```
+
+## Dùng
+
+```bash
+agmx login                                  # hỏi email + mật khẩu, cất token
+agmx runner start --project agmx=~/code/AgentMatrix
+```
+
+`--project` lặp lại được nhiều lần. Server **chỉ** gửi `project_id`; đường dẫn
+thật do máy này quyết định, và một `project_id` chưa đăng ký ở đây bị báo
+`failed` chứ không bao giờ bị đoán thành một thư mục nào đó.
+
+## Cấu hình ở đâu
+
+| File | Quyền | Chứa gì |
+|---|---|---|
+| `~/.agmx/.credentials.json` | `0600` | token đăng nhập |
+| `~/.agmx/settings.json` | `0644` | `server`, `email`, `runner_id` |
+
+`AGMX_CONFIG_DIR` đổi được thư mục. File `config.json` một-cục của bản cũ vẫn
+đọc được, và được dọn đi ở lần ghi kế tiếp.
+
+## Một run chạy như thế nào
+
+Mỗi run được cấp một `git worktree` riêng trên nhánh `ct-run/<run_id>`, cắt từ
+HEAD hiện tại. Lệnh chạy trong worktree đó, output đẩy về server theo mẻ trong
+lúc đang chạy. Xong thì `git add -A` + commit, gỡ worktree nhưng **giữ nhánh**:
+commit sống tiếp trong repo chính.
+
+Runner **không phán xét**: nó báo mã thoát, `base_sha`, `head_sha`, có quá giờ
+hay không. Ai thành ai bại là việc của server.

agmx-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+agmx/__init__.py,sha256=Jv8VreW4TpZg2Q6sig5j7Z51Kq24QbNOSY90UpNwoxU,265
+agmx/__main__.py,sha256=jvdCOHNgtVNYRsKlHH-T-JPKEeNY9WOu6YxR936e7bE,14082
+agmx/client.py,sha256=hTivg69RFxKfX6fGTs-rqMWqKDEJm19s8Z86a6cjcGg,2829
+agmx/config.py,sha256=deR7TjuzpuuBlTblAl8TERGE7hPxzry-mZUv7rZcsFA,3385
+agmx/executor.py,sha256=LcjCWJNerU73aVbJM_RMQKcLILQueFlyzhyHB_pAY-o,10008
+agmx-0.1.0.dist-info/METADATA,sha256=b9mFZ5xtJ0khSpEBzmsfJ4AEKA6Q0mZPEwRaV6hL9So,2340
+agmx-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agmx-0.1.0.dist-info/entry_points.txt,sha256=vORGlZDzZ7lwDMiF9NcoAjdiVc5dyVstT0WKTLI_JpM,44
+agmx-0.1.0.dist-info/top_level.txt,sha256=yPHqVMtQ7iM-JK4O-zaZNnvUbOaPstG8nYmkFcEfoN4,5
+agmx-0.1.0.dist-info/RECORD,,

agmx-0.1.0.dist-info/WHEEL

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

agmx-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agmx = agmx.__main__:main

agmx-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agmx