agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk_runtime_common/workspace_files/preview.py

@@ -0,0 +1,96 @@
+"""HTML preview helpers shared by local server and deployed runtime routes."""
+
+from __future__ import annotations
+
+import html as html_lib
+import re
+from urllib.parse import quote
+
+
+def _source_list(*sources: str | None) -> str:
+    seen: list[str] = []
+    for source in sources:
+        if source and source not in seen:
+            seen.append(source)
+    return " ".join(seen)
+
+
+def _quote_workspace_path(path: str) -> str:
+    return "/".join(quote(segment, safe="") for segment in path.split("/") if segment)
+
+
+def build_workspace_file_base_href(file_path: str) -> str:
+    normalized = str(file_path or "").replace("\\", "/").strip("/")
+    if "/" not in normalized:
+        return "/_ksadk/workspace/v1/files/"
+    dir_path = normalized.rsplit("/", 1)[0]
+    encoded_dir_path = _quote_workspace_path(dir_path)
+    return f"/_ksadk/workspace/v1/files/{encoded_dir_path}/"
+
+
+def build_workspace_preview_csp(asset_source: str | None = None) -> str:
+    script_sources = _source_list(
+        "'unsafe-inline'",
+        "'unsafe-eval'",
+        "'self'",
+        "https:",
+        asset_source,
+    )
+    render_asset_sources = _source_list("'self'", "https:", asset_source)
+    return "; ".join(
+        [
+            "sandbox allow-scripts allow-downloads",
+            "default-src 'none'",
+            f"script-src {script_sources}",
+            f"style-src 'unsafe-inline' data: {render_asset_sources}",
+            f"img-src data: blob: {render_asset_sources}",
+            f"font-src data: {render_asset_sources}",
+            f"media-src data: blob: {render_asset_sources}",
+            "worker-src blob:",
+            "connect-src 'none'",
+            "form-action 'none'",
+            "base-uri 'self'",
+        ]
+    )
+
+
+HASH_ANCHOR_HANDLER = """<script data-ksadk-preview-anchor-handler>
+(function() {
+  function scrollToHash(rawHref) {
+    if (!rawHref || rawHref === '#') return;
+    var rawId = rawHref.slice(1);
+    var id = rawId;
+    try {
+      id = decodeURIComponent(rawId);
+    } catch (_) {}
+    var target = document.getElementById(id) || document.getElementsByName(id)[0];
+    if (target) {
+      target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+  }
+  document.addEventListener('click', function(event) {
+    var target = event.target && event.target.closest ? event.target.closest('a') : null;
+    if (!target) return;
+    var rawHref = target.getAttribute('href') || '';
+    if (rawHref.charAt(0) === '#') {
+      event.preventDefault();
+      scrollToHash(rawHref);
+    }
+  }, true);
+})();
+</script>"""
+
+
+def inject_workspace_html_preview(html_doc: str, file_path: str) -> str:
+    base_href = build_workspace_file_base_href(file_path)
+    base_tag = f'<base href="{html_lib.escape(base_href, quote=True)}">'
+    injection = f"{base_tag}{HASH_ANCHOR_HANDLER}"
+    if re.search(r"<head[^>]*>", html_doc, re.IGNORECASE):
+        return re.sub(
+            r"<head[^>]*>",
+            lambda match: match.group() + injection,
+            html_doc,
+            count=1,
+            flags=re.IGNORECASE,
+        )
+    return injection + html_doc

ksadk_runtime_common/workspace_files/router.py

@@ -0,0 +1,254 @@
+"""Workspace files FastAPI router - preserves the current contract exactly."""
+
+from __future__ import annotations
+
+import io
+import mimetypes
+import zipfile
+from collections.abc import Callable
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Annotated
+
+from fastapi import APIRouter, File, HTTPException, Query, Response, UploadFile
+from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
+
+from ksadk_runtime_common.workspace_files.bootstrap import (
+    workspace_files_enabled,
+    workspace_files_max_upload_bytes,
+    workspace_files_root_label,
+)
+from ksadk_runtime_common.workspace_files.path_utils import (
+    _resolve_workspace_root,
+    _resolve_workspace_target,
+)
+from ksadk_runtime_common.workspace_files.preview import (
+    build_workspace_preview_csp,
+    inject_workspace_html_preview,
+)
+
+EntryPayload = dict[str, str | int | None]
+EntriesResponse = dict[str, str | list[EntryPayload]]
+HealthzResponse = dict[str, bool | str]
+UploadResponse = dict[str, EntryPayload]
+
+
+def _trusted_workspace_path(root: Path, path: Path) -> Path:
+    resolved_root = root.resolve(strict=False)
+    resolved_path = path.resolve(strict=False)
+    if resolved_path != resolved_root and resolved_root not in resolved_path.parents:
+        raise HTTPException(status_code=400, detail="workspace path escapes root")
+    return resolved_path
+
+
+def _isoformat_timestamp(path: Path) -> str:
+    """Get an ISO 8601 timestamp for a file modification time."""
+    path = path.resolve(strict=False)
+    return (
+        datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc)
+        .isoformat()
+        .replace("+00:00", "Z")
+    )
+
+
+def _entry_payload(root: Path, path: Path) -> EntryPayload:
+    """Build entry payload for file and directory listing."""
+    entry_type = "directory" if path.is_dir() else "file"
+    mime_type = None if entry_type == "directory" else mimetypes.guess_type(path.name)[0]
+    size_bytes = None if entry_type == "directory" else path.stat().st_size
+    return {
+        "Name": path.name,
+        "Path": path.relative_to(root).as_posix(),
+        "Type": entry_type,
+        "SizeBytes": size_bytes,
+        "MimeType": mime_type,
+        "ModifiedAt": _isoformat_timestamp(path),
+    }
+
+
+def create_workspace_files_router(
+    *,
+    root_getter: Callable[[], Path],
+    enabled_getter: Callable[[], bool] | None = None,
+) -> APIRouter:
+    """Create a workspace files router using the v1 contract."""
+    router = APIRouter(prefix="/_ksadk/workspace/v1", tags=["workspace-files"])
+    is_enabled = enabled_getter or (lambda: workspace_files_enabled(default=True))
+
+    def _ensure_enabled() -> None:
+        if not is_enabled():
+            raise HTTPException(status_code=404, detail="workspace files are disabled")
+
+    @router.get("/healthz")
+    async def workspace_healthz() -> HealthzResponse:
+        _ensure_enabled()
+        root = _resolve_workspace_root(root_getter)
+        return {
+            "ok": True,
+            "root": workspace_files_root_label(),
+            "workspace_path": str(root),
+        }
+
+    @router.get("/entries")
+    async def list_workspace_entries(
+        path: str = Query(".", alias="path"),
+        recursive: bool = Query(False, alias="recursive"),
+    ) -> EntriesResponse:
+        _ensure_enabled()
+        root = _resolve_workspace_root(root_getter)
+        normalized, target = _resolve_workspace_target(root, path, allow_root=True)
+        target = _trusted_workspace_path(root, target)
+        if not target.exists():
+            raise HTTPException(status_code=404, detail="workspace path not found")
+        if not target.is_dir():
+            raise HTTPException(status_code=400, detail="workspace path is not a directory")
+
+        iterator = target.rglob("*") if recursive else target.iterdir()
+        entries = sorted(
+            [entry for entry in iterator if entry.exists()],
+            key=lambda entry: (entry.is_file(), entry.name.lower()),
+        )
+        return {
+            "Root": workspace_files_root_label(),
+            "Path": normalized,
+            "Entries": [_entry_payload(root, entry) for entry in entries],
+        }
+
+    @router.get("/export-zip")
+    async def export_workspace_zip(path: str = Query(".", alias="path")) -> StreamingResponse:
+        _ensure_enabled()
+        root = _resolve_workspace_root(root_getter)
+        normalized, target = _resolve_workspace_target(root, path, allow_root=True)
+        target = _trusted_workspace_path(root, target)
+        if not target.exists():
+            raise HTTPException(status_code=404, detail="workspace path not found")
+        if not target.is_dir():
+            raise HTTPException(status_code=400, detail="workspace path is not a directory")
+
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as archive:
+            for entry in sorted(target.rglob("*")):
+                if not entry.exists() or not entry.is_file() or entry.is_symlink():
+                    continue
+                try:
+                    resolved_entry = entry.resolve(strict=True)
+                except OSError:
+                    continue
+                if resolved_entry == root or root not in resolved_entry.parents:
+                    continue
+                archive.write(resolved_entry, resolved_entry.relative_to(root).as_posix())
+
+        buf.seek(0)
+        zip_name = f"workspace-{normalized.replace('/', '-')}.zip" if normalized != "." else "workspace.zip"
+        return StreamingResponse(
+            buf,
+            media_type="application/zip",
+            headers={"Content-Disposition": f'attachment; filename="{zip_name}"'},
+        )
+
+    @router.head("/files/{file_path:path}")
+    async def head_workspace_file(file_path: str) -> Response:
+        _ensure_enabled()
+        root = _resolve_workspace_root(root_getter)
+        _, target = _resolve_workspace_target(root, file_path, allow_root=False)
+        target = _trusted_workspace_path(root, target)
+        if not target.exists() or not target.is_file():
+            raise HTTPException(status_code=404, detail="workspace file not found")
+        media_type, _ = mimetypes.guess_type(target.name)
+        return Response(
+            status_code=200,
+            headers={
+                "Content-Length": str(target.stat().st_size),
+                "Content-Type": media_type or "application/octet-stream",
+                "Last-Modified": _isoformat_timestamp(target),
+            },
+        )
+
+    @router.get("/files/{file_path:path}")
+    async def download_workspace_file(file_path: str) -> Response:
+        _ensure_enabled()
+        root = _resolve_workspace_root(root_getter)
+        _, target = _resolve_workspace_target(root, file_path, allow_root=False)
+        target = _trusted_workspace_path(root, target)
+        if not target.exists() or not target.is_file():
+            raise HTTPException(status_code=404, detail="workspace file not found")
+        media_type, _ = mimetypes.guess_type(target.name)
+        is_html = (media_type or "").split(";")[0].lower() == "text/html" or target.suffix.lower() in {
+            ".html",
+            ".htm",
+        }
+        if is_html:
+            html_doc = target.read_bytes().decode("utf-8", errors="replace")
+            return Response(
+                content=inject_workspace_html_preview(html_doc, file_path).encode("utf-8"),
+                media_type="text/html; charset=utf-8",
+                headers={
+                    "Content-Security-Policy": build_workspace_preview_csp(),
+                    "Last-Modified": _isoformat_timestamp(target),
+                },
+            )
+        return FileResponse(
+            target,
+            media_type=media_type or "application/octet-stream",
+            filename=target.name,
+        )
+
+    @router.post("/files/{file_path:path}")
+    async def upload_workspace_file(
+        file_path: str,
+        file: Annotated[UploadFile, File(...)],
+    ) -> UploadResponse:
+        _ensure_enabled()
+        root = _resolve_workspace_root(root_getter)
+        _, target = _resolve_workspace_target(root, file_path, allow_root=False)
+        target = _trusted_workspace_path(root, target)
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        size_bytes = 0
+        max_upload_bytes = workspace_files_max_upload_bytes()
+        try:
+            with target.open("wb") as handle:
+                while True:
+                    chunk = await file.read(1024 * 1024)
+                    if not chunk:
+                        break
+                    size_bytes += len(chunk)
+                    if size_bytes > max_upload_bytes:
+                        raise HTTPException(
+                            status_code=413, detail="workspace file exceeds upload limit"
+                        )
+                    handle.write(chunk)
+        except HTTPException:
+            target.unlink(missing_ok=True)
+            raise
+        finally:
+            await file.close()
+
+        entry = _entry_payload(root, target)
+        if file.content_type:
+            entry["MimeType"] = file.content_type
+        return {"Entry": entry}
+
+    @router.delete("/files/{file_path:path}")
+    async def delete_workspace_file(file_path: str) -> JSONResponse:
+        _ensure_enabled()
+        root = _resolve_workspace_root(root_getter)
+        _, target = _resolve_workspace_target(root, file_path, allow_root=False)
+        target = _trusted_workspace_path(root, target)
+        if not target.exists():
+            raise HTTPException(status_code=404, detail="workspace file not found")
+        if target.is_dir():
+            try:
+                target.rmdir()
+            except OSError as exc:
+                raise HTTPException(
+                    status_code=409,
+                    detail="workspace directory is not empty",
+                ) from exc
+            return JSONResponse({"Deleted": True})
+        if not target.is_file():
+            raise HTTPException(status_code=400, detail="workspace path is not a file or directory")
+        target.unlink()
+        return JSONResponse({"Deleted": True})
+
+    return router

agentengine_sdk_python-0.6.2.dist-info/METADATA

@@ -1,46 +0,0 @@
-Metadata-Version: 2.4
-Name: agentengine-sdk-python
-Version: 0.6.2
-Summary: Kingsoft Cloud Agent Engine SDK (alias for ksadk)
-Author-email: KsADK Team <xiayu@kingsoft.com>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/kingsoftcloud/ksadk-python
-Project-URL: Repository, https://github.com/kingsoftcloud/ksadk-python
-Keywords: agent,langchain,langgraph,adk,kingsoft cloud,ai,llm
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: ksadk==0.6.2
-
-# agentengine-sdk-python
-
-**Kingsoft Cloud Agent Engine SDK** - 别名包
-
-这是 [ksadk](https://pypi.org/project/ksadk/) 的别名包，安装后会自动安装对应版本的 ksadk。
-
-当前版本：`0.6.2`
-
-当前别名包依赖：`ksadk==0.6.2`
-
-## 安装
-
-```bash
-# 任选一种方式安装
-pip install agentengine-sdk-python
-# 或
-pip install ksadk
-```
-
-## 使用
-
-```bash
-agentengine --help
-ksadk --help
-```
-
-Python SDK、命令行工具和更多文档请参考 [ksadk](https://github.com/kingsoftcloud/ksadk-python)。

agentengine_sdk_python-0.6.2.dist-info/RECORD

@@ -1,4 +0,0 @@
-agentengine_sdk_python-0.6.2.dist-info/METADATA,sha256=qKY8Hy36WQfnGItEO2ECKP8SuCEMRFiDJXMZGFxbJ_o,1308
-agentengine_sdk_python-0.6.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-agentengine_sdk_python-0.6.2.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-agentengine_sdk_python-0.6.2.dist-info/RECORD,,

agentengine_sdk_python-0.6.2.dist-info/top_level.txt

@@ -1 +0,0 @@
-