hostanagent-client 0.2.4__tar.gz

hostanagent_client-0.2.4/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+.venv-release/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.env
+.env.*
+!.env.example
+data/
+*.sqlite*
+.coverage
+htmlcov/

hostanagent_client-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GeekArt Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hostanagent_client-0.2.4/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: hostanagent-client
+Version: 0.2.4
+Summary: Thin async client for the HostAnAgent public protocol
+Project-URL: Repository, https://github.com/ffskyfan/HostAnAgentBackend
+Project-URL: Documentation, https://pypi.org/project/hostanagent-client/
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Description-Content-Type: text/markdown
+
+# hostanagent-client 0.2.4
+
+用于产品后端的独立异步 SDK，Python >=3.10，仅依赖 httpx；不安装 HostAnAgent 服务、Worker 或 aisuite。协议兼容 1.0。0.2.4 为 MIT 许可准备版本，提供 wheel 和源码包，尚未公开发布到 PyPI。本 SDK 及随包文档采用 [MIT](https://opensource.org/license/mit)，版权归 GeekArt Inc.；这项授权覆盖 SDK 目录，服务端另行管理。正式发布后，本 README 会随 PyPI 项目页公开；当前元数据中的 PyPI 文档地址尚未上线。
+
+```bash
+python -m pip install ./hostanagent_client-0.2.4-py3-none-any.whl
+```
+
+在自己的控制台发布 Agent，用服务端应用 Key 连接。平台管理模型供应商凭证。当前代码已整合 D01：创建限制到目标 Agent 的 `runtime:read`、`runtime:write` Key；工具执行额外需要 `tools:execute`。运行发现使用 `await client.bootstrap()`，不需要配置管理权限。部署状态以文档仓库实施记录为准。
+
+```python
+import os
+from hostanagent import AgentClient, HostingError, idempotency_key
+
+async def chat(trusted_product_user_id):
+    async with AgentClient("https://api.hostanagent.com/v1", os.environ["HAA_APPLICATION_KEY"],
+                           subject=trusted_product_user_id) as client:
+        # Subject 必须来自产品验证过的登录态，不能直接取浏览器提交的 user_id。
+        models = await client.models()  # reasoning_options 决定可用五档思考强度
+        session = await client.create_session()
+        key = idempotency_key()  # 产品保存本请求的 key、正文和参数，未知结果时原样重试
+        try:
+            accepted = await client.run(session["id"], os.environ["HAA_AGENT_VERSION"], "整理我的任务",
+                idempotency_key=key, reasoning_effort="high", execution_mode="propose",
+                limits={"max_cost_usd": "1.000000000000"})
+        except HostingError as error:
+            if error.code == "INSUFFICIENT_BALANCE":
+                # 没有模型调用；当前人工测试入账，在线充值尚未开放。
+                return
+            raise
+        async for event in client.events(accepted["run_id"]):
+            print(event["sequence"], event["type"])
+```
+
+`endpoint` 可使用主机根路径或 `/v1`。`run` 支持规范所有现有参数；`create_run(body, idempotency_key=...)` 直接发送完整 RunCreate。
+`bootstrap()` 读取受限运行目录；`agent_runtime(agent_id, version_id=...)` 读取可启动状态和模型元数据；`capabilities/models` 读取能力；`sessions/session/messages/delete_session` 管理授权历史；`snapshot/cancel/add_input/approve/claim/receipt/events` 沿用协议。`create_session` 暴露 history_mode/runtime_mode，但 unsupported 模式仍由服务器拒绝，不能据此承诺 external/ephemeral 已实现。
+
+网络与恢复：
+
+- SDK 不自动重试 POST，也不生成隐式新请求。`httpx` 连接异常意味着结果可能未知，应原样重试原 key 或查询已接受 Run；不能换 key 重启付费 Run。
+- `events` 是单次观察订阅，按 UTF-8、CRLF、多行 data 解析，不调用工具 handler。网络断开后先 `snapshot(run_id)` 替换自己的投影，再 `events(run_id, after=snapshot["resume_cursor"])`。用事件 sequence 去重；缺口重新取快照。终态结束重连。401/403 停止恢复并重新核对权限。
+- `cancel(run_id)` 才是明确的停止请求。停止读取 events 或 close 客户端不取消 Agent/业务任务。
+- `add_input` 用同一幂等键重试。claim 的 replayed=true 要读取已有持久回执或由产品核对；绝不再次执行副作用。`receipt_id` 持久保存到确认完成。
+- `HostingError` 提供 code、status_code、request_id、details；不要将内部异常或完整请求正文写入浏览器或日志。USD 原样保持十进制字符串。
+- 恢复已有 session 保持其 agent_version；升级使用新会话。停用/归档由 D05 服务端最终拒绝，不自动换版本或提权。
+
+构建：安装 hatchling 后从干净提交执行 `python scripts/build_sdk.py`；生成 `dist/sdk/0.2.4/` 的 wheel、源码包、来源提交、固定契约摘要、构建工具版本与 SHA-256 清单。目录存在则拒绝覆盖。开发使用 `--candidate`。运行 `python scripts/check_sdk_release.py <产物目录>` 核对文件和包内容；加 `--publish-ready` 会额外拒绝许可证缺失、private 标记和未提交来源。`python scripts/test_sdk_install.py <wheel 或 tar.gz>` 在系统临时目录新建 venv、实际安装并调用，不依赖源码路径。离线依赖可通过 `HAA_WHEELHOUSE` 指定本地 wheelhouse。
+
+0.2.2 已整合 D01/D02/D03/D04/D05，保留固定版本调用方式；新增 `run(session_id, content="文本", agent_id="逻辑 Agent ID", idempotency_key=key)`。`agent_id` 和 `agent_version` 必须二选一。使用逻辑 ID 时由服务端在首次接受 Run 时固定版本，已有 Session 不跟随新发布；停用后原请求仍可按原 key 核对。0.2.2 快照与事件均拒绝非 1.0 协议。旧版 0.2.0/0.2.1/0.2.2 保留，不覆盖原文件。已用本机真实 API 签发的受限测试 Key 验证运行发现、文本 Run、SSE、跨 Agent 拒绝和撤销；模型及邮件均使用 mock。D02 执行器接口可经通用 `request` 调用，参考 `examples/README-executor.md`。
+
+0.2.3 保留上述 SDK API，增加源码包、发布检查和安装矩阵；采用包含 D07 与 durable 执行补齐的协议基线。
+
+0.2.4 补充客户端 MIT 许可；0.2.3 及更早产物保持不变。
+
+httpx 及传递依赖由 pip 独立安装，不打入本 wheel。第三方许可见 THIRD_PARTY_NOTICES.md。MIT 许可见 LICENSE；公开发布和真实产品/生产联合验收另行安排。

hostanagent_client-0.2.4/README.md

@@ -0,0 +1,55 @@
+# hostanagent-client 0.2.4
+
+用于产品后端的独立异步 SDK，Python >=3.10，仅依赖 httpx；不安装 HostAnAgent 服务、Worker 或 aisuite。协议兼容 1.0。0.2.4 为 MIT 许可准备版本，提供 wheel 和源码包，尚未公开发布到 PyPI。本 SDK 及随包文档采用 [MIT](https://opensource.org/license/mit)，版权归 GeekArt Inc.；这项授权覆盖 SDK 目录，服务端另行管理。正式发布后，本 README 会随 PyPI 项目页公开；当前元数据中的 PyPI 文档地址尚未上线。
+
+```bash
+python -m pip install ./hostanagent_client-0.2.4-py3-none-any.whl
+```
+
+在自己的控制台发布 Agent，用服务端应用 Key 连接。平台管理模型供应商凭证。当前代码已整合 D01：创建限制到目标 Agent 的 `runtime:read`、`runtime:write` Key；工具执行额外需要 `tools:execute`。运行发现使用 `await client.bootstrap()`，不需要配置管理权限。部署状态以文档仓库实施记录为准。
+
+```python
+import os
+from hostanagent import AgentClient, HostingError, idempotency_key
+
+async def chat(trusted_product_user_id):
+    async with AgentClient("https://api.hostanagent.com/v1", os.environ["HAA_APPLICATION_KEY"],
+                           subject=trusted_product_user_id) as client:
+        # Subject 必须来自产品验证过的登录态，不能直接取浏览器提交的 user_id。
+        models = await client.models()  # reasoning_options 决定可用五档思考强度
+        session = await client.create_session()
+        key = idempotency_key()  # 产品保存本请求的 key、正文和参数，未知结果时原样重试
+        try:
+            accepted = await client.run(session["id"], os.environ["HAA_AGENT_VERSION"], "整理我的任务",
+                idempotency_key=key, reasoning_effort="high", execution_mode="propose",
+                limits={"max_cost_usd": "1.000000000000"})
+        except HostingError as error:
+            if error.code == "INSUFFICIENT_BALANCE":
+                # 没有模型调用；当前人工测试入账，在线充值尚未开放。
+                return
+            raise
+        async for event in client.events(accepted["run_id"]):
+            print(event["sequence"], event["type"])
+```
+
+`endpoint` 可使用主机根路径或 `/v1`。`run` 支持规范所有现有参数；`create_run(body, idempotency_key=...)` 直接发送完整 RunCreate。
+`bootstrap()` 读取受限运行目录；`agent_runtime(agent_id, version_id=...)` 读取可启动状态和模型元数据；`capabilities/models` 读取能力；`sessions/session/messages/delete_session` 管理授权历史；`snapshot/cancel/add_input/approve/claim/receipt/events` 沿用协议。`create_session` 暴露 history_mode/runtime_mode，但 unsupported 模式仍由服务器拒绝，不能据此承诺 external/ephemeral 已实现。
+
+网络与恢复：
+
+- SDK 不自动重试 POST，也不生成隐式新请求。`httpx` 连接异常意味着结果可能未知，应原样重试原 key 或查询已接受 Run；不能换 key 重启付费 Run。
+- `events` 是单次观察订阅，按 UTF-8、CRLF、多行 data 解析，不调用工具 handler。网络断开后先 `snapshot(run_id)` 替换自己的投影，再 `events(run_id, after=snapshot["resume_cursor"])`。用事件 sequence 去重；缺口重新取快照。终态结束重连。401/403 停止恢复并重新核对权限。
+- `cancel(run_id)` 才是明确的停止请求。停止读取 events 或 close 客户端不取消 Agent/业务任务。
+- `add_input` 用同一幂等键重试。claim 的 replayed=true 要读取已有持久回执或由产品核对；绝不再次执行副作用。`receipt_id` 持久保存到确认完成。
+- `HostingError` 提供 code、status_code、request_id、details；不要将内部异常或完整请求正文写入浏览器或日志。USD 原样保持十进制字符串。
+- 恢复已有 session 保持其 agent_version；升级使用新会话。停用/归档由 D05 服务端最终拒绝，不自动换版本或提权。
+
+构建：安装 hatchling 后从干净提交执行 `python scripts/build_sdk.py`；生成 `dist/sdk/0.2.4/` 的 wheel、源码包、来源提交、固定契约摘要、构建工具版本与 SHA-256 清单。目录存在则拒绝覆盖。开发使用 `--candidate`。运行 `python scripts/check_sdk_release.py <产物目录>` 核对文件和包内容；加 `--publish-ready` 会额外拒绝许可证缺失、private 标记和未提交来源。`python scripts/test_sdk_install.py <wheel 或 tar.gz>` 在系统临时目录新建 venv、实际安装并调用，不依赖源码路径。离线依赖可通过 `HAA_WHEELHOUSE` 指定本地 wheelhouse。
+
+0.2.2 已整合 D01/D02/D03/D04/D05，保留固定版本调用方式；新增 `run(session_id, content="文本", agent_id="逻辑 Agent ID", idempotency_key=key)`。`agent_id` 和 `agent_version` 必须二选一。使用逻辑 ID 时由服务端在首次接受 Run 时固定版本，已有 Session 不跟随新发布；停用后原请求仍可按原 key 核对。0.2.2 快照与事件均拒绝非 1.0 协议。旧版 0.2.0/0.2.1/0.2.2 保留，不覆盖原文件。已用本机真实 API 签发的受限测试 Key 验证运行发现、文本 Run、SSE、跨 Agent 拒绝和撤销；模型及邮件均使用 mock。D02 执行器接口可经通用 `request` 调用，参考 `examples/README-executor.md`。
+
+0.2.3 保留上述 SDK API，增加源码包、发布检查和安装矩阵；采用包含 D07 与 durable 执行补齐的协议基线。
+
+0.2.4 补充客户端 MIT 许可；0.2.3 及更早产物保持不变。
+
+httpx 及传递依赖由 pip 独立安装，不打入本 wheel。第三方许可见 THIRD_PARTY_NOTICES.md。MIT 许可见 LICENSE；公开发布和真实产品/生产联合验收另行安排。

hostanagent_client-0.2.4/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,7 @@
+# 许可与第三方依赖
+
+本 SDK 及随包文档采用 MIT，Copyright (c) 2026 GeekArt Inc.，完整文本见 LICENSE。第三方依赖继续适用各自的许可证。
+
+本 wheel 只含 HostAnAgent SDK 代码。运行依赖 httpx（BSD-3-Clause），由 pip 独立安装，未内嵌。传递依赖包括 httpcore（BSD-3-Clause）、anyio（MIT）、certifi（MPL-2.0）、idna（BSD-3-Clause）、h11（MIT）以及按环境需要的 typing_extensions（PSF-2.0）。以实际安装版本的 dist-info/licenses 和元数据为准，测试脚本记录实际依赖列表；若打包整个环境，需一并保留这些许可。
+
+构建使用 hatchling（MIT），不属于发布 wheel 的运行依赖。

hostanagent_client-0.2.4/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hostanagent-client"
+version = "0.2.4"
+description = "Thin async client for the HostAnAgent public protocol"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.28,<1"]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.urls]
+Repository = "https://github.com/ffskyfan/HostAnAgentBackend"
+Documentation = "https://pypi.org/project/hostanagent-client/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hostanagent"]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.wheel.force-include]
+"THIRD_PARTY_NOTICES.md" = "hostanagent/THIRD_PARTY_NOTICES.md"
+
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.4"
+include = ["/src/hostanagent", "/pyproject.toml", "/README.md", "/THIRD_PARTY_NOTICES.md", "/LICENSE"]

hostanagent_client-0.2.4/src/hostanagent/__init__.py

@@ -0,0 +1,170 @@
+import json
+import uuid
+from urllib.parse import quote
+
+import httpx
+
+
+class HostingError(Exception):
+    def __init__(self, code, message, status_code, request_id=None, details=None, retryable=False):
+        self.code, self.status_code, self.request_id = code, status_code, request_id
+        self.details = details or {}
+        self.retryable = retryable
+        super().__init__(message)
+
+
+class AgentClient:
+    """Server-side only. The application authenticates its user before setting subject."""
+
+    def __init__(self, endpoint, application_key, subject, *, transport=None):
+        base = endpoint.rstrip("/")
+        if not base.endswith("/v1"):
+            base += "/v1"
+        self.http = httpx.AsyncClient(base_url=base + "/", timeout=30,
+            transport=transport, headers={"Authorization": f"Bearer {application_key}", "X-Subject": subject})
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_):
+        await self.close()
+
+    async def close(self):
+        await self.http.aclose()
+
+    @staticmethod
+    def check(response):
+        if response.is_error:
+            try:
+                error = response.json()
+            except ValueError:
+                error = {}
+            if not isinstance(error, dict):
+                error = {}
+            raise HostingError(error.get("code", "HTTP_ERROR"), error.get("message", "Hosting request failed"),
+                               response.status_code,
+                               error.get("request_id") or response.headers.get("x-request-id"),
+                               error.get("details"), error.get("retryable", False))
+
+    async def request(self, method, path, *, body=None, headers=None):
+        response = await self.http.request(method, path, json=body, headers=headers)
+        self.check(response)
+        return response.json() if response.content else None
+
+    async def capabilities(self):
+        return await self.request("GET", "capabilities")
+
+    async def models(self):
+        return await self.request("GET", "models")
+
+    async def bootstrap(self):
+        """Discover only the Agents allowed by this runtime credential."""
+        return await self.request("GET", "runtime/bootstrap")
+
+    async def agent_runtime(self, agent_id, *, version_id=None):
+        """Read lifecycle/model metadata without configuration permissions."""
+        path = f"agents/{quote(agent_id, safe='')}/runtime"
+        if version_id is not None:
+            path += f"?version_id={quote(version_id, safe='')}"
+        return await self.request("GET", path)
+
+    async def create_session(self, title="新会话", *, history_mode="managed", runtime_mode="durable"):
+        return await self.request("POST", "sessions", body={
+            "title": title, "history_mode": history_mode, "runtime_mode": runtime_mode,
+        })
+
+    async def sessions(self):
+        return await self.request("GET", "sessions")
+
+    async def session(self, session_id):
+        return await self.request("GET", f"sessions/{quote(session_id, safe='')}")
+
+    async def messages(self, session_id, *, before=None, limit=50):
+        path = f"sessions/{quote(session_id, safe='')}/messages?limit={int(limit)}"
+        if before is not None:
+            path += f"&before={int(before)}"
+        return await self.request("GET", path)
+
+    async def delete_session(self, session_id):
+        return await self.request("DELETE", f"sessions/{quote(session_id, safe='')}")
+
+    async def create_run(self, body, *, idempotency_key):
+        """Send the complete protocol RunCreate. No implicit retries or key generation."""
+        return await self.request("POST", "runs", body=body,
+                                  headers={"Idempotency-Key": idempotency_key})
+
+    async def run(self, session_id, agent_version=None, content=None, *, agent_id=None,
+                  idempotency_key, context_refs=None, execution_mode="propose", limits=None,
+                  reasoning_effort=None):
+        """Select a fixed version or let Hosting pin agent_id on the first accepted Run."""
+        if bool(agent_version) == bool(agent_id):
+            raise ValueError("Provide exactly one of agent_version or agent_id")
+        if content is None:
+            raise ValueError("Message content is required")
+        selection = {"agent_version": agent_version} if agent_version else {"agent_id": agent_id}
+        body = {"session_id": session_id, **selection,
+                "input": {"type": "message", "content": content}, "context_refs": context_refs or [],
+                "execution_mode": execution_mode}
+        if limits is not None:
+            body["limits"] = limits
+        if reasoning_effort is not None:
+            body["reasoning_effort"] = reasoning_effort
+        return await self.create_run(body, idempotency_key=idempotency_key)
+
+    async def snapshot(self, run_id):
+        snapshot = await self.request("GET", f"runs/{quote(run_id, safe='')}")
+        if not isinstance(snapshot, dict) or snapshot.get("protocol_version") != "1.0":
+            raise HostingError("PROTOCOL_UNSUPPORTED", "Unsupported snapshot protocol", 0)
+        return snapshot
+
+    async def cancel(self, run_id):
+        return await self.request("POST", f"runs/{quote(run_id, safe='')}/cancel")
+
+    async def add_input(self, run_id, content, *, idempotency_key):
+        return await self.request("POST", f"runs/{quote(run_id, safe='')}/inputs", body={"content": content},
+                                  headers={"Idempotency-Key": idempotency_key})
+
+    async def approve(self, run_id, call, decision):
+        return await self.request("POST", f"runs/{quote(run_id, safe='')}/approvals", body={
+            "approval_id": call["approval_id"], "tool_call_id": call["id"],
+            "arguments_digest": call["arguments_digest"], "decision": decision,
+        })
+
+    async def claim(self, run_id, call_id, executor_id):
+        return await self.request("POST", f"runs/{quote(run_id, safe='')}/tool-calls/{quote(call_id, safe='')}/claim",
+                                  body={"executor_id": executor_id})
+
+    async def receipt(self, run_id, call_id, grant, *, receipt_id, kind, **value):
+        return await self.request("POST", f"runs/{quote(run_id, safe='')}/tool-calls/{quote(call_id, safe='')}/receipts",
+            body={"receipt_id": receipt_id, "kind": kind, **value}, headers={"X-Tool-Grant": grant})
+
+    async def events(self, run_id, *, after=0):
+        """One SSE subscription. On reconnect fetch snapshot, then pass its resume_cursor."""
+        async with self.http.stream("GET", f"runs/{quote(run_id, safe='')}/events",
+                                    params={"after": after}, headers={"Accept": "text/event-stream"},
+                                    timeout=None) as response:
+            if response.is_error:
+                await response.aread()
+                self.check(response)
+            data = []
+            size = 0
+            async for line in response.aiter_lines():
+                size += len(line)
+                if size > 1048576:
+                    raise HostingError("EVENT_TOO_LARGE", "Event exceeds frame limit", 0)
+                if not line:
+                    if data:
+                        event = json.loads("\n".join(data))
+                        if not isinstance(event, dict) or event.get("protocol_version") != "1.0":
+                            raise HostingError("PROTOCOL_UNSUPPORTED", "Unsupported event protocol", 0)
+                        yield event
+                    data, size = [], 0
+                elif line.startswith("data:"):
+                    data.append(line[5:].lstrip())
+
+
+def idempotency_key():
+    return str(uuid.uuid4())
+
+
+__all__ = ["AgentClient", "HostingError", "idempotency_key"]