dmt-agent-api 0.3.0__py3-none-any.whl

dmt_agent_api-0.3.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: dmt-agent-api
+Version: 0.3.0
+Summary: DMT Agent API Python SDK for DuMate
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: notebook
+Requires-Dist: ipython>=8; extra == "notebook"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+
+# DuMate Python SDK
+
+面向 DuMate 老版 `/api/v1` 的 Python 客户端。Python 3.10+，提供同步 `DuMate` 和异步 `AsyncDuMate`。当前版本 0.3.0，为独立开发的 SDK。
+
+应用层快速接入与前端数据协议见 [APPLICATIONS.md](docs/APPLICATIONS.md)。提供 `skills.ensure`、`conversations.create/history/stream` 和 `notebook.stream`。
+
+## 安装
+
+```bash
+pip install ./dmt_agent_api-0.3.0-py3-none-any.whl
+```
+
+源码安装：`pip install .`。配置环境变量 `DUMATE_API_KEY`；可选 `DUMATE_BASE_URL`，默认 `https://api.dumate.cn/api/v1`。Key 仅放在后端。
+
+## 一次调用，等待最终结果
+
+```python
+from dumate import DuMate
+
+with DuMate() as client:
+    agent = client.agents.create(name="我的助手")
+    session = client.sessions.create(agent_id=agent["id"])
+    result = client.runs.run_and_wait(
+        session_id=session["id"],
+        message="介绍你能完成的工作",
+        timeout=180,
+    )
+    print(result.output_text)
+```
+
+`runs.run_and_wait` 在客户端发送一次消息并轮询历史，关联本次用户消息与最终回答；没有对应的服务端 `/runs` 接口。适合网页的一键任务按钮：后端执行调用，完成后返回 `output_text`，前端展示结果即可。较长任务应由应用队列执行并提供任务状态查询。
+
+同一会话串行发送，不同会话可以并发。超时仅停止本地等待，服务端任务可能仍在执行；可查询历史或显式 `sessions.interrupt`。`timeout` 限制轮询等待，单次网络请求还受客户端 `timeout` 约束。默认等待时间无限，建议显式设置。
+
+## 流式事件
+
+```python
+with client.sessions.stream(session_id, message="帮我分析这个问题") as events:
+    for event in events:
+        if event.type == "message.part.updated":
+            part = event.properties.get("part", {})
+            print(part.get("type"), part.get("text", ""))
+        elif event.type == "session.idle" or (
+            event.type == "session.status"
+            and event.properties.get("status", {}).get("type") == "idle"
+        ):
+            break
+```
+
+流建立后才发送消息。事件保留原始 `type`、`properties` 和 `raw`，未知事件也会返回；SSE `id`、`event` 字段独立保留。应用处理规则：
+
+|数据|处理方式|
+|---|---|
+|message.updated 的 info|按消息 ID 更新角色、完成状态和错误|
+|message.part.updated 的 part|按 part ID 替换快照；text 展示文字，reasoning 折叠展示，tool 按真实状态展示|
+|增量事件|仅对明确增量字段追加；快照和增量同时出现时避免重复拼接|
+|工具调用|保留调用 ID、输入、状态和输出；只展示真实事件|
+|session.status / session.idle|更新运行状态；idle 还需核对历史中的最终答案或错误|
+|未知事件|保留原始对象供兼容处理|
+
+SDK 提供事件解析，不包含网页组件。断流抛出 `StreamInterruptedError`；应用先恢复 `sessions.history`，再重新订阅，不能自动重发原 query。SDK 不承诺事件重放或 Last-Event-ID 恢复。完整事件字段以服务端实际返回为准。
+
+## Skill
+
+ZIP 中包含技能目录和 `SKILL.md`，文件带 YAML `name`、`description`。
+
+```python
+skill = client.skills.upload("my-skill.zip")
+mount = client.skills.mount(skill["id"])
+session = client.sessions.create(agent_id=agent_id, skills=[mount])
+
+updated = client.skills.update_zip(skill["id"], "my-skill-v2.zip")
+new_mount = client.skills.mount(skill["id"])
+client.sessions.update(session["id"], skills=[new_mount])
+```
+
+挂载使用 `skillID`、`releaseID`、`type`；`mount()` 从详情取得 `releaseId`，不能把展示版本号当作发布 ID。URL 导入用 `skills.create(url=...)`，URL 更新用 `skills.update(skill_id, url=...)`。
+
+## Vault、凭据和 MCP
+
+```python
+import os
+
+vault = client.vaults.create(name="业务系统")
+credentials = client.vaults.credentials(vault["id"])
+credential = credentials.create(
+    name="业务访问令牌",
+    auth={
+        "type": "environment_variable",
+        "secretName": "BUSINESS_TOKEN",
+        "secretValue": os.environ["BUSINESS_TOKEN"],
+        "networking": {
+            "type": "limited",
+            "allowedHosts": ["api.your-company.com"],
+        },
+    },
+)
+session = client.sessions.create(agent_id=agent_id, vault_ids=[vault["id"]])
+```
+
+`auth` 原样传递平台的 `environment_variable`、`static_bearer` 或 `mcp_oauth` 结构，敏感值不要记录到日志。MCP 配置通过 `mcp_servers` 传入 Agent 或 Session，例如 `[{"type":"url","name":"business","url":"https://your-company.com/mcp"}]`；会话配置 MCP 时同时提供对应 `vault_ids`。各 MCP 的认证字段须按官方文档及服务商要求填写；SDK 不代办 OAuth 授权。平台未提供凭据更新接口，轮换需创建新凭据并迁移使用后删除旧凭据。
+
+## 文件与产物
+
+```python
+uploaded = client.files.upload("input.pdf", session_id=session_id)
+result = client.runs.run_and_wait(
+    session_id=session_id, message="总结附件", file_ids=[uploaded["fileID"]], timeout=300,
+)
+client.files.download(uploaded["fileID"], "downloaded.pdf")
+
+mapping = client.artifacts.path_map(session_id)
+for path, artifact in mapping.items():
+    if artifact.get("uploadStatus") == "ready":
+        client.artifacts.download(session_id, artifact["artifactID"], "output.bin")
+        break
+```
+
+path-map 是整个会话的产物集合，不能全部当作本轮产物。按本轮回答中的文件路径、工具结果或执行前后的映射差异关联。`output.bin` 应由业务层按选中的文件设置名称；不要直接信任远端路径。
+
+下载返回落盘信息，默认禁止覆盖，支持 `max_bytes`。文件先写临时文件，成功后提交；校验响应长度并计算 SHA-256。产物必须 ready；存储返回 403 时刷新一次 URL。存储下载不携带 DuMate Key。URL 校验阻止明显私网地址及不安全跳转；生产环境仍需网络出口策略防止 DNS 重绑定。
+
+预览由应用后端代理文件，前端按 MIME 展示图片、音视频、PDF；HTML 应隔离在 sandbox iframe 中，未知类型提供下载。签名 URL 有时效，不应长期保存为产物身份。
+
+## 异步
+
+```python
+import asyncio
+from dumate import AsyncDuMate
+
+async def main():
+    async with AsyncDuMate() as client:
+        session = await client.sessions.create(agent_id="你的 Agent ID")
+        result = await client.runs.run_and_wait(
+            session_id=session["id"], message="你好", timeout=180,
+        )
+        print(result.output_text)
+
+asyncio.run(main())
+```
+
+异步资源方法使用 `await`；列表迭代用 `async for item in client.agents.iter()`；流用 `async with client.sessions.stream(...) as events` 和 `async for`。文件落盘及 DNS 检查仍包含短同步操作，大文件应用可用专门下载工作进程。
+
+## 错误与运行边界
+
+- GET 对网络错误、429 和部分 5xx 做有限重试，默认 2 次；写操作不自动重试。
+- 写请求连接失败时 `ConnectionError.outcome_unknown=True`，先核对服务端状态，避免重复创建或执行。
+- `APIError` 包含状态码及请求 ID；异常文本不包含响应正文或 Key。应用不要直接打印凭据查询返回值。
+- `RunTimeoutError`、`RunFailedError`、`ProtocolError` 区分等待超时、运行失败和协议异常。
+- 会话与租户归属校验、鉴权、队列持久化、限流和登录恢复由业务后端负责。
+- 删除 Agent 会级联删除其会话；只清理自己创建且确认不再使用的资源。
+
+完整方法见 [API.md](docs/API.md)，验证范围见 [TESTING.md](docs/TESTING.md)。

dmt_agent_api-0.3.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+dumate/__init__.py,sha256=pM4DaPI0169XJZmw097VrilaOZ4IGCkfaoBG6xS6pkM,947
+dumate/_async_client.py,sha256=H7FwwfLbot8Plg-iC0YDu2nbGe4u4pwkEX8iW6gswlI,7563
+dumate/_async_resources.py,sha256=qJnsaPxOsjB0V93pokEwoaOUq2-J2wCSEyk78Mmv-ZA,11742
+dumate/_async_runs.py,sha256=6fX7dfXTKc9yFXjs5wUAo0NXIRcISb5NMonZcSJ9sj0,1713
+dumate/_client.py,sha256=-f0SF13EnZONzGe6EUn74J4He5HldltYgLrTwdqChIQ,7256
+dumate/_common.py,sha256=qJTPS4WhNp-bQwmA8CoD7MBFUwZhOMYhNrFmb4K5Cg8,2693
+dumate/_downloads.py,sha256=h4dTzbg-jzV2hLfQHjq20aR2PetPWUd7VkprIjToSY4,3528
+dumate/_sse.py,sha256=oSqbwvVsehIvsLUc7gUUMKTBSl6U6yyIOElMwl8Xj8A,3102
+dumate/conversation.py,sha256=uII9ZIHjPlYzP_3QuAMUjbOsxMjbmgEPnO1QlTozAgg,8053
+dumate/errors.py,sha256=cV9lgGRvmnsuPJKF94LI9Gb_qQkZsj83ccFJBajYJPI,1717
+dumate/notebook.py,sha256=FMNGbNyO2wnTWdhhnH2nbs20Xik6x5IVITZYjytmZz0,2356
+dumate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dumate/resources.py,sha256=XPghfLZoffsZDfqnHJRzIblrckJIU1S4BOgpwWqpsi0,11009
+dumate/runs.py,sha256=aa6FhHV_5uPwWTaRDnWdvOiFbQVR4Xr0tG83vqeyKqo,3076
+dumate/types.py,sha256=2x5RDTpsd8KgvVrEobuBdilo3iqyAkPykyy2nnZBER8,1364
+dmt_agent_api-0.3.0.dist-info/METADATA,sha256=em5I-IMVV0zNbFjLisZED5tKTnJgSum8FcHuYtNo5_A,8095
+dmt_agent_api-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+dmt_agent_api-0.3.0.dist-info/top_level.txt,sha256=_hxsJUveyKhaX0dtmcHT4BlVj-4LB20fCcORTF50ZCM,7
+dmt_agent_api-0.3.0.dist-info/RECORD,,

dmt_agent_api-0.3.0.dist-info/WHEEL

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

dmt_agent_api-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dumate

dumate/__init__.py

@@ -0,0 +1,13 @@
+from ._client import DuMate
+from ._async_client import AsyncDuMate
+from .types import Event, SendReceipt, RunResult, SkillMount, MCPServer, FileMount
+from .errors import (DuMateError, APIError, AuthenticationError, PermissionDeniedError,
+                     NotFoundError, ConflictError, RateLimitError, ConnectionError,
+                     ProtocolError, PaginationError, StreamInterruptedError,
+                     RunTimeoutError, RunFailedError, DownloadError, ArtifactNotReadyError)
+
+__version__ = "0.3.0"
+__all__ = ["DuMate", "AsyncDuMate", "Event", "SendReceipt", "RunResult", "SkillMount", "MCPServer", "FileMount",
+           "DuMateError", "APIError", "AuthenticationError", "PermissionDeniedError", "NotFoundError", "ConflictError",
+           "RateLimitError", "ConnectionError", "ProtocolError", "PaginationError", "StreamInterruptedError",
+           "RunTimeoutError", "RunFailedError", "DownloadError", "ArtifactNotReadyError"]

dumate/_async_client.py

@@ -0,0 +1,151 @@
+# Generated by tools/generate_async.py; edit synchronous source.
+import asyncio
+import mimetypes
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+from urllib.parse import urljoin
+import httpx
+from . import _async_resources as resources
+from ._common import config, check_response, decode, delay, request_id, segment
+from ._downloads import public_url, select_artifact, AtomicDownload
+from ._sse import SSEDecoder
+from .errors import ConnectionError, ProtocolError, StreamInterruptedError, DownloadError, APIError
+from .types import SendReceipt
+
+class AsyncDuMate:
+
+    def __init__(self, api_key=None, *, base_url=None, timeout=60.0, stream_timeout=60.0, max_retries=2, max_frame_bytes=4 * 1024 * 1024, transport=None):
+        key, base = config(api_key, base_url, max_retries)
+        self.base_url = base
+        self.max_retries = max_retries
+        self.max_frame_bytes = max_frame_bytes
+        self.stream_timeout = stream_timeout
+        self._http = httpx.AsyncClient(base_url=base + '/', headers={'Authorization': 'Bearer ' + key, 'User-Agent': 'dumate-agent-sdk/0.2.0'}, timeout=timeout, follow_redirects=False, trust_env=False, transport=transport)
+        self._storage = httpx.AsyncClient(timeout=timeout, follow_redirects=False, trust_env=False, headers={'Accept-Encoding': 'identity'})
+        self.agents = resources.AsyncAgents(self, 'agents')
+        self.skills = resources.AsyncSkills(self, 'skills')
+        self.vaults = resources.AsyncVaults(self, 'vaults')
+        self.sessions = resources.AsyncSessions(self, 'sessions')
+        self.files = resources.AsyncFiles(self, 'files')
+        self.artifacts = resources.AsyncArtifacts(self, '')
+        from ._async_runs import AsyncRuns
+        self.runs = AsyncRuns(self)
+        from .conversation import AsyncConversations
+        self.conversations = AsyncConversations(self)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def close(self):
+        await self._http.aclose()
+        await self._storage.aclose()
+
+    async def _response(self, method, path, **kwargs):
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._http.request(method, path, **kwargs)
+            except httpx.TransportError:
+                if method == 'GET' and attempt < self.max_retries:
+                    await asyncio.sleep(delay(None, attempt))
+                    continue
+                raise ConnectionError(outcome_unknown=method != 'GET') from None
+            if method == 'GET' and response.status_code in (429, 500, 502, 503, 504) and (attempt < self.max_retries):
+                wait = delay(response, attempt)
+                await response.aclose()
+                await asyncio.sleep(wait)
+                continue
+            check_response(response)
+            return response
+        raise AssertionError('Unreachable')
+
+    async def _request(self, method, path, **kwargs):
+        response = await self._response(method, path, **kwargs)
+        try:
+            return decode(response)
+        finally:
+            await response.aclose()
+
+    async def _upload(self, method, path, file, *, data=None):
+        path_file = Path(file)
+        with path_file.open('rb') as handle:
+            return await self._request(method, path, data=data, files={'file': (path_file.name, handle, mimetypes.guess_type(path_file.name)[0] or 'application/octet-stream')})
+
+    async def _send(self, session_id, event):
+        response = await self._response('POST', f'sessions/{segment(session_id)}/events', json={'events': [event]})
+        try:
+            return SendReceipt(session_id, request_id(response))
+        finally:
+            await response.aclose()
+
+    @asynccontextmanager
+    async def _stream(self, session_id, *, message=None, file_ids=None):
+        try:
+            async with self._http.stream('GET', f'sessions/{segment(session_id)}/events/stream', headers={'Accept': 'text/event-stream'}, timeout=self.stream_timeout) as response:
+                check_response(response)
+                if 'text/event-stream' not in response.headers.get('content-type', '').lower():
+                    raise ProtocolError('Expected text/event-stream')
+                if message is not None:
+                    await self.sessions.send(session_id, message=message, file_ids=file_ids)
+                yield self._events(response, session_id)
+        except httpx.TransportError:
+            raise StreamInterruptedError(session_id) from None
+
+    async def _events(self, response, session_id):
+        decoder = SSEDecoder(self.max_frame_bytes)
+        try:
+            async for chunk in response.aiter_bytes():
+                for event in decoder.feed(chunk):
+                    if event.session_id is None or event.session_id == session_id:
+                        yield event
+            decoder.finish()
+        except httpx.TransportError:
+            raise StreamInterruptedError(session_id) from None
+
+    async def _save(self, response, destination, *, max_bytes, overwrite):
+        target = AtomicDownload(destination, max_bytes=max_bytes, overwrite=overwrite, headers=response.headers)
+        try:
+            async for chunk in response.aiter_raw():
+                target.write(chunk)
+            return target.commit()
+        except httpx.TransportError:
+            raise DownloadError('Download interrupted; destination was not committed') from None
+        finally:
+            target.close()
+
+    async def _download_api(self, path, destination, *, max_bytes, overwrite):
+        try:
+            async with self._http.stream('GET', path, headers={'Accept-Encoding': 'identity'}) as response:
+                check_response(response)
+                return await self._save(response, destination, max_bytes=max_bytes, overwrite=overwrite)
+        except httpx.TransportError:
+            raise DownloadError('File download connection failed') from None
+
+    async def _download_artifact(self, session_id, artifact_id, destination, *, max_bytes, overwrite):
+        for attempt in range(2):
+            row = select_artifact(await self.artifacts.path_map(session_id), artifact_id)
+            url = public_url(row.get('downloadUrl'))
+            expired = False
+            try:
+                for hop in range(5):
+                    async with self._storage.stream('GET', url) as response:
+                        if response.status_code in (301, 302, 303, 307, 308):
+                            location = response.headers.get('location')
+                            if not location or hop == 4:
+                                raise DownloadError('Artifact redirect limit reached')
+                            url = public_url(urljoin(url, location))
+                            continue
+                        if response.status_code == 403 and attempt == 0:
+                            expired = True
+                            break
+                        if response.status_code != 200:
+                            raise DownloadError(f'Artifact storage HTTP {response.status_code}')
+                        return await self._save(response, destination, max_bytes=max_bytes, overwrite=overwrite)
+            except httpx.TransportError:
+                raise DownloadError('Artifact download connection failed') from None
+            if not expired:
+                raise DownloadError('Artifact download failed')
+        raise DownloadError('Artifact download failed after refresh')

dumate/_async_resources.py

@@ -0,0 +1,217 @@
+# Generated by tools/generate_async.py; edit synchronous source.
+import asyncio
+"""Legacy API resources. Responses retain the original JSON field names."""
+from ._common import segment, fields
+from .errors import PaginationError, ProtocolError
+
+class AsyncResource:
+
+    def __init__(self, client, path):
+        self._client = client
+        self._path = path
+
+    async def iter(self, **params):
+        """Iterate cursor pages; raise rather than silently return partial data."""
+        cursor = params.pop('cursor', None)
+        seen = set()
+        while True:
+            page = await self.list(cursor=cursor, **params)
+            if not isinstance(page, dict) or not isinstance(page.get('data'), list):
+                raise PaginationError('Invalid list response')
+            for item in page['data']:
+                yield item
+            if page.get('hasMore') is False:
+                return
+            if page.get('hasMore') is not True:
+                raise PaginationError('Missing explicit hasMore')
+            nxt = page.get('nextCursor')
+            if not isinstance(nxt, (str, int)) or isinstance(nxt, bool) or (not str(nxt)) or (str(nxt) == str(cursor)) or (str(nxt) in seen):
+                raise PaginationError('Cursor did not advance')
+            seen.add(str(nxt))
+            cursor = str(nxt)
+
+class AsyncAgents(AsyncResource):
+
+    async def list(self, *, keyword=None, cursor=None, limit=None):
+        return await self._client._request('GET', self._path, params=fields(keyword=keyword, cursor=cursor, limit=limit))
+
+    async def create(self, *, name, description=None, system=None, skills=None, files=None, mcp_servers=None, tools=None):
+        return await self._client._request('POST', self._path, json=fields(name=name, description=description, system=system, skills=skills, files=files, mcpServers=mcp_servers, tools=tools))
+
+    async def get(self, agent_id, *, version=None):
+        return await self._client._request('GET', f'{self._path}/{segment(agent_id)}', params=fields(version=version))
+
+    async def update(self, agent_id, *, version, system=None, skills=None, files=None, mcp_servers=None, tools=None):
+        return await self._client._request('POST', f'{self._path}/{segment(agent_id)}', json=fields(version=version, system=system, skills=skills, files=files, mcpServers=mcp_servers, tools=tools))
+
+    async def delete(self, agent_id):
+        """Destructive: the platform also deletes associated sessions."""
+        return await self._client._request('DELETE', f'{self._path}/{segment(agent_id)}')
+
+class AsyncSkills(AsyncResource):
+
+    async def list(self, *, page=1, page_size=20, skill_id=None, keyword=None, order=None):
+        return await self._client._request('GET', self._path, params=fields(page=page, pageSize=page_size, skillId=skill_id, keyword=keyword, order=order))
+
+    async def iter(self, *, page_size=20, **params):
+        page_number, count, total = (1, 0, None)
+        seen = set()
+        while True:
+            page = await self.list(page=page_number, page_size=page_size, **params)
+            if not isinstance(page, dict) or not isinstance(page.get('data'), list) or (not isinstance(page.get('total'), int)):
+                raise PaginationError('Invalid Skill page')
+            if total is not None and page['total'] != total:
+                raise PaginationError('Skill total changed while paginating')
+            total = page['total']
+            for row in page['data']:
+                identity = (row.get('id'), row.get('releaseId'))
+                if not identity[0] or identity in seen:
+                    raise PaginationError('Repeated or unidentified Skill')
+                seen.add(identity)
+                count += 1
+                yield row
+            if count == total:
+                return
+            if count > total or not page['data']:
+                raise PaginationError('Skill page count inconsistent with total')
+            page_number += 1
+
+    async def ensure(self, *, name, file):
+        """Reuse an exact name; upload only when absent. Does not update existing content."""
+        matches = [row async for row in self.iter(keyword=name) if row.get('name') == name]
+        if len(matches) > 1:
+            raise ProtocolError('Multiple matching Skills; select an explicit ID')
+        return matches[0] if matches else await self.upload(file)
+
+    async def upload(self, file):
+        return await self._client._upload('POST', f'{self._path}/upload', file)
+
+    async def create(self, *, url):
+        return await self._client._request('POST', self._path, json={'url': url})
+
+    async def get(self, skill_id, *, release_id=None):
+        return await self._client._request('GET', f'{self._path}/{segment(skill_id)}', params=fields(releaseId=release_id))
+
+    async def update(self, skill_id, *, url):
+        return await self._client._request('POST', f'{self._path}/{segment(skill_id)}', json={'url': url})
+
+    async def update_zip(self, skill_id, file):
+        return await self._client._upload('POST', f'{self._path}/{segment(skill_id)}/update', file)
+
+    async def delete(self, skill_id):
+        return await self._client._request('DELETE', f'{self._path}/{segment(skill_id)}')
+
+    async def mount(self, skill_id, *, release_id=None, type='custom'):
+        """Read releaseId, never confuse it with the display version."""
+        skill = await self.get(skill_id, release_id=release_id)
+        if not skill.get('releaseId'):
+            raise ProtocolError('Skill releaseId is not available yet')
+        if type not in ('custom', 'official'):
+            raise ValueError('type must be custom or official')
+        return {'skillID': skill_id, 'releaseID': skill['releaseId'], 'type': type}
+
+class AsyncVaults(AsyncResource):
+
+    async def list(self, *, cursor=None, limit=None):
+        return await self._client._request('GET', self._path, params=fields(cursor=cursor, limit=limit))
+
+    async def create(self, *, name):
+        return await self._client._request('POST', self._path, json={'name': name})
+
+    async def get(self, vault_id):
+        return await self._client._request('GET', f'{self._path}/{segment(vault_id)}')
+
+    async def delete(self, vault_id):
+        return await self._client._request('DELETE', f'{self._path}/{segment(vault_id)}')
+
+    def credentials(self, vault_id):
+        return AsyncCredentials(self._client, f'{self._path}/{segment(vault_id)}/credentials')
+
+class AsyncCredentials(AsyncResource):
+
+    async def list(self, *, cursor=None, limit=None, auth_type=None):
+        return await self._client._request('GET', self._path, params=fields(cursor=cursor, limit=limit, authType=auth_type))
+
+    async def create(self, *, name, auth):
+        return await self._client._request('POST', self._path, json={'name': name, 'auth': auth})
+
+    async def get(self, credential_id):
+        return await self._client._request('GET', f'{self._path}/{segment(credential_id)}')
+
+    async def delete(self, credential_id):
+        return await self._client._request('DELETE', f'{self._path}/{segment(credential_id)}')
+
+class AsyncSessions(AsyncResource):
+
+    async def list(self, *, cursor=None, limit=None, status=None):
+        return await self._client._request('GET', self._path, params=fields(cursor=cursor, limit=limit, status=status))
+
+    async def create(self, *, agent_id, metadata=None, vault_ids=None, skills=None, mcp_servers=None):
+        return await self._client._request('POST', self._path, json=fields(agent={'id': agent_id}, metadata=metadata, vaultIds=vault_ids, skills=skills, mcpServers=mcp_servers))
+
+    async def get(self, session_id):
+        return await self._client._request('GET', f'{self._path}/{segment(session_id)}')
+
+    async def update(self, session_id, *, metadata=None, vault_ids=None, skills=None, mcp_servers=None):
+        return await self._client._request('POST', f'{self._path}/{segment(session_id)}', json=fields(metadata=metadata, vaultIds=vault_ids, skills=skills, mcpServers=mcp_servers))
+
+    async def delete(self, session_id):
+        return await self._client._request('DELETE', f'{self._path}/{segment(session_id)}')
+
+    async def history(self, session_id, *, limit=None, paginated=False):
+        return await self._client._request('GET', f'{self._path}/{segment(session_id)}/events', params=fields(limit=limit, paginated=str(paginated).lower()))
+
+    async def send(self, session_id, *, message, file_ids=None):
+        content = [{'type': 'text', 'text': message}]
+        content.extend(({'type': 'file', 'file_id': fid} for fid in file_ids or []))
+        return await self._client._send(session_id, {'type': 'user.message', 'content': content})
+
+    async def send_event(self, session_id, event):
+        if not isinstance(event, dict) or not isinstance(event.get('type'), str):
+            raise ValueError('event must be a single typed object')
+        return await self._client._request('POST', f'{self._path}/{segment(session_id)}/events', json={'events': [event]})
+
+    async def interrupt(self, session_id):
+        return await self.send_event(session_id, {'type': 'user.interrupt'})
+
+    async def submit_tool_result(self, session_id, *, custom_tool_use_id, content, is_error=False):
+        return await self.send_event(session_id, {'type': 'user.custom_tool_result', 'content': [{'customToolUseId': custom_tool_use_id, 'content': content, 'isError': is_error}]})
+
+    async def resource_points(self, session_id, *, start_at=None, end_at=None):
+        if start_at is not None and start_at < 0 or (end_at is not None and end_at < 0):
+            raise ValueError('timestamps must be non-negative')
+        if start_at is not None and end_at is not None and (start_at >= end_at):
+            raise ValueError('start_at must be less than end_at')
+        return await self._client._request('GET', f'{self._path}/{segment(session_id)}/resource-points', params=fields(startAt=start_at, endAt=end_at))
+
+    def stream(self, session_id, *, message=None, file_ids=None):
+        """Context manager; connect before optional send, never automatically resend."""
+        return self._client._stream(session_id, message=message, file_ids=file_ids)
+
+class AsyncFiles(AsyncResource):
+
+    async def list(self, *, cursor=None, limit=None, order=None, file_ids=None):
+        return await self._client._request('GET', self._path, params=fields(cursor=cursor, limit=limit, order=order, fileIds=file_ids))
+
+    async def upload(self, file, *, session_id=None, mime_type=None):
+        return await self._client._upload('POST', self._path, file, data=fields(sessionId=session_id, mimeType=mime_type))
+
+    async def update(self, file_id, file):
+        return await self._client._upload('PUT', f'{self._path}/{segment(file_id)}', file)
+
+    async def get(self, file_id):
+        return await self._client._request('GET', f'{self._path}/{segment(file_id)}')
+
+    async def delete(self, file_id):
+        return await self._client._request('DELETE', f'{self._path}/{segment(file_id)}')
+
+    async def download(self, file_id, destination, *, max_bytes=100 * 1024 * 1024, overwrite=False):
+        return await self._client._download_api(f'{self._path}/{segment(file_id)}/content', destination, max_bytes=max_bytes, overwrite=overwrite)
+
+class AsyncArtifacts(AsyncResource):
+
+    async def path_map(self, session_id, *, paths=None):
+        return await self._client._request('GET', f'sessions/{segment(session_id)}/artifact/path-map', params=fields(path=paths))
+
+    async def download(self, session_id, artifact_id, destination, *, max_bytes=100 * 1024 * 1024, overwrite=False):
+        return await self._client._download_artifact(session_id, artifact_id, destination, max_bytes=max_bytes, overwrite=overwrite)

dumate/_async_runs.py

@@ -0,0 +1,34 @@
+# Generated by tools/generate_async.py; edit synchronous source.
+import asyncio
+from .runs import correlated_result
+'Client-side convenience calls over sessions/events, not a server /runs API.'
+import time
+from ._common import history_messages
+from .errors import ProtocolError, RunTimeoutError, RunFailedError
+from .types import RunResult
+
+class AsyncRuns:
+
+    def __init__(self, client):
+        self._client = client
+
+    async def run_and_wait(self, *, session_id, message, file_ids=None, timeout=None, poll_interval=2.0):
+        """Poll authoritative history. No event replay, persistence or automatic resubmit.
+
+        One caller at a time per session. Timeout stops waiting, not remote execution.
+        """
+        if poll_interval <= 0 or (timeout is not None and timeout <= 0):
+            raise ValueError('poll_interval and timeout must be positive')
+        baseline = history_messages(await self._client.sessions.history(session_id))
+        baseline_ids = {x['info'].get('id') for x in baseline}
+        receipt = await self._client.sessions.send(session_id, message=message, file_ids=file_ids)
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            rows = await self._client.sessions.history(session_id)
+            result = correlated_result(session_id, rows, baseline_ids, message, receipt.request_id)
+            if result is not None:
+                return result
+            if deadline is not None and time.monotonic() >= deadline:
+                raise RunTimeoutError(session_id)
+            wait = poll_interval if deadline is None else min(poll_interval, max(0, deadline - time.monotonic()))
+            await asyncio.sleep(wait)