agentengine-sdk-python 0.6.4__py3-none-any.whl → 0.7.0__py3-none-any.whl

ksadk_runtime_common/memory_backend/render.py

@@ -0,0 +1,71 @@
+"""Memory backend config renderer for runtime bootstrap integration."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from typing import Any
+
+from ksadk_runtime_common.memory_backend.manifest import (
+    MemoryBackendManifest,
+    parse_manifest,
+)
+from ksadk_runtime_common.memory_backend.registry import (
+    RenderResult,
+    get_provider,
+)
+
+MANIFEST_ENV_VAR = "MEMORY_BACKEND_MANIFEST"
+MEMORY_BACKEND_PLUGIN_IDS = ["openclaw-mem0", "memory-lancedb"]
+MEMORY_BACKEND_PLUGIN_SLOTS = ["memory"]
+
+
+def render_memory_backend_config(
+    manifest: MemoryBackendManifest | str | Mapping[str, Any] | None = None,
+) -> RenderResult:
+    """Render memory backend config from a manifest."""
+    if manifest is None:
+        manifest_raw = os.getenv(MANIFEST_ENV_VAR)
+        if not manifest_raw:
+            return RenderResult(
+                backend_type="openclaw_default",
+                config_patch={},
+                required_env=[],
+                plugin_ids=[],
+            )
+        manifest = manifest_raw
+
+    parsed = parse_manifest(manifest)
+    if parsed is None:
+        return RenderResult(
+            backend_type="openclaw_default",
+            config_patch={},
+            required_env=[],
+            plugin_ids=[],
+        )
+
+    if parsed.backend_type == "openclaw_default":
+        return RenderResult(
+            backend_type="openclaw_default",
+            config_patch={},
+            required_env=[],
+            disabled_plugin_ids=MEMORY_BACKEND_PLUGIN_IDS,
+            clear_plugin_slots=MEMORY_BACKEND_PLUGIN_SLOTS,
+        )
+
+    provider = get_provider(parsed.backend_type)
+    if provider is None:
+        raise ValueError(f"Unknown backend_type: {parsed.backend_type}")
+
+    return provider.render(parsed)
+
+
+def render_to_json(manifest: MemoryBackendManifest | str | dict[str, Any] | None = None) -> str:
+    """Render memory backend config to a JSON string."""
+    result = render_memory_backend_config(manifest)
+    return json.dumps(result.model_dump())
+
+
+if __name__ == "__main__":
+    print(render_to_json())

ksadk_runtime_common/schemas/memory_backend_manifest.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kingsoftcloud.github.io/ksadk-python/schemas/memory_backend_manifest/v1",
+  "title": "MemoryBackendManifest",
+  "description": "Memory backend manifest for OpenClaw runtime configuration.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "backend_type"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "v1",
+      "description": "Schema version identifier. Must be 'v1'."
+    },
+    "backend_type": {
+      "type": "string",
+      "enum": [
+        "openclaw_default",
+        "mem0",
+        "lancedb"
+      ],
+      "description": "Memory backend type. Supports 'openclaw_default', 'mem0', and 'lancedb'."
+    },
+    "config": {
+      "type": "object",
+      "description": "Backend-specific configuration.",
+      "additionalProperties": true,
+      "properties": {
+        "mem0_instance_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Mem0 instance UUID (required when backend_type is 'mem0')."
+        },
+        "mem0_instance_name": {
+          "type": "string",
+          "description": "Mem0 instance display name."
+        },
+        "mem0_region": {
+          "type": "string",
+          "description": "Mem0 instance region."
+        },
+        "dbPath": {
+          "type": "string",
+          "description": "Optional LanceDB plugin dbPath override."
+        },
+        "database_uri": {
+          "type": "string",
+          "description": "Database URI for LanceDB storage (e.g. s3://bucket/prefix). Mapped to dbPath when dbPath is absent."
+        },
+        "embedding": {
+          "type": "object",
+          "description": "Optional LanceDB plugin embedding configuration.",
+          "additionalProperties": true
+        },
+        "embedding_provider": {
+          "type": "string",
+          "description": "Embedding provider for LanceDB (e.g. openai)."
+        },
+        "embedding_model": {
+          "type": "string",
+          "description": "Embedding model name for LanceDB."
+        },
+        "embedding_dimensions": {
+          "type": "integer",
+          "description": "Embedding vector dimensions for LanceDB."
+        },
+        "embedding_base_url": {
+          "type": "string",
+          "description": "Embedding provider base URL for LanceDB."
+        },
+        "storageOptions": {
+          "type": "object",
+          "description": "Optional LanceDB plugin storage options.",
+          "additionalProperties": true
+        },
+        "storage_endpoint": {
+          "type": "string",
+          "description": "S3-compatible storage endpoint URL. Mapped into storageOptions.endpoint."
+        },
+        "storage_region": {
+          "type": "string",
+          "description": "S3-compatible storage region. Mapped into storageOptions.region."
+        },
+        "storage_bucket": {
+          "type": "string",
+          "description": "S3-compatible storage bucket. Mapped into storageOptions.bucket."
+        },
+        "storage_prefix": {
+          "type": "string",
+          "description": "S3-compatible storage key prefix. Mapped into storageOptions.prefix."
+        },
+        "storage_access_key_id": {
+          "type": "string",
+          "description": "S3-compatible storage access key id. Mapped into storageOptions.accessKeyId."
+        },
+        "storage_secret_access_key": {
+          "type": "string",
+          "description": "S3-compatible storage secret access key. Mapped into storageOptions.secretAccessKey."
+        },
+        "storage_allow_http": {
+          "type": ["boolean", "string"],
+          "description": "Allow plain HTTP for S3-compatible storage. Mapped into storageOptions.allowHttp as a string (\"true\"/\"false\")."
+        }
+      }
+    },
+    "secrets_env": {
+      "type": "object",
+      "description": "Environment variable names for secrets. Values are env var names, not actual secrets.",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "properties": {
+        "api_key": {
+          "type": "string",
+          "description": "Environment variable name for API key (e.g., 'MEM0_API_KEY')."
+        },
+        "memory_id": {
+          "type": "string",
+          "description": "Environment variable name for memory ID (e.g., 'MEM0_MEMORY_ID')."
+        },
+        "embedding_api_key": {
+          "type": "string",
+          "description": "Reserved for future LanceDB embedding secrets."
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "backend_type": { "const": "mem0" }
+        }
+      },
+      "then": {
+        "required": ["config"],
+        "properties": {
+          "config": {
+            "required": ["mem0_instance_id"]
+          }
+        }
+      }
+    }
+  ]
+}

ksadk_runtime_common/workspace_files/__init__.py

@@ -0,0 +1,29 @@
+"""Workspace files module shared across bundled runtimes."""
+
+from ksadk_runtime_common.workspace_files.bootstrap import (
+    build_workspace_files_bootstrap,
+    workspace_files_enabled,
+    workspace_files_max_upload_bytes,
+    workspace_files_root_label,
+)
+from ksadk_runtime_common.workspace_files.constants import (
+    DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES,
+    WORKSPACE_CONTENT_PATH,
+    WORKSPACE_ENTRY_ACTION,
+    WORKSPACE_PATH_ESCAPE_DETAIL,
+    WORKSPACE_UPLOAD_ACTION,
+)
+from ksadk_runtime_common.workspace_files.router import create_workspace_files_router
+
+__all__ = [
+    "create_workspace_files_router",
+    "build_workspace_files_bootstrap",
+    "workspace_files_enabled",
+    "workspace_files_root_label",
+    "workspace_files_max_upload_bytes",
+    "DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES",
+    "WORKSPACE_PATH_ESCAPE_DETAIL",
+    "WORKSPACE_ENTRY_ACTION",
+    "WORKSPACE_UPLOAD_ACTION",
+    "WORKSPACE_CONTENT_PATH",
+]

ksadk_runtime_common/workspace_files/bootstrap.py

@@ -0,0 +1,56 @@
+"""Workspace files bootstrap configuration builder."""
+
+from __future__ import annotations
+
+import os
+
+from ksadk_runtime_common.workspace_files.constants import (
+    DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES,
+    WORKSPACE_CONTENT_PATH,
+    WORKSPACE_ENTRY_ACTION,
+    WORKSPACE_UPLOAD_ACTION,
+)
+
+
+def _env_flag(name: str, default: bool) -> bool:
+    """Parse boolean environment variable."""
+    raw = str(os.getenv(name, "")).strip().lower()
+    if not raw:
+        return default
+    return raw in {"1", "true", "yes", "on"}
+
+
+def workspace_files_enabled(*, default: bool = True) -> bool:
+    """Check if workspace files feature is enabled."""
+    return _env_flag("KSADK_WORKSPACE_FILES_ENABLED", default)
+
+
+def workspace_files_root_label() -> str:
+    """Get workspace root label for UI display."""
+    return str(os.getenv("KSADK_WORKSPACE_ROOT_LABEL") or "workspace").strip() or "workspace"
+
+
+def workspace_files_max_upload_bytes() -> int:
+    """Get max upload size in bytes."""
+    raw = str(os.getenv("KSADK_WORKSPACE_MAX_UPLOAD_BYTES") or "").strip()
+    if not raw:
+        return DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES
+    try:
+        return max(int(raw), 1)
+    except ValueError:
+        return DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES
+
+
+def build_workspace_files_bootstrap(*, enabled: bool) -> dict[str, bool | int | str] | None:
+    """Build bootstrap configuration for workspace files."""
+    if not enabled:
+        return None
+    return {
+        "Enabled": True,
+        "MaxUploadBytes": workspace_files_max_upload_bytes(),
+        "SupportsDelete": True,
+        "RootLabel": workspace_files_root_label(),
+        "EntryAction": WORKSPACE_ENTRY_ACTION,
+        "UploadAction": WORKSPACE_UPLOAD_ACTION,
+        "ContentPath": WORKSPACE_CONTENT_PATH,
+    }

ksadk_runtime_common/workspace_files/constants.py

@@ -0,0 +1,9 @@
+"""Workspace files constants - preserves the existing contract exactly."""
+
+DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES = 100 * 1024 * 1024
+
+WORKSPACE_PATH_ESCAPE_DETAIL = "workspace path escapes the workspace root"
+
+WORKSPACE_ENTRY_ACTION = "ListWorkspaceFiles"
+WORKSPACE_UPLOAD_ACTION = "AddWorkspaceFile"
+WORKSPACE_CONTENT_PATH = "/agentengine/api/v1/GetWorkspaceFileContent"

ksadk_runtime_common/workspace_files/path_utils.py

@@ -0,0 +1,71 @@
+"""Workspace files path utilities and security helpers."""
+
+from __future__ import annotations
+
+import os
+import posixpath
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+from fastapi import HTTPException
+
+from ksadk_runtime_common.workspace_files.constants import WORKSPACE_PATH_ESCAPE_DETAIL
+
+_SAFE_WORKSPACE_SEGMENT_RE = re.compile(r"^[^/\x00]+$")
+
+
+def _env_flag(name: str, default: bool) -> bool:
+    """Parse boolean environment variable."""
+    raw = str(os.getenv(name, "")).strip().lower()
+    if not raw:
+        return default
+    return raw in {"1", "true", "yes", "on"}
+
+
+def _normalize_workspace_path(raw_path: str | None, *, allow_root: bool) -> str:
+    """Normalize and validate a workspace path."""
+    raw = str(raw_path or ".").strip().replace("\\", "/")
+    if raw in {"", "."}:
+        if allow_root:
+            return "."
+        raise HTTPException(status_code=400, detail="workspace file path must not be empty")
+    if raw.startswith("/"):
+        raise HTTPException(status_code=400, detail=WORKSPACE_PATH_ESCAPE_DETAIL)
+
+    normalized = posixpath.normpath(raw)
+    if normalized in {"", "."}:
+        if allow_root:
+            return "."
+        raise HTTPException(status_code=400, detail="workspace file path must not be empty")
+    if normalized == ".." or normalized.startswith("../"):
+        raise HTTPException(status_code=400, detail=WORKSPACE_PATH_ESCAPE_DETAIL)
+    return normalized
+
+
+def _resolve_workspace_root(root_getter: Callable[[], Path]) -> Path:
+    """Resolve and create the workspace root directory."""
+    root = Path(root_getter()).expanduser().resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def _resolve_workspace_target(
+    root: Path, raw_path: str | None, *, allow_root: bool
+) -> tuple[str, Path]:
+    """Resolve a path within the workspace root with an escape check."""
+    normalized = _normalize_workspace_path(raw_path, allow_root=allow_root)
+    if normalized == ".":
+        target = root
+    else:
+        segments = tuple(part for part in normalized.split("/") if part)
+        if not segments or any(
+            part in {".", ".."} or not _SAFE_WORKSPACE_SEGMENT_RE.fullmatch(part)
+            for part in segments
+        ):
+            raise HTTPException(status_code=400, detail=WORKSPACE_PATH_ESCAPE_DETAIL)
+        target = root.joinpath(*segments)
+    resolved_target = target.resolve(strict=False)
+    if resolved_target != root and root not in resolved_target.parents:
+        raise HTTPException(status_code=400, detail=WORKSPACE_PATH_ESCAPE_DETAIL)
+    return normalized, resolved_target

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