@agentunion/kite 1.0.0

package/__init__.py

@@ -0,0 +1 @@
+# Kite framework package

package/__main__.py

@@ -0,0 +1,15 @@
+"""Allow running Kite as a package: python -m Kite"""
+import os, sys
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import secrets
+from core.launcher.entry import Launcher
+
+
+def main():
+    token = secrets.token_hex(32)
+    print(f"[main] KITE_TOKEN generated ({len(token)} chars)")
+    Launcher(kite_token=token).run()
+
+
+if __name__ == "__main__":
+    main()

package/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Kite CLI — Node.js entry point.
+ * Generates KITE_TOKEN, spawns the Python launcher, forwards output.
+ *
+ * Usage:
+ *   kite                     # after npm install -g / npm link
+ *   kite --cwd /some/path    # override working directory
+ *   node cli.js              # direct execution
+ *
+ * Environment variables passed to Python:
+ *   KITE_HOME  — Kite framework root (where core/, extensions/ live)
+ *   KITE_CWD   — directory where user executed the kite command
+ */
+const { spawn } = require('child_process');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+// Parse CLI args
+const args = process.argv.slice(2);
+const pythonArgs = [];
+let cwdOverride = null;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--cwd' && args[i + 1]) {
+    cwdOverride = path.resolve(args[++i]);
+  } else {
+    pythonArgs.push(args[i]);
+  }
+}
+
+const token = crypto.randomBytes(32).toString('hex');
+const kiteHome = fs.realpathSync(__dirname);
+const kiteCwd = cwdOverride || process.cwd();
+
+console.log(`[main] KITE_TOKEN generated (${token.length} chars)`);
+console.log(`[main] KITE_HOME: ${kiteHome}`);
+console.log(`[main] KITE_CWD:  ${kiteCwd}`);
+
+// Spawn Python using package mode: python -m Kite
+// PYTHONPATH points to Kite's parent so "import Kite" / "python -m Kite" works
+const kiteParent = path.dirname(kiteHome);
+const env = {
+  ...process.env,
+  KITE_HOME: kiteHome,
+  KITE_CWD: kiteCwd,
+  PYTHONPATH: kiteParent + (process.env.PYTHONPATH ? path.delimiter + process.env.PYTHONPATH : ''),
+  PYTHONUTF8: '1',
+};
+
+const python = process.platform === 'win32' ? 'python' : 'python3';
+const child = spawn(
+  python,
+  [path.join(kiteHome, 'main.py'), ...pythonArgs],
+  { cwd: kiteHome, env, stdio: 'inherit' }
+);
+
+child.on('error', err => {
+  console.error(`[main] Failed to start Python: ${err.message}`);
+  console.error(`[main] Make sure '${python}' is in PATH and dependencies are installed`);
+  process.exit(1);
+});
+
+child.on('exit', code => process.exit(code ?? 0));
+
+// Forward signals for graceful shutdown
+for (const sig of ['SIGINT', 'SIGTERM']) {
+  process.on(sig, () => child.kill(sig));
+}

package/core/event_hub/BENCHMARK.md

@@ -0,0 +1,94 @@
+# Event Hub 基准测试指南
+
+## 快速开始
+
+从 Kite 根目录运行：
+
+```bash
+python -m core.event_hub.bench_perf
+```
+
+运行约 20 秒，结果自动保存到 `core/event_hub/bench_results/` 目录。
+
+## 测试项说明
+
+### 1. Throughput（吞吐量）
+
+一次性发送 10000 个事件，测量整条链路的处理速度。
+
+| 指标 | 含义 |
+|------|------|
+| send_rate | publisher 每秒发送事件数（evt/s） |
+| hub_queued | hub 成功放入订阅者队列的数量 |
+| hub_routed | hub sender loop 成功发出的数量 |
+| client_recv | 订阅者客户端实际收到的数量 |
+
+三个数字一致 = 零丢失。哪个数字变小，哪个环节就是瓶颈。
+
+### 2. Latency（延迟）
+
+逐条发送 200 个事件，测量端到端耗时。
+
+| 指标 | 含义 |
+|------|------|
+| avg_ms | 平均延迟 |
+| p50_ms | 中位数延迟（50% 的请求低于此值） |
+| p95_ms | 95 分位延迟 |
+| p99_ms | 99 分位延迟（最差情况） |
+
+### 3. Fan-out（扇出）
+
+1 个 publisher 发送 2000 个事件，N 个 subscriber 同时接收。
+
+| 场景 | 含义 |
+|------|------|
+| x1 | 1 个订阅者，基线性能 |
+| x10 | 10 个订阅者，中等负载 |
+| x50 | 50 个订阅者，高负载 |
+
+每个场景报告 `avg_recv`（平均接收数）和 `min_recv`（最少接收数）。全部等于发送数 = 零丢失。
+
+## 结果文件
+
+每次运行自动保存到 `core/event_hub/bench_results/`：
+
+```
+bench_results/
+  2026-02-28_05-22-18.json
+  2026-02-28_06-30-00.json
+```
+
+JSON 结构：
+
+```json
+{
+  "timestamp": "2026-02-28T05:22:18",
+  "env": { "platform": "win32", "python": "3.12.0" },
+  "throughput": { "send_rate": 9752, "hub_queued": 10000, ... },
+  "latency": { "avg_ms": 0.6, "p50_ms": 0.55, ... },
+  "fanout_1": { ... },
+  "fanout_10": { ... },
+  "fanout_50": { ... },
+  "hub_counters": { ... }
+}
+```
+
+## 如何对比优化效果
+
+1. 改动代码前跑一次 `python -m core.event_hub.bench_perf`
+2. 实施优化
+3. 再跑一次
+4. 对比两个 JSON 文件中的关键指标
+
+重点关注：
+- `throughput.send_rate` — 越高越好
+- `latency.p99_ms` — 越低越好
+- `fanout_50.min_recv` — 应等于 2000（零丢失）
+
+## 其他测试脚本
+
+| 脚本 | 用途 | 耗时 |
+|------|------|------|
+| `bench_perf` | 快速基准对比 | ~20s |
+| `bench_extreme` | 极限压测（50000 burst、100MB 消息、50 subscriber） | ~5min |
+| `bench` | 长时间混合压力测试 | ~10min |

package/core/event_hub/bench.py

@@ -0,0 +1,459 @@
+"""
+Event Hub stress test (standalone).
+
+Usage:  python -m core.event_hub.bench
+        (from Kite root directory)
+
+Phase 1: 3-channel mixed stress test (10 minutes)
+  CH1 — high-freq small messages (500 evt/s)
+  CH2 — medium-freq large messages (50 evt/s, 10KB)
+  CH3 — bursty traffic (200-event burst every 2s)
+
+Phase 2: 3 extreme tests
+  EX1 — max burst (ramp until failure)
+  EX2 — max concurrent connections
+  EX3 — max message size
+"""
+
+import asyncio
+import json
+import os
+import socket
+import statistics
+import sys
+import threading
+import time
+import uuid
+from datetime import datetime, timezone
+
+_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+if _root not in sys.path:
+    sys.path.insert(0, _root)
+
+import psutil
+import uvicorn
+import websockets
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+from core.event_hub.hub import EventHub
+
+
+# ── Minimal Event Hub server (no auth) ──
+
+def _create_app(hub: EventHub) -> FastAPI:
+    app = FastAPI()
+
+    @app.websocket("/ws")
+    async def ws(ws: WebSocket):
+        mid = ws.query_params.get("id", f"anon_{id(ws)}")
+        await ws.accept()
+        hub.add_connection(mid, ws)
+        try:
+            while True:
+                raw = await ws.receive_text()
+                await hub.handle_message(mid, ws, raw)
+        except (WebSocketDisconnect, Exception):
+            pass
+        finally:
+            hub.remove_connection(mid)
+
+    return app
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+# ── Client ──
+
+class C:
+    """Lightweight WS client."""
+    def __init__(self, url: str, name: str):
+        self.url, self.name, self.ws = url, name, None
+
+    async def connect(self):
+        self.ws = await websockets.connect(f"{self.url}?id={self.name}", max_size=None)
+
+    async def sub(self, patterns):
+        await self.ws.send(json.dumps({"type": "subscribe", "events": patterns}))
+
+    async def pub(self, event: str, data: dict) -> str:
+        eid = str(uuid.uuid4())
+        await self.ws.send(json.dumps({
+            "type": "event", "event_id": eid, "event": event,
+            "source": self.name, "timestamp": datetime.now(timezone.utc).isoformat(),
+            "data": data,
+        }))
+        return eid
+
+    async def recv(self, timeout=5.0):
+        try:
+            return json.loads(await asyncio.wait_for(self.ws.recv(), timeout=timeout))
+        except Exception:
+            return None
+
+    async def drain(self, timeout=0.05):
+        while await self.recv(timeout=timeout) is not None:
+            pass
+
+    async def close(self):
+        if self.ws:
+            await self.ws.close()
+
+
+# ── Stats collector ──
+
+class Stats:
+    def __init__(self):
+        self.sent = 0
+        self.received = 0
+        self.acked = 0
+        self.latencies: list[float] = []
+        self.lock = asyncio.Lock()
+
+    async def record_latency(self, ts_iso: str):
+        try:
+            sent = datetime.fromisoformat(ts_iso)
+            ms = (datetime.now(timezone.utc) - sent).total_seconds() * 1000
+            async with self.lock:
+                self.latencies.append(ms)
+        except Exception:
+            pass
+
+    def summary(self) -> dict:
+        lat = sorted(self.latencies) if self.latencies else [0]
+        return {
+            "sent": self.sent,
+            "recv": self.received,
+            "acked": self.acked,
+            "loss": self.sent - self.received,
+            "lat_avg": round(statistics.mean(lat), 1),
+            "lat_p50": round(statistics.median(lat), 1),
+            "lat_p95": round(lat[int(len(lat) * 0.95)], 1),
+            "lat_p99": round(lat[int(len(lat) * 0.99)], 1),
+        }
+
+
+# ── Benchmark ──
+
+class Benchmark:
+    def __init__(self):
+        self.hub = EventHub()
+        self.port = _free_port()
+        self.ws_url = f"ws://127.0.0.1:{self.port}/ws"
+        self._server: uvicorn.Server | None = None
+        self.proc = psutil.Process()
+
+    def _start_server(self):
+        app = _create_app(self.hub)
+        cfg = uvicorn.Config(app, host="127.0.0.1", port=self.port, log_level="warning")
+        self._server = uvicorn.Server(cfg)
+        threading.Thread(target=self._server.run, daemon=True).start()
+        deadline = time.time() + 5
+        while time.time() < deadline:
+            if self._server.started:
+                return
+            time.sleep(0.05)
+        raise RuntimeError("Server failed to start")
+
+    def _res_snapshot(self) -> dict:
+        return {
+            "cpu": self.proc.cpu_percent(),
+            "mem_mb": round(self.proc.memory_info().rss / 1024 / 1024, 1),
+        }
+
+    async def _make_channel(self, pub_name: str, sub_name: str, pattern: str):
+        """Create a pub/sub pair, subscribe, return (pub, sub, stats)."""
+        pub = C(self.ws_url, pub_name)
+        sub = C(self.ws_url, sub_name)
+        await pub.connect()
+        await sub.connect()
+        await sub.sub([pattern])
+        await asyncio.sleep(0.1)
+        return pub, sub, Stats()
+
+    # ── ACK drainer (keeps publisher WS buffer clear) ──
+
+    async def _drainer(self, pub: C, stats: Stats, stop: asyncio.Event):
+        while not stop.is_set():
+            msg = await pub.recv(timeout=0.3)
+            if msg and msg.get("type") == "ack":
+                stats.acked += 1
+
+    # ── Subscriber receiver (shared by all channels) ──
+
+    async def _receiver(self, sub: C, stats: Stats, stop: asyncio.Event):
+        while not stop.is_set():
+            msg = await sub.recv(timeout=0.3)
+            if not msg:
+                continue
+            if msg.get("type") == "event":
+                stats.received += 1
+                ts = msg.get("timestamp", "")
+                if ts:
+                    await stats.record_latency(ts)
+
+    # ── CH1: high-freq small messages ──
+
+    async def _ch1_sender(self, pub: C, stats: Stats, stop: asyncio.Event):
+        """500 evt/s, tiny payload."""
+        while not stop.is_set():
+            await pub.pub("ch1.fast", {"seq": stats.sent})
+            stats.sent += 1
+            await asyncio.sleep(0.002)
+
+    # ── CH2: medium-freq large messages ──
+
+    async def _ch2_sender(self, pub: C, stats: Stats, stop: asyncio.Event):
+        """50 evt/s, 10KB payload."""
+        payload = "X" * 10240
+        while not stop.is_set():
+            await pub.pub("ch2.large", {"p": payload})
+            stats.sent += 1
+            await asyncio.sleep(0.02)
+
+    # ── CH3: bursty traffic ──
+
+    async def _ch3_sender(self, pub: C, stats: Stats, stop: asyncio.Event):
+        """200-event burst every 2s."""
+        while not stop.is_set():
+            for _ in range(200):
+                await pub.pub("ch3.burst", {"b": stats.sent})
+                stats.sent += 1
+            await asyncio.sleep(2)
+
+    # ── Phase 1: 10-min mixed stress ──
+
+    async def phase1(self, duration=600):
+        print("=" * 60)
+        print(f"PHASE 1: 3-channel mixed stress test ({duration}s)")
+        print("=" * 60)
+
+        p1, s1, st1 = await self._make_channel("ch1_pub", "ch1_sub", "ch1.*")
+        p2, s2, st2 = await self._make_channel("ch2_pub", "ch2_sub", "ch2.*")
+        p3, s3, st3 = await self._make_channel("ch3_pub", "ch3_sub", "ch3.*")
+        stop = asyncio.Event()
+
+        tasks = [
+            asyncio.create_task(self._ch1_sender(p1, st1, stop)),
+            asyncio.create_task(self._drainer(p1, st1, stop)),
+            asyncio.create_task(self._receiver(s1, st1, stop)),
+            asyncio.create_task(self._ch2_sender(p2, st2, stop)),
+            asyncio.create_task(self._drainer(p2, st2, stop)),
+            asyncio.create_task(self._receiver(s2, st2, stop)),
+            asyncio.create_task(self._ch3_sender(p3, st3, stop)),
+            asyncio.create_task(self._drainer(p3, st3, stop)),
+            asyncio.create_task(self._receiver(s3, st3, stop)),
+        ]
+
+        self.proc.cpu_percent()  # prime
+        start = time.time()
+        interval = 30  # report every 30s
+        next_report = start + interval
+
+        while time.time() - start < duration:
+            await asyncio.sleep(1)
+            if time.time() >= next_report:
+                elapsed = round(time.time() - start)
+                res = self._res_snapshot()
+                hub_stats = self.hub._counters_dict()
+                print(f"\n  [{elapsed:>4}s] cpu={res['cpu']:.0f}%  mem={res['mem_mb']}MB  "
+                      f"hub_recv={hub_stats['events_received']}  hub_route={hub_stats['events_routed']}")
+                for name, st in [("CH1-fast", st1), ("CH2-large", st2), ("CH3-burst", st3)]:
+                    s = st.summary()
+                    print(f"    {name}: sent={s['sent']}  recv={s['recv']}  loss={s['loss']}  "
+                          f"avg={s['lat_avg']}ms  p95={s['lat_p95']}ms  p99={s['lat_p99']}ms")
+                next_report = time.time() + interval
+
+        stop.set()
+        for t in tasks:
+            t.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Final report
+        print(f"\n  FINAL ({duration}s):")
+        res = self._res_snapshot()
+        print(f"  cpu={res['cpu']:.0f}%  mem={res['mem_mb']}MB")
+        for name, st in [("CH1-fast", st1), ("CH2-large", st2), ("CH3-burst", st3)]:
+            s = st.summary()
+            print(f"    {name}: sent={s['sent']}  recv={s['recv']}  loss={s['loss']}  "
+                  f"avg={s['lat_avg']}ms  p50={s['lat_p50']}ms  p95={s['lat_p95']}ms  p99={s['lat_p99']}ms")
+
+        for c in [p1, s1, p2, s2, p3, s3]:
+            await c.close()
+        print()
+
+    # ── Phase 2: Extreme tests ──
+
+    async def extreme1_max_burst(self):
+        """Ramp burst size until loss or timeout."""
+        print("=" * 60)
+        print("EXTREME 1: Max burst (ramp until loss)")
+        print("=" * 60)
+
+        pub, sub, _ = await self._make_channel("ex1_pub", "ex1_sub", "ex1.*")
+
+        for size in [1000, 5000, 10000, 20000, 50000]:
+            recvd = 0
+            stop = asyncio.Event()
+
+            async def _recv():
+                nonlocal recvd
+                while not stop.is_set():
+                    msg = await sub.recv(timeout=0.3)
+                    if msg and msg.get("type") == "event":
+                        recvd += 1
+
+            task = asyncio.create_task(_recv())
+            start = time.time()
+            for i in range(size):
+                await pub.pub("ex1.burst", {"i": i})
+            send_time = time.time() - start
+
+            # Wait for delivery
+            await asyncio.sleep(max(3, size / 2000))
+            stop.set()
+            await task
+            await pub.drain()
+            await sub.drain()
+
+            rate = size / send_time if send_time > 0 else 0
+            loss = size - recvd
+            loss_pct = loss / size * 100
+            res = self._res_snapshot()
+            print(f"  burst={size:>6}: recv={recvd}  loss={loss}({loss_pct:.1f}%)  "
+                  f"rate={rate:.0f} evt/s  cpu={res['cpu']:.0f}%  mem={res['mem_mb']}MB")
+
+            if loss_pct > 5:
+                print(f"  >> Loss exceeded 5%, stopping ramp")
+                break
+
+        await pub.close()
+        await sub.close()
+        print()
+
+    async def extreme2_max_connections(self):
+        """Ramp concurrent connections, each publishing 1 evt/s."""
+        print("=" * 60)
+        print("EXTREME 2: Max concurrent connections")
+        print("=" * 60)
+
+        # One global subscriber
+        gsub = C(self.ws_url, "ex2_gsub")
+        await gsub.connect()
+        await gsub.sub(["ex2.*"])
+        await asyncio.sleep(0.1)
+
+        for n_conn in [10, 50, 100, 200, 500]:
+            clients = []
+            try:
+                for i in range(n_conn):
+                    c = C(self.ws_url, f"ex2_c{i}")
+                    await c.connect()
+                    clients.append(c)
+            except Exception as e:
+                print(f"  {len(clients)} connections: FAILED to open more ({e})")
+                break
+
+            # Each client sends 1 event
+            recvd = 0
+            stop = asyncio.Event()
+
+            async def _recv():
+                nonlocal recvd
+                while not stop.is_set():
+                    msg = await gsub.recv(timeout=0.3)
+                    if msg and msg.get("type") == "event":
+                        recvd += 1
+
+            task = asyncio.create_task(_recv())
+            start = time.time()
+            for c in clients:
+                await c.pub("ex2.ping", {"from": c.name})
+            send_time = time.time() - start
+
+            await asyncio.sleep(max(2, n_conn / 200))
+            stop.set()
+            await task
+
+            res = self._res_snapshot()
+            print(f"  {n_conn:>4} conns: recv={recvd}/{n_conn}  "
+                  f"send_time={send_time:.2f}s  cpu={res['cpu']:.0f}%  mem={res['mem_mb']}MB")
+
+            for c in clients:
+                await c.close()
+
+        await gsub.close()
+        print()
+
+    async def extreme3_max_message_size(self):
+        """Ramp message size until failure."""
+        print("=" * 60)
+        print("EXTREME 3: Max message size")
+        print("=" * 60)
+
+        pub, sub, _ = await self._make_channel("ex3_pub", "ex3_sub", "ex3.*")
+
+        for size_kb in [100, 500, 1000, 2000, 5000]:
+            payload = "Z" * (size_kb * 1024)
+            latencies = []
+            ok = True
+
+            for _ in range(5):
+                try:
+                    await pub.pub("ex3.big", {"p": payload})
+                except Exception as e:
+                    print(f"  {size_kb:>5} KB: SEND FAILED ({e})")
+                    ok = False
+                    break
+
+            if not ok:
+                break
+
+            await asyncio.sleep(max(1, size_kb / 500))
+            # Collect
+            for _ in range(20):
+                msg = await sub.recv(timeout=0.3)
+                if msg and msg.get("type") == "event":
+                    ts = msg.get("timestamp", "")
+                    try:
+                        sent = datetime.fromisoformat(ts)
+                        latencies.append((datetime.now(timezone.utc) - sent).total_seconds() * 1000)
+                    except Exception:
+                        pass
+                if msg is None:
+                    break
+
+            await pub.drain()
+            res = self._res_snapshot()
+            if latencies:
+                avg = statistics.mean(latencies)
+                print(f"  {size_kb:>5} KB: recv={len(latencies)}/5  "
+                      f"avg={avg:.1f}ms  cpu={res['cpu']:.0f}%  mem={res['mem_mb']}MB")
+            else:
+                print(f"  {size_kb:>5} KB: recv=0/5  cpu={res['cpu']:.0f}%  mem={res['mem_mb']}MB")
+
+        await pub.close()
+        await sub.close()
+        print()
+
+    # ── Entry ──
+
+    async def run_all(self):
+        self._start_server()
+        print(f"Event Hub started on port {self.port}\n")
+        try:
+            await self.phase1(duration=600)
+            await self.extreme1_max_burst()
+            await self.extreme2_max_connections()
+            await self.extreme3_max_message_size()
+            print("All tests complete.")
+        finally:
+            if self._server:
+                self._server.should_exit = True
+
+
+if __name__ == "__main__":
+    asyncio.run(Benchmark().run_all())