teamver-agent-sdk 0.6.1__tar.gz

teamver_agent_sdk-0.6.1/.gitignore

@@ -0,0 +1,50 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+node_modules/
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+.next/
+/out/
+out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+dist/
+
+# vite build output
+examples/react-ai-app/dist/
+
+# python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/

teamver_agent_sdk-0.6.1/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog — teamver-agent-sdk
+
+Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.6.1] - 2026-08-02
+
+### Changed (OpenClaw → agent 용어)
+- Prefer `teamver_agent_sdk.tools` / `AgentToolAdapter` (function-calling).
+- `OpenClawAdapter` · `teamver_agent_sdk.openclaw` 는 하위 호환 alias/shim.
+- Docs·examples·publish 스크립트: `docs_reference/agent`, `examples/python-docker-agent`,
+  `scripts/publish-agent-pypi.sh`, `.github/workflows/publish-agent-pypi.yml`.
+
+## [0.6.0] - 2026-08-02
+
+### Added (Drive / DM for agent runtimes)
+- `DmClient` — workspace DM list/open/read/post (`/api/v2/workspace/{ws}/dm/*`).
+- `DriveClient` — shared-drive list, file list, download-url, local download, presigned 3-step upload.
+- Agent tools: `teamver_channel_read` / `react`, `teamver_dm_*` (4), `teamver_drive_*` (5).
+  Catalog **13 → 24**.
+- Docs: `docs/11_agent_sdk_Drive_DM_확장_상위설계.md` + 구현설계·현황.
+- Tests: `test_dm_client.py`, `test_drive_client.py`; adapter catalog assertions.
+
+## [0.5.0] - 2026-07-23
+
+### Added (15-1 §07.2-E — Engine 런타임 결선)
+- `intent_runtime.py` — `JobIntentClassifier`: 주입된 `chat_fn`(동기/비동기)으로 판단 루프
+  수행(규칙 선필터 → 구조화 출력 LLM → 계약 검증 → 선택적 apply). 잘못된 LLM 출력은 안전
+  CLARIFY 로 폴백. `ChatCompletionFn` Protocol. 모델·프레임워크 무관(테스트는 가짜 chat_fn).
+- `classify_and_apply()` — 판단 후 `AgentToolAdapter` 로 create/attach/NO_JOB 라우팅.
+- 신규 export + `tests/test_intent_runtime.py`(5). 49 passed.
+
+## [0.4.0] - 2026-07-23
+
+### Added (15-1 §07.2 판단 위치·Engine 연동)
+- `job_intent.py` — Job 의도 판단을 **Engine LLM** 이 하도록 돕는 계약/프롬프트:
+  `JobCandidate`/`InboundMessage`/`JobDecisionContext`, `SYSTEM_PROMPT`+`FEW_SHOTS`,
+  `render_context`/`build_job_decision_messages`(모델 무관), `job_decision_response_schema`
+  (구조화 출력), `rule_prefilter`(명백한 잡담→NONE, LLM 생략).
+- `AgentToolAdapter.build_job_decision_request()`(messages+schema+선필터) /
+  `apply_job_decision()`(검증된 decision → create/attach/NO_JOB 라우팅).
+- `jobs.create()` + `JobsCreateArgs` 에 `request_intent`/`related_job_id`/`link_type`/
+  `confidence` 추가(서버 링크·SUPERSEDE 종료·confidence 가드 연동).
+- 신규 export + `tests/test_job_intent_golden.py`(10). 44 passed.
+
+## [0.3.0] - 2026-07-23
+
+### Added (15-1 §07.1 요청 의도 분류 / Request Intent Classification)
+- `AgentJobDecision` 확장: `request_intent`(AMEND/SUPERSEDE/FOLLOW_UP/NEW/NONE/
+  CLARIFY), `related_job_id`, `link_type`(follow_up|supersedes), `clarification`.
+- `effective_intent` — `request_intent` 미지정 시 `action` 에서 유도(ATTACH→AMEND,
+  CREATE→NEW, NO_JOB→NONE).
+- 검증 규칙: AMEND→existing_job_id, SUPERSEDE/FOLLOW_UP→related_job_id,
+  link_type→related_job_id 정합. `contracts/schemas/job-decision.schema.json` 동기.
+- 신규 export: `RequestIntent`, `LinkType`, `Clarification`.
+
+## [0.2.0] - 2026-07-23
+
+### Changed (16-1 §7, §13, §17)
+- **BREAKING**: HTTP transport (channel/events/jobs/runtime) now delegates to
+  `teamver-sdk-core` (`TeamverAsyncTransport`). Per-surface retry/error loops
+  removed (§17). `AgentHTTP` builds the transport per request so a swapped
+  underlying client is honored (test injection).
+- Errors unified onto the core tree: `TeamverAgentError`→`TeamverSDKError`,
+  `TeamverAgentConfigError`→`ConfigurationError`, `TeamverAgentAPIError`→root.
+
+### Added
+- **Agent Tool Adapter** (§8): `teamver_agent_sdk.tools` (`AgentToolAdapter`;
+  legacy `openclaw`/`OpenClawAdapter` alias) with `ToolSpec`,
+  `build_tool_specs`, `tool_json_schemas` (validate args → route to agent surface).
+  13 tools; JSON Schema generated from Pydantic models.
+- **Job decision** (§9): `AgentJobDecision` model + `JobsClient.decide()` — a
+  local schema validator (no server decide API); conditional required fields for
+  CREATE_JOB / ATTACH_JOB.
+- `teamver-sdk-core>=0.1.0` dependency; bumped `teamver-mail-agent>=0.3.0`.
+
+## [0.1.0] - previous
+
+### Added
+- Unified Teamver SDK for agent runtimes: channel reporting, event receive
+  loop, and mail integration.
+- Event checkpoint stores (`InMemoryCheckpointStore`, `FileCheckpointStore`) and
+  `dedup_key` helper for idempotent event processing (15-1 §04).

teamver_agent_sdk-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Neural Studio
+
+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.

teamver_agent_sdk-0.6.1/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: teamver-agent-sdk
+Version: 0.6.1
+Summary: Unified Teamver SDK for agent runtimes (channel, DM, drive, events, jobs, mail, agent tools)
+Project-URL: Homepage, https://teamver.com
+Project-URL: Documentation, https://github.com/NeuralStudioKr/ns-teamver-packages/tree/main/packages/python/teamver-agent-sdk-python
+Project-URL: Repository, https://github.com/NeuralStudioKr/ns-teamver-packages
+Project-URL: Issues, https://github.com/NeuralStudioKr/ns-teamver-packages/issues
+Project-URL: Changelog, https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/CHANGELOG.md
+Author-email: Teamver <dev@teamver.com>
+Maintainer-email: Teamver <dev@teamver.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,agent-tools,channel,dm,drive,mail,sdk,teamver
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<0.28,>=0.27.0
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: teamver-mail-agent>=0.3.0
+Requires-Dist: teamver-sdk-core>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# teamver-agent-sdk
+
+Official **Teamver Agent SDK** for agent runtimes (e.g. OpenClaw, Hermes).
+
+One facade (`TeamverAgent` + `AgentToolAdapter`) for:
+
+- **Channels** — list / post / read / react
+- **DM** — threads open / read / post
+- **Drive** — list / download / upload (presigned)
+- **Mail** — via `teamver-mail-agent`
+- **Jobs · heartbeat · SSE events**
+- **agent tools** — `adapter.list_tools()` / `adapter.dispatch(...)`
+
+## Install
+
+```bash
+pip install teamver-agent-sdk
+```
+
+Pulls in `teamver-mail-agent` and `teamver-sdk-core`. Python **≥ 3.11**.
+
+## Environment
+
+| env | purpose |
+|-----|---------|
+| `TEAMVER_WORKSPACE_ID` | workspace id (`WS-…`) |
+| `TEAMVER_AGENT_ID` | agent id (`AGT-…`) |
+| `TEAMVER_CHANNEL_API_BASE` | Main API host (`https://api.teamver.com`, **no** `/api`) |
+| `TEAMVER_AGENT_TOKEN` | channel/DM/drive grant (`tv_ak_*`) |
+| `TEAMVER_AGENT_API_BASE` | Agents BE host (jobs / heartbeat) |
+| `TEAMVER_MAIL_API_BASE` | Mail API host (**no** `/v1`) |
+| `TEAMVER_MAIL_AGENT_TOKEN` | mail agent token (`tv_agent_*`) |
+
+Do **not** put user passwords or `TEAMVER_INTERNAL_API_KEY` in the agent runtime.
+
+## Quick start
+
+```python
+import asyncio
+from teamver_agent_sdk import TeamverAgent, AgentToolAdapter
+
+async def main():
+    agent = TeamverAgent()  # from env
+    adapter = AgentToolAdapter(agent)
+
+    # agent function-calling schemas
+    tools = adapter.list_tools()
+
+    await agent.report(text="Deploy finished ✅", channel_id="CH-…")
+    files = await agent.drive.list_files(drive_id="personal", limit=20)
+    threads = await agent.dm.list_threads(limit=10)
+
+    # Tool dispatch example
+    await adapter.dispatch(
+        "teamver_channel_post",
+        {"channel_id": "CH-…", "text": "hello", "idempotency_key": "k1"},
+    )
+
+    await agent.aclose()
+
+asyncio.run(main())
+```
+
+Surfaces are lazy: channel-only agents need not set mail env (and vice versa).
+
+## Documentation
+
+- [AI Agent Guide](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/docs/teamver_agent_sdk_AI_AGENT_GUIDE.md)
+- [API Quickref](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/docs/teamver_agent_sdk_API_QUICKREF.md)
+- [Drive/DM design](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/docs/11_agent_sdk_Drive_DM_확장_상위설계.md)
+- [agent ops guide](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/docs_reference/agent/README.md)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

teamver_agent_sdk-0.6.1/README.md

@@ -0,0 +1,82 @@
+# teamver-agent-sdk
+
+Official **Teamver Agent SDK** for agent runtimes (e.g. OpenClaw, Hermes).
+
+One facade (`TeamverAgent` + `AgentToolAdapter`) for:
+
+- **Channels** — list / post / read / react
+- **DM** — threads open / read / post
+- **Drive** — list / download / upload (presigned)
+- **Mail** — via `teamver-mail-agent`
+- **Jobs · heartbeat · SSE events**
+- **agent tools** — `adapter.list_tools()` / `adapter.dispatch(...)`
+
+## Install
+
+```bash
+pip install teamver-agent-sdk
+```
+
+Pulls in `teamver-mail-agent` and `teamver-sdk-core`. Python **≥ 3.11**.
+
+## Environment
+
+| env | purpose |
+|-----|---------|
+| `TEAMVER_WORKSPACE_ID` | workspace id (`WS-…`) |
+| `TEAMVER_AGENT_ID` | agent id (`AGT-…`) |
+| `TEAMVER_CHANNEL_API_BASE` | Main API host (`https://api.teamver.com`, **no** `/api`) |
+| `TEAMVER_AGENT_TOKEN` | channel/DM/drive grant (`tv_ak_*`) |
+| `TEAMVER_AGENT_API_BASE` | Agents BE host (jobs / heartbeat) |
+| `TEAMVER_MAIL_API_BASE` | Mail API host (**no** `/v1`) |
+| `TEAMVER_MAIL_AGENT_TOKEN` | mail agent token (`tv_agent_*`) |
+
+Do **not** put user passwords or `TEAMVER_INTERNAL_API_KEY` in the agent runtime.
+
+## Quick start
+
+```python
+import asyncio
+from teamver_agent_sdk import TeamverAgent, AgentToolAdapter
+
+async def main():
+    agent = TeamverAgent()  # from env
+    adapter = AgentToolAdapter(agent)
+
+    # agent function-calling schemas
+    tools = adapter.list_tools()
+
+    await agent.report(text="Deploy finished ✅", channel_id="CH-…")
+    files = await agent.drive.list_files(drive_id="personal", limit=20)
+    threads = await agent.dm.list_threads(limit=10)
+
+    # Tool dispatch example
+    await adapter.dispatch(
+        "teamver_channel_post",
+        {"channel_id": "CH-…", "text": "hello", "idempotency_key": "k1"},
+    )
+
+    await agent.aclose()
+
+asyncio.run(main())
+```
+
+Surfaces are lazy: channel-only agents need not set mail env (and vice versa).
+
+## Documentation
+
+- [AI Agent Guide](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/docs/teamver_agent_sdk_AI_AGENT_GUIDE.md)
+- [API Quickref](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/docs/teamver_agent_sdk_API_QUICKREF.md)
+- [Drive/DM design](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/packages/python/teamver-agent-sdk-python/docs/11_agent_sdk_Drive_DM_확장_상위설계.md)
+- [agent ops guide](https://github.com/NeuralStudioKr/ns-teamver-packages/blob/main/docs_reference/agent/README.md)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

teamver_agent_sdk-0.6.1/docs/11_1_agent_sdk_Drive_DM_/352/265/254/355/230/204/354/204/244/352/263/204.md

@@ -0,0 +1,119 @@
+# teamver-agent-sdk — Drive / DM 구현설계 (루프)
+
+## 변경 이력
+
+| 일시 (KST) | 변경 내용 |
+|---|-----|
+| 2026-08-02 15:55 | Phase 4 — 0.6.0 · CHANGELOG · agent smoke 동기화 |
+| 2026-08-02 15:50 | Phase 3 — DriveClient + agent drive tools |
+| 2026-08-02 15:45 | Phase 2 — DmClient + agent DM tools |
+| 2026-08-02 15:42 | Phase 1 — channel read/react tool 구현 반영 |
+| 2026-08-02 15:40 | Phase 0 — 상위설계 반영, Phase 1~4 상세 초안 |
+
+**SSOT 상위:** [11_agent_sdk_Drive_DM_확장_상위설계.md](./11_agent_sdk_Drive_DM_확장_상위설계.md)  
+**현황:** [11_2_agent_sdk_Drive_DM_구현현황.md](./11_2_agent_sdk_Drive_DM_구현현황.md)
+
+---
+
+## Phase 0 — 문서 (완료 기준)
+
+- [x] 상위설계 문서
+- [x] 본 구현설계 · 현황 문서 골격
+
+---
+
+## Phase 1 — Channel agent tools ✅
+
+### 설계
+
+기존 `ChannelClient.read_messages` / `react` 를 tool로 노출.
+
+| 항목 | 내용 |
+|------|------|
+| Args | `ChannelReadArgs(channel_id, limit=50, cursor?)`, `ChannelReactArgs(channel_id, message_id, emoji)` |
+| tools | `teamver_channel_read`, `teamver_channel_react` |
+| adapter | `_invoke`에 `channel.read_messages`, `channel.react` |
+| tests | catalog **15**, fake channel dispatch |
+
+### 파일
+
+- `teamver_agent_sdk/tools/catalog.py`
+- `teamver_agent_sdk/tools/adapter.py`
+- `tests/test_agent_tools.py`
+- (하위 호환) `teamver_agent_sdk/openclaw/*` → `tools` re-export
+
+---
+
+## Phase 2 — DM surface ✅
+
+### 설계
+
+`teamver_agent_sdk/dm.py` — `DmClient` (AgentHTTP, base=`…/api/v2`).
+
+```python
+class DmClient:
+    async def list_threads(self, *, limit=50, cursor=None) -> dict
+    async def open_thread(self, peer_user_id: str, *, idempotency_key=None) -> dict
+    async def read_messages(self, thread_id, *, limit=50, cursor=None) -> dict
+    async def post_message(self, thread_id, text, *, reply_to_message_id=None, idempotency_key=None) -> dict
+    async def aclose(self) -> None
+```
+
+Paths:
+
+- `GET /workspace/{ws}/dm/threads`
+- `POST /workspace/{ws}/dm/threads` JSON `{"peer_user_id": "…"}`
+- `GET /workspace/{ws}/dm/threads/{thread_id}/messages`
+- `POST /workspace/{ws}/dm/threads/{thread_id}/messages` JSON `{"text": "…"}`
+
+`TeamverAgent.dm` lazy property; `aclose`에 포함.
+
+agent tools 4개 (§상위설계 §4).
+
+---
+
+## Phase 3 — Drive surface ✅
+
+### 설계
+
+`teamver_agent_sdk/drive.py` — `DriveClient`.
+
+- `_http_v1`: AgentHTTP base `{channel_api_base}/api`
+- `_http_v2`: AgentHTTP base `{channel_api_base}/api/v2` (또는 channel과 공유 가능하나 생명주기 단순화를 위해 Drive 전용 v2 client)
+
+```python
+class DriveClient:
+    async def list_shared_drives(self) -> dict
+    async def list_files(self, *, drive_id="personal", limit=50, folder_id=None) -> dict
+    async def download_url(self, asset_id, *, drive_id="personal") -> dict  # {download_url,…}
+    async def download(self, asset_id, dest_path, *, drive_id="personal") -> dict  # {path, bytes}
+    async def upload(self, *, local_path, filename=None, drive_id="personal", folder_id=None, content_type=None) -> dict
+    async def aclose(self) -> None
+```
+
+Upload:
+
+1. POST `/drive/upload-request`
+2. PUT `upload_url` with file body
+3. POST `/drive/upload-confirm` `{asset_id}`
+
+agent tools 5개. `drive.download` / `upload`는 **로컬 path** 필수(컨테이너/VM 가정).
+
+---
+
+## Phase 4 — 마무리 ✅
+
+- `__version__` / `pyproject` → **0.6.0**
+- CHANGELOG, API_QUICKREF, AI_AGENT_GUIDE, DESIGN, README
+- `docs_reference/agent/01·02` tool·버전 갱신
+- `examples/python-docker-agent/agent_smoke.py` dm/drive 섹션
+- export `DmClient` / `DriveClient`
+
+---
+
+## 공통 규칙
+
+- docstring 한국어 모듈 목적 (repo rule)
+- 토큰 로그 금지
+- 기존 channel/mail/jobs 동작 회귀 금지
+- main 직접 push, PR/CI 없음

teamver_agent_sdk-0.6.1/docs/11_2_agent_sdk_Drive_DM_/352/265/254/355/230/204/355/230/204/355/231/251.md

@@ -0,0 +1,70 @@
+# teamver-agent-sdk — Drive / DM 구현현황
+
+## 변경 이력
+
+| 일시 (KST) | 변경 내용 |
+|---|-----|
+| 2026-08-02 15:55 | Phase 4 완료 — 0.6.0 릴리스 위생 · 문서/smoke 동기화 |
+| 2026-08-02 15:50 | Phase 3 완료 — DriveClient + drive tools 5종 |
+| 2026-08-02 15:45 | Phase 2 완료 — DmClient + DM tools 4종 |
+| 2026-08-02 15:42 | Phase 1 완료 — channel read/react agent tools |
+| 2026-08-02 15:40 | Phase 0 문서 착수 — 구현 전 baseline |
+
+**상위설계:** [11_agent_sdk_Drive_DM_확장_상위설계.md](./11_agent_sdk_Drive_DM_확장_상위설계.md)  
+**구현설계:** [11_1_agent_sdk_Drive_DM_구현설계.md](./11_1_agent_sdk_Drive_DM_구현설계.md)
+
+---
+
+## 진행 요약
+
+| Phase | 상태 | 메모 |
+|-------|------|------|
+| 0 상위·구현설계 문서 | ✅ | 본 세트 작성 |
+| 1 Channel read/react tools | ✅ | tools 13→15 |
+| 2 DmClient + tools | ✅ | tools 15→19 · `dm.py` |
+| 3 DriveClient + tools | ✅ | tools 19→24 · `drive.py` |
+| 4 0.6.0 · 문서/smoke 동기화 | ✅ | version 0.6.0 |
+
+---
+
+## Baseline (0.5.0)
+
+- agent tools: **13**
+- Channel: list/post (+ read/react 클라이언트만)
+- DM / Drive: 없음
+
+---
+
+## Phase별 로그
+
+### Phase 0 — 2026-08-02 15:40 KST
+
+- 추가: `docs/11_*.md` 3종
+- 코드 변경 없음
+
+### Phase 1 — 2026-08-02 15:42 KST
+
+- `teamver_channel_read` / `teamver_channel_react` 도구 + adapter 라우팅
+- `tests/test_agent_tools.py` catalog=24, fake dispatch 검증
+- agent tools 총 **15**
+
+### Phase 2 — 2026-08-02 15:45 KST
+
+- `DmClient`: list_threads / open_thread / read_messages / post_message
+- `TeamverAgent.dm` lazy + aclose
+- tools: `teamver_dm_*` 4종 · `tests/test_dm_client.py`
+- agent tools 총 **19**
+
+### Phase 3 — 2026-08-02 15:50 KST
+
+- `DriveClient`: list_shared_drives / list_files / download_url / download / upload(3-step)
+- `TeamverAgent.drive` lazy + aclose
+- tools: `teamver_drive_*` 5종 · `tests/test_drive_client.py`
+- agent tools 총 **24**
+
+### Phase 4 — 2026-08-02 15:55 KST
+
+- `teamver-agent-sdk` **0.6.0** (pyproject / `__version__` / User-Agent)
+- CHANGELOG · DESIGN · API_QUICKREF · AI_AGENT_GUIDE · README
+- `docs_reference/agent` + Docker smoke dm/drive 단계
+- 단위 테스트 전부 통과 (구현 시점 54+)

teamver_agent_sdk-0.6.1/docs/11_agent_sdk_Drive_DM_/355/231/225/354/236/245_/354/203/201/354/234/204/354/204/244/352/263/204.md

@@ -0,0 +1,145 @@
+# teamver-agent-sdk — Drive / DM 확장 상위설계
+
+## 변경 이력
+
+| 일시 (KST) | 변경 내용 |
+|---|-----|
+| 2026-08-02 15:40 | v0.1 초안 — agent 런타임용 channel 보강 · DM · Drive surface/tool |
+
+**목표:** agent 런타임(예: OpenClaw·Hermes 등)이 Teamver **채널 읽기·쓰기**, **DM 읽기·쓰기**, **Drive 목록·다운로드·업로드**를 `teamver-agent-sdk` 한 파사드(+ agent tools)로 수행한다.  
+**대상 패키지:** `packages/python/teamver-agent-sdk-python` (배포명 `teamver-agent-sdk`)  
+**인증:** 기존과 동일 — Main Bearer **`tv_ak_*`** + `TEAMVER_CHANNEL_API_BASE` / `TEAMVER_WORKSPACE_ID` (별도 Drive/DM 토큰 없음).  
+**비목표:** 사용자 login/signup, Mail M2M, WebSocket, `TEAMVER_INTERNAL_API_KEY`.
+
+---
+
+## 1. 배경 · Gap
+
+| 요구 | 0.5.x 상태 |
+|------|------------|
+| 채널 쓰기 · 목록 | ✅ + agent tool |
+| 채널 읽기 · react | △ 클라이언트만 / tool 없음 |
+| DM | ❌ |
+| Drive | ❌ (DESIGN non-goal이었음) |
+
+상위 agent 제품 요구로 Drive/DM이 **in-scope**로 승격된다. 전체 Main 카탈로그(`teamver-be-sdk`)를 끌어오지 않고, agent에 필요한 **최소 surface**만 추가한다.
+
+---
+
+## 2. 아키텍처
+
+```text
+TeamverAgent
+  ├─ channel   (기존 + tool 보강)
+  ├─ dm        (신규 DmClient)          ← /api/v2/workspace/{ws}/dm/*
+  ├─ drive     (신규 DriveClient)       ← /api/drive/* + /api/v2/shared-drive|drive/*
+  ├─ events / mail / jobs / runtime     (기존)
+  └─ AgentToolAdapter.dispatch(tool)     (tools 카탈로그 확장)
+```
+
+| Surface | HTTP base | Auth |
+|---------|-----------|------|
+| channel / dm / events | `{CHANNEL_API_BASE}/api/v2` | `tv_ak_*` |
+| drive v1 (list/upload/download-url) | `{CHANNEL_API_BASE}/api` | `tv_ak_*` |
+| drive v2 (shared-drive, home/recent) | `{CHANNEL_API_BASE}/api/v2` | `tv_ak_*` |
+
+`drive_enabled` / `dm_enabled` ≡ `channel_enabled` (동일 base+token).  
+공유 드라이브는 `X-Shared-Drive-Id` 또는 query `shared_drive_id` (BE 호환: 헤더 우선, 예시는 host-wheels와 동일).
+
+---
+
+## 3. API 매핑 (agent 최소 집합)
+
+### 3.1 Channel (보강)
+
+| SDK | HTTP |
+|-----|------|
+| `read_messages(channel_id, limit, cursor)` | GET `…/channels/{id}/messages` |
+| `react(channel_id, message_id, emoji)` | POST `…/messages/{id}/reactions` |
+
+(이미 `channel.py` 존재 — **agent tool만 추가**해도 Phase 1 완료 가능.)
+
+### 3.2 DM (신규)
+
+레포 확인 경로: `GET /api/v2/workspace/{ws}/dm/threads` (`api_perf_monitor`).  
+메시지 경로는 채널과 대칭으로 둔다 (BE 불일치 시 escape `request`).
+
+| SDK | HTTP (가정·대칭) |
+|-----|------------------|
+| `list_threads(limit, cursor)` | GET `/workspace/{ws}/dm/threads` |
+| `open_thread(peer_user_id)` | POST `/workspace/{ws}/dm/threads` body `{peer_user_id}` |
+| `read_messages(thread_id, limit, cursor)` | GET `…/dm/threads/{id}/messages` |
+| `post_message(thread_id, text, …)` | POST `…/dm/threads/{id}/messages` |
+
+### 3.3 Drive (신규)
+
+| SDK | HTTP |
+|-----|------|
+| `list_shared_drives()` | GET `/api/v2/shared-drive` |
+| `list_files(drive_id?, limit, folder_id?)` | GET `/api/drive/list` (+ personal/shared 헤더) |
+| `download_url(asset_id, drive_id?)` | GET `/api/drive/asset/{id}/download-url` |
+| `download(asset_id, dest_path, …)` | download-url → httpx GET → 파일 저장 |
+| `upload(path\|bytes, filename, …)` | upload-request → PUT presign → upload-confirm |
+
+업로드는 be-sdk / host-wheels 와 동일한 **3-step presigned** 계약.
+
+---
+
+## 4. agent tools (추가)
+
+| tool | handler |
+|------|---------|
+| `teamver_channel_read` | `channel.read_messages` |
+| `teamver_channel_react` | `channel.react` |
+| `teamver_dm_list_threads` | `dm.list_threads` |
+| `teamver_dm_open_thread` | `dm.open_thread` |
+| `teamver_dm_read_messages` | `dm.read_messages` |
+| `teamver_dm_post_message` | `dm.post_message` |
+| `teamver_drive_list_drives` | `drive.list_shared_drives` |
+| `teamver_drive_list_files` | `drive.list_files` |
+| `teamver_drive_download_url` | `drive.download_url` |
+| `teamver_drive_download` | `drive.download` (dest_path) |
+| `teamver_drive_upload` | `drive.upload` (local path) |
+
+대용량 바이너리는 tool 결과에 넣지 않는다 — **경로·URL·asset_id 메타만** 반환.
+
+---
+
+## 5. 구현 루프 (Phase)
+
+| Phase | 내용 | 산출 |
+|-------|------|------|
+| **0** | 본 상위설계 + 현황 문서 | docs |
+| **1** | Channel read/react agent tools + 테스트 | tools/adapter/tests |
+| **2** | `DmClient` + facade + tools + 테스트 | `dm.py` |
+| **3** | `DriveClient` + facade + tools + 테스트 | `drive.py` |
+| **4** | 버전 0.6.0 · CHANGELOG · smoke/example · docs_reference/agent 동기화 | release hygiene |
+
+각 Phase마다 **구현설계 절 갱신 · 구현현황 문서 갱신 · main push**.
+
+---
+
+## 6. 테스트 전략
+
+- httpx `MockTransport` 또는 Fake surface (기존 `test_agent_tools` 패턴).
+- Drive upload: request/confirm mock + PUT용 ASGI/MockTransport.
+- DM path는 mock으로 계약 고정; live는 opt-in 아님(이 루프에서는 mock만).
+
+---
+
+## 7. 리스크
+
+| 리스크 | 완화 |
+|--------|------|
+| DM POST body 필드명 BE와 불일치 | `open_thread`/`post_message`에 raw `body` escape; 문서에 가정 명시 |
+| Agent 토큰에 drive/dm 스코프 부족 | 403 → 명확한 APIError; Console 스코프 문서화 |
+| 업로드 메모리 | 파일 path 스트리밍 PUT 권장 |
+
+---
+
+## 8. 관련 문서
+
+- 구현설계(루프): [11_1_agent_sdk_Drive_DM_구현설계.md](./11_1_agent_sdk_Drive_DM_구현설계.md)
+- 구현현황: [11_2_agent_sdk_Drive_DM_구현현황.md](./11_2_agent_sdk_Drive_DM_구현현황.md)
+- 기존: [teamver_agent_sdk_DESIGN.md](./teamver_agent_sdk_DESIGN.md)
+- 예시 패턴: `examples/python-docker-host-wheels/download_drive_file.py`