sesame-kit 0.4.0

package/clients/js/sesame-client.mjs

@@ -0,0 +1,208 @@
+// sesame serve の薄い公式 JS クライアント (Node 18+, 依存ゼロ)。
+// 別プロセスで動いている serve デーモンに繋ぐ用途。
+//
+//   import { SesameClient } from "./sesame-client.mjs";
+//   const c = SesameClient.unix();                 // 既定 UDS パス (POSIX。sesame serve で起動)
+//   console.log(await c.unlock("front"));
+//   await c.subscribe(["lockState"], (topic, p) => console.log("EVENT", topic, p));
+//
+//   const h = SesameClient.http("http://127.0.0.1:8080"); // token は serve.token から自動
+//   const w = await SesameClient.ws("ws://127.0.0.1:8081"); // Windows でも全二重 (要 Node22+ or ws)
+//
+// 失敗は SesameError(message, kind) を throw (kind: not_authenticated / connection_lost / timeout)。
+// subscribe は **常に await** すること (接続/認証エラーを取りこぼさないため)。
+
+import net from "node:net";
+import readline from "node:readline";
+import os from "node:os";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+
+function defaultSocketPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(os.homedir(), ".config");
+  return join(base, "sesame-hub3", "sesame.sock");
+}
+function defaultTokenPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(os.homedir(), ".config");
+  return join(base, "sesame-hub3", "serve.token");
+}
+function defaultToken() {
+  try { return readFileSync(defaultTokenPath(), "utf8").trim(); } catch { return null; }
+}
+
+export class SesameError extends Error {
+  constructor(message, kind, code) { super(message); this.name = "SesameError"; this.kind = kind; this.code = code; }
+}
+
+export class SesameClient {
+  constructor(transport) { this._t = transport; }
+
+  static unix(path = defaultSocketPath()) {
+    if (process.platform === "win32") {
+      throw new SesameError("Unix socket は POSIX 専用です。Windows では SesameClient.http() か .ws() を使ってください", "not_implemented");
+    }
+    return new SesameClient(new StreamTransport(path));
+  }
+  static http(base = "http://127.0.0.1:8080", token = defaultToken()) {
+    return new SesameClient(new HttpTransport(base.replace(/\/$/, ""), token));
+  }
+  /** WebSocket クライアント。`ws` パッケージ(ヘッダ認証可)を優先し、無ければ global WebSocket (await 必須)。 */
+  static async ws(url = "ws://127.0.0.1:8081", token = defaultToken()) {
+    // ws パッケージは upgrade で Authorization ヘッダを送れる (token を URL に載せず済む)。
+    // 無ければ global WebSocket (ブラウザ/Node22+) にフォールバックし URL ?token= を使う。
+    const pkg = await import("ws").then((m) => m.WebSocket).catch(() => null);
+    const WS = pkg || globalThis.WebSocket;
+    if (!WS) throw new SesameError("WebSocket が無い。Node 18+ で `npm i ws`、または Node 22+ が必要です", "not_implemented");
+    const t = new WsTransport(WS, url, token, /* useHeader */ !!pkg);
+    await t.ready();
+    return new SesameClient(t);
+  }
+
+  async call(method, params = {}) {
+    const resp = await this._t.request({ jsonrpc: "2.0", method, params }); // id は transport が採番
+    if (resp.error) throw new SesameError(resp.error.message, resp.error.data?.kind, resp.error.code);
+    return resp.result;
+  }
+  /** topics を購読。常に await すること (接続/認証/不正 topic エラーが throw で返る)。 */
+  async subscribe(topics, onEvent) {
+    const resp = await this._t.subscribe(topics, onEvent);
+    // UDS/WS は購読要求の応答 (msg) を返す。error があれば握り潰さず throw (不正 topic 等)。
+    if (resp && resp.error) throw new SesameError(resp.error.message, resp.error.data?.kind, resp.error.code);
+    return resp?.result;
+  }
+  async discover() { return this.call("rpc.discover"); }
+
+  unlock(name, kw = {}) { return this.call("lock.unlock", name ? { name, ...kw } : kw); }
+  lock(name, kw = {}) { return this.call("lock.lock", name ? { name, ...kw } : kw); }
+  status() { return this.call("status"); }
+  devices() { return this.call("devices.list"); }
+  close() { this._t.close(); }
+}
+
+/** 受信行を id/event で振り分ける共通処理 (UDS/WS で共有)。 */
+function routeMessage(self, line) {
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; } // 壊れた行で落ちない
+  if ("id" in msg && self._pending.has(msg.id)) {
+    const { resolve } = self._pending.get(msg.id); self._pending.delete(msg.id); resolve(msg);
+  } else if (typeof msg.method === "string" && msg.method.startsWith("event.")) {
+    self._onEvent?.(msg.method.slice("event.".length), msg.params);
+  }
+}
+
+class StreamTransport {
+  constructor(path) {
+    this._ids = 0; this._pending = new Map(); this._onEvent = null; this._fatal = null;
+    this._sock = net.connect(path);
+    this._sock.on("error", (e) => {
+      const msg = (e.code === "ENOENT" || e.code === "ECONNREFUSED")
+        ? `sesame serve が起動していません (socket: ${path})。別ターミナルで \`sesame serve\` を実行してください`
+        : `socket エラー: ${e.message}`;
+      this._fatal = new SesameError(msg, "connection_lost");
+      for (const { reject } of this._pending.values()) reject(this._fatal);
+      this._pending.clear();
+    });
+    const rl = readline.createInterface({ input: this._sock });
+    rl.on("error", () => { /* socket 'error' 側で処理 */ });
+    rl.on("line", (line) => { if (line.trim()) routeMessage(this, line); });
+  }
+  request(msg) {
+    if (this._fatal) return Promise.reject(this._fatal);
+    const id = ++this._ids;
+    return new Promise((resolve, reject) => {
+      const to = setTimeout(() => { this._pending.delete(id); reject(new SesameError("request timed out", "timeout")); }, 20000);
+      this._pending.set(id, { resolve: (m) => { clearTimeout(to); resolve(m); }, reject: (e) => { clearTimeout(to); reject(e); } });
+      this._sock.write(JSON.stringify({ ...msg, id }) + "\n");
+    });
+  }
+  subscribe(topics, onEvent) { this._onEvent = onEvent; return this.request({ jsonrpc: "2.0", method: "events.subscribe", params: { topics } }); }
+  close() { this._sock.destroy(); }
+}
+
+class WsTransport {
+  constructor(WS, url, token, useHeader) {
+    this._ids = 0; this._pending = new Map(); this._onEvent = null; this._fatal = null;
+    // ヘッダ送信可 (ws パッケージ) なら Authorization ヘッダ、不可 (ブラウザ) なら URL ?token=。
+    this._ws = useHeader && token
+      ? new WS(url, { headers: { authorization: `Bearer ${token}` } })
+      : new WS(url + (url.includes("?") ? "&" : "?") + (token ? `token=${token}` : ""));
+    this._open = new Promise((resolve, reject) => {
+      const fail = (e) => { this._fatal = e; for (const { reject: rj } of this._pending.values()) rj(e); this._pending.clear(); reject(e); };
+      this._ws.addEventListener("open", () => resolve());
+      // 握手 401 (verifyClient 拒否) は error として届く。message に 401 を含めば認証失敗。
+      this._ws.addEventListener("error", (ev) => {
+        const m = String(ev?.message || ev?.error?.message || "");
+        if (/401|403|unauthorized/i.test(m)) fail(new SesameError("unauthorized (token 不一致/未指定)", "not_authenticated", 401));
+        else fail(new SesameError(`ws 接続失敗 (${url})。sesame serve --ws を起動しましたか?`, "connection_lost"));
+      });
+      // 念のため close 1008 も認証失敗として扱う (open が先勝ちした場合の保険)。
+      this._ws.addEventListener("close", (ev) => { if (ev.code === 1008) fail(new SesameError("unauthorized (token)", "not_authenticated", 1008)); });
+    });
+    this._open.catch(() => {}); // unhandled rejection 抑止 (ready() で受ける)
+    this._ws.addEventListener("message", (ev) => routeMessage(this, typeof ev.data === "string" ? ev.data : ev.data.toString()));
+  }
+  ready() { return this._open; }
+  async request(msg) {
+    if (this._fatal) return Promise.reject(this._fatal);
+    await this._open;
+    if (this._fatal) return Promise.reject(this._fatal);
+    const id = ++this._ids;
+    return new Promise((resolve, reject) => {
+      const to = setTimeout(() => { this._pending.delete(id); reject(new SesameError("request timed out", "timeout")); }, 20000);
+      this._pending.set(id, { resolve: (m) => { clearTimeout(to); resolve(m); }, reject });
+      this._ws.send(JSON.stringify({ ...msg, id }));
+    });
+  }
+  subscribe(topics, onEvent) { this._onEvent = onEvent; return this.request({ jsonrpc: "2.0", method: "events.subscribe", params: { topics } }); }
+  close() { try { this._ws.close(); } catch { /* ignore */ } }
+}
+
+class HttpTransport {
+  constructor(base, token) { this._base = base; this._token = token; this._ids = 0; }
+  _headers() { return this._token ? { "content-type": "application/json", authorization: `Bearer ${this._token}` } : { "content-type": "application/json" }; }
+  _unauthorized() {
+    return this._token
+      ? new SesameError("unauthorized (token 不一致)", "not_authenticated", 401)
+      : new SesameError(`token が見つかりません。\`sesame serve --http\` で起動すると ${defaultTokenPath()} に保存されます`, "not_authenticated", 401);
+  }
+  async request(msg) {
+    let r;
+    try {
+      r = await fetch(`${this._base}/rpc`, { method: "POST", headers: this._headers(), body: JSON.stringify({ ...msg, id: ++this._ids }) });
+    } catch (e) {
+      throw new SesameError(`接続失敗: ${e.message}。\`sesame serve --http\` を起動しましたか?`, "connection_lost");
+    }
+    if (r.status === 401) throw this._unauthorized();
+    return r.status === 204 ? { id: this._ids, result: null } : r.json();
+  }
+  async subscribe(topics, onEvent) {
+    const url = `${this._base}/events?topics=${topics.join(",")}` + (this._token ? `&token=${this._token}` : "");
+    let res;
+    try { res = await fetch(url, { headers: this._headers() }); }
+    catch (e) { throw new SesameError(`events 接続失敗: ${e.message}`, "connection_lost"); }
+    if (res.status === 401) throw this._unauthorized();
+    if (res.status >= 400) { // 400 = 不正 topic 等。黙ってストリームを張らず明示エラーに。
+      let detail = ""; try { detail = JSON.stringify(await res.json()); } catch { /* ignore */ }
+      throw new SesameError(`events 購読失敗 (HTTP ${res.status}): ${detail}`, "bad_params", res.status);
+    }
+    const reader = res.body.getReader();
+    const dec = new TextDecoder();
+    let buf = "";
+    (async () => {
+      try {
+        for (;;) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value, { stream: true });
+          let nl;
+          while ((nl = buf.indexOf("\n\n")) >= 0) {
+            const block = buf.slice(0, nl); buf = buf.slice(nl + 2);
+            const line = block.split("\n").find((l) => l.startsWith("data: "));
+            if (line) { let m; try { m = JSON.parse(line.slice(6)); } catch { continue; } if (m.method?.startsWith("event.")) onEvent(m.method.slice(6), m.params); }
+          }
+        }
+      } catch (e) { console.error("[sesame] subscribe error:", e.message); }
+    })();
+  }
+  close() {}
+}

package/clients/python/pyproject.toml

@@ -0,0 +1,5 @@
+# メタデータは setup.cfg に置く (古い setuptools でも正しく読めるため。理由は setup.cfg 冒頭参照)。
+# ここはビルドバックエンドの宣言のみ。
+[build-system]
+requires = ["setuptools>=40.8.0"]
+build-backend = "setuptools.build_meta"

package/clients/python/sesame_client.py

@@ -0,0 +1,323 @@
+"""sesame serve の薄い公式 Python クライアント (標準ライブラリのみ・依存ゼロ)。
+
+事前に CLI 側でログイン:  sesame login <email>
+
+    pip install ./clients/python      # どこからでも import 可能に
+    from sesame_client import SesameClient
+
+    c = SesameClient.unix()                       # 既定 UDS パスを自動解決 (sesame serve で起動)
+    print(c.status())
+    print(c.unlock("front"))                      # = c.call("lock.unlock", name="front")
+
+    # HTTP:   SesameClient.http("http://127.0.0.1:8080")   (token は serve.token から自動)
+    # 埋め込み: SesameClient.stdio()
+
+    # イベント購読 (UDS/stdio/HTTP 共通)。受信し続けるには wait() でメインを生かす。
+    c.subscribe(["lockState"], lambda topic, payload: print("EVENT", topic, payload))
+    c.wait()
+
+失敗は SesameError(message, kind) を raise (kind: not_authenticated / connection_lost / timeout …)。
+エラーメッセージは「次に何をすべきか」を含む (例: デーモン未起動なら起動コマンドを案内)。
+"""
+from __future__ import annotations
+
+import itertools
+import json
+import os
+import socket
+import subprocess
+import sys
+import threading
+import time
+import urllib.request
+from typing import Any, Callable, Optional
+
+
+def _default_socket_path() -> str:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
+    return os.path.join(base, "sesame-hub3", "sesame.sock")
+
+
+def _default_token_path() -> str:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
+    return os.path.join(base, "sesame-hub3", "serve.token")
+
+
+class SesameError(RuntimeError):
+    def __init__(self, message: str, kind: Optional[str] = None, code: Optional[int] = None):
+        super().__init__(message)
+        self.message, self.kind, self.code = message, kind, code
+
+    def __str__(self):
+        extra = f" [{self.kind}]" if self.kind else ""
+        return f"{self.message}{extra}"
+
+
+class SesameClient:
+    """JSON-RPC over UDS / stdio / HTTP. 直接 new せず unix()/stdio()/http() を使う。"""
+
+    def __init__(self, transport):
+        self._t = transport  # id 採番は transport が一元管理 (call と subscribe で衝突しないよう)
+
+    # ---- ファクトリ ----
+    @classmethod
+    def unix(cls, path: Optional[str] = None) -> "SesameClient":
+        path = path or _default_socket_path()
+        if not hasattr(socket, "AF_UNIX"):
+            raise SesameError("Unix socket は POSIX 専用です。Windows では SesameClient.http() か .stdio() を使ってください",
+                              kind="not_implemented")
+        return cls(_StreamTransport(_connect_unix(path)))
+
+    @classmethod
+    def stdio(cls, cmd=("sesame", "serve", "--stdio")) -> "SesameClient":
+        return cls(_StdioTransport(cmd))
+
+    @classmethod
+    def http(cls, base: str = "http://127.0.0.1:8080", token: Optional[str] = None) -> "SesameClient":
+        if token is None:
+            try:
+                with open(_default_token_path()) as f:
+                    token = f.read().strip()
+            except OSError:
+                token = None  # 後続 401 で具体的に案内する
+        return cls(_HttpTransport(base.rstrip("/"), token))
+
+    # ---- 基本 API ----
+    def call(self, method: str, **params) -> Any:
+        # id は transport が採番する (call と subscribe で id 空間を共有させ衝突を防ぐ)。
+        resp = self._t.request({"jsonrpc": "2.0", "method": method, "params": params})
+        if "error" in resp:
+            e = resp["error"]
+            raise SesameError(e.get("message", "error"), (e.get("data") or {}).get("kind"), e.get("code"))
+        return resp.get("result")
+
+    def subscribe(self, topics, on_event: Callable[[str, Any], None]) -> None:
+        """topics を購読し、各イベントで on_event(topic, payload) を呼ぶ (バックグラウンド)。
+        受信し続けるにはメインスレッドを生かすこと → wait() が使える。
+        接続/認証/不正 topic エラーは握り潰さず SesameError を raise する (JS クライアントと対称)。"""
+        resp = self._t.subscribe(list(topics), on_event)
+        # UDS/stdio は購読要求の応答 (dict) を返す。error があれば raise (不正 topic 等)。
+        # HTTP は初回接続を同期確立し 401/400 をその場で raise 済み (resp は None)。
+        if isinstance(resp, dict) and "error" in resp:
+            e = resp["error"]
+            raise SesameError(e.get("message", "error"), (e.get("data") or {}).get("kind"), e.get("code"))
+
+    def wait(self) -> None:
+        """購読を生かしたままブロックする (Ctrl-C で抜ける)。"""
+        try:
+            while True:
+                time.sleep(3600)
+        except KeyboardInterrupt:
+            pass
+
+    def discover(self) -> Any:
+        return self.call("rpc.discover")
+
+    def discover_names(self):
+        return [m["name"] for m in self.discover()["methods"]]
+
+    # ---- よく使うショートカット ----
+    def status(self):
+        return self.call("status")
+
+    def unlock(self, name=None, **kw):
+        return self.call("lock.unlock", **({"name": name} if name else {}), **kw)
+
+    def lock(self, name=None, **kw):
+        return self.call("lock.lock", **({"name": name} if name else {}), **kw)
+
+    def toggle(self, name=None, **kw):
+        return self.call("lock.toggle", **({"name": name} if name else {}), **kw)
+
+    def devices(self):
+        return self.call("devices.list")
+
+    def close(self):
+        self._t.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+# ---------------- transports ----------------
+
+def _connect_unix(path: str):
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    try:
+        s.connect(path)
+    except (FileNotFoundError, ConnectionRefusedError):
+        s.close()
+        raise SesameError(
+            f"sesame serve が起動していません (socket: {path})。別ターミナルで `sesame serve` を実行してください",
+            kind="connection_lost") from None
+    except OSError as e:
+        s.close()
+        raise SesameError(f"socket 接続失敗: {e}", kind="connection_lost") from e
+    return s
+
+
+class _StreamTransport:
+    """UDS など双方向ストリーム共通。応答とイベントを id/method で振り分ける。"""
+
+    def __init__(self, sock):
+        self._sock = sock
+        self._wfile = sock.makefile("w")
+        self._rfile = sock.makefile("r")
+        self._pending: dict[int, dict] = {}
+        self._ids = itertools.count(1)  # call と subscribe で共有する id 空間
+        self._on_event: Optional[Callable[[str, Any], None]] = None
+        self._lock = threading.Lock()
+        threading.Thread(target=self._reader, daemon=True).start()
+
+    def _reader(self):
+        for line in self._rfile:
+            line = line.strip()
+            if not line:
+                continue
+            msg = json.loads(line)
+            slot = None
+            if "id" in msg:
+                with self._lock:               # pending の参照/取り出しは登録と同一 lock で保護
+                    slot = self._pending.pop(msg["id"], None)
+            if slot is not None:
+                slot["msg"] = msg
+                slot["ev"].set()
+            elif isinstance(msg.get("method"), str) and msg["method"].startswith("event."):
+                if self._on_event:
+                    self._on_event(msg["method"][len("event."):], msg.get("params"))
+
+    def request(self, msg: dict) -> dict:
+        mid = next(self._ids)             # ここで一意 id を採番 (caller は id を持たない)
+        msg = {**msg, "id": mid}
+        slot = {"ev": threading.Event(), "msg": None}
+        with self._lock:                  # pending 登録と write を同一 lock 内で (reader との競合を防ぐ)
+            self._pending[mid] = slot
+            self._wfile.write(json.dumps(msg) + "\n")
+            self._wfile.flush()
+        if not slot["ev"].wait(timeout=20):
+            with self._lock:
+                self._pending.pop(mid, None)
+            raise SesameError("request timed out", kind="timeout")
+        return slot["msg"]
+
+    def subscribe(self, topics, on_event):
+        self._on_event = on_event
+        return self.request({"jsonrpc": "2.0", "method": "events.subscribe", "params": {"topics": topics}})
+
+    def close(self):
+        try:
+            self._sock.close()
+        except OSError:
+            pass
+
+
+class _StdioTransport(_StreamTransport):
+    def __init__(self, cmd):
+        try:
+            self._proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                          stderr=subprocess.PIPE, text=True, bufsize=1)
+        except FileNotFoundError:
+            raise SesameError(
+                f"`{cmd[0]}` が見つかりません。`npm link` (sesame-kit 内で実行) で PATH を通すか、"
+                f"cmd=['node','bin/sesame.js','serve','--stdio'] を渡してください",
+                kind="connection_lost") from None
+        # stderr を読む儀式は不要 (早期入力は OS パイプが buffer。request は timeout 付き)。
+        # 起動直後に死んだ場合だけ検知して分かりやすく報告する。
+        if self._proc.poll() is not None:
+            err = (self._proc.stderr.read() or "").strip()
+            raise SesameError(f"sesame serve が起動直後に終了しました: {err}", kind="connection_lost")
+        self._wfile = self._proc.stdin
+        self._rfile = self._proc.stdout
+        self._pending = {}
+        self._ids = itertools.count(1)
+        self._on_event = None
+        self._lock = threading.Lock()
+        threading.Thread(target=self._reader, daemon=True).start()
+
+    def close(self):
+        try:
+            self._proc.stdin.close()
+            self._proc.terminate()
+        except Exception:
+            pass
+
+
+class _HttpTransport:
+    def __init__(self, base: str, token: Optional[str]):
+        self._base, self._token = base, token
+        self._ids = itertools.count(1)
+
+    def _headers(self):
+        h = {"content-type": "application/json"}
+        if self._token:
+            h["authorization"] = f"Bearer {self._token}"
+        return h
+
+    def _unauthorized(self):
+        if not self._token:
+            return SesameError(
+                f"token が見つかりません。`sesame serve --http` で起動すると {_default_token_path()} に保存されます "
+                f"(または http(token=...) で明示指定)", kind="not_authenticated", code=401)
+        return SesameError("unauthorized (token 不一致)", kind="not_authenticated", code=401)
+
+    def request(self, msg: dict) -> dict:
+        msg = {**msg, "id": next(self._ids)}  # id 必須 (無いと通知扱いで応答が返らない)
+        data = json.dumps(msg).encode()
+        req = urllib.request.Request(f"{self._base}/rpc", data=data, headers=self._headers(), method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=20) as r:
+                body = r.read()
+                return json.loads(body) if body else {"id": msg["id"], "result": None}
+        except urllib.error.HTTPError as e:
+            if e.code == 401:
+                raise self._unauthorized() from None
+            raise SesameError(f"HTTP {e.code}: {e.reason}", kind="internal", code=e.code) from None
+        except urllib.error.URLError as e:
+            raise SesameError(f"接続失敗: {e.reason}。`sesame serve --http` を起動しましたか?",
+                              kind="connection_lost") from None
+
+    def subscribe(self, topics, on_event):
+        q = ",".join(topics)
+        url = f"{self._base}/events?topics={q}"
+        if self._token:
+            url += f"&token={self._token}"
+        # 初回接続を**同期で**確立し、401/400 (不正 topic) をその場で raise (JS と対称。
+        # バックグラウンドで黙って失敗していた旧挙動を是正)。
+        req = urllib.request.Request(url, headers=self._headers())
+        try:
+            r = urllib.request.urlopen(req)
+        except urllib.error.HTTPError as e:
+            if e.code == 401:
+                raise self._unauthorized() from None
+            raise SesameError(f"events 購読失敗 (HTTP {e.code}): {e.reason}", kind="bad_params", code=e.code) from None
+        except urllib.error.URLError as e:
+            raise SesameError(f"events 接続失敗: {e.reason}。`sesame serve --http` を起動しましたか?",
+                              kind="connection_lost") from None
+
+        def run():
+            try:
+                with r:
+                    for raw in r:
+                        line = raw.decode().strip()
+                        if line.startswith("data: "):
+                            msg = json.loads(line[len("data: "):])
+                            m = msg.get("method", "")
+                            if m.startswith("event."):
+                                on_event(m[len("event."):], msg.get("params"))
+            except Exception as exc:  # 確立後のストリーム中断は握り潰さず stderr に
+                print(f"[sesame] subscribe stream error: {exc}", file=sys.stderr)
+
+        threading.Thread(target=run, daemon=True).start()
+
+    def close(self):
+        pass
+
+
+if __name__ == "__main__":
+    mode = sys.argv[1] if len(sys.argv) > 1 else "unix"
+    c = SesameClient.http() if mode == "http" else SesameClient.unix()
+    print("status:", c.status())
+    print("methods:", len(c.discover_names()))

package/clients/python/setup.cfg

@@ -0,0 +1,11 @@
+# 宣言的メタデータ (setuptools 30.3+/2017 以降が読む)。PEP 621 の pyproject [project] は
+# setuptools>=61 が必須で、古い環境では name/version を黙って無視し UNKNOWN-0.0.0 の空 wheel に
+# なる (初学者が古い Python で詰まる)。単一モジュールの薄いクライアントは互換性を優先し setup.cfg にする。
+[metadata]
+name = sesame-client
+version = 0.1.0
+description = Thin zero-dependency Python client for `sesame serve` (JSON-RPC over UDS/stdio/HTTP).
+
+[options]
+py_modules = sesame_client
+python_requires = >=3.8