agmx 0.1.0__tar.gz

agmx-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,42 @@
+# 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/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-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-0.1.0/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-0.1.0/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)