agent-phonon-sdk 0.2.4__py3-none-any.whl

agent_phonon/__init__.py

@@ -0,0 +1,6 @@
+"""agent-phonon Server SDK — orchestrate AI agents across multiple devices."""
+from .server import PhononServer, PhononDevice, PhononSession
+from .rpc import RpcPeer, RpcError
+
+__all__ = ["PhononServer", "PhononDevice", "PhononSession", "RpcPeer", "RpcError"]
+__version__ = "0.2.4"

agent_phonon/rpc.py

@@ -0,0 +1,75 @@
+"""双向 JSON-RPC 2.0 peer（asyncio）。每个 device 连接一个。"""
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from typing import Any, Awaitable, Callable
+
+RpcHandler = Callable[[str, Any], Awaitable[Any]]
+
+
+class RpcPeer:
+    def __init__(self, send: Callable[[str], Awaitable[None]], handler: RpcHandler) -> None:
+        self._send = send
+        self._handler = handler
+        self._pending: dict[Any, asyncio.Future] = {}
+        self._next_id = 1
+
+    async def request(self, method: str, params: Any, timeout: float = 600.0) -> Any:
+        rid = self._next_id
+        self._next_id += 1
+        fut: asyncio.Future = asyncio.get_event_loop().create_future()
+        self._pending[rid] = fut
+        await self._send(json.dumps({"jsonrpc": "2.0", "id": rid, "method": method, "params": params}))
+        try:
+            return await asyncio.wait_for(fut, timeout)
+        finally:
+            self._pending.pop(rid, None)
+
+    async def notify(self, method: str, params: Any) -> None:
+        await self._send(json.dumps({"jsonrpc": "2.0", "method": method, "params": params}))
+
+    async def handle(self, data: str) -> None:
+        try:
+            msg = json.loads(data)
+        except json.JSONDecodeError:
+            return
+        # 响应
+        if ("result" in msg or "error" in msg) and "id" in msg:
+            fut = self._pending.get(msg["id"])
+            if fut and not fut.done():
+                if "error" in msg and msg["error"]:
+                    fut.set_exception(RpcError(msg["error"]))
+                else:
+                    fut.set_result(msg.get("result"))
+            return
+        # 请求 / 通知
+        method = msg.get("method")
+        if isinstance(method, str):
+            is_notification = "id" not in msg or msg.get("id") is None
+            try:
+                result = await self._handler(method, msg.get("params"))
+                if not is_notification:
+                    await self._send(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": result if result is not None else None}))
+            except Exception as e:  # noqa: BLE001
+                if not is_notification:
+                    await self._send(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "error": {"code": -32000, "message": str(e)}}))
+
+    def reject_all(self, reason: str) -> None:
+        for fut in self._pending.values():
+            if not fut.done():
+                fut.set_exception(ConnectionError(reason))
+        self._pending.clear()
+
+
+class RpcError(Exception):
+    def __init__(self, error: Any) -> None:
+        self.error = error
+        msg = error.get("message", str(error)) if isinstance(error, dict) else str(error)
+        self.app_code = (error.get("data") or {}).get("appCode") if isinstance(error, dict) else None
+        super().__init__(msg)
+
+
+def new_id() -> str:
+    return str(uuid.uuid4())

agent_phonon/server.py

@@ -0,0 +1,241 @@
+"""agent-phonon Server SDK（Python）。
+
+让任何 Python 项目「一键成为 phonon 服务端」：导入 SDK → 配鉴权 → 监听 device →
+用干净接口（discover / create_session / send / stream / on_hook）编排多台设备上的 agent。
+协议帧/握手/ack/HITL 路由全由 SDK 处理。支持多设备。
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, AsyncIterator, Awaitable, Callable, Optional
+
+import websockets
+
+from .rpc import RpcPeer, new_id
+
+# 鉴权回调：返回 tenantId 字符串表示通过，返回 None 拒绝。
+Authenticate = Callable[[str, Optional[str]], Awaitable[Optional[str]]]
+# HITL 裁决：返回 "continue"/"abort"/"inject"/"modify" 或 (action, reason)。
+HookDecider = Callable[[dict, Optional["PhononSession"]], Awaitable[Any]]
+
+
+class PhononSession:
+    """一个会话。流式输出用 async iterator。"""
+
+    def __init__(self, device: "PhononDevice", session_id: str) -> None:
+        self.session_id = session_id
+        self.device = device
+        self._queue: asyncio.Queue = asyncio.Queue()
+        self._last_seq = -1
+
+    async def send(self, text: str, **opts: Any) -> dict:
+        return await self.device.call("session.send", {"sessionId": self.session_id, "input": text, **opts})
+
+    async def stream(self) -> AsyncIterator[dict]:
+        """异步迭代本会话的流式事件，直到 final。"""
+        while True:
+            ev = await self._queue.get()
+            yield ev
+            if ev.get("final"):
+                break
+
+    async def inject(self, context: list[dict]) -> Any:
+        return await self.device.call("session.inject", {"sessionId": self.session_id, "context": context})
+
+    async def interrupt(self, reason: str | None = None) -> Any:
+        return await self.device.call("session.interrupt", {"sessionId": self.session_id, "reason": reason})
+
+    async def switch_model(self, model: str) -> Any:
+        return await self.device.call("session.switchModel", {"sessionId": self.session_id, "model": model})
+
+    async def compress(self, mode: str = "native") -> Any:
+        return await self.device.call("session.compress", {"sessionId": self.session_id, "mode": mode})
+
+    async def status(self) -> dict:
+        return await self.device.call("session.status", {"sessionId": self.session_id})
+
+    async def terminate(self) -> Any:
+        return await self.device.call("session.terminate", {"sessionId": self.session_id})
+
+    def _on_stream(self, ev: dict) -> None:
+        seq = ev.get("seq", -1)
+        if seq > self._last_seq:
+            self._last_seq = seq
+        self._queue.put_nowait(ev)
+
+
+class PhononDevice:
+    """一台连入的设备。"""
+
+    def __init__(self, device_id: str, tenant_id: str, peer: RpcPeer) -> None:
+        self.device_id = device_id
+        self.tenant_id = tenant_id
+        self._peer = peer
+        self._sessions: dict[str, PhononSession] = {}
+        self._hook_decider: Optional[HookDecider] = None
+        self._unsolicited: Optional[Callable[[dict], None]] = None
+
+    async def call(self, method: str, params: Any) -> Any:
+        return await self._peer.request(method, params)
+
+    async def discover(self) -> list[dict]:
+        r = await self._peer.request("discovery.list", {})
+        return r.get("agents", [])
+
+    async def create_session(self, project: str, agent: str, model: str, **opts: Any) -> PhononSession:
+        r = await self._peer.request("session.create", {"project": project, "agent": agent, "model": model, "verbosity": "messages", **opts})
+        s = PhononSession(self, r["sessionId"])
+        self._sessions[r["sessionId"]] = s
+        return s
+
+    async def list_sessions(self, **filt: Any) -> dict:
+        return await self._peer.request("session.list", filt)
+
+    async def info(self) -> dict:
+        """设备 OS/机器信息，用于服务端做任务调度决策。"""
+        return await self._peer.request("device.info", {})
+
+    async def resources(self) -> dict:
+        """设备资源快照：CPU/内存/磁盘/进程/GPU best-effort。"""
+        return await self._peer.request("device.resources", {})
+
+    # ---- project / file / skill 便捷封装 ----
+    async def project_create(self, name: str, git: bool = True, **opts: Any) -> dict:
+        return await self._peer.request("project.create", {"name": name, "git": git, **opts})
+
+    async def project_list(self) -> dict:
+        return await self._peer.request("project.list", {})
+
+    async def project_remove(self, project_id: str, **opts: Any) -> Any:
+        return await self._peer.request("project.remove", {"projectId": project_id, **opts})
+
+    async def env_set(self, scope: str, name: str, value: str, **opts: Any) -> dict:
+        return await self._peer.request("env.set", {"scope": scope, "name": name, "value": value, **opts})
+
+    async def env_list(self, **opts: Any) -> dict:
+        return await self._peer.request("env.list", opts)
+
+    async def env_delete(self, scope: str, name: str, **opts: Any) -> dict:
+        return await self._peer.request("env.delete", {"scope": scope, "name": name, **opts})
+
+    async def file_read(self, project_id: str, path: str, **opts: Any) -> dict:
+        return await self._peer.request("file.read", {"projectId": project_id, "path": path, **opts})
+
+    async def file_write(self, project_id: str, path: str, data: str, **opts: Any) -> dict:
+        return await self._peer.request("file.write", {"projectId": project_id, "path": path, "data": data, **opts})
+
+    async def file_list(self, project_id: str, path: str = ".", **opts: Any) -> dict:
+        return await self._peer.request("file.list", {"projectId": project_id, "path": path, **opts})
+
+    async def file_stat(self, project_id: str, path: str, **opts: Any) -> dict:
+        return await self._peer.request("file.stat", {"projectId": project_id, "path": path, **opts})
+
+    async def file_mkdir(self, project_id: str, path: str, **opts: Any) -> dict:
+        return await self._peer.request("file.mkdir", {"projectId": project_id, "path": path, **opts})
+
+    async def skill_install(self, agent: str, name: str, scope: str, source: dict, project_id: str | None = None) -> Any:
+        return await self._peer.request("skill.install", {"agent": agent, "name": name, "scope": scope, "projectId": project_id, "source": source})
+
+    async def skill_list(self, **filt: Any) -> dict:
+        return await self._peer.request("skill.list", filt)
+
+    def set_hook_decider(self, fn: HookDecider) -> None:
+        self._hook_decider = fn
+
+    def set_unsolicited_handler(self, fn: Callable[[dict], None]) -> None:
+        self._unsolicited = fn
+
+    async def _handle_inbound(self, method: str, params: Any) -> Any:
+        if method == "stream.event":
+            ev = params or {}
+            s = self._sessions.get(ev.get("sessionId"))
+            if s is not None:
+                s._on_stream(ev)
+                await self._peer.notify("stream.ack", {"sessionId": ev.get("sessionId"), "lastSeq": s._last_seq})
+            elif ev.get("origin") == "unsolicited" and self._unsolicited:
+                self._unsolicited(ev)
+            return None
+        if method == "hook.fired":
+            s = self._sessions.get((params or {}).get("sessionId"))
+            if not self._hook_decider:
+                return {"applied": True}
+            d = await self._hook_decider(params, s)
+            if isinstance(d, tuple):
+                return {"action": d[0], "reason": d[1]}
+            return {"action": d}
+        return None
+
+    def _on_close(self) -> None:
+        self._peer.reject_all("device disconnected")
+
+
+class PhononServer:
+    """监听 ws，管理多设备。"""
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 0, authenticate: Optional[Authenticate] = None) -> None:
+        self._host = host
+        self._port = port
+        self._authenticate = authenticate
+        self._devices: dict[str, PhononDevice] = {}
+        self._on_device: Optional[Callable[[PhononDevice], Awaitable[None]]] = None
+        self._server: Any = None
+        self.port = port
+
+    def on_device(self, fn: Callable[[PhononDevice], Awaitable[None]]) -> Callable:
+        """装饰器/setter：设备拨入时回调。"""
+        self._on_device = fn
+        return fn
+
+    def list_devices(self) -> list[PhononDevice]:
+        return list(self._devices.values())
+
+    def get_device(self, device_id: str) -> Optional[PhononDevice]:
+        return self._devices.get(device_id)
+
+    async def listen(self) -> int:
+        self._server = await websockets.serve(self._on_connection, self._host, self._port)
+        sock = list(self._server.sockets)[0]
+        self.port = sock.getsockname()[1]
+        return self.port
+
+    async def _on_connection(self, ws: Any) -> None:
+        device: Optional[PhononDevice] = None
+
+        async def send(data: str) -> None:
+            await ws.send(data)
+
+        async def handler(method: str, params: Any) -> Any:
+            nonlocal device
+            if method == "connect.hello":
+                p = params or {}
+                device_id = p.get("deviceId")
+                device_key = (p.get("auth") or {}).get("deviceKey")
+                if self._authenticate:
+                    tenant = await self._authenticate(device_id, device_key)
+                else:
+                    tenant = f"tenant-{device_id}"
+                if tenant is None:
+                    raise PermissionError("unauthorized")
+                device = PhononDevice(device_id, tenant, peer)
+                self._devices[device_id] = device
+                if self._on_device:
+                    asyncio.create_task(self._on_device(device))
+                import datetime
+                return {"protocolVersion": "0.1.0", "tenantId": tenant, "features": [], "at": datetime.datetime.now(datetime.timezone.utc).isoformat()}
+            if device is None:
+                raise RuntimeError("not connected")
+            return await device._handle_inbound(method, params)
+
+        peer = RpcPeer(send, handler)
+        try:
+            async for raw in ws:
+                await peer.handle(raw if isinstance(raw, str) else raw.decode())
+        finally:
+            if device is not None:
+                self._devices.pop(device.device_id, None)
+                device._on_close()
+
+    async def close(self) -> None:
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()

agent_phonon_sdk-0.2.4.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: agent-phonon-sdk
+Version: 0.2.4
+Summary: Server SDK for agent-phonon — orchestrate AI agents across multiple devices.
+Author: agent-phonon contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hackerphysics/agent-phonon
+Project-URL: Repository, https://github.com/hackerphysics/agent-phonon
+Project-URL: Issues, https://github.com/hackerphysics/agent-phonon/issues
+Keywords: ai,agents,orchestration,llm,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+
+# agent-phonon — Python Server SDK
+
+让任何 Python 项目「一键成为 agent-phonon 服务端」：编排**多台设备**上的 AI agent（Claude Code / Codex / OpenCode / OpenClaw / Hermes）。
+
+## 安装
+
+```bash
+pip install agent-phonon   # 或 pip install -e sdk-python/
+```
+
+## 用法
+
+```python
+import asyncio
+from agent_phonon import PhononServer
+
+async def main():
+    server = PhononServer(port=8080, authenticate=verify_device)
+
+    @server.on_device
+    async def handle(device):                       # 每台设备拨入时
+        agents = await device.discover()            # 列设备上的 agent
+        proj = await device.project_create("my-proj")
+        session = await device.create_session(
+            project=proj["project"]["projectId"],
+            agent="openclaw:main", model="claude-opus-4.8",
+        )
+        # HITL：危险操作裁决
+        device.set_hook_decider(
+            lambda hook, s: "abort" if "rm -rf" in str(hook.get("payload", {})) else "continue"
+        )
+        await session.send("帮我重构这个函数")
+        async for event in session.stream():        # 流式输出
+            if event.get("type") == "message":
+                print(event["text"], end="")
+
+    await server.listen()
+    await asyncio.Future()  # 长跑
+
+async def verify_device(device_id, device_key):
+    return "tenant-1" if device_key == "secret" else None  # None = 拒绝
+
+asyncio.run(main())
+```
+
+## 核心抽象
+
+- **`PhononServer`** — ws 监听，管理多设备；`authenticate(device_id, device_key) -> tenant_id | None`；`on_device` 回调；`list_devices()` / `get_device()`
+- **`PhononDevice`** — `discover()` / `create_session()` / `list_sessions()` + `project_*` / `skill_*` 封装；`set_hook_decider()`（HITL）/ `set_unsolicited_handler()`（自发输出）
+- **`PhononSession`** — `send()` + `async for event in session.stream()`（流式）；`inject/interrupt/switch_model/compress/status/terminate`；自动 stream.ack
+
+## 多设备
+
+一个 `PhononServer` 同时连多个 phonon 设备，各设备 tenant 隔离、互不干扰——这是 phonon 作为「个人设备编排中心」的核心。
+
+## 协议
+
+JSON-RPC 2.0 over WebSocket。与 TS SDK（`@agent-phonon/server-sdk`）完全协议兼容——Python 服务端能指挥 TS phonon，反之亦然。

agent_phonon_sdk-0.2.4.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_phonon/__init__.py,sha256=4xcYD3zHqyExp9-0NHBdyec-LoNk3Hk2CkWHcsTKsiQ,284
+agent_phonon/rpc.py,sha256=z-3M1RD-HBhYholVetMA1pDkbDOYaNXdrsu126odKIc,2896
+agent_phonon/server.py,sha256=u_p8bBx2Su3dVZDVRSGAS4wbVmpO8UM7Mk-MFbDNPGA,10460
+agent_phonon_sdk-0.2.4.dist-info/METADATA,sha256=uOQKT83HvqwWEv6ndNRSh7FcUY3KZB4GDSGrBFyVrK0,3085
+agent_phonon_sdk-0.2.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agent_phonon_sdk-0.2.4.dist-info/top_level.txt,sha256=ENHMEURuw8-nSaYIUAoni5TS754pWMm9FOLO3iU7WL0,13
+agent_phonon_sdk-0.2.4.dist-info/RECORD,,

agent_phonon_sdk-0.2.4.dist-info/WHEEL

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

agent_phonon_sdk-0.2.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_phonon