DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
feat(plugins): add reviewed managed lifecycle and revocable runtime gates (#1307)
Bingxi Zhao (Frank)7885daa98aec
diff --git a/deeptutor/api/main.py b/deeptutor/api/main.pyindex d4a72a29c..26dc3e27e 100644--- a/deeptutor/api/main.py+++ b/deeptutor/api/main.py@@ -546,6 +546,7 @@ from deeptutor.api.routers import (partner_groups,partners,personas,+ plugins,practice,question,question_notebook,@@ -735,6 +736,7 @@ app.include_router(subagents.router, prefix="/api/subagents", tags=["subagents"], dependencies=_auth)app.include_router(personas.router, prefix="/api", tags=["personas"], dependencies=_auth)+app.include_router(plugins.router, prefix="/api/plugins", tags=["plugins"])app.include_router(tools_router.router, prefix="/api/tools", tags=["tools"], dependencies=_auth)app.include_router(system.router, prefix="/api/system", tags=["system"], dependencies=_auth)app.include_router(voice.router, prefix="/api/voice", tags=["voice"], dependencies=_auth)diff --git a/deeptutor/api/routers/auth.py b/deeptutor/api/routers/auth.pyindex 01d4699cd..0b63eff22 100644--- a/deeptutor/api/routers/auth.py+++ b/deeptutor/api/routers/auth.py@@ -97,6 +97,7 @@ logger = logging.getLogger(__name__)router = APIRouter()_COOKIE_NAME = "dt_token"+AUTH_COOKIE_NAME = _COOKIE_NAME_COOKIE_MAX_AGE = TOKEN_EXPIRE_HOURS * 3600_USER_IMPORT_MAX_BYTES = 2 * 1024 * 1024_USER_IMPORT_MAX_ROWS = 500@@ -608,6 +609,8 @@ _LEARNER_KB_READ_ROUTES = frozenset("/api/knowledge-bases/{kb_name}/files/{filename:path}","/api/knowledge-bases/{kb_name}/file-preview-text/{filename:path}","/api/knowledge-bases/{kb_name}/visual-assets/{asset_id}",+ "/api/knowledge-bases/{kb_name}/indexing-run",+ "/api/knowledge-bases/{kb_name}/indexing-readiness","/api/knowledge-bases/{kb_name}/progress",})diff --git a/deeptutor/api/routers/plugins.py b/deeptutor/api/routers/plugins.pynew file mode 100644index 000000000..7fef1fc6f--- /dev/null+++ b/deeptutor/api/routers/plugins.py@@ -0,0 +1,416 @@+"""Authenticated introspection and managed plugin HTTP route dispatch."""++from __future__ import annotations++import asyncio+import json+import logging+from pathlib import Path+from typing import Any++from fastapi import APIRouter, Depends, HTTPException, Request+from fastapi.responses import FileResponse, JSONResponse, RedirectResponse, Response+from pydantic import BaseModel, Field++from deeptutor.api.routers.auth import AUTH_COOKIE_NAME, require_admin, require_auth+from deeptutor.plugins.catalog import load_catalog+from deeptutor.plugins.distribution import CatalogInstallManager, PluginDistributionError+from deeptutor.plugins.frontend import (+ FrontendPageError,+ load_frontend_page_manifest,+ resolve_frontend_page_asset,+)+from deeptutor.plugins.lifecycle import PluginLifecycleError, PluginLifecycleManager+from deeptutor.plugins.manifest import PluginExtension+from deeptutor.plugins.registry import (+ PluginInstallation,+ PluginRecord,+ PluginRegistry,+ PluginStateError,+)+from deeptutor.plugins.runtime import (+ PluginHttpResponse,+ PluginRuntimeError,+ PluginWorkerHttpRoute,+)++logger = logging.getLogger(__name__)+router = APIRouter()+_registry_factory = PluginRegistry+_MAX_JSON_BODY_BYTES = 1024 * 1024+_FRONTEND_CSP = (+ "default-src 'none'; "+ "script-src 'self'; "+ "style-src 'self' 'unsafe-inline'; "+ "img-src 'self' data: blob:; "+ "font-src 'self' data:; "+ "media-src 'self' data: blob:; "+ "connect-src 'none'; frame-src 'none'; object-src 'none'; "+ "base-uri 'none'; form-action 'none'; frame-ancestors 'self'; "+ "sandbox allow-scripts"+)+++async def _require_authenticated(request: Request):+ return await require_auth(+ authorization=request.headers.get("Authorization"),+ dt_token=request.cookies.get(AUTH_COOKIE_NAME),+ request=request,+ )+++async def _require_admin(request: Request):+ return await require_admin(+ payload=await _require_authenticated(request),+ )+++def _managed_records(registry: PluginRegistry) -> list[PluginRecord]:+ return [+ record+ for record in registry.list_plugins(include_catalog=False)+ if record.status == "enabled"+ and record.distribution == "managed"+ and record.manifest is not None+ and record.installation is not None+ ]+++def _extensions_payload(records: list[PluginRecord]) -> list[dict[str, Any]]:+ result: list[dict[str, Any]] = []+ for record in records:+ if record.manifest is None:+ continue+ extensions: list[dict[str, Any]] = []+ for extension in record.manifest.extensions:+ payload = extension.to_dict()+ if extension.type == "frontend_page" and extension.manifest:+ payload["entry_url"] = f"/api/plugins/{record.id}/pages/{extension.id}/"+ extensions.append(payload)+ result.append(+ {+ "id": record.id,+ "name": record.name,+ "version": record.version,+ "extensions": extensions,+ }+ )+ return result+++def _find_route(+ *,+ plugin_id: str,+ plugin_path: str,+) -> tuple[PluginRecord, PluginExtension, PluginInstallation] | None:+ normalized_path = _normalize_plugin_path(plugin_path)+ if normalized_path is None:+ return None+ for record in _managed_records(_registry_factory()):+ if record.id != plugin_id or record.manifest is None or record.installation is None:+ continue+ for extension in record.manifest.extensions:+ if extension.type == "http_route" and extension.path == normalized_path:+ return record, extension, record.installation+ return None+++def _find_frontend_page(+ *,+ plugin_id: str,+ extension_id: str,+) -> tuple[PluginRecord, PluginExtension, PluginInstallation, Path] | None:+ for record in _managed_records(_registry_factory()):+ if record.id != plugin_id or record.manifest is None or record.installation is None:+ continue+ if record.installation.package_path is None:+ continue+ for extension in record.manifest.extensions:+ if extension.type == "frontend_page" and extension.id == extension_id:+ return record, extension, record.installation, record.installation.package_path+ return None+++def _normalize_plugin_path(value: str) -> str | None:+ if not value or "\x00" in value or "%" in value or "\\" in value:+ return None+ return "/" + value.strip("/")+++async def _authenticate_plugin_route(request: Request) -> None:+ payload = await _require_authenticated(request)+ matched = _find_route(+ plugin_id=request.path_params["plugin_id"],+ plugin_path=request.path_params["plugin_path"],+ )+ if matched is None:+ return+ request.state.plugin_route = matched+ policy = matched[1].auth+ if policy == "admin":+ await require_admin(payload=payload)+++async def _authenticate_plugin_page(request: Request) -> None:+ payload = await _require_authenticated(request)+ matched = _find_frontend_page(+ plugin_id=request.path_params["plugin_id"],+ extension_id=request.path_params["extension_id"],+ )+ if matched is None:+ return+ request.state.plugin_page = matched+ policy = matched[1].auth+ if policy == "admin":+ await require_admin(payload=payload)++[email protected]("/extensions", dependencies=[Depends(_require_authenticated)])+def list_extensions() -> dict[str, Any]:+ return {"plugins": _extensions_payload(_managed_records(_registry_factory()))}+++ "/{plugin_id}/pages/{extension_id}",+ dependencies=[Depends(_authenticate_plugin_page)],+)+def redirect_plugin_frontend_page(request: Request) -> RedirectResponse:+ matched = getattr(request.state, "plugin_page", None)+ if matched is None:+ raise HTTPException(status_code=404, detail="Plugin page not found")+ return RedirectResponse(url=f"{request.url.path}/", status_code=307)+++ "/{plugin_id}/pages/{extension_id}/",+ dependencies=[Depends(_authenticate_plugin_page)],+)+def get_plugin_frontend_page(request: Request) -> FileResponse:+ matched = getattr(request.state, "plugin_page", None)+ if matched is None:+ raise HTTPException(status_code=404, detail="Plugin page not found")+ _, extension, _, package_path = matched+ if not extension.manifest:+ raise HTTPException(status_code=404, detail="Plugin page not found")+ try:+ page = load_frontend_page_manifest(package_path / extension.manifest)+ path = resolve_frontend_page_asset(page, package_path, page.entry)+ except FrontendPageError as exc:+ logger.warning(+ "Managed frontend page %s/%s failed validation",+ matched[0].id,+ extension.id,+ exc_info=exc,+ )+ raise HTTPException(status_code=404, detail="Plugin page not found") from exc+ return _frontend_file_response(path)+++ "/{plugin_id}/pages/{extension_id}/assets/{asset_path:path}",+ dependencies=[Depends(_authenticate_plugin_page)],+)+def get_plugin_frontend_asset(request: Request) -> FileResponse:+ matched = getattr(request.state, "plugin_page", None)+ if matched is None:+ raise HTTPException(status_code=404, detail="Plugin page not found")+ _, extension, _, package_path = matched+ if not extension.manifest:+ raise HTTPException(status_code=404, detail="Plugin page not found")+ requested = request.path_params["asset_path"]+ try:+ page = load_frontend_page_manifest(package_path / extension.manifest)+ path = resolve_frontend_page_asset(page, package_path, requested)+ except FrontendPageError as exc:+ logger.warning(+ "Managed frontend asset %s/%s failed validation",+ matched[0].id,+ extension.id,+ exc_info=exc,+ )+ raise HTTPException(status_code=404, detail="Plugin page not found") from exc+ return _frontend_file_response(path, asset=True)+++async def dispatch_plugin_route(request: Request) -> Response:+ matched = getattr(request.state, "plugin_route", None)+ if matched is None:+ raise HTTPException(status_code=404, detail="Plugin route not found")+ record, extension, installation = matched+ if request.method not in extension.methods:+ raise HTTPException(+ status_code=405,+ detail="Method not allowed",+ headers={"Allow": ", ".join(extension.methods)},+ )++ chunks = []+ size = 0+ async for chunk in request.stream():+ size += len(chunk)+ if size > _MAX_JSON_BODY_BYTES:+ raise HTTPException(status_code=413, detail="Plugin request body is too large")+ chunks.append(chunk)+ raw_body = b"".join(chunks)+ body = None+ if raw_body:+ try:+ body = json.loads(raw_body)+ except ValueError as exc:+ raise HTTPException(status_code=400, detail="Request body must be JSON") from exc++ query: dict[str, tuple[str, ...]] = {+ name: tuple(request.query_params.getlist(name)) for name in request.query_params.keys()+ }+ worker = PluginWorkerHttpRoute(+ manifest=record.manifest,+ installation=installation,+ extension_id=extension.id,+ registry=_registry_factory(),+ )+ try:+ result = await asyncio.to_thread(+ worker.handle,+ method=request.method,+ path=extension.path,+ query=query,+ body=body,+ )+ except PluginRuntimeError as exc:+ logger.warning(+ "Managed HTTP route %s/%s failed its worker contract",+ record.id,+ extension.id,+ exc_info=exc,+ )+ raise HTTPException(status_code=500, detail="Plugin route failed") from exc+ return _http_response(result)+++class ApprovalRequest(BaseModel):+ snapshot_digest: str = Field(pattern="^[0-9a-f]{64}$")+++class InstallRequest(BaseModel):+ version: str = Field(default="latest", max_length=64)+ allow_deprecated: bool = False++[email protected]("/catalog", dependencies=[Depends(_require_authenticated)])+def plugin_catalog():+ return {"entries": [entry.to_dict() for entry in load_catalog()]}++[email protected]("/state", dependencies=[Depends(_require_authenticated)])+def plugin_state():+ return {"plugins": [record.to_dict() for record in _registry_factory().list_plugins()]}++[email protected]("/{plugin_id}/info", dependencies=[Depends(_require_authenticated)])+def plugin_info(plugin_id: str):+ record = _registry_factory().get_plugin(plugin_id)+ if record is None:+ raise HTTPException(404, "Plugin not found")+ return record.to_dict()++[email protected]("/{plugin_id}/approve", dependencies=[Depends(_require_admin)])+def approve_plugin(plugin_id: str, payload: ApprovalRequest):+ try:+ return (+ _registry_factory()+ .approve(plugin_id, expected_digest=payload.snapshot_digest)+ .to_dict()+ )+ except PluginStateError as exc:+ raise HTTPException(409, str(exc)) from exc++[email protected]("/{plugin_id}/enable", dependencies=[Depends(_require_admin)])+def enable_plugin(plugin_id: str):+ try:+ return _registry_factory().set_enabled(plugin_id, True).to_dict()+ except PluginStateError as exc:+ raise HTTPException(409, str(exc)) from exc++[email protected]("/{plugin_id}/disable", dependencies=[Depends(_require_admin)])+def disable_plugin(plugin_id: str):+ try:+ return _registry_factory().set_enabled(plugin_id, False).to_dict()+ except PluginStateError as exc:+ raise HTTPException(409, str(exc)) from exc++[email protected]("/{plugin_id}/install", dependencies=[Depends(_require_admin)])+def install_plugin(plugin_id: str, payload: InstallRequest):+ try:+ result = CatalogInstallManager(+ lifecycle_factory=lambda: PluginLifecycleManager(registry=_registry_factory())+ ).install(plugin_id, version=payload.version, allow_deprecated=payload.allow_deprecated)+ return {+ "id": result.lifecycle.plugin_id,+ "version": result.lifecycle.version,+ "action": result.lifecycle.action,+ "approval_required": True,+ }+ except (PluginStateError, PluginLifecycleError, PluginDistributionError) as exc:+ raise HTTPException(409, str(exc)) from exc++[email protected]("/{plugin_id}/rollback", dependencies=[Depends(_require_admin)])+def rollback_plugin(plugin_id: str):+ try:+ result = PluginLifecycleManager(registry=_registry_factory()).rollback(plugin_id)+ return {"id": result.plugin_id, "version": result.version, "approval_required": True}+ except (PluginStateError, PluginLifecycleError) as exc:+ raise HTTPException(409, str(exc)) from exc++[email protected]("/{plugin_id}/installation", dependencies=[Depends(_require_admin)])+def uninstall_plugin(plugin_id: str):+ try:+ result = PluginLifecycleManager(registry=_registry_factory()).uninstall(plugin_id)+ return {"id": result.plugin_id, "action": result.action}+ except (PluginStateError, PluginLifecycleError) as exc:+ raise HTTPException(409, str(exc)) from exc+++for _method in ("GET", "POST", "PUT", "PATCH", "DELETE"):+ router.add_api_route(+ "/{plugin_id}/{plugin_path:path}",+ dispatch_plugin_route,+ methods=[_method],+ operation_id=f"dispatch_plugin_route_{_method.lower()}",+ dependencies=[Depends(_authenticate_plugin_route)],+ )+++def _http_response(result: PluginHttpResponse) -> Response:+ if result.status == 204:+ return Response(status_code=204, headers=dict(result.headers or {}))+ return JSONResponse(+ status_code=result.status,+ content=result.body,+ headers=dict(result.headers or {}),+ )+++def _frontend_file_response(path: Path, *, asset: bool = False) -> FileResponse:+ media_type = "text/html; charset=utf-8" if path.suffix.lower() == ".html" else None+ return FileResponse(+ path,+ media_type=media_type,+ headers={+ "Cache-Control": "no-store",+ "Vary": "Authorization, Cookie",+ "Content-Security-Policy": _FRONTEND_CSP,+ "Cross-Origin-Resource-Policy": "cross-origin" if asset else "same-origin",+ "Permissions-Policy": "camera=(), microphone=(), geolocation=()",+ "Referrer-Policy": "no-referrer",+ "X-Content-Type-Options": "nosniff",+ },+ )+++__all__ = ["router"]diff --git a/deeptutor/capabilities/registry.py b/deeptutor/capabilities/registry.pyindex 3c46e88c7..f7116102f 100644--- a/deeptutor/capabilities/registry.py+++ b/deeptutor/capabilities/registry.py@@ -128,7 +128,7 @@ def _coerce_loop_factory(loaded: object) -> tuple[LoopExtension, LoopFactory] |instance = produced()else:instance = produced- factory = type(produced)+ factory = objelse:instance = objfactory = type(obj)@@ -146,7 +146,7 @@ def _coerce_loop_factory(loaded: object) -> tuple[LoopExtension, LoopFactory] |@cache-def discover_external_loop_capabilities() -> tuple[tuple[str, LoopFactory], ...]:+def _discover_external_loop_capabilities() -> tuple[tuple[str, LoopFactory], ...]:"""Discover factory specs from canonical and one-version legacy groups."""seen = {spec.name for spec in BUILTIN_LOOP_CAPABILITY_SPECS}@@ -177,6 +177,17 @@ def discover_external_loop_capabilities() -> tuple[tuple[str, LoopFactory], ...]return tuple([*canonical, *legacy])+def discover_external_loop_capabilities():+ return tuple(+ item+ for item in _discover_external_loop_capabilities()+ if getattr(item[1], "_plugin_allowed", lambda: True)()+ )+++discover_external_loop_capabilities.cache_clear = _discover_external_loop_capabilities.cache_clear++def _register_loop_entry(name: str, factory: LoopFactory) -> None:preview = factory()get_capability_catalog().register(diff --git a/deeptutor/core/entry_points.py b/deeptutor/core/entry_points.pyindex 81ef83ebc..659789370 100644--- a/deeptutor/core/entry_points.py+++ b/deeptutor/core/entry_points.py@@ -48,7 +48,15 @@ def load_entry_point_group(for ep in discovered:name = getattr(ep, "name", str(ep))try:- value = coerce(name, ep.load())+ from deeptutor.plugins.runtime import entry_point_can_load, guard_entry_point_loaded++ if not entry_point_can_load(ep, group):+ emit.warning(+ "Plugin entry point %r is disabled, incompatible or unapproved; skipping import.",+ name,+ )+ continue+ value = coerce(name, guard_entry_point_loaded(ep, group, ep.load()))except Exception:emit.warning("Failed to load %s entry point %r; skipping.", group, name, exc_info=True)continuediff --git a/deeptutor/plugins/catalog.json b/deeptutor/plugins/catalog.jsonnew file mode 100644index 000000000..ca992b02b--- /dev/null+++ b/deeptutor/plugins/catalog.json@@ -0,0 +1,9 @@+{+ "schema_version": "deeptutor.plugin-catalog/v2",+ "meta": {+ "generated_at": "2026-08-31T00:00:00Z",+ "reviewed_at": "2026-08-31T00:00:00Z",+ "reviewers": ["DeepTutor maintainers"]+ },+ "entries": []+}diff --git a/deeptutor/plugins/catalog.py b/deeptutor/plugins/catalog.pynew file mode 100644index 000000000..c8e42e994--- /dev/null+++ b/deeptutor/plugins/catalog.py@@ -0,0 +1,387 @@+"""Read and search DeepTutor's vendored official plugin catalog.++The catalog is an index, not an installer and not a live registry client. It is+reviewed and pinned in the DeepTutor release, so browsing never depends on a+third-party service being online.+"""++from __future__ import annotations++from dataclasses import dataclass+from functools import lru_cache+import json+import logging+from pathlib import Path+import re+from typing import Any, Mapping+from urllib.parse import urlsplit++from packaging.requirements import InvalidRequirement, Requirement+from packaging.version import Version++from deeptutor.plugins.manifest import (+ ManifestValidationError,+ PluginCompatibility,+ PluginPermissions,+ is_sha256,+ parse_manifest,+)++logger = logging.getLogger(__name__)++CATALOG_SCHEMA_VERSION = "deeptutor.plugin-catalog/v2"+SUPPORTED_CATALOG_SCHEMA_VERSIONS = frozenset(+ {"deeptutor.plugin-catalog/v1", CATALOG_SCHEMA_VERSION}+)+CATALOG_PATH = Path(__file__).with_name("catalog.json")+CATALOG_STATUSES = frozenset({"available", "deprecated", "hidden"})+MAX_CATALOG_ARTIFACT_BYTES = 256 * 1024 * 1024+PLATFORM_TAG = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")+++class CatalogValidationError(ValueError):+ """Raised when a catalog row cannot be modeled."""+++class CatalogResolutionError(ValueError):+ """Raised when a reviewed catalog version cannot be selected."""+++@dataclass(frozen=True, slots=True)+class CatalogArtifact:+ kind: str+ requirement: str+ sha256: str+ url: str = ""+ size_bytes: int = 0+ platform_tags: tuple[str, ...] = ()+++@dataclass(frozen=True, slots=True)+class CatalogEntry:+ id: str+ name: str+ version: str+ description_i18n: Mapping[str, str]+ author: str+ license: str+ homepage: str+ source_url: str+ compatibility: PluginCompatibility+ permissions: PluginPermissions+ dependencies: tuple[str, ...]+ artifact: CatalogArtifact+ status: str++ def to_dict(self) -> dict[str, Any]:+ return {+ "id": self.id,+ "name": self.name,+ "version": self.version,+ "description_i18n": dict(self.description_i18n),+ "author": self.author,+ "license": self.license,+ "homepage": self.homepage,+ "source_url": self.source_url,+ "compatibility": self.compatibility.to_dict(),+ "permissions": self.permissions.to_dict(),+ "dependencies": list(self.dependencies),+ "artifact": {+ "kind": self.artifact.kind,+ "requirement": self.artifact.requirement,+ "sha256": self.artifact.sha256,+ **(+ {+ "url": self.artifact.url,+ "size_bytes": self.artifact.size_bytes,+ "platform_tags": list(self.artifact.platform_tags),+ }+ if self.artifact.url+ else {}+ ),+ },+ "status": self.status,+ }+++@lru_cache(maxsize=8)+def load_catalog(path: Path = CATALOG_PATH) -> tuple[CatalogEntry, ...]:+ """Return every valid non-hidden catalog row in deterministic ID order."""+ try:+ payload = json.loads(Path(path).read_text(encoding="utf-8"))+ except (OSError, json.JSONDecodeError):+ logger.exception("Plugin catalog is unreadable at %s", path)+ return ()++ try:+ schema_version = _validate_root(payload)+ except CatalogValidationError as exc:+ logger.error("Ignoring plugin catalog at %s: %s", path, exc)+ return ()++ entries: list[CatalogEntry] = []+ seen: set[str | tuple[str, str]] = set()+ for row in payload["entries"]:+ try:+ entry = parse_catalog_entry(row, schema_version=schema_version)+ except (CatalogValidationError, ManifestValidationError) as exc:+ row_id = row.get("id") if isinstance(row, Mapping) else "?"+ logger.warning("Skipping invalid plugin catalog entry %r: %s", row_id, exc)+ continue+ identity = entry.id if schema_version.endswith("/v1") else (entry.id, entry.version)+ if identity in seen:+ logger.warning("Skipping duplicate plugin catalog entry %r", identity)+ continue+ seen.add(identity)+ if entry.status != "hidden":+ entries.append(entry)+ return tuple(sorted(entries, key=lambda entry: (entry.id, Version(entry.version))))+++def reset_catalog_cache() -> None:+ load_catalog.cache_clear()+++def search_catalog(query: str = "", *, path: Path = CATALOG_PATH) -> tuple[CatalogEntry, ...]:+ needle = query.strip().casefold()+ if not needle:+ return load_catalog(path)+ matches = []+ for entry in load_catalog(path):+ haystack = " ".join(+ (+ entry.id,+ entry.name,+ entry.version,+ entry.author,+ *entry.description_i18n.values(),+ )+ ).casefold()+ if needle in haystack:+ matches.append(entry)+ return tuple(matches)+++def get_catalog_entry(entry_id: str, *, path: Path = CATALOG_PATH) -> CatalogEntry | None:+ try:+ return resolve_catalog_entry(+ entry_id,+ allow_deprecated=True,+ allow_prerelease=True,+ path=path,+ )+ except CatalogResolutionError:+ return None+++def resolve_catalog_entry(+ plugin_id: str,+ version: str = "latest",+ *,+ allow_deprecated: bool = False,+ allow_prerelease: bool = False,+ path: Path = CATALOG_PATH,+) -> CatalogEntry:+ """Resolve one browsable catalog row without consulting remote state."""+ candidates = [entry for entry in load_catalog(path) if entry.id == plugin_id]+ if not candidates:+ raise CatalogResolutionError(f"plugin {plugin_id!r} is not in the reviewed catalog")++ if version != "latest":+ matches = [entry for entry in candidates if entry.version == version]+ if len(matches) != 1:+ raise CatalogResolutionError(+ f"plugin {plugin_id!r} version {version!r} is not available"+ )+ entry = matches[0]+ if entry.status == "deprecated" and not allow_deprecated:+ raise CatalogResolutionError(+ f"plugin {plugin_id!r} version {version!r} is deprecated; use --allow-deprecated"+ )+ return entry++ eligible = [+ entry+ for entry in candidates+ if entry.status == "available" or (allow_deprecated and entry.status == "deprecated")+ ]+ stable = [+ entry for entry in eligible if allow_prerelease or not Version(entry.version).is_prerelease+ ]+ if not stable:+ raise CatalogResolutionError(+ f"plugin {plugin_id!r} has no available stable catalog version"+ )+ return max(stable, key=lambda entry: Version(entry.version))+++def parse_catalog_entry(raw: Any, *, schema_version: str = CATALOG_SCHEMA_VERSION) -> CatalogEntry:+ if not isinstance(raw, Mapping):+ raise CatalogValidationError("catalog entry must be an object")+ if schema_version not in SUPPORTED_CATALOG_SCHEMA_VERSIONS:+ raise CatalogValidationError("unsupported catalog schema_version")++ # Reuse identity and typed declaration validation while allowing catalog-only+ # packaging fields on top of the package manifest shape.+ manifest_fields = {+ "id",+ "name",+ "version",+ "description_i18n",+ "author",+ "license",+ "homepage",+ "source_url",+ "compatibility",+ "permissions",+ "dependencies",+ "status",+ "artifact",+ }+ unknown = set(raw) - manifest_fields+ if unknown:+ raise CatalogValidationError(f"unknown fields: {', '.join(sorted(unknown))}")+ manifest_view = {key: value for key, value in raw.items() if key not in {"status", "artifact"}}+ manifest_view["schema_version"] = "deeptutor.plugin/v1"+ manifest_view["extensions"] = []+ manifest = parse_manifest(manifest_view)++ status = raw.get("status", "available")+ if status not in CATALOG_STATUSES:+ raise CatalogValidationError(f"invalid status {status!r}")+ artifact_raw = raw.get("artifact")+ if not isinstance(artifact_raw, Mapping):+ raise CatalogValidationError("artifact must be an object")+ artifact_fields = {"kind", "requirement", "sha256"}+ if schema_version == CATALOG_SCHEMA_VERSION:+ artifact_fields.update({"url", "size_bytes", "platform_tags"})+ _reject_unknown(artifact_raw, artifact_fields)+ kind = artifact_raw.get("kind")+ requirement = artifact_raw.get("requirement")+ sha256 = artifact_raw.get("sha256")+ if kind != "python-package":+ raise CatalogValidationError("artifact.kind must be python-package")+ if not isinstance(requirement, str) or not requirement.strip():+ raise CatalogValidationError("artifact.requirement is required")+ try:+ parsed_requirement = Requirement(requirement)+ except InvalidRequirement as exc:+ raise CatalogValidationError("artifact.requirement is invalid") from exc+ _require_pinned_requirement(parsed_requirement, manifest.version)+ if not isinstance(sha256, str) or not is_sha256(sha256):+ raise CatalogValidationError("artifact.sha256 must be a lowercase SHA-256")+ url = artifact_raw.get("url", "")+ size_bytes = artifact_raw.get("size_bytes", 0)+ platform_tags_raw = artifact_raw.get("platform_tags", [])+ if schema_version == CATALOG_SCHEMA_VERSION:+ _validate_download_artifact(url, size_bytes, platform_tags_raw)+ url = str(url)+ size_bytes = int(size_bytes)+ platform_tags = tuple(platform_tags_raw)+ else:+ platform_tags = ()++ return CatalogEntry(+ id=manifest.id,+ name=manifest.name,+ version=str(manifest.version),+ description_i18n=manifest.description_i18n,+ author=manifest.author,+ license=manifest.license,+ homepage=manifest.homepage,+ source_url=manifest.source_url,+ compatibility=manifest.compatibility,+ permissions=manifest.permissions,+ dependencies=manifest.dependencies,+ artifact=CatalogArtifact(+ kind=str(kind),+ requirement=requirement.strip(),+ sha256=sha256,+ url=url,+ size_bytes=size_bytes,+ platform_tags=platform_tags,+ ),+ status=str(status),+ )+++def _validate_root(payload: Any) -> str:+ if not isinstance(payload, Mapping):+ raise CatalogValidationError("catalog must be an object")+ _reject_unknown(payload, {"schema_version", "meta", "entries"})+ schema_version = payload.get("schema_version")+ if not isinstance(schema_version, str):+ raise CatalogValidationError("catalog schema_version must be a string")+ if schema_version not in SUPPORTED_CATALOG_SCHEMA_VERSIONS:+ raise CatalogValidationError("unsupported catalog schema_version")+ meta = payload.get("meta")+ if not isinstance(meta, Mapping):+ raise CatalogValidationError("catalog meta must be an object")+ _reject_unknown(meta, {"generated_at", "reviewed_at", "reviewers"})+ if not isinstance(meta.get("generated_at"), str) or not meta["generated_at"].strip():+ raise CatalogValidationError("catalog meta.generated_at is required")+ if not isinstance(meta.get("reviewed_at"), str) or not meta["reviewed_at"].strip():+ raise CatalogValidationError("catalog meta.reviewed_at is required")+ reviewers = meta.get("reviewers")+ if not isinstance(reviewers, list) or not reviewers:+ raise CatalogValidationError("catalog meta.reviewers must be a non-empty array")+ if not all(isinstance(reviewer, str) and reviewer.strip() for reviewer in reviewers):+ raise CatalogValidationError("catalog reviewers must be non-empty strings")+ if not isinstance(payload.get("entries"), list):+ raise CatalogValidationError("catalog entries must be an array")+ return str(schema_version)+++def _validate_download_artifact(url: Any, size_bytes: Any, platform_tags: Any) -> None:+ if not isinstance(url, str) or not url.strip():+ raise CatalogValidationError("artifact.url is required")+ parsed = urlsplit(url)+ if parsed.scheme != "https" or not parsed.hostname:+ raise CatalogValidationError("artifact.url must be an HTTPS URL")+ if parsed.username or parsed.password or parsed.query or parsed.fragment:+ raise CatalogValidationError("artifact.url must be a direct immutable path")+ if not parsed.path.lower().endswith(".whl"):+ raise CatalogValidationError("artifact.url must point to a wheel")+ if (+ isinstance(size_bytes, bool)+ or not isinstance(size_bytes, int)+ or not (0 < size_bytes <= MAX_CATALOG_ARTIFACT_BYTES)+ ):+ raise CatalogValidationError("artifact.size_bytes is outside the supported range")+ if not isinstance(platform_tags, list) or not platform_tags:+ raise CatalogValidationError("artifact.platform_tags must be a non-empty array")+ if any(not isinstance(tag, str) or not PLATFORM_TAG.fullmatch(tag) for tag in platform_tags):+ raise CatalogValidationError("artifact.platform_tags contain an invalid tag")+ if len(set(platform_tags)) != len(platform_tags):+ raise CatalogValidationError("artifact.platform_tags must be unique")+++def _reject_unknown(raw: Mapping[str, Any], allowed: set[str]) -> None:+ unknown = set(raw) - allowed+ if unknown:+ raise CatalogValidationError(f"unknown fields: {', '.join(sorted(unknown))}")+++def _require_pinned_requirement(requirement: Requirement, expected_version: Version) -> None:+ if requirement.url or requirement.marker or requirement.extras:+ raise CatalogValidationError("artifact.requirement must be a direct pinned package name")+ specifiers = list(requirement.specifier)+ if len(specifiers) != 1 or specifiers[0].operator != "==":+ raise CatalogValidationError("artifact.requirement must use exactly one == pin")+ if Version(str(specifiers[0].version)) != expected_version:+ raise CatalogValidationError("artifact.requirement and entry version must match")+++__all__ = [+ "CATALOG_PATH",+ "CATALOG_SCHEMA_VERSION",+ "CatalogArtifact",+ "CatalogEntry",+ "CatalogValidationError",+ "CatalogResolutionError",+ "get_catalog_entry",+ "load_catalog",+ "parse_catalog_entry",+ "reset_catalog_cache",+ "search_catalog",+]diff --git a/deeptutor/plugins/distribution.py b/deeptutor/plugins/distribution.pynew file mode 100644index 000000000..c9c2cc6fc--- /dev/null+++ b/deeptutor/plugins/distribution.py@@ -0,0 +1,209 @@+"""Download and install reviewed catalog artifact pins."""++from __future__ import annotations++from dataclasses import dataclass+import hashlib+from pathlib import Path+import tempfile+from typing import Callable, Protocol+from urllib.parse import unquote, urlsplit++import httpx+from packaging.utils import parse_wheel_filename++from deeptutor.plugins.catalog import (+ CatalogArtifact,+ CatalogResolutionError,+ resolve_catalog_entry,+)+from deeptutor.plugins.lifecycle import (+ LifecycleResult,+ PluginLifecycleManager,+ _manifest_from_wheel,+)++DEFAULT_DOWNLOAD_TIMEOUT_SECONDS = 60.0+++class PluginDistributionError(ValueError):+ """Raised when a reviewed artifact cannot be downloaded safely."""+++@dataclass(frozen=True, slots=True)+class CatalogDownloadResult:+ path: Path+ url: str+ size_bytes: int+ sha256: str+++@dataclass(frozen=True, slots=True)+class CatalogInstallResult:+ lifecycle: LifecycleResult+ artifact_url: str+++class _DownloadClient(Protocol):+ def __enter__(self) -> _DownloadClient: ...++ def __exit__(self, *args: object) -> None: ...++ def stream(self, method: str, url: str) -> httpx.Response: ...+++class CatalogArtifactDownloader:+ """Stream a catalog-pinned wheel into a temporary local file."""++ def __init__(+ self,+ *,+ client_factory: Callable[[float], _DownloadClient] | None = None,+ ) -> None:+ self._client_factory = client_factory or _default_client++ def download(+ self,+ artifact: CatalogArtifact,+ *,+ destination_dir: Path,+ timeout_seconds: float = DEFAULT_DOWNLOAD_TIMEOUT_SECONDS,+ ) -> CatalogDownloadResult:+ if timeout_seconds <= 0:+ raise PluginDistributionError("artifact download timeout must be positive")+ if not artifact.url:+ raise PluginDistributionError("catalog artifact has no download URL")+ destination_dir.mkdir(parents=True, exist_ok=True)+ wheel_name = unquote(Path(urlsplit(artifact.url).path).name)+ try:+ parse_wheel_filename(wheel_name)+ except ValueError as exc:+ raise PluginDistributionError(+ "Catalog artifact has an invalid wheel filename."+ ) from exc+ folder = Path(tempfile.mkdtemp(prefix="deeptutor-plugin-", dir=destination_dir))+ destination = folder / wheel_name+ digest = hashlib.sha256()+ size = 0+ try:+ with self._client_factory(timeout_seconds) as client:+ with client.stream("GET", artifact.url) as response:+ if 300 <= response.status_code < 400:+ raise PluginDistributionError("catalog artifact redirects are not allowed")+ if response.status_code != 200:+ raise PluginDistributionError(+ f"catalog artifact download exited {response.status_code}"+ )+ content_length = response.headers.get("content-length")+ if content_length is not None:+ try:+ declared_size = int(content_length)+ except ValueError as exc:+ raise PluginDistributionError(+ "catalog artifact has an invalid Content-Length"+ ) from exc+ if declared_size != artifact.size_bytes:+ raise PluginDistributionError(+ "catalog artifact Content-Length does not match reviewed size"+ )+ with destination.open("wb") as handle:+ for chunk in response.iter_bytes():+ size += len(chunk)+ if size > artifact.size_bytes:+ raise PluginDistributionError(+ "catalog artifact exceeds reviewed size"+ )+ digest.update(chunk)+ handle.write(chunk)+ if size != artifact.size_bytes:+ raise PluginDistributionError("catalog artifact is smaller than reviewed size")+ if digest.hexdigest() != artifact.sha256:+ raise PluginDistributionError(+ "catalog artifact SHA-256 does not match reviewed pin"+ )+ except (+ OSError,+ httpx.HTTPError,+ PluginDistributionError,+ ) as exc:+ destination.unlink(missing_ok=True)+ folder.rmdir()+ if isinstance(exc, PluginDistributionError):+ raise+ raise PluginDistributionError(f"catalog artifact download failed: {exc}") from exc+ return CatalogDownloadResult(+ path=destination,+ url=artifact.url,+ size_bytes=size,+ sha256=digest.hexdigest(),+ )+++class CatalogInstallManager:+ """Resolve a reviewed row, download its exact wheel, then run local lifecycle."""++ def __init__(+ self,+ *,+ downloader_factory: Callable[[], CatalogArtifactDownloader] | None = None,+ lifecycle_factory: Callable[[], PluginLifecycleManager] | None = None,+ ) -> None:+ self._downloader_factory = downloader_factory or CatalogArtifactDownloader+ self._lifecycle_factory = lifecycle_factory or PluginLifecycleManager++ def install(+ self,+ plugin_id: str,+ *,+ version: str = "latest",+ allow_deprecated: bool = False,+ timeout_seconds: float = DEFAULT_DOWNLOAD_TIMEOUT_SECONDS,+ allow_reinstall: bool = False,+ ) -> CatalogInstallResult:+ try:+ entry = resolve_catalog_entry(+ plugin_id,+ version,+ allow_deprecated=allow_deprecated,+ )+ except CatalogResolutionError as exc:+ raise PluginDistributionError(str(exc)) from exc+ if not entry.artifact.url:+ raise PluginDistributionError(+ f"catalog entry for {plugin_id!r} {entry.version} has no download URL"+ )++ with tempfile.TemporaryDirectory(prefix="deeptutor-plugin-download-") as temporary:+ downloaded = self._downloader_factory().download(+ entry.artifact,+ destination_dir=Path(temporary),+ timeout_seconds=timeout_seconds,+ )+ manifest, _ = _manifest_from_wheel(downloaded.path)+ if (+ manifest.id != entry.id+ or str(manifest.version) != entry.version+ or manifest.permissions.to_dict() != entry.permissions.to_dict()+ or manifest.dependencies != entry.dependencies+ or manifest.compatibility.to_dict() != entry.compatibility.to_dict()+ ):+ raise PluginDistributionError(+ "Wheel manifest does not match the reviewed catalog snapshot."+ )+ lifecycle = self._lifecycle_factory().install(+ downloaded.path,+ expected_sha256=entry.artifact.sha256,+ allow_reinstall=allow_reinstall,+ )+ return CatalogInstallResult(+ lifecycle=lifecycle,+ artifact_url=entry.artifact.url,+ )+++def _default_client(timeout_seconds: float) -> _DownloadClient:+ return httpx.Client(+ timeout=timeout_seconds,+ follow_redirects=False,+ headers={"User-Agent": "DeepTutor-plugin-catalog/2"},+ )diff --git a/deeptutor/plugins/frontend.py b/deeptutor/plugins/frontend.pynew file mode 100644index 000000000..480083977--- /dev/null+++ b/deeptutor/plugins/frontend.py@@ -0,0 +1,158 @@+"""Validated static frontend page contracts for managed plugins."""++from __future__ import annotations++from dataclasses import dataclass+import json+from pathlib import Path, PurePosixPath+import re+from typing import Any, Mapping++FRONTEND_PAGE_SCHEMA_VERSION = "deeptutor.plugin-frontend-page/v1"+MAX_PAGE_MANIFEST_BYTES = 64 * 1024+MAX_PAGE_ASSET_BYTES = 5 * 1024 * 1024+MAX_PAGE_ASSET_TOTAL_BYTES = 20 * 1024 * 1024+MAX_PAGE_ASSETS = 64+_ASSET_SEGMENT = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$")+_ASSET_SUFFIXES = frozenset(+ {+ ".css",+ ".html",+ ".ico",+ ".jpeg",+ ".jpg",+ ".js",+ ".json",+ ".png",+ ".svg",+ ".txt",+ ".webp",+ ".woff2",+ }+)+++class FrontendPageError(ValueError):+ """Raised when a packaged frontend page is invalid or unsafe."""+++@dataclass(frozen=True, slots=True)+class FrontendPageManifest:+ entry: str+ assets: tuple[str, ...]++ def to_dict(self) -> dict[str, Any]:+ return {+ "schema_version": FRONTEND_PAGE_SCHEMA_VERSION,+ "entry": self.entry,+ "assets": list(self.assets),+ }+++def parse_frontend_page_manifest(raw: Any) -> FrontendPageManifest:+ if not isinstance(raw, Mapping):+ raise FrontendPageError("frontend page manifest must be an object")+ _reject_unknown(raw, {"schema_version", "entry", "assets"})+ if raw.get("schema_version") != FRONTEND_PAGE_SCHEMA_VERSION:+ raise FrontendPageError("unsupported frontend page schema_version")+ entry = _asset_path("entry", raw.get("entry"))+ assets_raw = raw.get("assets")+ if not isinstance(assets_raw, list) or not assets_raw:+ raise FrontendPageError("frontend page assets must be a non-empty array")+ if len(assets_raw) > MAX_PAGE_ASSETS:+ raise FrontendPageError(f"frontend page supports at most {MAX_PAGE_ASSETS} assets")+ assets = tuple(_asset_path("assets[]", item) for item in assets_raw)+ if len(set(assets)) != len(assets):+ raise FrontendPageError("frontend page assets must be unique")+ if entry not in assets:+ raise FrontendPageError("frontend page entry must be listed in assets")+ return FrontendPageManifest(entry=entry, assets=assets)+++def load_frontend_page_manifest(path: Path) -> FrontendPageManifest:+ try:+ payload = path.read_bytes()+ if len(payload) > MAX_PAGE_MANIFEST_BYTES:+ raise FrontendPageError("frontend page manifest exceeds 64 KiB")+ return parse_frontend_page_manifest(json.loads(payload))+ except FrontendPageError:+ raise+ except (OSError, json.JSONDecodeError, UnicodeDecodeError) as exc:+ raise FrontendPageError("frontend page manifest is unreadable") from exc+++def resolve_frontend_page_asset(+ page: FrontendPageManifest,+ package_root: Path,+ requested: str,+) -> Path:+ if requested not in page.assets:+ raise FrontendPageError("frontend page asset is not declared")+ root = _package_root(package_root)+ total = 0+ selected = None+ try:+ for asset in page.assets:+ path = _resolve_asset(root, asset)+ size = path.stat().st_size+ if size > MAX_PAGE_ASSET_BYTES:+ raise FrontendPageError("frontend page asset exceeds 5 MiB")+ total += size+ if total > MAX_PAGE_ASSET_TOTAL_BYTES:+ raise FrontendPageError("frontend page assets exceed 20 MiB total")+ if asset == requested:+ selected = path+ except OSError as exc:+ raise FrontendPageError("frontend page asset is unreadable") from exc+ if selected is not None:+ return selected+ raise FrontendPageError("frontend page asset is unavailable")+++def _package_root(value: Path) -> Path:+ try:+ root = value.resolve(strict=True)+ if not root.is_dir():+ raise FrontendPageError("plugin package root is unavailable")+ return root+ except OSError as exc:+ raise FrontendPageError("plugin package root is unavailable") from exc+++def _resolve_asset(root: Path, asset: str) -> Path:+ relative = PurePosixPath(asset)+ lexical = root.joinpath(*relative.parts)+ current = lexical+ while current != root:+ if current.is_symlink():+ raise FrontendPageError("frontend page assets must not be symlinks")+ current = current.parent+ resolved = lexical.resolve(strict=True)+ try:+ resolved.relative_to(root)+ except ValueError as exc:+ raise FrontendPageError("frontend page asset escapes the plugin package") from exc+ if not resolved.is_file():+ raise FrontendPageError("frontend page asset is not a file")+ return resolved+++def _asset_path(name: str, value: Any) -> str:+ if not isinstance(value, str):+ raise FrontendPageError(f"{name} must be a POSIX asset path")+ path = PurePosixPath(value)+ if len(value) > 256 or path.is_absolute() or not path.parts:+ raise FrontendPageError(f"{name} must be a relative asset path")+ if any(part in {"", ".", ".."} for part in path.parts):+ raise FrontendPageError(f"{name} must not contain traversal segments")+ if any(_ASSET_SEGMENT.fullmatch(part) is None for part in path.parts):+ raise FrontendPageError(f"{name} contains an invalid path segment")+ if path.suffix.lower() not in _ASSET_SUFFIXES:+ raise FrontendPageError(f"{name} has an unsupported file type")+ return value+++def _reject_unknown(raw: Mapping[str, Any], allowed: set[str]) -> None:+ unknown = set(raw) - allowed+ if unknown:+ raise FrontendPageError(f"unknown fields: {', '.join(sorted(unknown))}")diff --git a/deeptutor/plugins/lifecycle.py b/deeptutor/plugins/lifecycle.pynew file mode 100644index 000000000..0ed61622a--- /dev/null+++ b/deeptutor/plugins/lifecycle.py@@ -0,0 +1,468 @@+"""Local plugin package lifecycle with isolated environments and rollback."""++from __future__ import annotations++from dataclasses import dataclass+from datetime import UTC, datetime+from email.parser import BytesParser+import hashlib+import json+import os+from pathlib import Path, PurePosixPath+import shutil+import subprocess+import sys+import tempfile+import zipfile++from packaging.version import InvalidVersion, Version++from deeptutor.plugins.manifest import (+ MANIFEST_FILENAME,+ ManifestValidationError,+ PluginManifestData,+ parse_manifest,+)+from deeptutor.plugins.registry import (+ PluginInstallation,+ PluginRegistry,+ PluginStateError,+)+from deeptutor.plugins.transactions import serialized+from deeptutor.services.path_service import get_path_service+++class PluginLifecycleError(ValueError):+ """Raised when a package cannot be installed, upgraded, or rolled back."""+++@dataclass(frozen=True, slots=True)+class LifecycleResult:+ plugin_id: str+ version: str+ action: str+ artifact_sha256: str+ venv_path: Path+ log: str = ""+++class PluginLifecycleManager:+ """Install wheel packages without importing plugin code into this process.++ Manifest dependencies are an explicit, isolated closure. They are installed+ with ``--no-deps`` so pip cannot silently mutate the host environment or+ resolve a different transitive graph later.+ """++ def __init__(+ self,+ registry: PluginRegistry | None = None,+ *,+ root: Path | None = None,+ runner=None,+ ) -> None:+ self.registry = registry or PluginRegistry()+ if root is None:+ settings_path = get_path_service().get_settings_file("plugins")+ root = settings_path.parent.parent / "plugins"+ self.root = root+ self._runner = runner or _run_command++ @serialized+ def install(+ self,+ artifact: Path,+ *,+ expected_sha256: str = "",+ allow_reinstall: bool = False,+ ) -> LifecycleResult:+ artifact = Path(artifact).expanduser().resolve()+ if artifact.suffix != ".whl" or not artifact.is_file():+ raise PluginLifecycleError("artifact must be an existing local wheel")++ digest = _sha256(artifact)+ if expected_sha256 and digest != expected_sha256.lower():+ raise PluginLifecycleError("artifact SHA-256 does not match the reviewed pin")++ manifest, package_root_in_wheel = _manifest_from_wheel(artifact)+ existing = self.registry.get_plugin(manifest.id)+ if existing is not None and existing.installation is not None:+ self._validate_transition(+ existing.installation.version, str(manifest.version), allow_reinstall+ )++ plugin_root = self.root / manifest.id+ version_dir = plugin_root / "versions" / str(manifest.version)+ artifact_dir = plugin_root / "artifacts" / str(manifest.version)+ venv_dir = version_dir / "venv"+ staging_dir = version_dir / ".venv-staging"+ backup = None+ installed_new = False+ shutil.rmtree(staging_dir, ignore_errors=True)+ if artifact_dir.is_dir():+ existing_artifacts = list(artifact_dir.glob("*.whl"))+ if any(_sha256(path) != digest for path in existing_artifacts):+ raise PluginLifecycleError(+ "A plugin version's artifact is immutable. Publish a new version for changed bytes."+ )+ artifact_dir.mkdir(parents=True, exist_ok=True)+ durable_artifact = artifact_dir / artifact.name+ if artifact != durable_artifact:+ shutil.copyfile(artifact, durable_artifact)++ chunks: list[str] = []+ try:+ code, output = self._runner([sys.executable, "-m", "venv", str(staging_dir)])+ chunks.append(f"$ {' '.join(('python', '-m', 'venv', str(staging_dir)))}\n{output}")+ if code != 0:+ raise PluginLifecycleError(f"virtual environment creation exited {code}")++ python_path = _venv_python(staging_dir)+ install_target = [*manifest.dependencies, str(durable_artifact)]+ argv = [+ str(python_path),+ "-m",+ "pip",+ "install",+ "--no-input",+ "--disable-pip-version-check",+ "--no-deps",+ "--only-binary=:all:",+ *install_target,+ ]+ code, output = self._runner(argv, env=_clean_env())+ chunks.append(f"$ pip install --no-deps {', '.join(install_target)}\n{output}")+ if code != 0:+ raise PluginLifecycleError(f"isolated dependency install exited {code}")++ if venv_dir.exists():+ backup = version_dir / ".venv-old"+ shutil.rmtree(backup, ignore_errors=True)+ os.replace(venv_dir, backup)+ os.replace(staging_dir, venv_dir)+ installed_new = True+ package_path = _installed_package_path(venv_dir, package_root_in_wheel)+ installation = PluginInstallation(+ version=str(manifest.version),+ artifact_path=durable_artifact,+ artifact_sha256=digest,+ venv_path=venv_dir,+ python_path=_venv_python(venv_dir),+ installed_at=_timestamp(),+ dependencies=manifest.dependencies,+ package_path=package_path,+ )+ self._commit_installation(manifest, installation)+ if backup is not None:+ shutil.rmtree(backup, ignore_errors=True)+ except (OSError, PluginStateError, ValueError) as exc:+ shutil.rmtree(staging_dir, ignore_errors=True)+ if installed_new:+ shutil.rmtree(venv_dir, ignore_errors=True)+ if backup is not None:+ os.replace(backup, venv_dir)+ raise PluginLifecycleError(str(exc)) from exc++ return LifecycleResult(+ plugin_id=manifest.id,+ version=str(manifest.version),+ action="reinstalled" if allow_reinstall and existing is not None else "installed",+ artifact_sha256=digest,+ venv_path=venv_dir,+ log=_log(plugin_root, chunks),+ )++ @serialized+ def rollback(self, plugin_id: str) -> LifecycleResult:+ state = self.registry.state_snapshot()+ row = state.get("plugins", {}).get(plugin_id)+ if not isinstance(row, dict):+ raise PluginLifecycleError(f"plugin {plugin_id!r} has no managed installation")+ history = [item for item in row.get("history", []) if isinstance(item, dict)]+ if not history:+ raise PluginLifecycleError(f"plugin {plugin_id!r} has no rollback version")+ candidate = history[-1]+ installation = _installation_from_history(candidate)+ if installation is None or not installation.venv_path.is_dir():+ raise PluginLifecycleError(f"rollback environment for {plugin_id!r} is missing")++ if (+ not installation.artifact_path.is_file()+ or _sha256(installation.artifact_path) != installation.artifact_sha256+ ):+ raise PluginLifecycleError("Rollback artifact failed its recorded SHA-256 check.")+ previous_manifest_raw = row.get("manifest", {})+ manifest = parse_manifest(candidate.get("manifest"))+ current = PluginInstallation(+ version=row["installation"]["version"],+ artifact_path=Path(row["installation"]["artifact_path"]),+ artifact_sha256=row["installation"]["artifact_sha256"],+ venv_path=Path(row["installation"]["venv_path"]),+ python_path=Path(row["installation"]["python_path"]),+ installed_at=row["installation"]["installed_at"],+ dependencies=tuple(row["installation"].get("dependencies", [])),+ package_path=Path(row["installation"]["package_path"])+ if row["installation"].get("package_path")+ else None,+ )+ row["installation"] = installation.to_dict()+ row["manifest"] = manifest.to_dict()+ row.pop("approval", None)+ row["history"] = [item for item in history if item is not candidate] + [+ {+ "version": current.version,+ "manifest": previous_manifest_raw,+ "installation": current.to_dict(),+ }+ ]+ self.registry.replace_state(state)+ return LifecycleResult(+ plugin_id=plugin_id,+ version=installation.version,+ action="rolled-back",+ artifact_sha256=installation.artifact_sha256,+ venv_path=installation.venv_path,+ )++ @serialized+ def uninstall(self, plugin_id: str) -> LifecycleResult:+ state = self.registry.state_snapshot()+ row = state.get("plugins", {}).get(plugin_id)+ if not isinstance(row, dict):+ raise PluginLifecycleError(f"plugin {plugin_id!r} has no managed installation")+ installation_raw = row.get("installation")+ if not isinstance(installation_raw, dict):+ raise PluginLifecycleError(f"plugin {plugin_id!r} has an invalid installation")+ version = installation_raw.get("version", "")+ digest = installation_raw.get("artifact_sha256", "")+ state["plugins"].pop(plugin_id, None)+ state["disabled"] = sorted(set(state.get("disabled", [])) - {plugin_id})+ self.registry.replace_state(state)+ shutil.rmtree(self.root / plugin_id, ignore_errors=True)+ return LifecycleResult(+ plugin_id=plugin_id,+ version=version,+ action="uninstalled",+ artifact_sha256=digest,+ venv_path=self.root / plugin_id,+ )++ def _validate_transition(self, current: str, target: str, allow_reinstall: bool) -> None:+ try:+ current_version = Version(current)+ target_version = Version(target)+ except InvalidVersion as exc:+ raise PluginLifecycleError("installed plugin version is invalid") from exc+ if target_version == current_version and not allow_reinstall:+ raise PluginLifecycleError(f"version {target} is already installed")+ if target_version < current_version:+ raise PluginLifecycleError("downgrades require rollback or explicit reinstall")++ def _commit_installation(+ self,+ manifest: PluginManifestData,+ installation: PluginInstallation,+ ) -> None:+ plugin_id = manifest.id+ state = self.registry.state_snapshot()+ row = state.setdefault("plugins", {}).get(plugin_id)+ if row is None:+ row = {"history": []}+ state["plugins"][plugin_id] = row+ if not isinstance(row, dict):+ raise PluginLifecycleError(f"plugin state for {plugin_id!r} is invalid")+ previous_installation = row.get("installation")+ if (+ previous_installation is not None+ and previous_installation.get("version") != installation.version+ ):+ row.setdefault("history", []).append(+ {+ "version": previous_installation.get("version", ""),+ "manifest": row.get("manifest", {}),+ "installation": previous_installation,+ }+ )+ row["manifest"] = manifest.to_dict()+ row["installation"] = installation.to_dict()+ row.pop("approval", None)+ self.registry.replace_state(state)+++def _manifest_from_wheel(artifact: Path) -> tuple[PluginManifestData, PurePosixPath]:+ try:+ with zipfile.ZipFile(artifact) as archive:+ if artifact.stat().st_size > 256 * 1024 * 1024:+ raise PluginLifecycleError("wheel exceeds 256 MiB")+ if sum(info.file_size for info in archive.infolist()) > 512 * 1024 * 1024:+ raise PluginLifecycleError("expanded wheel exceeds 512 MiB")+ for info in archive.infolist():+ path = PurePosixPath(info.filename)+ if (+ path.is_absolute()+ or ".." in path.parts+ or "\\" in info.filename+ or any(":" in part for part in path.parts)+ or ((info.external_attr >> 16) & 0o170000) == 0o120000+ ):+ raise PluginLifecycleError("wheel contains an unsafe path or symlink")+ names = [+ name+ for name in archive.namelist()+ if Path(name).name == MANIFEST_FILENAME and not name.startswith("..")+ ]+ if len(names) != 1:+ raise PluginLifecycleError(f"wheel must contain exactly one {MANIFEST_FILENAME}")+ if archive.getinfo(names[0]).file_size > 64 * 1024:+ raise PluginLifecycleError("wheel manifest exceeds 64 KiB")+ raw = json.loads(archive.read(names[0]).decode("utf-8"))+ source = PurePosixPath(names[0])+ if source.is_absolute() or any(part in {"", ".", ".."} for part in source.parts):+ raise PluginLifecycleError("artifact manifest has an invalid package path")+ manifest = parse_manifest(raw)+ metadata_files = [+ name for name in archive.namelist() if name.endswith(".dist-info/METADATA")+ ]+ if (+ len(metadata_files) != 1+ or archive.getinfo(metadata_files[0]).file_size > 1024 * 1024+ ):+ raise PluginLifecycleError("wheel must contain one bounded package metadata record")+ metadata = BytesParser().parsebytes(archive.read(metadata_files[0]))+ if Version(metadata.get("Version", "")) != manifest.version:+ raise PluginLifecycleError(+ "wheel package version does not match its plugin manifest"+ )+ return manifest, source.parent+ except (+ OSError,+ zipfile.BadZipFile,+ UnicodeDecodeError,+ ValueError,+ ManifestValidationError,+ ) as exc:+ if isinstance(exc, PluginLifecycleError):+ raise+ raise PluginLifecycleError(f"artifact manifest is unreadable: {exc}") from exc+++def _sha256(path: Path) -> str:+ digest = hashlib.sha256()+ with path.open("rb") as handle:+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):+ digest.update(chunk)+ return digest.hexdigest()+++def _installed_package_path(venv_root: Path, package_root: PurePosixPath) -> Path:+ if sys.platform == "win32":+ candidates = [venv_root / "Lib" / "site-packages"]+ else:+ candidates = sorted((venv_root / "lib").glob("python*/site-packages"))+ for site_packages in candidates:+ candidate = site_packages.joinpath(*package_root.parts)+ try:+ resolved = candidate.resolve(strict=True)+ except OSError:+ continue+ if resolved.is_dir():+ return resolved+ raise PluginLifecycleError("installed plugin package root is missing")+++def _venv_python(root: Path) -> Path:+ if sys.platform == "win32":+ return root / "Scripts" / "python.exe"+ return root / "bin" / "python"+++def _clean_env() -> dict[str, str]:+ keep = ("PATH", "HOME", "LANG", "LC_ALL", "TMPDIR", "SSL_CERT_FILE", "SSL_CERT_DIR")+ env = {key: os.environ[key] for key in keep if key in os.environ}+ for key in ("HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy"):+ if key in os.environ:+ env[key] = os.environ[key]+ env["PIP_DISABLE_PIP_VERSION_CHECK"] = "1"+ env["PYTHONDONTWRITEBYTECODE"] = "1"+ return env+++def _run_command(argv: list[str], *, env: dict[str, str] | None = None) -> tuple[int, str]:+ try:+ completed = subprocess.run( # noqa: S603 - argv is assembled here+ argv,+ env=env,+ capture_output=True,+ text=True,+ timeout=900,+ check=False,+ )+ except FileNotFoundError:+ return 127, f"{argv[0]}: not found"+ except subprocess.TimeoutExpired:+ return 124, "installation timed out after 900s"+ return completed.returncode, (completed.stdout or "") + (completed.stderr or "")+++def _installation_from_history(raw: dict) -> PluginInstallation | None:+ installation_raw = raw.get("installation")+ if not isinstance(installation_raw, dict):+ return None+ dependencies = installation_raw.get("dependencies", [])+ if not isinstance(dependencies, list):+ dependencies = []+ required = (+ "version",+ "artifact_path",+ "artifact_sha256",+ "venv_path",+ "python_path",+ "installed_at",+ )+ if not all(isinstance(installation_raw.get(name), str) for name in required):+ return None+ package_path_raw = installation_raw.get("package_path")+ if package_path_raw is not None and (+ not isinstance(package_path_raw, str) or not package_path_raw+ ):+ return None+ return PluginInstallation(+ version=installation_raw["version"],+ artifact_path=Path(installation_raw["artifact_path"]),+ artifact_sha256=installation_raw["artifact_sha256"],+ venv_path=Path(installation_raw["venv_path"]),+ python_path=Path(installation_raw["python_path"]),+ installed_at=installation_raw["installed_at"],+ dependencies=tuple(item for item in dependencies if isinstance(item, str)),+ package_path=Path(package_path_raw) if package_path_raw else None,+ )+++def _log(plugin_root: Path, chunks: list[str]) -> str:+ text = "\n\n".join(chunks)+ try:+ plugin_root.mkdir(parents=True, exist_ok=True)+ path = plugin_root / "install.log"+ with tempfile.NamedTemporaryFile(+ "w",+ encoding="utf-8",+ dir=plugin_root,+ delete=False,+ ) as handle:+ handle.write(text)+ temp = Path(handle.name)+ temp.replace(path)+ except OSError:+ pass+ return text[-20_000:]+++def _timestamp() -> str:+ return datetime.now(UTC).isoformat()+++__all__ = [+ "LifecycleResult",+ "PluginLifecycleError",+ "PluginLifecycleManager",+]diff --git a/deeptutor/plugins/loader.py b/deeptutor/plugins/loader.pyindex feb444b86..f99b64630 100644--- a/deeptutor/plugins/loader.py+++ b/deeptutor/plugins/loader.py@@ -53,6 +53,9 @@ def load_plugin_capability(manifest: PluginManifest) -> TurnCapability | None:if manifest.type and manifest.type != "capability":return None+ allowed = getattr(manifest, "_plugin_allowed", None)+ if allowed is not None and not allowed():+ return Noneobj = _resolve_entry(manifest.entry)return _instantiate_capability(obj)diff --git a/deeptutor/plugins/manifest.py b/deeptutor/plugins/manifest.pynew file mode 100644index 000000000..09b8fa249--- /dev/null+++ b/deeptutor/plugins/manifest.py@@ -0,0 +1,538 @@+"""Validation model for ``deeptutor.plugin.json``.++The root manifest is deliberately independent from runtime protocol classes.+Registry browsing must not import third-party Python modules, so this module+only accepts JSON-compatible dictionaries and normalizes them into small+dataclasses.+"""++from __future__ import annotations++from dataclasses import asdict, dataclass, field+import hashlib+import json+from pathlib import PurePosixPath+import re+from typing import Any, Mapping+from urllib.parse import urlsplit++from packaging.requirements import InvalidRequirement, Requirement+from packaging.specifiers import InvalidSpecifier, SpecifierSet+from packaging.version import InvalidVersion, Version++SCHEMA_VERSION = "deeptutor.plugin/v1"+MANIFEST_FILENAME = "deeptutor.plugin.json"++SUPPORTED_EXTENSION_TYPES = frozenset(+ {+ "app_connector",+ "capability",+ "frontend_page",+ "http_route",+ "loop_capability",+ "persistence_schema",+ "tool",+ "reading_extension",+ "visualizer",+ }+)+SUPPORTED_API_CONTRACTS = frozenset(SUPPORTED_EXTENSION_TYPES)+SUPPORTED_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"})+SUPPORTED_PLUGIN_AUTH_POLICIES = frozenset({"public", "authenticated", "admin"})+SUPPORTED_PERMISSION_SCOPES = frozenset(+ {+ "reading",+ "learning_events",+ "network",+ "models",+ "storage",+ "ui",+ }+)++_PLUGIN_ID = re.compile(r"^[a-z0-9][a-z0-9._-]{1,127}$")+_EXTENSION_ID = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")+_SHA256 = re.compile(r"^[0-9a-f]{64}$")+_LANGUAGE = re.compile(r"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$")+_API_VERSION = re.compile(r"^[0-9]+(?:\.[0-9]+)?$")+_HTTP_PATH = re.compile(r"^/[A-Za-z0-9][A-Za-z0-9._~-]*(?:/[A-Za-z0-9][A-Za-z0-9._~-]*)*$")+_OPERATION_ID = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")+++class ManifestValidationError(ValueError):+ """Raised when a plugin manifest cannot be modeled."""+++@dataclass(frozen=True, slots=True)+class PluginCompatibility:+ deeptutor: SpecifierSet+ api: Mapping[str, Version]++ def to_dict(self) -> dict[str, Any]:+ return {+ "deeptutor": str(self.deeptutor),+ "api": {name: str(version) for name, version in self.api.items()},+ }+++@dataclass(frozen=True, slots=True)+class PluginPermissions:+ scopes: Mapping[str, tuple[str, ...]]++ def to_dict(self) -> dict[str, Any]:+ return {name: list(values) for name, values in self.scopes.items()}+++@dataclass(frozen=True, slots=True)+class PluginExtension:+ type: str+ id: str+ entry_point: str = ""+ manifest: str = ""+ path: str = ""+ methods: tuple[str, ...] = ()+ auth: str = ""+ schema: str = ""+ operations: tuple[str, ...] = ()++ def to_dict(self) -> dict[str, Any]:+ result: dict[str, Any] = {"type": self.type, "id": self.id}+ if self.entry_point:+ result["entry_point"] = self.entry_point+ if self.manifest:+ result["manifest"] = self.manifest+ if self.path:+ result["path"] = self.path+ if self.methods:+ result["methods"] = list(self.methods)+ if self.auth:+ result["auth"] = self.auth+ if self.schema:+ result["schema"] = self.schema+ if self.operations:+ result["operations"] = list(self.operations)+ return result+++@dataclass(frozen=True, slots=True)+class PluginManifestData:+ schema_version: str+ id: str+ name: str+ version: Version+ description_i18n: Mapping[str, str]+ author: str+ license: str+ homepage: str+ source_url: str+ compatibility: PluginCompatibility+ permissions: PluginPermissions+ dependencies: tuple[str, ...] = field(default_factory=tuple)+ extensions: tuple[PluginExtension, ...] = field(default_factory=tuple)++ def to_dict(self) -> dict[str, Any]:+ result = asdict(self)+ result["version"] = str(self.version)+ result["compatibility"] = self.compatibility.to_dict()+ result["permissions"] = self.permissions.to_dict()+ result["dependencies"] = list(self.dependencies)+ result["extensions"] = [extension.to_dict() for extension in self.extensions]+ return result+++def parse_manifest(raw: Mapping[str, Any] | None) -> PluginManifestData:+ """Validate and normalize one root manifest.++ Unknown top-level fields are rejected rather than silently ignored. This is+ the compatibility contract third-party packages will build against, so a+ typo such as ``entryPoints`` must fail during review instead of changing+ behavior between DeepTutor releases.+ """+ if not isinstance(raw, Mapping):+ raise ManifestValidationError("manifest must be a JSON object")++ allowed = {+ "schema_version",+ "id",+ "name",+ "version",+ "description_i18n",+ "author",+ "license",+ "homepage",+ "source_url",+ "compatibility",+ "permissions",+ "dependencies",+ "extensions",+ }+ _reject_unknown("manifest", raw, allowed)++ schema_version = _required_str("schema_version", raw.get("schema_version"))+ if schema_version != SCHEMA_VERSION:+ raise ManifestValidationError(f"unsupported schema_version {schema_version!r}")++ plugin_id = _required_str("id", raw.get("id"))+ if not _PLUGIN_ID.fullmatch(plugin_id):+ raise ManifestValidationError("id must be lowercase reverse-DNS-like identifier")++ name = _required_str("name", raw.get("name"), max_length=120)+ version = _version(_required_str("version", raw.get("version")))+ description = _i18n(raw.get("description_i18n"), required_language="en")+ author = _required_str("author", raw.get("author"), max_length=160)+ license_ = _required_str("license", raw.get("license"), max_length=80)+ homepage = _optional_url("homepage", raw.get("homepage"))+ source_url = _url("source_url", raw.get("source_url"))++ compatibility_raw = raw.get("compatibility")+ if not isinstance(compatibility_raw, Mapping):+ raise ManifestValidationError("compatibility must be an object")+ compatibility = _compatibility(compatibility_raw)++ permissions_raw = raw.get("permissions")+ if not isinstance(permissions_raw, Mapping):+ raise ManifestValidationError("permissions must be an object")+ permissions = _permissions(permissions_raw)++ dependencies_raw = raw.get("dependencies", [])+ if not isinstance(dependencies_raw, list):+ raise ManifestValidationError("dependencies must be an array")+ dependencies = _dependencies(dependencies_raw)++ extensions_raw = raw.get("extensions")+ if not isinstance(extensions_raw, list):+ raise ManifestValidationError("extensions must be an array")+ extensions = _extensions(extensions_raw)+ if any(extension.type == "frontend_page" and extension.manifest for extension in extensions):+ ui_scopes = permissions.scopes.get("ui", ())+ if "sandboxed-iframe" not in ui_scopes:+ raise ManifestValidationError(+ "executable frontend_page requires permissions.ui sandboxed-iframe"+ )++ return PluginManifestData(+ schema_version=schema_version,+ id=plugin_id,+ name=name,+ version=version,+ description_i18n=description,+ author=author,+ license=license_,+ homepage=homepage,+ source_url=source_url,+ compatibility=compatibility,+ permissions=permissions,+ dependencies=dependencies,+ extensions=extensions,+ )+++def version_matches(version: Version, requirement: str | SpecifierSet) -> bool:+ try:+ specifier = (+ requirement if isinstance(requirement, SpecifierSet) else SpecifierSet(requirement)+ )+ except InvalidSpecifier as exc:+ raise ManifestValidationError(f"invalid version requirement {requirement!r}") from exc+ return specifier.contains(version, prereleases=True)+++def is_sha256(value: str) -> bool:+ return bool(_SHA256.fullmatch(value))+++def permission_digest(permissions: PluginPermissions) -> str:+ """Return a stable digest of the exact permission grant a user approved."""+ payload = json.dumps(+ permissions.to_dict(),+ sort_keys=True,+ separators=(",", ":"),+ ensure_ascii=False,+ ).encode("utf-8")+ return hashlib.sha256(payload).hexdigest()+++def _compatibility(raw: Mapping[str, Any]) -> PluginCompatibility:+ _reject_unknown("compatibility", raw, {"deeptutor", "api"})+ deeptutor_raw = raw.get("deeptutor")+ if not isinstance(deeptutor_raw, str) or not deeptutor_raw.strip():+ raise ManifestValidationError("compatibility.deeptutor is required")+ try:+ deeptutor = SpecifierSet(deeptutor_raw)+ except InvalidSpecifier as exc:+ raise ManifestValidationError("invalid compatibility.deeptutor specifier") from exc++ api_raw = raw.get("api")+ if not isinstance(api_raw, Mapping):+ raise ManifestValidationError("compatibility.api must be an object")+ _reject_unknown("compatibility.api", api_raw, SUPPORTED_API_CONTRACTS)+ api: dict[str, Version] = {}+ for name, value in api_raw.items():+ if name not in SUPPORTED_API_CONTRACTS:+ raise ManifestValidationError(f"unknown API contract {name!r}")+ if not isinstance(value, str) or not _API_VERSION.fullmatch(value):+ raise ManifestValidationError(f"compatibility.api.{name} must be a version")+ api[name] = Version(value)+ return PluginCompatibility(deeptutor=deeptutor, api=api)+++def _permissions(raw: Mapping[str, Any]) -> PluginPermissions:+ _reject_unknown("permissions", raw, SUPPORTED_PERMISSION_SCOPES)+ scopes: dict[str, tuple[str, ...]] = {}+ for name, values in raw.items():+ if not isinstance(values, list):+ raise ManifestValidationError(f"permissions.{name} must be an array")+ normalized = tuple(+ _required_str(f"permissions.{name}[]", value, max_length=240) for value in values+ )+ if len(set(normalized)) != len(normalized):+ raise ManifestValidationError(f"permissions.{name} contains duplicate values")+ scopes[name] = normalized+ return PluginPermissions(scopes=scopes)+++def _dependencies(raw: list[Any]) -> tuple[str, ...]:+ if len(raw) > 50:+ raise ManifestValidationError("dependencies supports at most 50 requirements")+ dependencies: list[str] = []+ seen: set[str] = set()+ for index, value in enumerate(raw):+ if not isinstance(value, str):+ raise ManifestValidationError(f"dependencies[{index}] must be a string")+ text = value.strip()+ if not text:+ raise ManifestValidationError(f"dependencies[{index}] is required")+ try:+ requirement = Requirement(text)+ except InvalidRequirement as exc:+ raise ManifestValidationError(+ f"dependencies[{index}] is not a valid PEP 508 requirement"+ ) from exc+ if requirement.url or requirement.marker or requirement.extras:+ raise ManifestValidationError(+ f"dependencies[{index}] must be a name-and-version requirement"+ )+ canonical_name = str(getattr(requirement, "canonical_name", requirement.name)).casefold()+ if canonical_name in seen:+ raise ManifestValidationError(f"dependencies contains duplicate {requirement.name}")+ seen.add(canonical_name)+ dependencies.append(str(requirement))+ return tuple(dependencies)+++def _extensions(raw: list[Any]) -> tuple[PluginExtension, ...]:+ extensions: list[PluginExtension] = []+ seen: set[str] = set()+ seen_http_paths: set[str] = set()+ allowed_fields = {+ "capability": {"type", "id", "entry_point"},+ "loop_capability": {"type", "id", "entry_point"},+ "tool": {"type", "id", "entry_point"},+ "reading_extension": {"type", "id", "entry_point"},+ "visualizer": {"type", "id", "manifest"},+ "http_route": {"type", "id", "entry_point", "path", "methods", "auth"},+ "frontend_page": {"type", "id", "path", "auth", "manifest"},+ "persistence_schema": {"type", "id", "schema", "operations"},+ "app_connector": {"type", "id", "operations"},+ }+ for index, row in enumerate(raw):+ label = f"extensions[{index}]"+ if not isinstance(row, Mapping):+ raise ManifestValidationError(f"{label} must be an object")+ extension_type = _required_str(f"{label}.type", row.get("type"))+ if extension_type not in SUPPORTED_EXTENSION_TYPES:+ raise ManifestValidationError(f"{label}.type is not supported")+ _reject_unknown(label, row, allowed_fields[extension_type])+ extension_id = _required_str(f"{label}.id", row.get("id"))+ if not _EXTENSION_ID.fullmatch(extension_id):+ raise ManifestValidationError(f"{label}.id is invalid")+ if extension_type == "tool" and re.fullmatch(r"[a-z0-9_-]{1,64}", extension_id) is None:+ raise ManifestValidationError(f"{label}.id is not a valid tool function name")+ if extension_id in seen:+ raise ManifestValidationError(f"duplicate extension id {extension_id!r}")+ seen.add(extension_id)++ entry_point = _optional_str(f"{label}.entry_point", row.get("entry_point"))+ manifest_path = _optional_str(f"{label}.manifest", row.get("manifest"))+ path = ""+ methods: tuple[str, ...] = ()+ auth = ""+ schema = ""+ operations: tuple[str, ...] = ()++ if extension_type == "visualizer":+ if not manifest_path:+ raise ManifestValidationError(f"{label}.manifest is required for visualizers")+ elif extension_type in {"capability", "loop_capability", "tool", "reading_extension"}:+ if not entry_point:+ raise ManifestValidationError(f"{label}.entry_point is required")+ elif extension_type == "http_route":+ if not entry_point:+ raise ManifestValidationError(f"{label}.entry_point is required")+ path = _http_path(f"{label}.path", row.get("path"))+ if path in seen_http_paths:+ raise ManifestValidationError(f"{label}.path is declared by multiple routes")+ seen_http_paths.add(path)+ methods = _methods(f"{label}.methods", row.get("methods"))+ auth = _auth_policy(f"{label}.auth", row.get("auth"))+ elif extension_type == "frontend_page":+ path = _http_path(f"{label}.path", row.get("path"))+ auth = _auth_policy(f"{label}.auth", row.get("auth"))+ if manifest_path:+ manifest_path = _package_path(f"{label}.manifest", manifest_path)+ elif extension_type == "persistence_schema":+ schema = _package_path(f"{label}.schema", row.get("schema"))+ operations = _operations(f"{label}.operations", row.get("operations"))+ elif extension_type == "app_connector":+ operations = _operations(f"{label}.operations", row.get("operations"))++ extensions.append(+ PluginExtension(+ type=extension_type,+ id=extension_id,+ entry_point=entry_point,+ manifest=manifest_path,+ path=path,+ methods=methods,+ auth=auth,+ schema=schema,+ operations=operations,+ )+ )+ return tuple(extensions)+++def _http_path(name: str, value: Any) -> str:+ result = _required_str(name, value, max_length=512)+ if _HTTP_PATH.fullmatch(result) is None:+ raise ManifestValidationError(f"{name} must be a static relative /path")+ return result+++def _methods(name: str, value: Any) -> tuple[str, ...]:+ if not isinstance(value, list) or not value:+ raise ManifestValidationError(f"{name} must be a non-empty array")+ result = tuple(_required_str(f"{name}[]", item, max_length=16) for item in value)+ if len(set(result)) != len(result):+ raise ManifestValidationError(f"{name} contains duplicate values")+ if not set(result).issubset(SUPPORTED_HTTP_METHODS):+ raise ManifestValidationError(f"{name} contains an unsupported HTTP method")+ return result+++def _auth_policy(name: str, value: Any) -> str:+ result = _required_str(name, value, max_length=32)+ if result not in SUPPORTED_PLUGIN_AUTH_POLICIES:+ raise ManifestValidationError(f"{name} must be public, authenticated, or admin")+ return result+++def _package_path(name: str, value: Any) -> str:+ result = _required_str(name, value, max_length=512)+ if "\\" in result or "\x00" in result:+ raise ManifestValidationError(f"{name} must be a POSIX package path")+ path = PurePosixPath(result)+ if path.is_absolute() or not path.parts or path.suffix != ".json":+ raise ManifestValidationError(f"{name} must be a packaged JSON file path")+ if any(part in {"", ".", ".."} for part in path.parts):+ raise ManifestValidationError(f"{name} must not contain traversal segments")+ return result+++def _operations(name: str, value: Any) -> tuple[str, ...]:+ if not isinstance(value, list) or not value:+ raise ManifestValidationError(f"{name} must be a non-empty array")+ if len(value) > 32:+ raise ManifestValidationError(f"{name} supports at most 32 operations")+ result = tuple(_required_str(f"{name}[]", item, max_length=64) for item in value)+ if len(set(result)) != len(result):+ raise ManifestValidationError(f"{name} contains duplicate values")+ if any(_OPERATION_ID.fullmatch(item) is None for item in result):+ raise ManifestValidationError(f"{name} contains an invalid operation id")+ return result+++def _i18n(raw: Any, *, required_language: str) -> dict[str, str]:+ if not isinstance(raw, Mapping):+ raise ManifestValidationError("description_i18n must be an object")+ result: dict[str, str] = {}+ for language, value in raw.items():+ if not isinstance(language, str) or not _LANGUAGE.fullmatch(language):+ raise ManifestValidationError(f"invalid language tag {language!r}")+ result[language] = _required_str(f"description_i18n.{language}", value, max_length=1000)+ if not result.get(required_language, "").strip():+ raise ManifestValidationError(f"description_i18n.{required_language} is required")+ return result+++def _version(value: str) -> Version:+ try:+ return Version(value)+ except InvalidVersion as exc:+ raise ManifestValidationError("version must be a valid semantic-style version") from exc+++def _required_str(name: str, value: Any, *, max_length: int = 300) -> str:+ result = _optional_str(name, value)+ if not result:+ raise ManifestValidationError(f"{name} is required")+ if len(result) > max_length:+ raise ManifestValidationError(f"{name} exceeds {max_length} characters")+ return result+++def _optional_str(name: str, value: Any) -> str:+ if value is None:+ return ""+ if not isinstance(value, str):+ raise ManifestValidationError(f"{name} must be a string")+ return value.strip()+++def _url(name: str, value: Any) -> str:+ result = _required_str(name, value, max_length=2048)+ parsed = urlsplit(result)+ if parsed.scheme not in {"http", "https"} or not parsed.netloc:+ raise ManifestValidationError(f"{name} must be an absolute http(s) URL")+ return result+++def _optional_url(name: str, value: Any) -> str:+ if value is None:+ return ""+ return _url(name, value)+++def _reject_unknown(label: str, raw: Mapping[str, Any], allowed: Any) -> None:+ allowed_names = set(allowed)+ unknown = set(raw) - allowed_names+ if unknown:+ names = ", ".join(sorted(str(name) for name in unknown))+ raise ManifestValidationError(f"{label} has unknown fields: {names}")+++__all__ = [+ "MANIFEST_FILENAME",+ "SCHEMA_VERSION",+ "SUPPORTED_API_CONTRACTS",+ "SUPPORTED_EXTENSION_TYPES",+ "SUPPORTED_HTTP_METHODS",+ "SUPPORTED_PLUGIN_AUTH_POLICIES",+ "SUPPORTED_PERMISSION_SCOPES",+ "ManifestValidationError",+ "PluginCompatibility",+ "PluginExtension",+ "PluginManifestData",+ "PluginPermissions",+ "is_sha256",+ "parse_manifest",+ "permission_digest",+ "version_matches",+]+++def approval_digest(manifest: PluginManifestData, artifact_identity: str = "") -> str:+ payload = {"manifest": manifest.to_dict(), "artifact_identity": artifact_identity}+ return hashlib.sha256(+ json.dumps(payload, sort_keys=True, ensure_ascii=False).encode()+ ).hexdigest()diff --git a/deeptutor/plugins/registry.py b/deeptutor/plugins/registry.pynew file mode 100644index 000000000..35a144528--- /dev/null+++ b/deeptutor/plugins/registry.py@@ -0,0 +1,648 @@+"""Read-only plugin discovery and local enablement state.++This registry manages marketplace-level state. It intentionally does not load+``BaseCapability`` or ``BaseTool`` implementations; legacy entry-point loading+remains in :mod:`deeptutor.plugins.loader`.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from datetime import UTC, datetime+import hashlib+from importlib.metadata import Distribution, distributions+import json+import logging+from pathlib import Path+from typing import Any++from packaging.version import Version++from deeptutor.__version__ import __version__+from deeptutor.plugins.catalog import (+ CATALOG_PATH,+ CatalogEntry,+ load_catalog,+ resolve_catalog_entry,+)+from deeptutor.plugins.manifest import (+ MANIFEST_FILENAME,+ ManifestValidationError,+ PluginManifestData,+ approval_digest,+ parse_manifest,+ version_matches,+)+from deeptutor.plugins.transactions import serialized+from deeptutor.services.file_io import atomic_write_json+from deeptutor.services.path_service import get_path_service++logger = logging.getLogger(__name__)++STATE_SCHEMA_VERSION = 2+LEGACY_STATE_SCHEMA_VERSION = 1+HOST_API_VERSIONS = {+ "app_connector": Version("1"),+ "capability": Version("1"),+ "frontend_page": Version("1"),+ "http_route": Version("1"),+ "loop_capability": Version("1"),+ "persistence_schema": Version("1"),+ "tool": Version("1"),+ "reading_extension": Version("1"),+ "visualizer": Version("1"),+}+++class PluginStateError(ValueError):+ """Raised when a plugin state transition is not safe."""+++@dataclass(frozen=True, slots=True)+class PluginRecord:+ id: str+ status: str+ manifest: PluginManifestData | None = None+ distribution: str = ""+ catalog_entry: CatalogEntry | None = None+ installation: "PluginInstallation | None" = None+ error: str = ""+ artifact_identity: str = ""++ @property+ def name(self) -> str:+ if self.manifest is not None:+ return self.manifest.name+ if self.catalog_entry is not None:+ return self.catalog_entry.name+ return self.id++ @property+ def version(self) -> str:+ if self.manifest is not None:+ return str(self.manifest.version)+ if self.catalog_entry is not None:+ return self.catalog_entry.version+ return ""++ @property+ def description(self) -> str:+ source = (+ self.manifest.description_i18n if self.manifest else self.catalog_entry.description_i18n+ )+ return source.get("en", "") if source else ""++ def to_dict(self) -> dict[str, Any]:+ result: dict[str, Any] = {+ "id": self.id,+ "name": self.name,+ "version": self.version,+ "status": self.status,+ "description": self.description,+ }+ if self.distribution:+ result["distribution"] = self.distribution+ if self.manifest is not None:+ result["manifest"] = self.manifest.to_dict()+ result["approval_digest"] = approval_digest(+ self.manifest,+ self.installation.artifact_sha256 if self.installation else self.artifact_identity,+ )+ if self.catalog_entry is not None:+ result["catalog"] = self.catalog_entry.to_dict()+ if self.installation is not None:+ result["installation"] = self.installation.to_dict()+ if self.error:+ result["error"] = self.error+ return result+++@dataclass(frozen=True, slots=True)+class PluginInstallation:+ """A managed, dependency-isolated plugin installation."""++ version: str+ artifact_path: Path+ artifact_sha256: str+ venv_path: Path+ python_path: Path+ installed_at: str+ dependencies: tuple[str, ...] = field(default_factory=tuple)+ package_path: Path | None = None++ def to_dict(self) -> dict[str, Any]:+ result = {+ "version": self.version,+ "artifact_path": str(self.artifact_path),+ "artifact_sha256": self.artifact_sha256,+ "venv_path": str(self.venv_path),+ "python_path": str(self.python_path),+ "installed_at": self.installed_at,+ "dependencies": list(self.dependencies),+ }+ if self.package_path is not None:+ result["package_path"] = str(self.package_path)+ return result+++@dataclass(frozen=True, slots=True)+class PluginApproval:+ """The exact permission snapshot accepted by a user."""++ digest: str+ approved_at: str++ def to_dict(self) -> dict[str, Any]:+ return {"digest": self.digest, "approved_at": self.approved_at}+++class PluginRegistry:+ """Discover installed manifests and catalog entries without importing them."""++ def __init__(+ self,+ *,+ state_path: Path | None = None,+ catalog_path: Path | None = None,+ deeptutor_version: str = __version__,+ installed_distributions: Any | None = None,+ ) -> None:+ self.state_path = state_path or get_path_service().get_settings_file("plugins")+ self.catalog_path = catalog_path+ self.deeptutor_version = Version(deeptutor_version)+ self._installed_distributions = installed_distributions++ def list_plugins(self, *, include_catalog: bool = True) -> list[PluginRecord]:+ records_by_id = {record.id: record for record in self._installed_records()}+ if include_catalog:+ catalog_path = self.catalog_path or CATALOG_PATH+ catalog_ids = {entry.id for entry in load_catalog(catalog_path)}+ for plugin_id in sorted(catalog_ids):+ if plugin_id not in records_by_id:+ entry = resolve_catalog_entry(+ plugin_id,+ allow_deprecated=True,+ allow_prerelease=True,+ path=catalog_path,+ )+ status = "deprecated" if entry.status == "deprecated" else "available"+ records_by_id[plugin_id] = PluginRecord(+ id=plugin_id,+ status=status,+ catalog_entry=entry,+ )+ return [records_by_id[plugin_id] for plugin_id in sorted(records_by_id)]++ def get_plugin(self, plugin_id: str) -> PluginRecord | None:+ return next((record for record in self.list_plugins() if record.id == plugin_id), None)++ def is_enabled(self, plugin_id: str) -> bool:+ return plugin_id not in self._state().get("disabled", [])++ @serialized+ def set_enabled(self, plugin_id: str, enabled: bool) -> PluginRecord:+ record = self.get_plugin(plugin_id)+ if record is None:+ raise PluginStateError(f"unknown plugin {plugin_id!r}")+ if record.status in {"broken", "incompatible"}:+ raise PluginStateError(f"plugin {plugin_id!r} is {record.status}")+ if record.status == "available":+ raise PluginStateError(f"plugin {plugin_id!r} is not installed")++ state = self._state()+ disabled = set(state.get("disabled", []))+ if enabled:+ disabled.discard(plugin_id)+ else:+ disabled.add(plugin_id)+ state["disabled"] = sorted(disabled)+ atomic_write_json(self.state_path, state)+ updated = self.get_plugin(plugin_id)+ assert updated is not None+ return updated++ @serialized+ def approve(self, plugin_id: str, *, expected_digest: str = "") -> PluginRecord:+ """Persist approval for the installed manifest's exact permission grant."""+ record = self.get_plugin(plugin_id)+ if record is None:+ raise PluginStateError(f"unknown plugin {plugin_id!r}")+ actual_digest = (+ approval_digest(+ record.manifest,+ record.installation.artifact_sha256+ if record.installation+ else record.artifact_identity,+ )+ if record.manifest+ else ""+ )+ if expected_digest and actual_digest != expected_digest:+ raise PluginStateError(+ "Plugin snapshot changed. Review the current manifest before approval."+ )+ if record.status == "enabled":+ return record+ if record.status != "approval-required" or record.manifest is None:+ raise PluginStateError(f"plugin {plugin_id!r} is {record.status}")++ state = self._state()+ row = _managed_row(state, plugin_id)+ if row is None:+ row = _external_row(state, plugin_id, record)+ row["manifest"] = record.manifest.to_dict()+ row["approval"] = PluginApproval(+ digest=approval_digest(+ record.manifest,+ record.installation.artifact_sha256+ if record.installation+ else record.artifact_identity,+ ),+ approved_at=_now(),+ ).to_dict()+ atomic_write_json(self.state_path, state)+ updated = self.get_plugin(plugin_id)+ assert updated is not None+ return updated++ def state_snapshot(self) -> dict[str, Any]:+ """Return the validated state document for lifecycle transactions."""+ return self._state()++ def replace_state(self, state: dict[str, Any]) -> None:+ """Atomically replace plugin state after a lifecycle transaction."""+ atomic_write_json(self.state_path, _validate_state(state))++ def _installed_records(self) -> list[PluginRecord]:+ grouped: dict[str, list[PluginRecord]] = {}+ unkeyed: list[PluginRecord] = []+ managed = self._managed_records()+ managed_ids = {record.id for record in managed}+ for dist in self._distributions():+ for path, raw, read_error in _manifest_files(dist):+ manifest, parse_error = _parse_manifest(raw, read_error)+ plugin_id = manifest.id if manifest is not None else _raw_id(raw)+ if plugin_id in managed_ids:+ continue+ distribution = _distribution_name(dist)+ if manifest is None or not plugin_id:+ record = PluginRecord(+ id=plugin_id or f"distribution:{distribution}",+ status="broken",+ distribution=distribution,+ error=parse_error,+ )+ if plugin_id:+ grouped.setdefault(plugin_id, []).append(record)+ else:+ unkeyed.append(record)+ continue++ compatible, compatibility_error = self._compatible(manifest)+ status = "incompatible" if not compatible else "approval-required"+ record = PluginRecord(+ id=plugin_id,+ status=status,+ manifest=manifest,+ distribution=distribution,+ error=compatibility_error,+ artifact_identity=_distribution_identity(dist),+ )+ grouped.setdefault(plugin_id, []).append(record)++ state = self._state()+ disabled = set(state.get("disabled", []))+ catalog_path = self.catalog_path or CATALOG_PATH+ catalog_entries = {(entry.id, entry.version): entry for entry in load_catalog(catalog_path)}+ records: list[PluginRecord] = list(managed)+ for plugin_id, candidates in grouped.items():+ if len(candidates) > 1:+ records.append(+ PluginRecord(+ id=plugin_id,+ status="broken",+ distribution=", ".join(sorted(item.distribution for item in candidates)),+ error="plugin id is provided by multiple installed distributions",+ )+ )+ continue+ record = candidates[0]+ if record.status == "approval-required" and record.manifest is not None:+ approval = _parse_approval(+ (state.get("plugins") or {}).get(plugin_id, {}).get("approval")+ if isinstance((state.get("plugins") or {}).get(plugin_id), dict)+ else None+ )+ if approval is not None and approval.digest == approval_digest(+ record.manifest, record.artifact_identity+ ):+ record = PluginRecord(+ id=record.id,+ status="enabled",+ manifest=record.manifest,+ distribution=record.distribution,+ error=record.error,+ artifact_identity=record.artifact_identity,+ )+ del approval+ if record.status != "incompatible" and plugin_id in disabled:+ record = PluginRecord(+ id=record.id,+ status="disabled",+ manifest=record.manifest,+ distribution=record.distribution,+ error=record.error,+ artifact_identity=record.artifact_identity,+ )+ else:+ installed_version = str(record.manifest.version) if record.manifest else ""+ catalog_entry = catalog_entries.get((plugin_id, installed_version))+ if catalog_entry is not None and catalog_entry.status == "deprecated":+ record = PluginRecord(+ id=record.id,+ status="deprecated",+ manifest=record.manifest,+ distribution=record.distribution,+ error=record.error,+ artifact_identity=record.artifact_identity,+ )+ records.append(record)+ return records + unkeyed++ def _managed_records(self) -> list[PluginRecord]:+ records: list[PluginRecord] = []+ state = self._state()+ catalog_entries = {+ (entry.id, entry.version): entry+ for entry in load_catalog(self.catalog_path or CATALOG_PATH)+ }+ for plugin_id, row in (state.get("plugins") or {}).items():+ if row.get("installation") is None:+ continue+ manifest, parse_error = _parse_manifest(row.get("manifest"), "")+ if manifest is None:+ records.append(+ PluginRecord(+ id=str(plugin_id),+ status="broken",+ distribution="managed",+ error=parse_error or "managed manifest is missing",+ )+ )+ continue++ installation = _parse_installation(row.get("installation"))+ if installation is None:+ records.append(+ PluginRecord(+ id=str(plugin_id),+ status="broken",+ distribution="managed",+ manifest=manifest,+ error="managed installation record is invalid",+ )+ )+ continue++ compatible, compatibility_error = self._compatible(manifest)+ status = "incompatible" if not compatible else "approval-required"+ if status != "incompatible":+ approval = _parse_approval(row.get("approval"))+ if approval is not None and approval.digest == approval_digest(+ manifest, installation.artifact_sha256+ ):+ status = "enabled"+ if status == "enabled" and plugin_id in state.get("disabled", []):+ status = "disabled"+ catalog_entry = catalog_entries.get((str(plugin_id), str(manifest.version)))+ if (+ catalog_entry is not None+ and catalog_entry.status == "deprecated"+ and status not in {"incompatible", "disabled"}+ ):+ status = "deprecated"+ records.append(+ PluginRecord(+ id=str(plugin_id),+ status=status,+ manifest=manifest,+ distribution="managed",+ installation=installation,+ error=compatibility_error,+ )+ )+ return records++ def _compatible(self, manifest: PluginManifestData) -> tuple[bool, str]:+ if not version_matches(self.deeptutor_version, manifest.compatibility.deeptutor):+ return False, f"requires DeepTutor {manifest.compatibility.deeptutor}"+ for extension in manifest.extensions:+ required = manifest.compatibility.api.get(extension.type)+ supported = HOST_API_VERSIONS.get(extension.type)+ if required is None or supported is None or required > supported:+ return False, f"requires {extension.type} API newer than this build"+ return True, ""++ def _state(self) -> dict[str, Any]:+ try:+ payload = json.loads(self.state_path.read_text(encoding="utf-8"))+ except FileNotFoundError:+ return _empty_state()+ except (OSError, ValueError, UnicodeError) as exc:+ raise PluginStateError("Plugin state is unreadable; original file preserved.") from exc+ if not isinstance(payload, dict) or payload.get("version") not in {+ STATE_SCHEMA_VERSION,+ LEGACY_STATE_SCHEMA_VERSION,+ }:+ raise PluginStateError(+ "Plugin state has an unsupported schema; original file preserved."+ )+ try:+ return _validate_state(payload)+ except (ValueError, ManifestValidationError) as exc:+ raise PluginStateError("Plugin state is malformed; original file preserved.") from exc++ def _distributions(self):+ if self._installed_distributions is not None:+ return list(self._installed_distributions)+ return distributions()+++_default_registry: PluginRegistry | None = None+++def get_plugin_registry() -> PluginRegistry:+ return PluginRegistry()+++def reset_plugin_registry_cache() -> None:+ global _default_registry+ _default_registry = None+++def _empty_state() -> dict[str, Any]:+ return {"version": STATE_SCHEMA_VERSION, "disabled": [], "plugins": {}}+++def _validate_state(payload: dict[str, Any]) -> dict[str, Any]:+ disabled = payload.get("disabled", [])+ plugins = payload.get("plugins", {})+ if not isinstance(disabled, list) or not all(isinstance(item, str) for item in disabled):+ raise ValueError("disabled must be an array of plugin IDs")+ if not isinstance(plugins, dict):+ raise ValueError("plugins must be an object")++ normalized = _empty_state()+ normalized["disabled"] = sorted(set(disabled))+ for plugin_id, row in plugins.items():+ if not isinstance(plugin_id, str) or not plugin_id.strip():+ raise ValueError("plugin state IDs must be non-empty strings")+ if not isinstance(row, dict):+ raise ValueError(f"plugin state for {plugin_id!r} must be an object")+ copied = dict(row)+ if copied.get("manifest") is not None:+ if parse_manifest(copied["manifest"]).id != plugin_id:+ raise ValueError("Plugin state identity does not match its manifest")+ if (+ copied.get("installation") is not None+ and _parse_installation(copied["installation"]) is None+ ):+ raise ValueError(f"plugin installation for {plugin_id!r} is invalid")+ if copied.get("approval") is not None and _parse_approval(copied["approval"]) is None:+ raise ValueError(f"plugin approval for {plugin_id!r} is invalid")+ history = copied.get("history", [])+ if not isinstance(history, list) or not all(+ isinstance(item, dict)+ and isinstance(item.get("version"), str)+ and isinstance(item.get("manifest"), dict)+ and isinstance(item.get("installation"), dict)+ for item in history+ ):+ raise ValueError(f"plugin history for {plugin_id!r} is invalid")+ copied["history"] = history+ normalized["plugins"][plugin_id] = copied+ return normalized+++def _managed_row(state: dict[str, Any], plugin_id: str) -> dict[str, Any] | None:+ row = state.get("plugins", {}).get(plugin_id)+ return row if isinstance(row, dict) else None+++def _external_row(+ state: dict[str, Any],+ plugin_id: str,+ record: PluginRecord,+) -> dict[str, Any]:+ if record.manifest is None:+ raise PluginStateError(f"plugin {plugin_id!r} has no valid manifest")+ row = {+ "manifest": record.manifest.to_dict(),+ "installation": record.installation.to_dict() if record.installation else None,+ "history": [],+ }+ state.setdefault("plugins", {})[plugin_id] = row+ return row+++def _parse_installation(raw: Any) -> PluginInstallation | None:+ if not isinstance(raw, dict):+ return None+ required_strings = (+ "version",+ "artifact_path",+ "artifact_sha256",+ "venv_path",+ "python_path",+ "installed_at",+ )+ if not all(isinstance(raw.get(name), str) and raw[name] for name in required_strings):+ return None+ dependencies_raw = raw.get("dependencies", [])+ if not isinstance(dependencies_raw, list) or not all(+ isinstance(item, str) for item in dependencies_raw+ ):+ return None+ package_path_raw = raw.get("package_path")+ if package_path_raw is not None and (+ not isinstance(package_path_raw, str) or not package_path_raw+ ):+ return None+ return PluginInstallation(+ version=raw["version"],+ artifact_path=Path(raw["artifact_path"]),+ artifact_sha256=raw["artifact_sha256"],+ venv_path=Path(raw["venv_path"]),+ python_path=Path(raw["python_path"]),+ installed_at=raw["installed_at"],+ dependencies=tuple(dependencies_raw),+ package_path=Path(package_path_raw) if package_path_raw else None,+ )+++def _parse_approval(raw: Any) -> PluginApproval | None:+ if not isinstance(raw, dict):+ return None+ digest = raw.get("digest")+ approved_at = raw.get("approved_at")+ if not isinstance(digest, str) or not isinstance(approved_at, str):+ return None+ return PluginApproval(digest=digest, approved_at=approved_at)+++def _now() -> str:+ return datetime.now(UTC).isoformat()+++def _manifest_files(dist: Distribution) -> list[tuple[Path, Any, str]]:+ files = dist.files or []+ results: list[tuple[Path, Any, str]] = []+ for item in files:+ if item.name.lower() != MANIFEST_FILENAME:+ continue+ path = Path(str(dist.locate_file(item)))+ try:+ results.append((Path(path), json.loads(Path(path).read_text(encoding="utf-8")), ""))+ except (OSError, json.JSONDecodeError, UnicodeDecodeError) as exc:+ results.append((Path(path), None, str(exc)))+ return results+++def _parse_manifest(raw: Any, read_error: str) -> tuple[PluginManifestData | None, str]:+ if read_error:+ return None, read_error+ try:+ return parse_manifest(raw), ""+ except ManifestValidationError as exc:+ return None, str(exc)+++def _raw_id(raw: Any) -> str:+ if isinstance(raw, dict) and isinstance(raw.get("id"), str):+ return raw["id"].strip()+ return ""+++def _distribution_name(dist: Distribution) -> str:+ return dist.metadata["Name"] or dist.metadata["name"] or "unknown"+++__all__ = [+ "HOST_API_VERSIONS",+ "PluginApproval",+ "PluginInstallation",+ "PluginRecord",+ "PluginRegistry",+ "PluginStateError",+ "get_plugin_registry",+ "reset_plugin_registry_cache",+]+++def _distribution_identity(dist) -> str:+ digest = hashlib.sha256(str(dist.metadata.get("Version", "")).encode())+ # RECORD pins installed wheel contents without importing its modules.+ reader = getattr(dist, "read_text", None)+ if callable(reader):+ digest.update((reader("RECORD") or "").encode())+ return digest.hexdigest()diff --git a/deeptutor/plugins/runtime.py b/deeptutor/plugins/runtime.pynew file mode 100644index 000000000..ad5dbf22f--- /dev/null+++ b/deeptutor/plugins/runtime.py@@ -0,0 +1,689 @@+"""Typed runtime adapters for managed plugin worker packages."""++from __future__ import annotations++import asyncio+from dataclasses import asdict, dataclass+import json+import logging+import os+from pathlib import Path+import re+import subprocess+from typing import Any, Mapping++from deeptutor.core.capability_protocol import (+ CapabilityManifest,+ StreamBusProtocol,+ TurnCapability,+)+from deeptutor.core.context import UnifiedContext+from deeptutor.core.stream import StreamEvent, StreamEventType+from deeptutor.core.tool_protocol import (+ BaseTool,+ ToolDefinition,+ ToolParameter,+ ToolResult,+)+from deeptutor.plugins.manifest import PluginManifestData+from deeptutor.plugins.registry import (+ PluginInstallation,+ PluginRecord,+ PluginRegistry,+ PluginStateError,+ _manifest_files,+ get_plugin_registry,+)++logger = logging.getLogger(__name__)+++class PluginRuntimeError(RuntimeError):+ """Raised when an enabled worker violates the plugin runtime contract."""+++_WORKER_MODULE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)+$")+_PERMISSION_KEYS = {"reading", "learning_events", "network", "models", "storage", "ui"}+_HTTP_STATUS_VALUES = frozenset({200, 201, 202, 204, 400, 404, 409, 422, 500})+_HTTP_HEADER_VALUES = re.compile(r"^(?:no-store|no-cache|max-age=[0-9]{1,8})$")+++@dataclass(frozen=True, slots=True)+class PluginHttpResponse:+ status: int+ body: Any = None+ headers: Mapping[str, str] | None = None+++class _WorkerClient:+ def __init__(+ self,+ *,+ python_path: Path,+ venv_path: Path,+ module: str,+ permissions: dict[str, tuple[str, ...]],+ guard=None,+ ) -> None:+ if _WORKER_MODULE.fullmatch(module) is None:+ raise PluginRuntimeError(f"invalid worker module {module!r}")+ self.python_path = python_path+ self.venv_path = venv_path+ self.module = module+ self.permissions = permissions+ self.guard = guard++ def request(self, operation: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:+ if self.guard is not None:+ self.guard()+ request = {"operation": operation, **(payload or {})}+ try:+ completed = _run_worker(+ [str(self.python_path), "-m", self.module],+ input=json.dumps(request, ensure_ascii=False, default=str),+ env=_clean_env(),+ cwd=self.venv_path,+ )+ except (OSError, subprocess.TimeoutExpired) as exc:+ raise PluginRuntimeError(f"plugin worker failed: {exc}") from exc+ if completed.returncode != 0:+ detail = (completed.stderr or completed.stdout or "").strip()[-2000:]+ raise PluginRuntimeError(f"plugin worker exited {completed.returncode}: {detail}")+ try:+ response = json.loads(completed.stdout)+ except json.JSONDecodeError as exc:+ raise PluginRuntimeError("plugin worker returned invalid JSON") from exc+ if not isinstance(response, dict):+ raise PluginRuntimeError("plugin worker response must be an object")+ if response.get("error") is not None:+ detail = str(response["error"])[-2000:]+ raise PluginRuntimeError(f"plugin worker error: {detail}")+ self.validate_permissions(response.get("permissions"))+ return response++ def validate_permissions(self, raw: Any) -> None:+ if raw is None:+ return+ if not isinstance(raw, dict):+ raise PluginRuntimeError("worker permissions must be an object")+ for scope, values in raw.items():+ if scope not in _PERMISSION_KEYS or not isinstance(values, list):+ raise PluginRuntimeError(f"worker declares invalid permission scope {scope!r}")+ if not all(isinstance(value, str) for value in values):+ raise PluginRuntimeError(f"worker declares invalid {scope} permissions")+ allowed = set(self.permissions.get(scope, ()))+ if not set(values).issubset(allowed):+ raise PluginRuntimeError(f"worker declares unapproved {scope} permissions")+++class PluginWorkerTool(BaseTool):+ deferred = True++ def __init__(+ self,+ *,+ manifest: PluginManifestData,+ installation: PluginInstallation,+ extension_id: str,+ registry: PluginRegistry | None = None,+ ) -> None:+ extension = _extension(manifest, "tool", extension_id)+ self._client = _WorkerClient(+ python_path=installation.python_path,+ venv_path=installation.venv_path,+ module=extension.entry_point,+ permissions=dict(manifest.permissions.scopes),+ guard=_managed_guard(manifest, installation, registry),+ )+ described = self._client.request("describe_tool")+ definition = described.get("definition")+ if not isinstance(definition, dict) or definition.get("name") != extension_id:+ raise PluginRuntimeError(f"worker tool declaration does not match {extension_id!r}")+ self._definition = _tool_definition(definition)++ def get_definition(self) -> ToolDefinition:+ return self._definition++ async def execute(self, **kwargs: Any) -> ToolResult:+ response = await asyncio.to_thread(+ self._client.request, "execute_tool", {"arguments": kwargs}+ )+ result = response.get("result")+ if not isinstance(result, dict):+ raise PluginRuntimeError("execute_tool response requires a result object")+ return ToolResult(+ content=str(result.get("content", "")),+ sources=list(result.get("sources", [])),+ metadata=dict(result.get("metadata", {})),+ success=bool(result.get("success", True)),+ )+++class PluginWorkerHttpRoute:+ def __init__(+ self,+ *,+ manifest: PluginManifestData,+ installation: PluginInstallation,+ extension_id: str,+ registry: PluginRegistry | None = None,+ ) -> None:+ extension = _extension(manifest, "http_route", extension_id)+ self.extension = extension+ self._client = _WorkerClient(+ python_path=installation.python_path,+ venv_path=installation.venv_path,+ module=extension.entry_point,+ permissions=dict(manifest.permissions.scopes),+ guard=_managed_guard(manifest, installation, registry),+ )++ def handle(+ self,+ *,+ method: str,+ path: str,+ query: Mapping[str, tuple[str, ...] | list[str]],+ body: Any = None,+ ) -> PluginHttpResponse:+ if method not in self.extension.methods:+ raise PluginRuntimeError(f"HTTP method {method!r} is not declared")+ if path != self.extension.path:+ raise PluginRuntimeError("HTTP route path does not match its manifest")+ response = self._client.request(+ "handle_http",+ {+ "http": {+ "method": method,+ "path": path,+ "query": {name: list(values) for name, values in query.items()},+ "body": body,+ "auth": self.extension.auth,+ }+ },+ )+ return _http_response(response.get("http"))+++class PluginWorkerCapability(TurnCapability):+ def __init__(+ self,+ *,+ manifest: PluginManifestData,+ installation: PluginInstallation,+ extension_id: str,+ registry: PluginRegistry | None = None,+ ) -> None:+ self._clone_args = dict(+ manifest=manifest, installation=installation, extension_id=extension_id+ )+ extension = _extension(manifest, "capability", extension_id)+ self._client = _WorkerClient(+ python_path=installation.python_path,+ venv_path=installation.venv_path,+ module=extension.entry_point,+ permissions=dict(manifest.permissions.scopes),+ guard=_managed_guard(manifest, installation, registry),+ )+ described = self._client.request("describe_capability")+ raw = described.get("capability")+ if not isinstance(raw, dict) or raw.get("name") != extension_id:+ raise PluginRuntimeError(+ f"worker capability declaration does not match {extension_id!r}"+ )+ self.manifest = CapabilityManifest(+ name=str(raw.get("name")),+ description=str(raw.get("description", "")),+ stages=[str(item) for item in raw.get("stages", [])],+ tools_used=[str(item) for item in raw.get("tools_used", [])],+ cli_aliases=[str(item) for item in raw.get("cli_aliases", [])],+ request_schema=dict(raw.get("request_schema", {})),+ config_defaults=dict(raw.get("config_defaults", {})),+ )++ def clone(self):+ return PluginWorkerCapability(**self._clone_args)++ async def run(self, context: UnifiedContext, stream: StreamBusProtocol) -> None:+ response = await asyncio.to_thread(+ self._client.request,+ "run_capability",+ {+ "context": {+ "session_id": context.session_id,+ "user_message": context.user_message,+ "conversation_history": context.conversation_history,+ "enabled_tools": context.enabled_tools,+ "active_capability": context.active_capability,+ "knowledge_bases": context.knowledge_bases,+ "attachments": [asdict(item) for item in context.attachments],+ "config_overrides": context.config_overrides,+ "language": context.language,+ "metadata": context.metadata,+ }+ },+ )+ events = response.get("events", [])+ if not isinstance(events, list):+ raise PluginRuntimeError("run_capability events must be an array")+ for raw in events:+ await stream.emit(_stream_event(raw, source=self.manifest.name))+++def load_enabled_workers(+ registry: PluginRegistry | None = None,+) -> tuple[BaseTool | TurnCapability, ...]:+ """Build tool/capability adapters only for approved managed installations."""+ registry = registry or get_plugin_registry()+ records = runtime_plugin_records(registry)+ extensions: list[BaseTool | TurnCapability] = []+ for record in records:+ if record.status != "enabled" or record.manifest is None or record.installation is None:+ continue+ for extension in record.manifest.extensions:+ try:+ if extension.type == "tool":+ extensions.append(+ PluginWorkerTool(+ manifest=record.manifest,+ installation=record.installation,+ extension_id=extension.id,+ registry=registry,+ )+ )+ elif extension.type == "capability":+ extensions.append(+ PluginWorkerCapability(+ manifest=record.manifest,+ installation=record.installation,+ extension_id=extension.id,+ registry=registry,+ )+ )+ except (PluginRuntimeError, ValueError, TypeError, KeyError) as exc:+ logger.warning(+ "Managed %s %r failed its worker contract; skipping",+ extension.type,+ extension.id,+ exc_info=exc,+ )+ return tuple(extensions)+++def load_enabled_tools(registry: PluginRegistry | None = None) -> tuple[BaseTool, ...]:+ return tuple(item for item in load_enabled_workers(registry) if isinstance(item, BaseTool))+++def load_enabled_capabilities(+ registry: PluginRegistry | None = None,+) -> tuple[TurnCapability, ...]:+ return tuple(+ item for item in load_enabled_workers(registry) if isinstance(item, TurnCapability)+ )+++def entry_point_allowed(+ registry: PluginRegistry,+ *,+ extension_type: str,+ entry_point: str,+) -> bool:+ """Gate only packages that declare this extension in a root manifest.++ Existing built-in and pre-v1 extension points keep working during the+ migration window. Once a package ships a root manifest, its exact+ extension, compatibility, approval digest, and local enablement state must+ all match before the entry point can load.+ """+ for record in registry.list_plugins(include_catalog=False):+ if record.manifest is None:+ continue+ declared = any(+ extension.type == extension_type and extension.entry_point == entry_point+ for extension in record.manifest.extensions+ )+ if declared:+ return record.status == "enabled"+ return True+++def _extension(manifest: PluginManifestData, extension_type: str, extension_id: str):+ for extension in manifest.extensions:+ if extension.type == extension_type and extension.id == extension_id:+ return extension+ raise PluginRuntimeError(f"manifest does not declare {extension_type} {extension_id!r}")+++def _tool_definition(raw: dict[str, Any]) -> ToolDefinition:+ parameters = []+ for item in raw.get("parameters", []):+ if not isinstance(item, dict) or not isinstance(item.get("name"), str):+ raise PluginRuntimeError("tool parameter requires a name")+ parameters.append(+ ToolParameter(+ name=item["name"],+ type=str(item.get("type", "string")),+ description=str(item.get("description", "")),+ required=bool(item.get("required", True)),+ default=item.get("default"),+ enum=item.get("enum"),+ items=item.get("items") if isinstance(item.get("items"), dict) else None,+ )+ )+ return ToolDefinition(+ name=str(raw.get("name", "")),+ description=str(raw.get("description", "")),+ parameters=parameters,+ )+++def _stream_event(raw: Any, *, source: str) -> StreamEvent:+ if not isinstance(raw, dict):+ raise PluginRuntimeError("worker stream events must be objects")+ try:+ event_type = StreamEventType(str(raw.get("type")))+ except ValueError as exc:+ raise PluginRuntimeError(f"unknown worker stream event {raw.get('type')!r}") from exc+ metadata = raw.get("metadata", {})+ if not isinstance(metadata, dict):+ raise PluginRuntimeError("worker stream metadata must be an object")+ return StreamEvent(+ type=event_type,+ source=source,+ stage=str(raw.get("stage", "")),+ content=str(raw.get("content", "")),+ metadata=metadata,+ )+++def _clean_env() -> dict[str, str]:+ keep = ("PATH", "HOME", "LANG", "LC_ALL", "TMPDIR", "SSL_CERT_FILE", "SSL_CERT_DIR")+ return {key: os.environ[key] for key in keep if key in os.environ}+++def _http_response(raw: Any) -> PluginHttpResponse:+ if not isinstance(raw, dict):+ raise PluginRuntimeError("handle_http response requires an http object")+ status = raw.get("status", 200)+ if not isinstance(status, int) or isinstance(status, bool) or status not in _HTTP_STATUS_VALUES:+ raise PluginRuntimeError("handle_http status is not allowed")+ body = raw.get("body")+ if status == 204 and body is not None:+ raise PluginRuntimeError("handle_http 204 response cannot include a body")+ raw_headers = raw.get("headers", {})+ if not isinstance(raw_headers, dict):+ raise PluginRuntimeError("handle_http headers must be an object")+ headers: dict[str, str] = {}+ for name, value in raw_headers.items():+ canonical = str(name).lower()+ if canonical != "cache-control":+ raise PluginRuntimeError(f"handle_http response header {name!r} is not allowed")+ if not isinstance(value, str) or _HTTP_HEADER_VALUES.fullmatch(value) is None:+ raise PluginRuntimeError("handle_http Cache-Control value is not allowed")+ headers["Cache-Control"] = value+ return PluginHttpResponse(status=status, body=body, headers=headers)+++__all__ = [+ "PluginRuntimeError",+ "PluginWorkerCapability",+ "PluginWorkerHttpRoute",+ "PluginWorkerTool",+ "PluginHttpResponse",+ "entry_point_allowed",+ "load_enabled_capabilities",+ "load_enabled_tools",+]+++_IMPORTED_GENERATIONS: dict[tuple[str, str], str] = {}++_GROUP_TYPES = {+ "deeptutor.tools": {"tool"},+ "deeptutor.extensions": {"capability", "loop_capability"},+ "deeptutor.plugins": {"capability", "tool"},+ "deeptutor.loop_capabilities": {"loop_capability"},+ "deeptutor.reading_extensions": {"reading_extension"},+}+++def _entry_record(ep, group):+ names = {getattr(ep, "name", ""), getattr(ep, "value", "")}+ dist = getattr(ep, "dist", None)+ distribution = str(dist.metadata.get("Name", "")) if dist is not None else ""+ for record in get_plugin_registry().list_plugins(include_catalog=False):+ if distribution:+ if record.distribution.casefold() == distribution.casefold():+ return record+ elif (+ record.distribution != "managed"+ and record.manifest+ and any(extension.entry_point in names for extension in record.manifest.extensions)+ ):+ return record+ if dist is not None and _manifest_files(dist):+ return PluginRecord(+ id=distribution,+ status="broken",+ distribution=distribution,+ error="Distribution manifest was shadowed or invalid.",+ )+ return None+++def entry_point_can_load(ep, group: str) -> bool:+ record = _entry_record(ep, group)+ if record is None:+ return True # Legacy packages without a root manifest retain compatibility.+ names = {getattr(ep, "name", ""), getattr(ep, "value", "")}+ allowed = (+ record.status == "enabled"+ and record.manifest is not None+ and any(+ extension.type in _GROUP_TYPES.get(group, set()) and extension.entry_point in names+ for extension in record.manifest.extensions+ )+ )++ if allowed and getattr(ep, "value", ""):+ from deeptutor.plugins.manifest import approval_digest++ key = (str(get_plugin_registry().state_path.resolve()), ep.value.split(":")[0])+ digest = approval_digest(record.manifest, record.artifact_identity)+ if key in _IMPORTED_GENERATIONS and _IMPORTED_GENERATIONS[key] != digest:+ logger.warning(+ "External plugin generation changed; restart DeepTutor to load reviewed code."+ )+ return False+ _IMPORTED_GENERATIONS[key] = digest+ return allowed+++def guard_entry_point_loaded(ep, group, loaded):+ """Keep cached objects revocable and bound to the reviewed generation."""+ from functools import wraps+ import inspect++ from deeptutor.plugins.manifest import approval_digest++ record = _entry_record(ep, group)+ if record is None:+ return loaded+ origin = get_plugin_registry().state_path.resolve()+ identity = approval_digest(record.manifest, record.artifact_identity)++ def allowed():+ try:+ current = _entry_record(ep, group)+ return (+ get_plugin_registry().state_path.resolve() == origin+ and current is not None+ and current.manifest is not None+ and entry_point_can_load(ep, group)+ and approval_digest(current.manifest, current.artifact_identity) == identity+ )+ except PluginStateError:+ return False++ def check():+ if not allowed():+ raise PluginRuntimeError(+ "Plugin is disabled, unapproved or belongs to another scope/generation."+ )++ def protect(obj):+ if inspect.isclass(obj):++ class Guarded(obj):+ def __init__(self, *args, **kwargs):+ check()+ super().__init__(*args, **kwargs)+ protect(self)++ Guarded._plugin_allowed = staticmethod(allowed)+ return Guarded+ for method in ("execute", "run", "run_action", "is_active", "create_capability"):+ original = getattr(obj, method, None)+ if not callable(original):+ continue+ if inspect.iscoroutinefunction(original):++ @wraps(original)+ async def asynchronous(*args, _original=original, **kwargs):+ check()+ return await _original(*args, **kwargs)++ setattr(obj, method, asynchronous)+ else:++ @wraps(original)+ def synchronous(*args, _original=original, **kwargs):+ check()+ return _original(*args, **kwargs)++ setattr(obj, method, synchronous)+ setattr(obj, "_plugin_allowed", allowed)+ return obj++ if inspect.isclass(loaded):+ return protect(loaded)+ if callable(loaded):++ @wraps(loaded)+ def factory(*args, **kwargs):+ check()+ return protect(loaded(*args, **kwargs))++ factory._plugin_allowed = allowed+ return factory+ return protect(loaded)+++def _managed_guard(manifest, installation, registry=None):+ from deeptutor.plugins.manifest import approval_digest++ registry = registry or get_plugin_registry()+ origin = get_plugin_registry().state_path.resolve()+ digest = approval_digest(manifest, installation.artifact_sha256)++ def check():+ current_registry = registry+ current = current_registry.get_plugin(manifest.id)+ if (+ get_plugin_registry().state_path.resolve() != origin+ or current is None+ or current.status != "enabled"+ or current.manifest is None+ or current.installation is None+ or approval_digest(current.manifest, current.installation.artifact_sha256) != digest+ or current.installation.python_path.resolve() != installation.python_path.resolve()+ ):+ raise PluginRuntimeError(+ "Plugin is disabled, unapproved or belongs to another scope/generation."+ )++ return check+++def _run_worker(argv, *, input, env, cwd):+ """Bound both worker time and captured output, without blocking the event loop."""+ import signal+ import threading+ from types import SimpleNamespace++ encoded = input.encode("utf-8")+ if len(encoded) > 1024 * 1024:+ raise PluginRuntimeError("Plugin worker request exceeds 1 MiB.")+ process = subprocess.Popen(+ argv,+ stdin=subprocess.PIPE,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ env=env,+ cwd=cwd,+ start_new_session=os.name != "nt",+ )+ buffers = {"stdout": bytearray(), "stderr": bytearray()}+ overflow = threading.Event()++ def stop():+ try:+ if os.name != "nt":+ os.killpg(process.pid, signal.SIGKILL)+ else:+ process.kill()+ except ProcessLookupError:+ pass++ def read(name, pipe, limit):+ while chunk := pipe.read(8192):+ if len(buffers[name]) + len(chunk) > limit:+ overflow.set()+ stop()+ return+ buffers[name].extend(chunk)++ def write():+ try:+ process.stdin.write(encoded)+ process.stdin.close()+ except (OSError, BrokenPipeError):+ pass++ threads = [+ threading.Thread(+ target=read, args=("stdout", process.stdout, 2 * 1024 * 1024), daemon=True+ ),+ threading.Thread(target=read, args=("stderr", process.stderr, 64 * 1024), daemon=True),+ threading.Thread(target=write, daemon=True),+ ]+ for thread in threads:+ thread.start()+ try:+ process.wait(timeout=60)+ except BaseException:+ stop()+ process.wait(timeout=3)+ raise+ finally:+ for thread in threads:+ thread.join(timeout=1)+ if any(thread.is_alive() for thread in threads):+ stop()+ if overflow.is_set() or any(thread.is_alive() for thread in threads):+ raise PluginRuntimeError("Plugin worker exceeded its output/process budget.")+ return SimpleNamespace(+ returncode=process.returncode,+ stdout=buffers["stdout"].decode("utf-8", "replace"),+ stderr=buffers["stderr"].decode("utf-8", "replace"),+ )+++def runtime_plugin_records(registry=None):+ try:+ return (registry or get_plugin_registry()).list_plugins(include_catalog=False)+ except PluginStateError:+ logger.warning(+ "Plugin state is invalid; runtime plugins are blocked and the original file is preserved."+ )+ return []diff --git a/deeptutor/plugins/transactions.py b/deeptutor/plugins/transactions.pynew file mode 100644index 000000000..87b8c2169--- /dev/null+++ b/deeptutor/plugins/transactions.py@@ -0,0 +1,50 @@+"""Nonblocking process ownership for plugin lifecycle/state transactions."""++from contextlib import contextmanager+from functools import wraps+import sys+++def serialized(method):+ @wraps(method)+ def call(self, *args, **kwargs):+ registry = getattr(self, "registry", self)+ with transaction(registry):+ return method(self, *args, **kwargs)++ return call+++@contextmanager+def transaction(registry):+ from deeptutor.plugins.registry import PluginStateError++ path = registry.state_path.with_suffix(".lock")+ path.parent.mkdir(parents=True, exist_ok=True)+ with path.open("a+b") as lease:+ try:+ if sys.platform == "win32":+ import msvcrt++ lease.seek(0)+ if not lease.read(1):+ lease.write(b"0")+ lease.flush()+ lease.seek(0)+ msvcrt.locking(lease.fileno(), msvcrt.LK_NBLCK, 1)+ else:+ import fcntl++ fcntl.flock(lease.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)+ except OSError as exc:+ raise PluginStateError(+ "Another plugin lifecycle transaction is active; retry after it finishes."+ ) from exc+ try:+ yield+ finally:+ if sys.platform == "win32":+ lease.seek(0)+ msvcrt.locking(lease.fileno(), msvcrt.LK_UNLCK, 1)+ else:+ fcntl.flock(lease.fileno(), fcntl.LOCK_UN)diff --git a/deeptutor/reading/extensions.py b/deeptutor/reading/extensions.pyindex dfe16087b..443432b40 100644--- a/deeptutor/reading/extensions.py+++ b/deeptutor/reading/extensions.py@@ -122,10 +122,18 @@ class ReadingExtensionRegistry:self._timed_out: set[str] = set()def all(self) -> list[ReadingExtension]:- return sorted(self._extensions.values(), key=lambda row: row.manifest.id)+ return sorted(+ (+ row+ for row in self._extensions.values()+ if getattr(row, "_plugin_allowed", lambda: True)()+ ),+ key=lambda row: row.manifest.id,+ )def get(self, extension_id: str) -> ReadingExtension | None:- return self._extensions.get(extension_id)+ row = self._extensions.get(extension_id)+ return row if row is not None and getattr(row, "_plugin_allowed", lambda: True)() else Nonedef begin_action(self, extension_id: str, *, circuit_break: bool = True) -> bool:"""Reserve one extension worker unless it is busy or circuit-broken.diff --git a/deeptutor/runtime/registry/capability_registry.py b/deeptutor/runtime/registry/capability_registry.pyindex 415045a74..d48e3af07 100644--- a/deeptutor/runtime/registry/capability_registry.py+++ b/deeptutor/runtime/registry/capability_registry.py@@ -45,7 +45,7 @@ def _turn_factory(loaded: object) -> tuple[TurnCapability, type[TurnCapability]]factory = producedelse:instance = produced- factory = type(produced)+ factory = objelse:instance = objfactory = type(obj)@@ -107,7 +107,11 @@ class CapabilityRegistry:if resolved is None:return Noneinstance, _factory = resolved- if self.catalog.get("turn", instance.name) is not None:+ existing = self.catalog.get("turn", instance.name)+ if (+ existing is not None+ and getattr(existing.factory, "_plugin_allowed", lambda: True)()+ ):logger.warning("Turn extension %s is already registered; ignoring", ep_name)return Noneself.register(loaded)@@ -138,14 +142,39 @@ class CapabilityRegistry:logger.debug("Legacy plugin loader unavailable", exc_info=True)def get(self, name: str) -> TurnCapability | None:+ if name not in BUILTIN_CAPABILITY_SPECS:+ from deeptutor.plugins.registry import PluginRegistry+ from deeptutor.plugins.runtime import PluginWorkerCapability, runtime_plugin_records++ for record in runtime_plugin_records(PluginRegistry()):+ if (+ record.status != "enabled"+ or record.manifest is None+ or record.installation is None+ ):+ continue+ if any(+ extension.type == "capability" and extension.id == name+ for extension in record.manifest.extensions+ ):+ return PluginWorkerCapability(+ manifest=record.manifest,+ installation=record.installation,+ extension_id=name,+ )+ if name not in BUILTIN_CAPABILITY_SPECS:+ self.load_plugins()+ entry = self.catalog.get("turn", name)+ if entry is not None and not getattr(entry.factory, "_plugin_allowed", lambda: True)():+ return Nonecapability = self.catalog.create("turn", name)return capability if isinstance(capability, TurnCapability) else Nonedef list_capabilities(self) -> list[str]:- return [entry.name for entry in self.catalog.entries("turn")]+ return [manifest["name"] for manifest in self.get_manifests()]def get_manifests(self) -> list[dict[str, Any]]:- return [+ manifests = [{"name": entry.name,"kind": entry.kind,@@ -161,7 +190,32 @@ class CapabilityRegistry:"config_defaults": entry.manifest.config_defaults,}for entry in self.catalog.entries("turn")+ if getattr(entry.factory, "_plugin_allowed", lambda: True)()]+ from deeptutor.plugins.runtime import runtime_plugin_records++ known = {row["name"] for row in manifests}+ for record in runtime_plugin_records():+ if record.status != "enabled" or record.manifest is None:+ continue+ for extension in record.manifest.extensions:+ if extension.type != "capability" or extension.id in known:+ continue+ manifests.append(+ {+ "name": extension.id,+ "kind": "turn",+ "description": record.description,+ "description_i18n": dict(record.manifest.description_i18n),+ "stages": [],+ "tools_used": [],+ "cli_aliases": [],+ "request_schema": EmptyConfig.model_json_schema(mode="validation"),+ "config_defaults": {},+ }+ )+ known.add(extension.id)+ return manifests_default_registry: CapabilityRegistry | None = Nonediff --git a/deeptutor/runtime/registry/tool_registry.py b/deeptutor/runtime/registry/tool_registry.pyindex 973a6f9a9..6f33a2cc1 100644--- a/deeptutor/runtime/registry/tool_registry.py+++ b/deeptutor/runtime/registry/tool_registry.py@@ -8,9 +8,11 @@ Provides lookup, listing, and OpenAI schema generation.from __future__ import annotations+import inspectimport loggingfrom typing import Any+from deeptutor.core.entry_points import load_entry_point_groupfrom deeptutor.core.tool_protocol import BaseTool, ToolDefinition, ToolPromptHintsfrom deeptutor.tools.builtin_specs import (BUILTIN_TOOL_NAMES,@@ -72,6 +74,27 @@ class ToolRegistry:logger.debug("Loaded built-in tool: %s", name)return tool+ def load_plugins(self) -> None:+ from deeptutor.plugins.registry import PluginRegistry+ from deeptutor.plugins.runtime import load_enabled_tools++ def coerce(name, loaded):+ candidate = loaded() if inspect.isclass(loaded) else loaded+ if callable(candidate) and not isinstance(candidate, BaseTool):+ candidate = candidate()+ if not isinstance(candidate, BaseTool):+ return None+ if candidate.name in BUILTIN_TOOL_SPEC_BY_NAME or candidate.name in self._tools:+ return None+ return candidate++ for tool in (+ *load_entry_point_group("deeptutor.tools", coerce, log=logger),+ *load_enabled_tools(PluginRegistry()),+ ):+ if tool.name not in BUILTIN_TOOL_SPEC_BY_NAME and tool.name not in self._tools:+ self.register(tool)+def _resolve_request(self,name: str,@@ -165,12 +188,23 @@ class ToolRegistry:_default_registry: ToolRegistry | None = None+_default_plugin_scope = Nonedef get_tool_registry() -> ToolRegistry:"""Return the global ToolRegistry (creating & loading builtins on first call)."""- global _default_registry- if _default_registry is None:+ global _default_registry, _default_plugin_scope+ from deeptutor.plugins.registry import PluginRegistry++ path = PluginRegistry().state_path+ try:+ stat = path.stat()+ scope = (str(path.resolve()), stat.st_mtime_ns, stat.st_size)+ except FileNotFoundError:+ scope = (str(path.resolve()), 0, 0)+ if _default_registry is None or _default_plugin_scope != scope:+ _default_plugin_scope = scope_default_registry = ToolRegistry()_default_registry.load_builtins()+ _default_registry.load_plugins()return _default_registrydiff --git a/deeptutor_cli/plugin.py b/deeptutor_cli/plugin.pyindex 8b59ed503..b5723e46e 100644--- a/deeptutor_cli/plugin.py+++ b/deeptutor_cli/plugin.py@@ -2,12 +2,14 @@CLI Plugin Command==================-List and inspect registered tools and capabilities.+List and inspect registered tools, capabilities, and plugin packages."""from __future__ import annotationsfrom dataclasses import asdict+import json+from pathlib import Pathfrom rich.console import Consolefrom rich.table import Table@@ -19,57 +21,62 @@ console = Console()def register(app: typer.Typer) -> None:@app.command("list")def plugin_list() -> None:- """List all registered tools and capabilities."""+ """List registered tools, capabilities, and plugin packages."""+ from deeptutor.plugins.registry import get_plugin_registryfrom deeptutor.runtime.registry.capability_registry import get_capability_registryfrom deeptutor.runtime.registry.tool_registry import get_tool_registry- tr = get_tool_registry()- cr = get_capability_registry()-table = Table(title="Registered Plugins")table.add_column("Name", style="bold")table.add_column("Type")+ table.add_column("Status")table.add_column("Description")- for defn in tr.get_definitions():- table.add_row(defn.name, "tool", defn.description[:80])+ for definition in get_tool_registry().get_definitions():+ table.add_row(definition.name, "tool", "enabled", definition.description[:80])++ for manifest in get_capability_registry().get_manifests():+ table.add_row(+ manifest["name"],+ "capability",+ "enabled",+ manifest["description"][:80],+ )- for m in cr.get_manifests():- table.add_row(m["name"], "capability", m["description"][:80])+ for record in get_plugin_registry().list_plugins():+ table.add_row(record.id, "plugin package", record.status, record.description[:80])console.print(table)@app.command("info")- def plugin_info(name: str = typer.Argument(..., help="Tool or capability name.")) -> None:- """Show details of a tool or capability."""- import json-+ def plugin_info(+ name: str = typer.Argument(..., help="Tool, capability, or plugin ID."),+ ) -> None:+ """Show details of a tool, capability, or plugin package."""+ from deeptutor.plugins.registry import get_plugin_registryfrom deeptutor.runtime.registry.capability_registry import get_capability_registryfrom deeptutor.runtime.registry.tool_registry import get_tool_registry- tr = get_tool_registry()- cr = get_capability_registry()-- tool = tr.get(name)+ tool = get_tool_registry().get(name)if tool:- defn = tool.get_definition()- console.print_json(json.dumps(defn.to_openai_schema(), indent=2))+ definition = tool.get_definition()+ console.print_json(json.dumps(definition.to_openai_schema(), indent=2))return- cap = cr.get(name)- if cap:+ capability = get_capability_registry().get(name)+ if capability:from deeptutor.app import DeepTutorAppavailability = DeepTutorApp().get_capability_availability(name)console.print_json(json.dumps({- "name": cap.manifest.name,- "description": cap.manifest.description,- "cli_aliases": cap.manifest.cli_aliases,- "stages": cap.manifest.stages,- "tools_used": cap.manifest.tools_used,- "config_defaults": cap.manifest.config_defaults,+ "name": capability.manifest.name,+ "description": capability.manifest.description,+ "cli_aliases": capability.manifest.cli_aliases,+ "stages": capability.manifest.stages,+ "tools_used": capability.manifest.tools_used,+ "config_defaults": capability.manifest.config_defaults,"availability": asdict(availability),},indent=2,@@ -77,5 +84,221 @@ def register(app: typer.Typer) -> None:)return+ record = get_plugin_registry().get_plugin(name)+ if record is not None:+ console.print_json(json.dumps(record.to_dict(), indent=2))+ return+console.print(f"[red]'{name}' not found.[/]")raise typer.Exit(code=1)++ @app.command("state")+ def plugin_state() -> None:+ """Show installed, catalog, approval, and compatibility state."""+ from deeptutor.plugins.registry import get_plugin_registry++ table = Table(title="Plugin Packages")+ table.add_column("ID", style="bold")+ table.add_column("Version")+ table.add_column("Status")+ table.add_column("Description")++ records = get_plugin_registry().list_plugins()+ if not records:+ table.add_row("-", "-", "empty", "No plugin packages are installed or cataloged")+ for record in records:+ table.add_row(record.id, record.version, record.status, record.description[:100])+ console.print(table)++ @app.command("search")+ def plugin_search(+ query: str = typer.Argument("", help="Search official catalog metadata."),+ ) -> None:+ """Search the vendored official plugin catalog."""+ from deeptutor.plugins.catalog import search_catalog++ table = Table(title="Official Plugin Catalog")+ table.add_column("ID", style="bold")+ table.add_column("Version")+ table.add_column("Status")+ table.add_column("Description")++ entries = search_catalog(query)+ if not entries:+ table.add_row("-", "-", "empty", "No matching catalog entries")+ for entry in entries:+ table.add_row(+ entry.id,+ entry.version,+ entry.status,+ entry.description_i18n.get("en", "")[:100],+ )+ console.print(table)++ @app.command("show")+ def plugin_show(+ plugin_id: str = typer.Argument(..., help="Installed or catalog plugin ID."),+ ) -> None:+ """Show full plugin package metadata."""+ from deeptutor.plugins.catalog import get_catalog_entry+ from deeptutor.plugins.registry import PluginRecord, get_plugin_registry++ record = get_plugin_registry().get_plugin(plugin_id)+ if record is None:+ entry = get_catalog_entry(plugin_id)+ if entry is None:+ console.print(f"[red]Plugin package '{plugin_id}' not found.[/]")+ raise typer.Exit(code=1) from None+ record = PluginRecord(+ id=entry.id,+ status="deprecated" if entry.status == "deprecated" else "available",+ catalog_entry=entry,+ )+ console.print_json(json.dumps(record.to_dict(), indent=2))++ @app.command("enable")+ def plugin_enable(plugin_id: str = typer.Argument(..., help="Installed plugin ID.")) -> None:+ """Record an installed plugin package as enabled."""+ from deeptutor.plugins.registry import PluginStateError, get_plugin_registry++ try:+ record = get_plugin_registry().set_enabled(plugin_id, True)+ except PluginStateError as exc:+ console.print(f"[red]{exc}[/]")+ raise typer.Exit(code=1) from None+ console.print(f"[green]{record.id} is {record.status}.[/]")++ @app.command("approve")+ def plugin_approve(plugin_id: str = typer.Argument(..., help="Installed plugin ID.")) -> None:+ """Approve the exact permissions declared by an installed plugin."""+ from deeptutor.plugins.registry import PluginStateError, get_plugin_registry++ try:+ record = get_plugin_registry().approve(plugin_id)+ except PluginStateError as exc:+ console.print(f"[red]{exc}[/]")+ raise typer.Exit(code=1) from None+ console.print(f"[green]{record.id} permissions approved; status is {record.status}.[/]")++ @app.command("install")+ def plugin_install(+ artifact: str = typer.Argument(+ ..., help="Local reviewed wheel or reviewed catalog plugin ID."+ ),+ sha256: str = typer.Option("", help="Expected artifact SHA-256."),+ version: str = typer.Option(+ "latest", help="Catalog version to install, or latest stable version."+ ),+ allow_deprecated: bool = typer.Option(+ False, help="Allow an explicitly deprecated catalog version."+ ),+ timeout: float = typer.Option(60.0, help="Artifact download timeout in seconds."),+ ) -> None:+ """Install a local or catalog-pinned wheel in an isolated environment."""+ import json as json_module++ from deeptutor.plugins.lifecycle import (+ PluginLifecycleError,+ PluginLifecycleManager,+ )++ local_artifact = Path(artifact)+ is_local_wheel = artifact.lower().endswith(".whl") or local_artifact.exists()+ if not is_local_wheel:+ from deeptutor.plugins.distribution import (+ CatalogInstallManager,+ PluginDistributionError,+ )++ if sha256:+ console.print("[red]--sha256 is only valid for a local wheel.[/]")+ raise typer.Exit(code=1)+ try:+ result = CatalogInstallManager().install(+ artifact,+ version=version,+ allow_deprecated=allow_deprecated,+ timeout_seconds=timeout,+ )+ except (PluginDistributionError, PluginLifecycleError) as exc:+ console.print(f"[red]{exc}[/]")+ raise typer.Exit(code=1) from None+ console.print_json(+ json_module.dumps(+ {+ "plugin": result.lifecycle.plugin_id,+ "version": result.lifecycle.version,+ "action": result.lifecycle.action,+ "artifact_url": result.artifact_url,+ "sha256": result.lifecycle.artifact_sha256,+ "venv": str(result.lifecycle.venv_path),+ "next_step": "review permissions, then run deeptutor plugin approve",+ },+ indent=2,+ )+ )+ return++ try:+ lifecycle_result = PluginLifecycleManager().install(+ local_artifact,+ expected_sha256=sha256,+ )+ except PluginLifecycleError as exc:+ console.print(f"[red]{exc}[/]")+ raise typer.Exit(code=1) from None+ console.print_json(+ json_module.dumps(+ {+ "plugin": lifecycle_result.plugin_id,+ "version": lifecycle_result.version,+ "action": lifecycle_result.action,+ "sha256": lifecycle_result.artifact_sha256,+ "venv": str(lifecycle_result.venv_path),+ "next_step": "review permissions, then run deeptutor plugin approve",+ },+ indent=2,+ )+ )++ @app.command("rollback")+ def plugin_rollback(plugin_id: str = typer.Argument(..., help="Installed plugin ID.")) -> None:+ """Restore the previous managed plugin version."""+ from deeptutor.plugins.lifecycle import (+ PluginLifecycleError,+ PluginLifecycleManager,+ )++ try:+ result = PluginLifecycleManager().rollback(plugin_id)+ except PluginLifecycleError as exc:+ console.print(f"[red]{exc}[/]")+ raise typer.Exit(code=1) from None+ console.print(f"[green]{result.plugin_id} rolled back to {result.version}.[/]")++ @app.command("uninstall")+ def plugin_uninstall(plugin_id: str = typer.Argument(..., help="Installed plugin ID.")) -> None:+ """Remove a managed plugin, its environments, artifacts, and state."""+ from deeptutor.plugins.lifecycle import (+ PluginLifecycleError,+ PluginLifecycleManager,+ )++ try:+ result = PluginLifecycleManager().uninstall(plugin_id)+ except PluginLifecycleError as exc:+ console.print(f"[red]{exc}[/]")+ raise typer.Exit(code=1) from None+ console.print(f"[green]{result.plugin_id} {result.version} removed.[/]")++ @app.command("disable")+ def plugin_disable(plugin_id: str = typer.Argument(..., help="Installed plugin ID.")) -> None:+ """Record an installed plugin package as disabled."""+ from deeptutor.plugins.registry import PluginStateError, get_plugin_registry++ try:+ record = get_plugin_registry().set_enabled(plugin_id, False)+ except PluginStateError as exc:+ console.print(f"[red]{exc}[/]")+ raise typer.Exit(code=1) from None+ console.print(f"[green]{record.id} is {record.status}.[/]")diff --git a/docs/plugin-platform-rfc.md b/docs/plugin-platform-rfc.mdnew file mode 100644index 000000000..0749a84bd--- /dev/null+++ b/docs/plugin-platform-rfc.md@@ -0,0 +1,399 @@+# DeepTutor Plugin Platform RFC (Phase C and Catalog E)++Status: accepted implementation slice+Schema: `deeptutor.plugin/v1`+Last reviewed: 2026-09-08++## Problem++DeepTutor already has several isolated extension mechanisms: capability+plugins, loop capabilities, Reading extensions, tools, and the newer+visualizer catalog. Third-party developers cannot describe one package with+one identity, compatibility matrix, permission disclosure, artifact pin, and+marketplace state. The absence of that root contract makes every extension+point invent its own distribution and trust model.++The plugin platform therefore standardizes package metadata and catalog state+first. It does not attempt to make every extension use one universal runtime+API.++## Non-goals for this slice++- No arbitrary Chrome CRX/extension loading. Chrome extensions assume browser+ APIs, extension process boundaries, and a browser permission model that do+ not map safely to a Python server process.+- No arbitrary URL installation, background update check, or automatic upgrade.+ Catalog installation is an explicit command that resolves a vendored,+ reviewed artifact pin before downloading.+- No claim that Python permission fields create an OS sandbox. They define the+ approval and runtime contract boundary. Managed Tool and Capability workers+ run in a separate Python process with a plugin-private environment, but that+ process boundary is dependency isolation, not a hard security sandbox.+- No replacement of the existing `deeptutor.plugins` capability loader,+ `deeptutor.loop_capabilities`, or `deeptutor.reading_extensions` entry-point+ behavior. Those loaders now honor an approved root manifest whenever a+ package declares one; packages without a root manifest retain the migration+ window.+- Learning Experience widgets/events are intentionally deferred.++## Root manifest++A Python plugin ships `deeptutor.plugin.json` inside its package or wheel. The+file is static JSON and must be readable without importing the plugin.++```json+{+ "schema_version": "deeptutor.plugin/v1",+ "id": "org.author.example",+ "name": "Example Plugin",+ "version": "1.0.0",+ "description_i18n": {+ "en": "Example extension package",+ "zh": "示例扩展包"+ },+ "author": "Author Name",+ "license": "Apache-2.0",+ "homepage": "https://example.com",+ "source_url": "https://github.com/author/example",+ "compatibility": {+ "deeptutor": ">=1.6.0,<2",+ "api": {+ "capability": "1",+ "loop_capability": "1",+ "http_route": "1",+ "frontend_page": "1",+ "persistence_schema": "1",+ "app_connector": "1",+ "tool": "1",+ "reading_extension": "1",+ "visualizer": "1"+ }+ },+ "permissions": {+ "reading": ["selection", "visible_text"],+ "learning_events": [],+ "network": ["https://api.example.com"],+ "models": [],+ "storage": ["plugin-private"],+ "ui": ["sandboxed-iframe"]+ },+ "dependencies": ["requests>=2.32,<3"],+ "extensions": [+ {+ "type": "reading_extension",+ "id": "translation",+ "entry_point": "translation"+ },+ {+ "type": "visualizer",+ "id": "fraction_tiles",+ "manifest": "visualizers/fraction_tiles/visualizer.json"+ },+ {+ "type": "http_route",+ "id": "study_summary",+ "entry_point": "example_plugin.worker",+ "path": "/study/summary",+ "methods": ["GET", "POST"],+ "auth": "authenticated"+ }+ ]+}+```++The manifest parser rejects unknown fields. This is deliberate: the root file+is a public compatibility contract, and silently accepting misspelled fields+would make plugin behavior depend on the DeepTutor release.++### Extension types++| Type | Meaning | Current behavior |+| --- | --- | --- |+| `capability` | Turn-owning capability | Existing entry points load only after manifest approval; managed workers load through the JSON subprocess adapter |+| `loop_capability` | Chat-loop capability | Existing entry points load only after manifest approval |+| `tool` | Single-shot LLM tool | Existing entry points load only after manifest approval; managed workers load through the JSON subprocess adapter |+| `reading_extension` | Reading toolbar/action extension | Existing entry point remains authoritative and loads only after manifest approval |+| `visualizer` | Packaged visualizer asset bundle | Manifest declaration; bundle manifest is not eagerly read |+| `http_route` | Managed JSON HTTP endpoint | Approved managed routes execute in the plugin venv worker |+| `frontend_page` | Declared plugin page | Packaged static pages are served through a host-gated asset route with an explicit asset closure and restrictive CSP |+| `persistence_schema` | Declared plugin data schema | Authenticated introspection only; migrations and data access are future work |+| `app_connector` | Declared downstream application adapter | Authenticated introspection only; adapter execution is future work |++Each extension has one stable `id`. Python-backed extensions declare+`entry_point`; visualizers declare their packaged bundle `manifest`. A root+manifest may contain multiple extensions, but it does not grant a universal+runtime API. Runtime code still binds each extension to its typed protocol.++`http_route` and `frontend_page` declare static paths beginning with `/`.+HTTP route methods are limited to `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`;+authentication is exactly one of `public`, `authenticated`, or `admin`.+Persistence schemas declare a packaged JSON file and named operations. App+connectors declare named operations. Unknown fields remain invalid for every+extension type.++Built-in DeepTutor IDs always win. A plugin cannot replace a built-in+capability, tool, Reading action, or visualizer by reusing its ID.++`dependencies` is an explicit, ordered closure. Requirements must be PEP 508+name-and-version constraints; direct URLs, environment markers, extras, and+duplicate canonical names are rejected. Managed installation passes every+requirement plus the plugin wheel to the plugin-private interpreter with+`pip install --no-deps --only-binary=:all:`, so pip cannot mutate the host environment or discover+a different transitive graph at install time.++## Registry states++`PluginRegistry` reads installed distribution files and the vendored catalog.+It never calls `entry_point.load()` and never imports third-party code.++| State | Meaning |+| --- | --- |+| `available` | Catalog entry is not installed |+| `approval-required` | Installed and compatible, but its exact permission snapshot has not been approved |+| `enabled` | Installed, compatible, and not locally disabled |+| `disabled` | Installed and locally disabled |+| `incompatible` | Installed, but its DeepTutor or API contract is not supported |+| `broken` | Manifest unreadable/invalid, duplicate ID, or cannot be represented |+| `deprecated` | Catalog or review metadata marks the plugin obsolete |++A malformed installed manifest affects only that plugin. A malformed catalog+row affects only that row. Existing entry-point loaders keep their containment+behavior.++Local enablement is persisted as:++```json+{+ "version": 2,+ "disabled": [],+ "plugins": {+ "org.author.example": {+ "manifest": {},+ "installation": null,+ "history": [],+ "approval": {+ "digest": "sha256-of-manifest-and-artifact-identity",+ "approved_at": "2026-09-08T00:00:00Z"+ }+ }+ }+}+```++The file is written atomically under `data/user/settings/plugins.json`. The+legacy version 1 `{version, disabled}` shape is read as version 2 with no+plugin rows; the legacy file itself is not rewritten until another plugin state+operation commits.++`approval.digest` binds the complete normalized manifest and the installed+artifact identity. Managed installs use the reviewed wheel SHA-256; external+distributions use their version and RECORD identity. A manifest, version or+artifact change invalidates approval even when permissions are unchanged.+External distribution upgrades require a process restart to replace already+imported host modules; managed workers start from their version-private environment. Approval does not automatically enable a locally+disabled plugin.++Managed installation records also retain the installed package root. Records+written before this field existed remain valid; executable frontend pages do+not guess or scan for that root and return 404 until the plugin is reinstalled+or upgraded.++## Official catalog++The official catalog is a vendored, manually reviewed JSON snapshot. Browsing+and version resolution do not make a live third-party registry request:++- schema `deeptutor.plugin-catalog/v2` has one row per immutable+ `(plugin ID, version)` pair; legacy v1 snapshots remain readable but cannot+ be remote-install sources;+- the package requirement is pinned;+- the distribution artifact has a direct immutable HTTPS wheel URL, SHA-256+ digest, exact byte size, and non-empty platform tags;+- compatibility and permissions are repeated from review-time metadata;+- status is `available`, `deprecated`, or `hidden`;+- malformed or duplicate rows are dropped without invalidating the catalog;+- `latest` resolves only the newest available non-prerelease version; exact+ versions must match the catalog string, deprecated versions require an+ explicit flag, and hidden rows are never returned.++The initial snapshot is intentionally empty. DeepTutor maintainers must not+invent third-party plugins to seed it. Real entries are added only with source+review, artifact pinning, and recorded reviewers.++## Catalog distribution++`deeptutor plugin install <plugin-id>` resolves a row in the vendored catalog,+downloads only that row's reviewed HTTPS URL, and then invokes the local+lifecycle with the catalog digest. Redirects are rejected, the download has a+timeout and bounded size, `Content-Length` must match the reviewed size, and+the streamed bytes must match both size and SHA-256 before installation. A+failed download removes its temporary wheel and never reaches pip or plugin+state. The URL is review metadata, not a CLI input: there is no arbitrary URL+install path and no automatic update check.++## Managed lifecycle++`PluginLifecycleManager` installs only an existing local wheel. That wheel can+come from the explicit local command or the verified catalog downloader. It+reads and validates the root manifest directly from the zip archive before+creating an environment or importing plugin code. An optional local `--sha256`+pin and the mandatory catalog pin are checked before install. The reviewed+artifact is copied under the plugin's managed root, and each plugin version+receives its own virtual environment.++Installation, upgrade, same-version reinstall, and rollback all clear the+previous approval. This is deliberate: the user approved an exact permission,+artifact, and manifest snapshot, not an implicit trust transfer to another+version. Failed dependency installation leaves the current version, approval,+and environment unchanged. A successful upgrade keeps the prior version+directory and environment for rollback; rollback moves the current version to+history and restores the prior environment. Uninstall removes the managed state,+artifacts, environments, and local enable/disable entry for that plugin.++Managed Tool and Capability extensions use a worker module entry point such as+`learning_echo.worker`. DeepTutor launches that module with the plugin venv+interpreter, exchanges one JSON request and response over stdin/stdout, and+rejects worker declarations whose permission snapshot exceeds the approved+manifest. Existing Python entry-point extensions continue to load classes or+factories in the host process, but only after the root-manifest gate accepts+them.++## Managed HTTP and introspection API++Managed HTTP routes are always dispatched under+`/api/plugins/{plugin-id}{path}`. They cannot override a built-in route and are+resolved from plugin state once at the start of each request. Only an approved,+compatible, enabled, managed installation with an installation record can+expose a route.+Unapproved, incompatible, broken, deprecated, disabled, external, and missing+routes all return the same HTTP 404 response.++The host performs route authentication before launching the worker. A public+route has no host credential dependency; `authenticated` uses the normal+session/bearer dependency; `admin` uses the host admin dependency. The worker+request contains only the declared method and path, normalized query values,+a JSON body no larger than 1 MiB, and the manifest's auth policy. Cookies,+bearer tokens, and raw host request headers are never forwarded.++Workers implement `handle_http` and return one JSON object containing a+response `status`, JSON `body`, and optional headers. Allowed statuses are the+normal application statuses the plugin can own (`200`, `201`, `202`, `204`,+`400`, `404`, `409`, `422`, and `500`); authentication and redirect statuses+belong to the host. `Cache-Control` is the only worker-provided response+header, with values limited to `no-store`, `no-cache`, or `max-age=<seconds>`.+The host always sets the JSON media type. Invalid worker output becomes a+generic HTTP 500 response and affects only that plugin request.++`GET /api/plugins/extensions` is authenticated and enumerates the extension+declarations of approved, enabled, managed installations. It is the discovery+surface for persistence schemas and app connectors. An executable+`frontend_page` also includes `entry_url`.++## Managed frontend pages++A `frontend_page` that declares a packaged page manifest executes as static+browser assets, not as host React or Next code. The page manifest is a separate+JSON contract (`deeptutor.plugin-frontend-page/v1`) with one `entry` and an+explicit `assets` closure. Paths are relative to the installed package root,+must be regular files, cannot be symlinks, and are limited to small web asset+types and aggregate sizes.++The host serves the canonical page URL+`/api/plugins/{plugin-id}/pages/{extension-id}/`; the non-slash form redirects+to it so relative asset URLs resolve predictably. It serves declared asset+paths only after registry gating and the manifest's host authentication+policy. Responses use `no-store` and `nosniff`, and carry a restrictive CSP with+`sandbox allow-scripts`,+`connect-src 'none'`, no framing by third parties, and no plugin-controlled+response headers. The entry document uses same-origin resource policy while+declared assets use `Cross-Origin-Resource-Policy: cross-origin`; the sandboxed+document has an opaque origin, so same-origin asset policy would block its own+packaged scripts. This gives static plugin UI a browser execution context+without injecting untrusted code into DeepTutor's frontend bundle. It is not a+signature system and does not remove the need for plugin review.++## Trust and compatibility++The current trust model is human curation plus pinned metadata. Catalog+browsing and version resolution remain offline. Local installation accepts a+wheel and verifies an optional artifact digest before invoking pip; catalog+installation additionally binds the download URL, size, and digest to the+reviewed snapshot. Signing and a process/container security sandbox are+separate future phases and must not be implied by this catalog format.++Python permissions are disclosure and approval metadata in v1. Existing+entry-point extensions still execute in the host Python process after approval.+Managed worker extensions execute outside the host process but retain host+operating-system access. Reviewers and users need that fact to be visible; OS+scope enforcement belongs to a later isolation design.++Reading extensions continue to use the server-verified Reading context and+restricted result types. A plugin cannot widen its context by changing its+manifest declaration.++Visualizers that need untrusted HTML/UI execution use the existing sandboxed+iframe model. Their packaged asset manifests and renderer contracts remain+separate typed specs. Managed frontend pages use their own explicit asset+closure and CSP sandbox rather than the visualizer runtime.++## Chrome compatibility++Direct Chrome extension reuse is out of scope. A future compatibility layer can+target a narrow subset, but it must translate a Chrome extension into a typed+DeepTutor extension declaration and a review record. It must not import Chrome+background/service-worker code into DeepTutor or hand browser-level authority+to a Python plugin. Marketplace distribution remains based on Python packages;+Chrome-specific assets may ship as resources inside such a package.++## Delivery phases++1. **Phase A - contract**: root manifest validation, RFC, catalog schema.+2. **Phase B - visibility**: metadata-only installed/catalog registry and CLI+ state/search/show/enable/disable commands.+3. **Phase C - runtime gating**: existing capability, loop, Reading, and tool+ loaders respect local enablement and manifest compatibility.+4. **Phase D - visualizer loading**: package visualizer manifests into the+ v1.6.2-style visualizer catalog while preserving built-in precedence.+5. **Phase E - installation**: pinned artifact download, digest verification,+ and an explicit user-approved installation flow.+6. **Phase F - sandbox/signing**: stronger isolation, signatures, and developer+ publishing workflow.++This repository currently implements Phases A through C, plus the local-wheel+and catalog-driven remote installation, approval, Tool/Capability/HTTP worker,+upgrade, rollback, uninstall, and managed introspection slice of Phase E.+Developer publishing automation, persistence migrations, app connector+execution, visualizer packaging, signing, and a stronger sandbox remain future+phases.++## Local dev completion of Phase 1 (#1307)++Root-manifest gates run before every `entry_point.load()` through the shared+loader, including legacy and reading groups. Cached objects recheck scope,+approval, generation and enablement before execution. Legacy packages without a+root manifest retain compatibility during migration. Private worker execution+uses a 60-second deadline, 1 MiB request budget, 2 MiB stdout budget and 64 KiB+stderr budget; async tool/capability/HTTP calls run off the event loop.++State mutations and lifecycle work have nonblocking process ownership. Corrupt+state is preserved and rejected. Version artifacts are immutable; failed+same-version installs preserve the prior environment and bytes. Rollback+verifies the retained artifact hash and clears approval. Installation accepts+wheel-only dependencies so installing an unapproved package does not build a+source distribution. Dependency constraints are disclosed; dependency hash+signatures and stronger isolation remain on the ecosystem roadmap above.++Authenticated API inspection includes `GET /api/plugins/catalog`, `/state`,+`/{id}/info` and `/extensions`. Admin mutations include `POST /{id}/install`+(reviewed catalog version), `/approve` (requires the inspected `snapshot_digest`),+`/enable`, `/disable`, `/rollback`, and `DELETE /{id}/installation`. CLI also+supports local wheel installation with an optional expected SHA-256. Install,+upgrade and rollback all require fresh approval. The vendored catalog starts+empty; the packaged learning_echo example exercises the real wheel/worker/static+page path without inventing third-party catalog entries.++Host authentication establishes the user scope before resolving any HTTP route+or frontend asset. With host authentication enabled, even a manifest's `public`+route needs a host session; `public` means no additional plugin-specific admin+check. No bearer token, cookie or authentication header is forwarded to workers.+The host's normal authentication-disabled local mode remains usable.diff --git a/examples/plugins/learning_echo/README.md b/examples/plugins/learning_echo/README.mdnew file mode 100644index 000000000..73251b2e7--- /dev/null+++ b/examples/plugins/learning_echo/README.md@@ -0,0 +1,20 @@+# Learning Echo plugin++This package is the reference implementation for the managed plugin runtime.+It declares one Tool, one Capability, one HTTP route, and one static frontend+page. The page requests only the `sandboxed-iframe` UI permission; the package+has no Python dependencies.++Build a local wheel:++```bash+python -m pip wheel --no-deps -w /tmp/deeptutor-plugins examples/plugins/learning_echo+```++Install, review, approve, and roll back through `deeptutor plugin`. The install+step reads `deeptutor.plugin.json` before importing plugin code and creates a+plugin-private virtual environment.++After approval and enablement, the page is available at+`/api/plugins/org.deeptutor.learning_echo/pages/learning_echo_page/`. Its entry+and asset closure are declared in `learning_echo/frontend/page.json`.diff --git a/examples/plugins/learning_echo/learning_echo/__init__.py b/examples/plugins/learning_echo/learning_echo/__init__.pynew file mode 100644index 000000000..f44577cb8--- /dev/null+++ b/examples/plugins/learning_echo/learning_echo/__init__.py@@ -0,0 +1 @@+"""Minimal dependency-free DeepTutor plugin worker."""diff --git a/examples/plugins/learning_echo/learning_echo/deeptutor.plugin.json b/examples/plugins/learning_echo/learning_echo/deeptutor.plugin.jsonnew file mode 100644index 000000000..6f9792235--- /dev/null+++ b/examples/plugins/learning_echo/learning_echo/deeptutor.plugin.json@@ -0,0 +1,59 @@+{+ "schema_version": "deeptutor.plugin/v1",+ "id": "org.deeptutor.learning_echo",+ "name": "Learning Echo Example",+ "version": "1.0.0",+ "description_i18n": {+ "en": "Minimal approved Tool and Capability worker example",+ "zh": "最小化的已审批 Tool 与 Capability worker 示例"+ },+ "author": "DeepTutor",+ "license": "Apache-2.0",+ "homepage": "https://github.com/HKUDS/DeepTutor",+ "source_url": "https://github.com/HKUDS/DeepTutor",+ "compatibility": {+ "deeptutor": ">=1.6.0,<3",+ "api": {+ "tool": "1",+ "capability": "1",+ "http_route": "1",+ "frontend_page": "1"+ }+ },+ "permissions": {+ "reading": [],+ "learning_events": [],+ "network": [],+ "models": [],+ "storage": [],+ "ui": ["sandboxed-iframe"]+ },+ "dependencies": [],+ "extensions": [+ {+ "type": "tool",+ "id": "learning_echo",+ "entry_point": "learning_echo.worker"+ },+ {+ "type": "capability",+ "id": "learning_echo_capability",+ "entry_point": "learning_echo.worker"+ },+ {+ "type": "http_route",+ "id": "learning_echo_http",+ "entry_point": "learning_echo.worker",+ "path": "/echo",+ "methods": ["POST"],+ "auth": "public"+ },+ {+ "type": "frontend_page",+ "id": "learning_echo_page",+ "path": "/learning-echo",+ "auth": "authenticated",+ "manifest": "frontend/page.json"+ }+ ]+}diff --git a/examples/plugins/learning_echo/learning_echo/frontend/app.js b/examples/plugins/learning_echo/learning_echo/frontend/app.jsnew file mode 100644index 000000000..647988d44--- /dev/null+++ b/examples/plugins/learning_echo/learning_echo/frontend/app.js@@ -0,0 +1,2 @@+document.getElementById("status").textContent =+ "Learning Echo page is running in its restricted asset context.";diff --git a/examples/plugins/learning_echo/learning_echo/frontend/index.html b/examples/plugins/learning_echo/learning_echo/frontend/index.htmlnew file mode 100644index 000000000..23720dd3f--- /dev/null+++ b/examples/plugins/learning_echo/learning_echo/frontend/index.html@@ -0,0 +1,15 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <title>Learning Echo</title>+ </head>+ <body>+ <main>+ <h1>Learning Echo</h1>+ <p id="status">Static plugin page loaded.</p>+ </main>+ <script src="assets/frontend/app.js"></script>+ </body>+</html>diff --git a/examples/plugins/learning_echo/learning_echo/frontend/page.json b/examples/plugins/learning_echo/learning_echo/frontend/page.jsonnew file mode 100644index 000000000..155ef0881--- /dev/null+++ b/examples/plugins/learning_echo/learning_echo/frontend/page.json@@ -0,0 +1,5 @@+{+ "schema_version": "deeptutor.plugin-frontend-page/v1",+ "entry": "frontend/index.html",+ "assets": ["frontend/app.js", "frontend/index.html"]+}diff --git a/examples/plugins/learning_echo/learning_echo/worker.py b/examples/plugins/learning_echo/learning_echo/worker.pynew file mode 100644index 000000000..1f3c7559b--- /dev/null+++ b/examples/plugins/learning_echo/learning_echo/worker.py@@ -0,0 +1,101 @@+"""JSON worker protocol for the Learning Echo example.++The host launches this module with the plugin venv interpreter. It reads one+request, returns one JSON response, and never imports DeepTutor host modules.+"""++from __future__ import annotations++import json+import sys+from typing import Any+++def main() -> None:+ request = json.loads(sys.stdin.read())+ operation = request.get("operation")+ if operation == "describe_tool":+ response = describe_tool()+ elif operation == "execute_tool":+ response = execute_tool(request.get("arguments") or {})+ elif operation == "describe_capability":+ response = describe_capability()+ elif operation == "run_capability":+ response = run_capability(request.get("context") or {})+ elif operation == "handle_http":+ response = handle_http(request.get("http") or {})+ else:+ response = {"error": f"unknown operation: {operation}"}+ print(json.dumps(response, ensure_ascii=False))+++def describe_tool() -> dict[str, Any]:+ return {+ "permissions": {},+ "definition": {+ "name": "learning_echo",+ "description": "Echo a learning prompt back with a stable prefix.",+ "parameters": [+ {+ "name": "message",+ "type": "string",+ "description": "Text to echo",+ "required": True,+ }+ ],+ },+ }+++def execute_tool(arguments: dict[str, Any]) -> dict[str, Any]:+ message = str(arguments.get("message", "")).strip()+ if not message:+ return {"result": {"content": "message is required", "success": False}}+ return {"result": {"content": f"learning echo: {message}", "success": True}}+++def describe_capability() -> dict[str, Any]:+ return {+ "permissions": {},+ "capability": {+ "name": "learning_echo_capability",+ "description": "Emit a one-event learning echo capability result.",+ "stages": ["responding"],+ },+ }+++def run_capability(context: dict[str, Any]) -> dict[str, Any]:+ message = str(context.get("user_message", "")).strip() or "empty learning turn"+ return {+ "permissions": {},+ "events": [+ {+ "type": "content",+ "stage": "responding",+ "content": f"learning capability echo: {message}",+ }+ ],+ }+++def handle_http(http: dict[str, Any]) -> dict[str, Any]:+ body = http.get("body")+ message = str(body.get("message", "")) if isinstance(body, dict) else ""+ return {+ "permissions": {},+ "http": {+ "status": 200,+ "headers": {"Cache-Control": "no-store"},+ "body": {+ "method": http.get("method"),+ "path": http.get("path"),+ "message": message,+ "auth": http.get("auth"),+ },+ },+ }+++if __name__ == "__main__":+ main()diff --git a/examples/plugins/learning_echo/pyproject.toml b/examples/plugins/learning_echo/pyproject.tomlnew file mode 100644index 000000000..543010e50--- /dev/null+++ b/examples/plugins/learning_echo/pyproject.toml@@ -0,0 +1,16 @@+[build-system]+requires = ["setuptools>=61"]+build-backend = "setuptools.build_meta"++[project]+name = "deeptutor-learning-echo"+version = "1.0.0"+description = "Minimal DeepTutor Tool and Capability plugin example"+requires-python = ">=3.11"+dependencies = []++[tool.setuptools]+packages = ["learning_echo"]++[tool.setuptools.package-data]+learning_echo = ["deeptutor.plugin.json", "frontend/*"]diff --git a/packaging/deeptutor-cli/pyproject.toml b/packaging/deeptutor-cli/pyproject.tomlindex 43d7b824a..22d124cad 100644--- a/packaging/deeptutor-cli/pyproject.toml+++ b/packaging/deeptutor-cli/pyproject.toml@@ -24,6 +24,7 @@ dependencies = ["tenacity>=8.0.0","pydantic>=2.0.0","pydantic-settings>=2.0.0",+ "packaging>=24.2","jsonschema>=4.20.0,<5.0.0","aiosqlite>=0.19.0","typer>=0.9.0",diff --git a/pyproject.toml b/pyproject.tomlindex 345ab6968..0f5bc7c5e 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -30,6 +30,7 @@ dependencies = ["tenacity>=8.0.0","pydantic>=2.0.0","pydantic-settings>=2.0.0",+ "packaging>=24.2","jsonschema>=4.20.0,<5.0.0","aiosqlite>=0.19.0","typer>=0.9.0",@@ -108,6 +109,7 @@ translation = "deeptutor.reading.translation:TranslationExtension"# already included in the public `deeptutor` wheel; the local CLI-only project# under `packaging/deeptutor-cli` uses the same list without Web assets/server deps.cli = [+ "packaging>=24.2",# LLM provider SDKs"anthropic>=0.30.0","dashscope>=1.14.0",diff --git a/requirements/cli.txt b/requirements/cli.txtindex f93536dee..092bdaa1a 100644--- a/requirements/cli.txt+++ b/requirements/cli.txt@@ -34,6 +34,7 @@ tenacity>=8.0.0# --- Data models & storage ---pydantic>=2.0.0pydantic-settings>=2.0.0+packaging>=24.2jsonschema>=4.20.0,<5.0.0aiosqlite>=0.19.0diff --git a/tests/api/test_plugins_router.py b/tests/api/test_plugins_router.pynew file mode 100644index 000000000..f86e34cee--- /dev/null+++ b/tests/api/test_plugins_router.py@@ -0,0 +1,582 @@+"""HTTP and introspection contracts for managed plugin extensions."""++from __future__ import annotations++import base64+import hashlib+from html.parser import HTMLParser+import json+from pathlib import Path+import sys+from typing import Any+from urllib.parse import urljoin+import zipfile++import pytest++try:+ from fastapi import FastAPI, HTTPException, Request+ from fastapi.testclient import TestClient+except Exception: # pragma: no cover+ FastAPI = None+ TestClient = None++from deeptutor.plugins.lifecycle import PluginLifecycleManager+from deeptutor.plugins.manifest import parse_manifest+from deeptutor.plugins.registry import PluginInstallation, PluginRegistry+from deeptutor.plugins.runtime import PluginHttpResponse++pytestmark = pytest.mark.skipif(+ FastAPI is None or TestClient is None, reason="fastapi not installed"+)+++def _raw_manifest() -> dict[str, Any]:+ return {+ "schema_version": "deeptutor.plugin/v1",+ "id": "org.deeptutor.learning_echo",+ "name": "Learning Echo Example",+ "version": "1.0.0",+ "description_i18n": {"en": "Example"},+ "author": "DeepTutor",+ "license": "Apache-2.0",+ "homepage": "https://example.com",+ "source_url": "https://example.com/source",+ "compatibility": {+ "deeptutor": ">=1.6,<3",+ "api": {+ "http_route": "1",+ "frontend_page": "1",+ "persistence_schema": "1",+ "app_connector": "1",+ },+ },+ "permissions": {"network": []},+ "dependencies": [],+ "extensions": [+ {+ "type": "http_route",+ "id": "learning_echo_http",+ "entry_point": "learning_echo.worker",+ "path": "/echo",+ "methods": ["POST"],+ "auth": "public",+ },+ {+ "type": "frontend_page",+ "id": "echo_page",+ "path": "/echo",+ "auth": "authenticated",+ },+ {+ "type": "persistence_schema",+ "id": "echo_store",+ "schema": "schemas/echo.json",+ "operations": ["read"],+ },+ {+ "type": "app_connector",+ "id": "echo_connector",+ "operations": ["import-course"],+ },+ ],+ }+++def _installation(tmp_path: Path) -> PluginInstallation:+ venv_path = tmp_path / "venv"+ venv_path.mkdir(exist_ok=True)+ return PluginInstallation(+ version="1.0.0",+ artifact_path=tmp_path / "learning_echo.whl",+ artifact_sha256="0" * 64,+ venv_path=venv_path,+ python_path=Path(sys.executable),+ installed_at="2026-09-08T00:00:00+00:00",+ )+++def _registry(tmp_path: Path, *, external: bool = False) -> PluginRegistry:+ manifest = parse_manifest(_raw_manifest())+ registry = PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[],+ deeptutor_version="1.6.0",+ )+ state = registry.state_snapshot()+ state["plugins"][manifest.id] = {+ "manifest": manifest.to_dict(),+ "installation": None if external else _installation(tmp_path).to_dict(),+ "history": [],+ }+ registry.replace_state(state)+ return registry+++def _frontend_registry(tmp_path: Path, *, legacy_installation: bool = False) -> PluginRegistry:+ raw = _raw_manifest()+ raw["permissions"]["ui"] = ["sandboxed-iframe"]+ raw["extensions"][1]["manifest"] = "frontend/page.json"+ package_path = tmp_path / "package"+ frontend_path = package_path / "frontend"+ frontend_path.mkdir(parents=True)+ (frontend_path / "page.json").write_text(+ json.dumps(+ {+ "schema_version": "deeptutor.plugin-frontend-page/v1",+ "entry": "frontend/index.html",+ "assets": ["frontend/app.js", "frontend/index.html"],+ }+ ),+ encoding="utf-8",+ )+ (frontend_path / "index.html").write_text(+ '<html><body>plugin page<script src="assets/frontend/app.js"></script></body></html>',+ encoding="utf-8",+ )+ (frontend_path / "app.js").write_text("console.log('ready')", encoding="utf-8")+ (package_path / "secret.txt").write_text("secret", encoding="utf-8")++ manifest = parse_manifest(raw)+ registry = PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[],+ deeptutor_version="1.6.0",+ )+ installation = _installation(tmp_path)+ if not legacy_installation:+ installation = PluginInstallation(+ **{**installation.to_dict(), "package_path": package_path}+ )+ state = registry.state_snapshot()+ state["plugins"][manifest.id] = {+ "manifest": manifest.to_dict(),+ "installation": installation.to_dict(),+ "history": [],+ }+ registry.replace_state(state)+ return registry+++def _record_line(name: str, payload: bytes) -> str:+ digest = base64.urlsafe_b64encode(hashlib.sha256(payload).digest()).rstrip(b"=")+ return f"{name},sha256={digest.decode('ascii')},{len(payload)}"+++class _ScriptSourceParser(HTMLParser):+ def __init__(self) -> None:+ super().__init__()+ self.sources: list[str] = []++ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:+ if tag == "script":+ self.sources.extend(value for key, value in attrs if key == "src" and value)+++def client() -> TestClient:+ from deeptutor.api.routers import plugins++ app = FastAPI()+ app.include_router(plugins.router, prefix="/api/plugins")+ return TestClient(app)+++def _use_registry(monkeypatch: pytest.MonkeyPatch, registry: PluginRegistry) -> None:+ from deeptutor.api.routers import plugins++ monkeypatch.setattr(plugins, "_registry_factory", lambda: registry)+++def test_introspection_lists_only_approved_enabled_managed_extensions(+ client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ registry = _registry(tmp_path)+ _use_registry(monkeypatch, registry)++ assert client.get("/api/plugins/extensions").json() == {"plugins": []}++ registry.approve("org.deeptutor.learning_echo")+ body = client.get("/api/plugins/extensions").json()++ assert [plugin["id"] for plugin in body["plugins"]] == ["org.deeptutor.learning_echo"]+ assert [extension["type"] for extension in body["plugins"][0]["extensions"]] == [+ "http_route",+ "frontend_page",+ "persistence_schema",+ "app_connector",+ ]++ registry.set_enabled("org.deeptutor.learning_echo", False)+ assert client.get("/api/plugins/extensions").json() == {"plugins": []}+++def test_introspection_requires_authentication(+ client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from deeptutor.api.routers import plugins++ _use_registry(monkeypatch, _registry(tmp_path))++ async def reject(+ *, authorization: str | None = None, dt_token: str | None = None, request=None+ ) -> None:+ raise HTTPException(status_code=401, detail="Authentication required")++ monkeypatch.setattr(plugins, "require_auth", reject)+ assert client.get("/api/plugins/extensions").status_code == 401+++def test_managed_frontend_page_serves_only_declared_assets(+ client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ registry = _frontend_registry(tmp_path)+ _use_registry(monkeypatch, registry)+ base = "/api/plugins/org.deeptutor.learning_echo/pages/echo_page/"++ assert client.get(base).status_code == 404++ registry.approve("org.deeptutor.learning_echo")+ redirect = client.get(base.rstrip("/"), follow_redirects=False)+ extensions = client.get("/api/plugins/extensions").json()["plugins"][0]["extensions"]+ page = client.get(base)+ parser = _ScriptSourceParser()+ parser.feed(page.text)+ assert parser.sources == ["assets/frontend/app.js"]+ asset = client.get(urljoin(str(page.url), parser.sources[0]))+ secret = client.get(f"{base}/assets/secret.txt")++ assert redirect.status_code == 307+ assert redirect.headers["location"] == base+ assert extensions[1]["entry_url"] == base+ assert page.status_code == 200+ assert "plugin page" in page.text+ assert page.headers["content-type"].startswith("text/html")+ assert "sandbox allow-scripts" in page.headers["content-security-policy"]+ assert page.headers["x-content-type-options"] == "nosniff"+ assert page.headers["cross-origin-resource-policy"] == "same-origin"+ assert asset.status_code == 200+ assert asset.text == "console.log('ready')"+ assert asset.headers["cross-origin-resource-policy"] == "cross-origin"+ assert secret.status_code == 404+++def test_frontend_page_host_auth_and_legacy_installation_boundary(+ client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from deeptutor.api.routers import plugins++ auth_registry = _frontend_registry(tmp_path / "auth")+ legacy_registry = _frontend_registry(tmp_path / "legacy", legacy_installation=True)+ auth_registry.approve("org.deeptutor.learning_echo")+ legacy_registry.approve("org.deeptutor.learning_echo")+ original_auth = plugins.require_auth+ _use_registry(monkeypatch, auth_registry)++ async def reject(+ *, authorization: str | None = None, dt_token: str | None = None, request=None+ ) -> None:+ raise HTTPException(status_code=401, detail="Authentication required")++ monkeypatch.setattr(plugins, "require_auth", reject)+ assert client.get("/api/plugins/org.deeptutor.learning_echo/pages/echo_page").status_code == 401++ _use_registry(monkeypatch, legacy_registry)+ monkeypatch.setattr(plugins, "require_auth", original_auth)+ assert client.get("/api/plugins/org.deeptutor.learning_echo/pages/echo_page").status_code == 404+++async def test_host_auth_dependencies_receive_request_credentials(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from types import SimpleNamespace++ from deeptutor.api.routers import plugins++ request = SimpleNamespace(+ headers={"Authorization": "Bearer host-token"},+ cookies={"dt_token": "host-cookie"},+ )+ captured: dict[str, str] = {}++ async def fake_require_auth(+ *, authorization: str | None, dt_token: str | None, request=None+ ) -> str:+ captured["authorization"] = authorization or ""+ captured["dt_token"] = dt_token or ""+ return "payload"++ async def fake_require_admin(*, payload: str) -> str:+ captured["admin_payload"] = payload+ return "admin"++ monkeypatch.setattr(plugins, "require_auth", fake_require_auth)+ monkeypatch.setattr(plugins, "require_admin", fake_require_admin)++ await plugins._require_authenticated(request)+ await plugins._require_admin(request)++ assert captured == {+ "authorization": "Bearer host-token",+ "dt_token": "host-cookie",+ "admin_payload": "payload",+ }+++def test_managed_route_requires_approval_and_enablement(+ client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ registry = _registry(tmp_path)+ _use_registry(monkeypatch, registry)++ assert client.post("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 404++ registry.approve("org.deeptutor.learning_echo")+ assert client.post("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 500++ registry.set_enabled("org.deeptutor.learning_echo", False)+ assert client.post("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 404+++def test_external_distributions_cannot_expose_managed_http_routes(+ client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ registry = _registry(tmp_path, external=True)+ _use_registry(monkeypatch, registry)++ assert client.get("/api/plugins/extensions").json() == {"plugins": []}+ assert client.post("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 404+++def test_http_route_auth_is_enforced_by_host_without_forwarding_credentials(+ client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from deeptutor.api.routers import plugins++ registry = _registry(tmp_path)+ registry.approve("org.deeptutor.learning_echo")+ _use_registry(monkeypatch, registry)+ captured: dict[str, Any] = {}++ class StubRoute:+ def __init__(self, **kwargs: Any) -> None:+ self.extension = kwargs["manifest"].extensions[0]++ def handle(self, **kwargs: Any) -> PluginHttpResponse:+ captured.update(kwargs)+ return PluginHttpResponse(status=200, body={"ok": True})++ monkeypatch.setattr(plugins, "PluginWorkerHttpRoute", StubRoute)+ headers = {"Authorization": "Bearer secret", "Cookie": "session=secret"}++ public = client.post(+ "/api/plugins/org.deeptutor.learning_echo/echo",+ json={"message": "hello"},+ headers=headers,+ )+ assert public.status_code == 200+ assert captured == {+ "method": "POST",+ "path": "/echo",+ "query": {},+ "body": {"message": "hello"},+ }++ async def reject_auth(+ *, authorization: str | None = None, dt_token: str | None = None, request=None+ ) -> None:+ raise HTTPException(status_code=401, detail="Authentication required")++ async def allow_auth(+ *, authorization: str | None = None, dt_token: str | None = None, request=None+ ) -> str:+ return "payload"++ async def reject_admin(*, payload: object = None) -> None:+ raise HTTPException(status_code=403, detail="Admin access required")++ state = registry.state_snapshot()+ manifest = parse_manifest(state["plugins"]["org.deeptutor.learning_echo"]["manifest"])+ for policy, reject in (("authenticated", reject_auth), ("admin", reject_admin)):+ extension = manifest.extensions[0]+ object.__setattr__(extension, "auth", policy)+ state["plugins"]["org.deeptutor.learning_echo"]["manifest"] = manifest.to_dict()+ registry.replace_state(state)+ registry.approve("org.deeptutor.learning_echo")+ monkeypatch.setattr(+ plugins,+ "require_auth",+ reject_auth if policy == "authenticated" else allow_auth,+ )+ monkeypatch.setattr(plugins, "require_admin", reject_admin)+ response = client.post(+ "/api/plugins/org.deeptutor.learning_echo/echo",+ json={},+ headers=headers,+ )+ assert response.status_code == (401 if policy == "authenticated" else 403)+++def test_http_route_rejects_disallowed_method_and_malformed_json(+ client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ registry = _registry(tmp_path)+ registry.approve("org.deeptutor.learning_echo")+ _use_registry(monkeypatch, registry)++ assert client.get("/api/plugins/org.deeptutor.learning_echo/echo").status_code == 405+ assert (+ client.post(+ "/api/plugins/org.deeptutor.learning_echo/echo",+ content=b"{invalid",+ headers={"Content-Type": "application/json"},+ ).status_code+ == 400+ )+++def test_real_wheel_http_flow_uses_managed_worker_subprocess(+ client: TestClient, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ raw = _raw_manifest()+ raw["permissions"]["ui"] = ["sandboxed-iframe"]+ raw["extensions"][1]["manifest"] = "frontend/page.json"+ wheel_path = tmp_path / "learning_echo-1.0.0-py3-none-any.whl"+ source_root = Path(__file__).parents[2] / "examples" / "plugins" / "learning_echo"+ files = {+ "learning_echo/deeptutor.plugin.json": json.dumps(raw).encode("utf-8"),+ "learning_echo/__init__.py": (+ '"""Minimal dependency-free DeepTutor plugin worker."""\n'+ ).encode("utf-8"),+ "learning_echo/worker.py": (source_root / "learning_echo" / "worker.py").read_bytes(),+ "learning_echo/frontend/page.json": (+ source_root / "learning_echo" / "frontend" / "page.json"+ ).read_bytes(),+ "learning_echo/frontend/index.html": (+ source_root / "learning_echo" / "frontend" / "index.html"+ ).read_bytes(),+ "learning_echo/frontend/app.js": (+ source_root / "learning_echo" / "frontend" / "app.js"+ ).read_bytes(),+ "learning_echo-1.0.0.dist-info/METADATA": ("Name: learning-echo\nVersion: 1.0.0\n").encode(+ "utf-8"+ ),+ "learning_echo-1.0.0.dist-info/WHEEL": (+ "Wheel-Version: 1.0\nRoot-Is-Purelib: true\nTag: py3-none-any\n"+ ).encode("utf-8"),+ }+ with zipfile.ZipFile(wheel_path, "w") as archive:+ for name, payload in files.items():+ archive.writestr(name, payload)+ record_name = "learning_echo-1.0.0.dist-info/RECORD"+ archive.writestr(+ record_name,+ "\n".join([_record_line(name, payload) for name, payload in files.items()])+ + f"\n{record_name},,\n",+ )++ registry = PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[],+ deeptutor_version="1.6.0",+ )+ manager = PluginLifecycleManager(registry, root=tmp_path / "plugin-root")+ manager.install(wheel_path)+ registry.approve("org.deeptutor.learning_echo")+ _use_registry(monkeypatch, registry)+ record = registry.get_plugin("org.deeptutor.learning_echo")+ assert record is not None and record.installation is not None++ response = client.post(+ "/api/plugins/org.deeptutor.learning_echo/echo?tag=math",+ json={"message": "hello"},+ headers={"Authorization": "Bearer must-not-forward", "Cookie": "session=secret"},+ )++ assert response.status_code == 200+ assert response.headers["cache-control"] == "no-store"+ assert response.json() == {+ "method": "POST",+ "path": "/echo",+ "message": "hello",+ "auth": "public",+ }++ page = client.get("/api/plugins/org.deeptutor.learning_echo/pages/echo_page")+ parser = _ScriptSourceParser()+ parser.feed(page.text)+ assert parser.sources == ["assets/frontend/app.js"]+ asset = client.get(urljoin(str(page.url), parser.sources[0]))++ assert page.status_code == 200+ assert "Learning Echo" in page.text+ assert "sandbox allow-scripts" in page.headers["content-security-policy"]+ assert asset.status_code == 200+ assert "restricted asset context" in asset.text+++def test_lifecycle_api_uses_reviewed_snapshot_and_admin_authority(client, tmp_path, monkeypatch):+ from deeptutor.api.routers import plugins++ registry = _registry(tmp_path)+ _use_registry(monkeypatch, registry)+ info = client.get("/api/plugins/org.deeptutor.learning_echo/info").json()+ assert info["status"] == "approval-required"+ assert (+ client.post(+ "/api/plugins/org.deeptutor.learning_echo/approve", json={"snapshot_digest": "0" * 64}+ ).status_code+ == 409+ )+ approved = client.post(+ "/api/plugins/org.deeptutor.learning_echo/approve",+ json={"snapshot_digest": info["approval_digest"]},+ )+ assert approved.json()["status"] == "enabled"+ assert (+ client.post("/api/plugins/org.deeptutor.learning_echo/disable").json()["status"]+ == "disabled"+ )+ assert (+ client.post("/api/plugins/org.deeptutor.learning_echo/enable").json()["status"] == "enabled"+ )++ async def reject(request: Request):+ raise HTTPException(403, "Admin access required")++ client.app.dependency_overrides[plugins._require_admin] = reject+ try:+ assert client.post("/api/plugins/org.deeptutor.learning_echo/disable").status_code == 403+ finally:+ client.app.dependency_overrides.clear()+++def test_host_identity_is_established_before_resolving_scoped_plugin_state(+ client, tmp_path, monkeypatch+):+ from deeptutor.api.routers import plugins++ registry = _registry(tmp_path)+ registry.approve("org.deeptutor.learning_echo")+ order = []++ async def authenticate(request):+ order.append("authenticated")+ return None++ def scoped_registry():+ assert order and order[0] == "authenticated"+ return registry++ class Worker:+ def __init__(self, **kwargs):+ pass++ def handle(self, **kwargs):+ return PluginHttpResponse(status=200, body={"ok": True})++ monkeypatch.setattr(plugins, "_require_authenticated", authenticate)+ monkeypatch.setattr(plugins, "_registry_factory", scoped_registry)+ monkeypatch.setattr(plugins, "PluginWorkerHttpRoute", Worker)+ assert client.post("/api/plugins/org.deeptutor.learning_echo/echo", json={}).status_code == 200diff --git a/tests/plugins/test_catalog.py b/tests/plugins/test_catalog.pynew file mode 100644index 000000000..86976ca21--- /dev/null+++ b/tests/plugins/test_catalog.py@@ -0,0 +1,194 @@+"""Catalog snapshot parsing must fail per row, not per store."""++from __future__ import annotations++import json+from pathlib import Path++import pytest++from deeptutor.plugins.catalog import (+ CATALOG_SCHEMA_VERSION,+ CatalogResolutionError,+ CatalogValidationError,+ load_catalog,+ parse_catalog_entry,+ resolve_catalog_entry,+)+++def _entry(plugin_id: str = "org.author.example") -> dict:+ return {+ "id": plugin_id,+ "name": "Example Plugin",+ "version": "1.0.0",+ "description_i18n": {"en": "Example extension package"},+ "author": "Author Name",+ "license": "Apache-2.0",+ "homepage": "https://example.com",+ "source_url": "https://github.com/author/example",+ "compatibility": {"deeptutor": ">=1.6.0,<2", "api": {"tool": "1"}},+ "permissions": {"network": ["https://api.example.com"]},+ "dependencies": ["helper==2.0"],+ "artifact": {+ "kind": "python-package",+ "requirement": "example-plugin==1.0.0",+ "sha256": "0" * 64,+ "url": "https://artifacts.example.com/example-plugin-1.0.0.whl",+ "size_bytes": 128,+ "platform_tags": ["py3-none-any"],+ },+ }+++def test_catalog_entry_requires_pinned_python_artifact() -> None:+ entry = parse_catalog_entry(_entry())++ assert entry.id == "org.author.example"+ assert entry.artifact.requirement == "example-plugin==1.0.0"+ assert entry.artifact.sha256 == "0" * 64+ assert entry.to_dict()["dependencies"] == ["helper==2.0"]+++def test_catalog_entry_rejects_unpinned_requirement() -> None:+ raw = _entry()+ raw["artifact"]["requirement"] = "example-plugin>=1.0"++ with pytest.raises(CatalogValidationError, match="exactly one == pin"):+ parse_catalog_entry(raw)+++def test_catalog_v1_remains_readable_without_download_metadata() -> None:+ raw = _entry()+ raw["artifact"].pop("url")+ raw["artifact"].pop("size_bytes")+ raw["artifact"].pop("platform_tags")++ entry = parse_catalog_entry(raw, schema_version="deeptutor.plugin-catalog/v1")++ assert entry.artifact.url == ""+ assert entry.to_dict()["artifact"] == {+ "kind": "python-package",+ "requirement": "example-plugin==1.0.0",+ "sha256": "0" * 64,+ }+++def test_catalog_v2_requires_complete_download_pin() -> None:+ raw = _entry()+ raw["artifact"]["url"] = "http://artifacts.example.com/example.whl"++ with pytest.raises(CatalogValidationError, match="HTTPS URL"):+ parse_catalog_entry(raw)++ raw["artifact"]["url"] = "https://artifacts.example.com/example.zip"+ with pytest.raises(CatalogValidationError, match="wheel"):+ parse_catalog_entry(raw)+++def test_catalog_v2_rejects_requirement_version_mismatch() -> None:+ raw = _entry()+ raw["artifact"]["requirement"] = "example-plugin==1.0.1"++ with pytest.raises(CatalogValidationError, match="entry version must match"):+ parse_catalog_entry(raw)+++def test_malformed_catalog_row_does_not_hide_valid_rows(tmp_path) -> None:+ valid = _entry()+ invalid = _entry("org.author.broken")+ invalid["artifact"]["sha256"] = "not-a-hash"+ payload = {+ "schema_version": CATALOG_SCHEMA_VERSION,+ "meta": {+ "generated_at": "2026-08-31T00:00:00Z",+ "reviewed_at": "2026-08-31T00:00:00Z",+ "reviewers": ["maintainer"],+ },+ "entries": [invalid, valid],+ }+ path = tmp_path / "catalog.json"+ path.write_text(json.dumps(payload), encoding="utf-8")++ entries = load_catalog(path)++ assert [entry.id for entry in entries] == ["org.author.example"]+++def test_resolver_selects_latest_stable_and_exact_catalog_versions(tmp_path) -> None:+ payload = _catalog(+ _entry(),+ _version_entry("1.1.0"),+ _version_entry("1.2.0b1"),+ _version_entry("1.0.0", status="deprecated"),+ )+ path = tmp_path / "catalog.json"+ path.write_text(json.dumps(payload), encoding="utf-8")++ latest = resolve_catalog_entry("org.author.example", path=path)+ exact = resolve_catalog_entry("org.author.example", "1.0.0", path=path)+ prerelease = resolve_catalog_entry("org.author.example", "1.2.0b1", path=path)++ assert latest.version == "1.1.0"+ assert exact.version == "1.0.0"+ assert prerelease.version == "1.2.0b1"+++def test_prerelease_is_install_explicit_but_browsable(tmp_path) -> None:+ path = _catalog_json(tmp_path, _version_entry("1.0.0b1"))++ with pytest.raises(CatalogResolutionError, match="stable"):+ resolve_catalog_entry("org.author.example", path=path)+ assert (+ resolve_catalog_entry("org.author.example", allow_prerelease=True, path=path).version+ == "1.0.0b1"+ )+++def test_resolver_requires_opt_in_for_deprecated_and_never_sees_hidden(+ tmp_path,+) -> None:+ payload = _catalog(+ _version_entry("1.0.0", status="deprecated"),+ _version_entry("1.1.0", status="hidden"),+ )+ path = tmp_path / "catalog.json"+ path.write_text(json.dumps(payload), encoding="utf-8")++ with pytest.raises(CatalogResolutionError, match="--allow-deprecated"):+ resolve_catalog_entry("org.author.example", "1.0.0", path=path)+ assert (+ resolve_catalog_entry(+ "org.author.example", "1.0.0", allow_deprecated=True, path=path+ ).version+ == "1.0.0"+ )+ with pytest.raises(CatalogResolutionError, match="not available"):+ resolve_catalog_entry("org.author.example", "1.1.0", path=path)+++def _version_entry(version: str, *, status: str = "available") -> dict:+ raw = _entry()+ raw["version"] = version+ raw["status"] = status+ raw["artifact"]["requirement"] = f"example-plugin=={version}"+ raw["artifact"]["url"] = f"https://artifacts.example.com/example-{version}.whl"+ return raw+++def _catalog(*entries: dict) -> dict:+ return {+ "schema_version": CATALOG_SCHEMA_VERSION,+ "meta": {+ "generated_at": "2026-08-31T00:00:00Z",+ "reviewed_at": "2026-08-31T00:00:00Z",+ "reviewers": ["maintainer"],+ },+ "entries": list(entries),+ }+++def _catalog_json(tmp_path, *entries: dict) -> Path:+ path = tmp_path / "catalog.json"+ path.write_text(json.dumps(_catalog(*entries)), encoding="utf-8")+ return pathdiff --git a/tests/plugins/test_cli.py b/tests/plugins/test_cli.pynew file mode 100644index 000000000..8743b95ca--- /dev/null+++ b/tests/plugins/test_cli.py@@ -0,0 +1,275 @@+"""CLI visibility for the unified plugin package registry."""++from __future__ import annotations++from pathlib import Path+from types import SimpleNamespace++import typer+from typer.testing import CliRunner++import deeptutor.plugins.catalog as plugin_catalog+import deeptutor.plugins.registry as plugin_registry+from deeptutor_cli.plugin import register+++def _plugin_cli(monkeypatch) -> typer.Typer:+ app = typer.Typer()+ register(app)+ return app+++def test_plugin_state_lists_package_status(monkeypatch) -> None:+ monkeypatch.setattr(+ plugin_registry,+ "get_plugin_registry",+ lambda: SimpleNamespace(+ list_plugins=lambda: [+ SimpleNamespace(+ id="org.author.example",+ version="1.0.0",+ status="enabled",+ description="Example package",+ )+ ]+ ),+ )+ app = _plugin_cli(monkeypatch)++ result = CliRunner().invoke(app, ["state"])++ assert result.exit_code == 0, result.output+ assert "org.author.example" in result.output+ assert "enabled" in result.output+++def test_plugin_search_uses_official_catalog(monkeypatch) -> None:+ monkeypatch.setattr(+ plugin_catalog,+ "search_catalog",+ lambda query: [+ SimpleNamespace(+ id="org.author.example",+ version="1.0.0",+ status="available",+ description_i18n={"en": "Example package"},+ )+ ],+ )+ app = _plugin_cli(monkeypatch)++ result = CliRunner().invoke(app, ["search", "example"])++ assert result.exit_code == 0, result.output+ assert "org.author.example" in result.output+ assert "available" in result.output+++def test_plugin_disable_and_enable_write_state(monkeypatch) -> None:+ calls: list[tuple[str, bool]] = []++ def set_enabled(plugin_id: str, enabled: bool):+ calls.append((plugin_id, enabled))+ return SimpleNamespace(id=plugin_id, status="enabled" if enabled else "disabled")++ monkeypatch.setattr(+ plugin_registry,+ "get_plugin_registry",+ lambda: SimpleNamespace(set_enabled=set_enabled),+ )+ app = _plugin_cli(monkeypatch)++ disabled = CliRunner().invoke(app, ["disable", "org.author.example"])+ enabled = CliRunner().invoke(app, ["enable", "org.author.example"])++ assert disabled.exit_code == 0, disabled.output+ assert enabled.exit_code == 0, enabled.output+ assert calls == [("org.author.example", False), ("org.author.example", True)]+++def test_plugin_show_outputs_package_metadata(monkeypatch) -> None:+ monkeypatch.setattr(+ plugin_registry,+ "get_plugin_registry",+ lambda: SimpleNamespace(+ get_plugin=lambda plugin_id: SimpleNamespace(+ to_dict=lambda: {+ "id": plugin_id,+ "status": "enabled",+ "manifest": {"schema_version": "deeptutor.plugin/v1"},+ }+ )+ ),+ )+ app = _plugin_cli(monkeypatch)++ result = CliRunner().invoke(app, ["show", "org.author.example"])++ assert result.exit_code == 0, result.output+ assert '"schema_version": "deeptutor.plugin/v1"' in result.output+++def test_plugin_approve_writes_permission_state(monkeypatch) -> None:+ calls: list[str] = []++ def approve(plugin_id: str):+ calls.append(plugin_id)+ return SimpleNamespace(id=plugin_id, status="enabled")++ monkeypatch.setattr(+ plugin_registry,+ "get_plugin_registry",+ lambda: SimpleNamespace(approve=approve),+ )+ app = _plugin_cli(monkeypatch)++ result = CliRunner().invoke(app, ["approve", "org.author.example"])++ assert result.exit_code == 0, result.output+ assert calls == ["org.author.example"]+ assert "permissions approved" in result.output+++def test_plugin_install_reports_reviewed_wheel(monkeypatch) -> None:+ calls: list[tuple[Path, str]] = []++ class FakeManager:+ def install(self, artifact: Path, *, expected_sha256: str):+ calls.append((artifact, expected_sha256))+ return SimpleNamespace(+ plugin_id="org.author.example",+ version="1.0.0",+ action="installed",+ artifact_sha256="0" * 64,+ venv_path=Path("/tmp/plugins/org.author.example/versions/1.0.0/venv"),+ )++ monkeypatch.setattr("deeptutor.plugins.lifecycle.PluginLifecycleManager", FakeManager)+ app = _plugin_cli(monkeypatch)++ result = CliRunner().invoke(+ app,+ [+ "install",+ "/tmp/example-1.0.0.whl",+ "--sha256",+ "0" * 64,+ ],+ )++ assert result.exit_code == 0, result.output+ assert calls == [(Path("/tmp/example-1.0.0.whl"), "0" * 64)]+ assert '"plugin": "org.author.example"' in result.output+ assert '"next_step": "review permissions' in result.output+++def test_plugin_install_uses_reviewed_catalog_pin(monkeypatch) -> None:+ calls: list[dict[str, object]] = []++ class FakeCatalogManager:+ def install(+ self,+ plugin_id: str,+ *,+ version: str,+ allow_deprecated: bool,+ timeout_seconds: float,+ ):+ calls.append(+ {+ "plugin_id": plugin_id,+ "version": version,+ "allow_deprecated": allow_deprecated,+ "timeout_seconds": timeout_seconds,+ }+ )+ return SimpleNamespace(+ artifact_url="https://artifacts.example.com/example-1.0.0.whl",+ lifecycle=SimpleNamespace(+ plugin_id=plugin_id,+ version="1.0.0",+ action="installed",+ artifact_sha256="0" * 64,+ venv_path=Path("/tmp/plugins/org.author.example/versions/1.0/venv"),+ ),+ )++ monkeypatch.setattr("deeptutor.plugins.distribution.CatalogInstallManager", FakeCatalogManager)+ app = _plugin_cli(monkeypatch)++ result = CliRunner().invoke(+ app,+ [+ "install",+ "org.author.example",+ "--version",+ "1.0.0",+ "--allow-deprecated",+ "--timeout",+ "12",+ ],+ )++ assert result.exit_code == 0, result.output+ assert calls == [+ {+ "plugin_id": "org.author.example",+ "version": "1.0.0",+ "allow_deprecated": True,+ "timeout_seconds": 12.0,+ }+ ]+ assert '"artifact_url"' in result.output+ assert '"sha256": "' + "0" * 64 in result.output+++def test_plugin_catalog_install_rejects_local_digest_override(monkeypatch) -> None:+ class UnexpectedManager:+ def __init__(self) -> None:+ raise AssertionError("remote catalog install must not accept a digest override")++ monkeypatch.setattr("deeptutor.plugins.distribution.CatalogInstallManager", UnexpectedManager)+ app = _plugin_cli(monkeypatch)++ result = CliRunner().invoke(app, ["install", "org.author.example", "--sha256", "0" * 64])++ assert result.exit_code == 1+ assert "--sha256 is only valid for a local wheel" in result.output+++def test_plugin_rollback_and_uninstall_use_managed_lifecycle(monkeypatch) -> None:+ actions: list[str] = []++ class FakeManager:+ def rollback(self, plugin_id: str):+ actions.append(("rollback", plugin_id))+ return SimpleNamespace(+ plugin_id=plugin_id,+ version="1.0.0",+ artifact_sha256="0" * 64,+ venv_path=Path("/tmp/plugins/org.author.example/versions/1.0.0/venv"),+ )++ def uninstall(self, plugin_id: str):+ actions.append(("uninstall", plugin_id))+ return SimpleNamespace(+ plugin_id=plugin_id,+ version="1.1.0",+ artifact_sha256="0" * 64,+ venv_path=Path("/tmp/plugins/org.author.example"),+ )++ monkeypatch.setattr("deeptutor.plugins.lifecycle.PluginLifecycleManager", FakeManager)+ app = _plugin_cli(monkeypatch)++ rollback = CliRunner().invoke(app, ["rollback", "org.author.example"])+ uninstall = CliRunner().invoke(app, ["uninstall", "org.author.example"])++ assert rollback.exit_code == 0, rollback.output+ assert uninstall.exit_code == 0, uninstall.output+ assert actions == [+ ("rollback", "org.author.example"),+ ("uninstall", "org.author.example"),+ ]+ assert "rolled back to 1.0.0" in rollback.output+ assert "1.1.0 removed" in uninstall.outputdiff --git a/tests/plugins/test_distribution.py b/tests/plugins/test_distribution.pynew file mode 100644index 000000000..5a0e542d3--- /dev/null+++ b/tests/plugins/test_distribution.py@@ -0,0 +1,168 @@+"""Reviewed catalog artifact download and install handoff tests."""++from __future__ import annotations++import hashlib+from pathlib import Path+from types import SimpleNamespace++import httpx+import pytest++from deeptutor.plugins.distribution import (+ CatalogArtifactDownloader,+ CatalogInstallManager,+ PluginDistributionError,+)+++def _artifact(payload: bytes) -> SimpleNamespace:+ return SimpleNamespace(+ url="https://artifacts.example.com/example-1.0.0-py3-none-any.whl",+ size_bytes=len(payload),+ sha256=hashlib.sha256(payload).hexdigest(),+ )+++def _client(response: httpx.Response) -> httpx.Client:+ return httpx.Client(+ transport=httpx.MockTransport(lambda request: response),+ follow_redirects=False,+ )+++def test_downloader_verifies_reviewed_size_and_digest(tmp_path: Path) -> None:+ payload = b"valid-wheel-bytes"+ downloader = CatalogArtifactDownloader(+ client_factory=lambda timeout: _client(+ httpx.Response(+ 200,+ content=payload,+ headers={"content-length": str(len(payload))},+ )+ )+ )++ result = downloader.download(_artifact(payload), destination_dir=tmp_path)++ assert result.path.read_bytes() == payload+ assert result.path.suffix == ".whl"+ assert result.sha256 == hashlib.sha256(payload).hexdigest()+ assert result.size_bytes == len(payload)+++def test_downloader_rejects_redirect_and_declared_size_mismatch(+ tmp_path: Path,+) -> None:+ redirect = CatalogArtifactDownloader(+ client_factory=lambda timeout: _client(+ httpx.Response(302, headers={"location": "https://other.example.com/artifact.whl"})+ )+ )+ size_mismatch = CatalogArtifactDownloader(+ client_factory=lambda timeout: _client(+ httpx.Response(200, content=b"12345", headers={"content-length": "5"})+ )+ )+ artifact = _artifact(b"1234")++ with pytest.raises(PluginDistributionError, match="redirects are not allowed"):+ redirect.download(artifact, destination_dir=tmp_path)+ with pytest.raises(+ PluginDistributionError, match="Content-Length does not match reviewed size"+ ):+ size_mismatch.download(artifact, destination_dir=tmp_path)+ assert list(tmp_path.iterdir()) == []+++def test_downloader_rejects_body_size_or_digest_mismatch_and_cleans(+ tmp_path: Path,+) -> None:+ artifact = _artifact(b"1234")+ oversized_response = httpx.Response(200, content=b"12345")+ oversized_response.headers["content-length"] = "4"+ oversized = CatalogArtifactDownloader(+ client_factory=lambda timeout: _client(oversized_response)+ )+ corrupt = CatalogArtifactDownloader(+ client_factory=lambda timeout: _client(httpx.Response(200, content=b"5678"))+ )++ with pytest.raises(PluginDistributionError, match="exceeds reviewed size"):+ oversized.download(artifact, destination_dir=tmp_path)+ with pytest.raises(PluginDistributionError, match="SHA-256"):+ corrupt.download(artifact, destination_dir=tmp_path)+ assert list(tmp_path.iterdir()) == []+++def test_catalog_install_uses_lifecycle_after_verified_download(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from deeptutor.plugins.manifest import parse_manifest+ from tests.plugins.test_lifecycle import _raw_manifest, _wheel++ payload = _wheel(tmp_path, "1.0.0").read_bytes()+ manifest = parse_manifest(_raw_manifest())+ artifact = _artifact(payload)+ calls: list[tuple[Path, str]] = []++ class FakeLifecycle:+ def install(self, path, *, expected_sha256, allow_reinstall=False):+ calls.append((path, expected_sha256))+ assert path.is_file()+ return SimpleNamespace(+ plugin_id="org.author.example",+ version="1.0.0",+ action="installed",+ artifact_sha256=expected_sha256,+ venv_path=tmp_path / "venv",+ )++ def fake_resolve(plugin_id, version, *, allow_deprecated, **kwargs):+ assert (plugin_id, version, allow_deprecated) == (+ "org.author.example",+ "1.0.0",+ True,+ )+ return SimpleNamespace(+ artifact=artifact,+ id=manifest.id,+ version=str(manifest.version),+ permissions=manifest.permissions,+ dependencies=manifest.dependencies,+ compatibility=manifest.compatibility,+ )++ monkeypatch.setattr("deeptutor.plugins.distribution.resolve_catalog_entry", fake_resolve)++ result = CatalogInstallManager(+ downloader_factory=lambda: CatalogArtifactDownloader(+ client_factory=lambda timeout: _client(httpx.Response(200, content=payload))+ ),+ lifecycle_factory=FakeLifecycle,+ ).install(+ "org.author.example",+ version="1.0.0",+ allow_deprecated=True,+ )++ assert result.artifact_url == artifact.url+ assert len(calls) == 1+ assert calls[0][1] == artifact.sha256+++def test_failed_catalog_download_never_reaches_lifecycle() -> None:+ class FailedDownloader:+ def download(self, artifact, *, destination_dir, timeout_seconds):+ raise PluginDistributionError("catalog artifact download failed")++ class UnexpectedLifecycle:+ def install(self, *args, **kwargs):+ raise AssertionError("download failure must not reach lifecycle")++ with pytest.raises(PluginDistributionError):+ CatalogInstallManager(+ downloader_factory=FailedDownloader,+ lifecycle_factory=UnexpectedLifecycle,+ ).install("org.author.example")diff --git a/tests/plugins/test_frontend.py b/tests/plugins/test_frontend.pynew file mode 100644index 000000000..7fb1bd3bd--- /dev/null+++ b/tests/plugins/test_frontend.py@@ -0,0 +1,73 @@+"""Static plugin frontend contract and filesystem boundary tests."""++from __future__ import annotations++import json+from pathlib import Path++import pytest++from deeptutor.plugins.frontend import (+ FrontendPageError,+ parse_frontend_page_manifest,+ resolve_frontend_page_asset,+)+++def _page() -> dict:+ return {+ "schema_version": "deeptutor.plugin-frontend-page/v1",+ "entry": "index.html",+ "assets": ["app.js", "index.html"],+ }+++def _package(tmp_path: Path) -> Path:+ root = tmp_path / "package"+ root.mkdir()+ (root / "index.html").write_text("<html></html>", encoding="utf-8")+ (root / "app.js").write_text("export {}", encoding="utf-8")+ return root+++def test_frontend_page_manifest_requires_explicit_asset_closure() -> None:+ page = parse_frontend_page_manifest(_page())++ assert page.entry == "index.html"+ assert page.assets == ("app.js", "index.html")++ raw = _page()+ raw["entry"] = "../index.html"+ with pytest.raises(FrontendPageError, match="traversal"):+ parse_frontend_page_manifest(raw)++ raw = _page()+ raw["assets"] = ["index.html", "app.exe"]+ with pytest.raises(FrontendPageError, match="unsupported file type"):+ parse_frontend_page_manifest(raw)+++def test_frontend_asset_resolution_serves_only_declared_regular_files(+ tmp_path: Path,+) -> None:+ root = _package(tmp_path)+ (root / "secret.txt").write_text("secret", encoding="utf-8")+ page = parse_frontend_page_manifest(_page())++ assert resolve_frontend_page_asset(page, root, "app.js").name == "app.js"+ with pytest.raises(FrontendPageError, match="not declared"):+ resolve_frontend_page_asset(page, root, "secret.txt")+ with pytest.raises(FrontendPageError, match="not declared"):+ resolve_frontend_page_asset(page, root, "../deeptutor.plugin.json")+++def test_frontend_asset_resolution_rejects_symlinks(tmp_path: Path) -> None:+ root = _package(tmp_path)+ outside = tmp_path / "outside.js"+ outside.write_text("outside", encoding="utf-8")+ (root / "app.js").unlink()+ (root / "app.js").symlink_to(outside)+ page = parse_frontend_page_manifest(_page())++ with pytest.raises(FrontendPageError, match="symlinks"):+ resolve_frontend_page_asset(page, root, "index.html")diff --git a/tests/plugins/test_lifecycle.py b/tests/plugins/test_lifecycle.pynew file mode 100644index 000000000..fa0f7cfeb--- /dev/null+++ b/tests/plugins/test_lifecycle.py@@ -0,0 +1,152 @@+"""Offline lifecycle tests for managed plugin wheels."""++from __future__ import annotations++import json+from pathlib import Path+import zipfile++import pytest++from deeptutor.plugins.lifecycle import (+ LifecycleResult,+ PluginLifecycleError,+ PluginLifecycleManager,+)+from deeptutor.plugins.manifest import parse_manifest+from deeptutor.plugins.registry import PluginRegistry+++def _raw_manifest(version: str = "1.0.0") -> dict:+ return {+ "schema_version": "deeptutor.plugin/v1",+ "id": "org.author.example",+ "name": "Example Plugin",+ "version": version,+ "description_i18n": {"en": "Example"},+ "author": "Author",+ "license": "Apache-2.0",+ "homepage": "https://example.com",+ "source_url": "https://example.com/source",+ "compatibility": {"deeptutor": ">=1.6,<3", "api": {"tool": "1"}},+ "permissions": {"network": []},+ "dependencies": ["helper==2.0"],+ "extensions": [+ {"type": "tool", "id": "example_tool", "entry_point": "example_plugin.worker"}+ ],+ }+++def _wheel(tmp_path: Path, version: str) -> Path:+ path = tmp_path / f"example-plugin-{version}-py3-none-any.whl"+ with zipfile.ZipFile(path, "w") as archive:+ archive.writestr("example_plugin/deeptutor.plugin.json", json.dumps(_raw_manifest(version)))+ archive.writestr(+ "example_plugin-1.dist-info/METADATA", f"Name: example-plugin\nVersion: {version}\n"+ )+ return path+++def _manager(tmp_path: Path, *, fail_install: bool = False) -> PluginLifecycleManager:+ registry = PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[],+ deeptutor_version="1.6.0",+ )++ def runner(argv: list[str], *, env=None) -> tuple[int, str]:+ if fail_install and argv[2:4] == ["pip", "install"]:+ return 3, "simulated dependency failure"+ if argv[1:3] == ["-m", "venv"]:+ root = Path(argv[-1])+ (root / "bin").mkdir(parents=True, exist_ok=True)+ package_root = root / "lib" / "python3.13" / "site-packages" / "example_plugin"+ package_root.mkdir(parents=True, exist_ok=True)+ python = root / "bin" / "python"+ python.write_text("#!python\n", encoding="utf-8")+ return 0, ""+ return 0, ""++ return PluginLifecycleManager(+ registry,+ root=tmp_path / "plugin-root",+ runner=runner,+ )+++def test_install_requires_permission_approval_and_isolates_dependencies(tmp_path) -> None:+ manager = _manager(tmp_path)++ result = manager.install(_wheel(tmp_path, "1.0.0"))++ registry = manager.registry+ record = registry.get_plugin("org.author.example")+ assert result.action == "installed"+ assert record is not None+ assert record.status == "approval-required"+ assert record.installation is not None+ assert record.installation.package_path is not None+ assert record.installation.package_path.is_dir()+ assert record.installation.dependencies == ("helper==2.0",)+ assert record.installation.venv_path.is_dir()+ assert record.installation.artifact_path.is_file()+++def test_upgrade_rollback_and_uninstall(tmp_path) -> None:+ manager = _manager(tmp_path)+ manager.install(_wheel(tmp_path, "1.0.0"))+ manager.registry.approve("org.author.example")++ upgraded = manager.install(_wheel(tmp_path, "1.1.0"))+ record = manager.registry.get_plugin("org.author.example")+ assert upgraded.version == "1.1.0"+ assert record is not None+ assert record.status == "approval-required"+ assert record.version == "1.1.0"++ rolled_back = manager.rollback("org.author.example")+ record = manager.registry.get_plugin("org.author.example")+ assert rolled_back.version == "1.0.0"+ assert record is not None+ assert record.version == "1.0.0"+ assert record.status == "approval-required"+ assert (manager.root / "org.author.example" / "versions" / "1.1.0").is_dir()++ uninstalled = manager.uninstall("org.author.example")+ assert uninstalled.action == "uninstalled"+ assert manager.registry.get_plugin("org.author.example") is None+ assert not (manager.root / "org.author.example").exists()+++def test_failed_upgrade_preserves_current_version_and_approval(tmp_path) -> None:+ manager = _manager(tmp_path)+ manager.install(_wheel(tmp_path, "1.0.0"))+ manager.registry.approve("org.author.example")++ with pytest.raises(PluginLifecycleError, match="isolated dependency install exited 3"):+ _manager(tmp_path, fail_install=True).install(_wheel(tmp_path, "1.1.0"))++ record = manager.registry.get_plugin("org.author.example")+ assert record is not None+ assert record.version == "1.0.0"+ assert record.status == "enabled"+++def test_digest_mismatch_is_rejected_before_install(tmp_path) -> None:+ manager = _manager(tmp_path)+ artifact = _wheel(tmp_path, "1.0.0")++ with pytest.raises(PluginLifecycleError, match="SHA-256"):+ manager.install(artifact, expected_sha256="0" * 64)+++def test_manifest_from_wheel_is_parsed_without_importing_plugin(tmp_path) -> None:+ artifact = _wheel(tmp_path, "1.0.0")+ manager = _manager(tmp_path)++ result = manager.install(artifact)++ assert isinstance(result, LifecycleResult)+ record = manager.registry.get_plugin(result.plugin_id)+ assert record is not None and record.manifest is not None+ assert parse_manifest(record.manifest.to_dict()).id == "org.author.example"diff --git a/tests/plugins/test_manifest.py b/tests/plugins/test_manifest.pynew file mode 100644index 000000000..9b80e3243--- /dev/null+++ b/tests/plugins/test_manifest.py@@ -0,0 +1,244 @@+"""Contract tests for the unified plugin root manifest."""++from __future__ import annotations++import pytest++from deeptutor.plugins.manifest import ManifestValidationError, parse_manifest+++def _manifest() -> dict:+ return {+ "schema_version": "deeptutor.plugin/v1",+ "id": "org.author.example",+ "name": "Example Plugin",+ "version": "1.0.0",+ "description_i18n": {"en": "Example extension package", "zh": "示例扩展包"},+ "author": "Author Name",+ "license": "Apache-2.0",+ "homepage": "https://example.com",+ "source_url": "https://github.com/author/example",+ "compatibility": {+ "deeptutor": ">=1.6.0,<2",+ "api": {"reading_extension": "1", "visualizer": "1"},+ },+ "permissions": {+ "reading": ["selection", "visible_text"],+ "learning_events": [],+ "network": ["https://api.example.com"],+ "models": [],+ "storage": ["plugin-private"],+ "ui": ["sandboxed-iframe"],+ },+ "dependencies": ["requests>=2.32,<3"],+ "extensions": [+ {"type": "reading_extension", "id": "translation", "entry_point": "translation"},+ {+ "type": "visualizer",+ "id": "fraction_tiles",+ "manifest": "visualizers/fraction_tiles/visualizer.json",+ },+ ],+ }+++def test_parse_manifest_normalizes_typed_extensions() -> None:+ manifest = parse_manifest(_manifest())++ assert manifest.id == "org.author.example"+ assert str(manifest.version) == "1.0.0"+ assert [extension.id for extension in manifest.extensions] == [+ "translation",+ "fraction_tiles",+ ]+ assert manifest.permissions.scopes["reading"] == ("selection", "visible_text")+ assert manifest.dependencies == ("requests<3,>=2.32",)+++def test_parse_manifest_normalizes_web_and_app_extension_contracts() -> None:+ raw = _manifest()+ raw["compatibility"]["api"] = {+ "app_connector": "1",+ "frontend_page": "1",+ "http_route": "1",+ "persistence_schema": "1",+ }+ raw["extensions"] = [+ {+ "type": "http_route",+ "id": "echo_route",+ "entry_point": "example.worker",+ "path": "/learning/echo",+ "methods": ["GET", "POST"],+ "auth": "authenticated",+ },+ {+ "type": "frontend_page",+ "id": "echo_page",+ "path": "/echo",+ "auth": "public",+ "manifest": "frontend/page.json",+ },+ {+ "type": "persistence_schema",+ "id": "echo_store",+ "schema": "schemas/echo.json",+ "operations": ["read", "write"],+ },+ {+ "type": "app_connector",+ "id": "echo_connector",+ "operations": ["import-course"],+ },+ ]++ manifest = parse_manifest(raw)++ assert [extension.to_dict() for extension in manifest.extensions] == [+ {+ "type": "http_route",+ "id": "echo_route",+ "entry_point": "example.worker",+ "path": "/learning/echo",+ "methods": ["GET", "POST"],+ "auth": "authenticated",+ },+ {+ "type": "frontend_page",+ "id": "echo_page",+ "path": "/echo",+ "auth": "public",+ "manifest": "frontend/page.json",+ },+ {+ "type": "persistence_schema",+ "id": "echo_store",+ "schema": "schemas/echo.json",+ "operations": ["read", "write"],+ },+ {+ "type": "app_connector",+ "id": "echo_connector",+ "operations": ["import-course"],+ },+ ]+++def test_executable_frontend_page_requires_sandboxed_ui_permission() -> None:+ raw = _manifest()+ raw["compatibility"]["api"] = {"frontend_page": "1"}+ raw["permissions"]["ui"] = []+ raw["extensions"] = [+ {+ "type": "frontend_page",+ "id": "echo_page",+ "path": "/echo",+ "auth": "authenticated",+ "manifest": "frontend/page.json",+ }+ ]++ with pytest.raises(ManifestValidationError, match="sandboxed-iframe"):+ parse_manifest(raw)+++ ("mutation", "message"),+ [+ ({"schema_version": "deeptutor.plugin/v2"}, "unsupported schema_version"),+ ({"entry_points": []}, "unknown fields: entry_points"),+ ({"compatibility": {"deeptutor": "not-a-specifier", "api": {}}}, "invalid"),+ (+ {"extensions": [{"type": "visualizer", "id": "broken"}]},+ "manifest is required for visualizers",+ ),+ (+ {"dependencies": ["requests>=2.32,<3; sys_platform == 'darwin'"]},+ "name-and-version",+ ),+ ({"dependencies": ["requests", "REQUESTS>=2"]}, "duplicate"),+ (+ {+ "compatibility": {"deeptutor": ">=1.6.0,<2", "api": {}},+ "extensions": [+ {+ "type": "http_route",+ "id": "echo",+ "entry_point": "example.worker",+ "path": "/../echo",+ "methods": ["GET"],+ "auth": "authenticated",+ }+ ],+ },+ "static relative /path",+ ),+ (+ {+ "compatibility": {"deeptutor": ">=1.6.0,<2", "api": {}},+ "extensions": [+ {+ "type": "http_route",+ "id": "echo",+ "entry_point": "example.worker",+ "path": "/echo",+ "methods": ["TRACE"],+ "auth": "authenticated",+ }+ ],+ },+ "unsupported HTTP method",+ ),+ (+ {+ "compatibility": {"deeptutor": ">=1.6.0,<2", "api": {}},+ "extensions": [+ {+ "type": "frontend_page",+ "id": "echo",+ "path": "/echo",+ "auth": "superuser",+ }+ ],+ },+ "public, authenticated, or admin",+ ),+ (+ {+ "compatibility": {"deeptutor": ">=1.6.0,<2", "api": {}},+ "extensions": [+ {+ "type": "persistence_schema",+ "id": "echo",+ "schema": "../schemas/echo.json",+ "operations": ["read"],+ }+ ],+ },+ "traversal segments",+ ),+ (+ {+ "compatibility": {"deeptutor": ">=1.6.0,<2", "api": {}},+ "extensions": [+ {+ "type": "http_route",+ "id": "echo",+ "entry_point": "example.worker",+ "path": "/echo",+ "methods": ["GET"],+ "auth": "authenticated",+ "schema": "schemas/echo.json",+ }+ ],+ },+ "unknown fields: schema",+ ),+ ],+)+def test_parse_manifest_rejects_invalid_contracts(mutation: dict, message: str) -> None:+ raw = _manifest()+ raw.update(mutation)++ with pytest.raises(ManifestValidationError, match=message):+ parse_manifest(raw)diff --git a/tests/plugins/test_recovery_boundaries.py b/tests/plugins/test_recovery_boundaries.pynew file mode 100644index 000000000..34dd33c44--- /dev/null+++ b/tests/plugins/test_recovery_boundaries.py@@ -0,0 +1,136 @@+"""Review, revocation, recovery and bounded execution workflows (#1307)."""++import json+from pathlib import Path+import sys+from types import SimpleNamespace++import pytest++from deeptutor.plugins.registry import PluginStateError+from deeptutor.plugins.runtime import PluginRuntimeError+from tests.plugins.test_lifecycle import _manager, _wheel+from tests.plugins.test_registry_gating import _EchoTool, _patch_entry_points, _plugin_registry+++def test_external_upgrade_requires_review_even_when_permissions_are_unchanged(tmp_path):+ registry = _plugin_registry(tmp_path)+ registry.approve("org.author.gated")+ source = tmp_path / "package" / "deeptutor.plugin.json"+ manifest = json.loads(source.read_text())+ manifest["version"] = "1.1.0"+ source.write_text(json.dumps(manifest))+ record = registry.get_plugin("org.author.gated")+ assert record.version == "1.1.0" and record.status == "approval-required"+ original = registry.state_path.read_bytes()+ with pytest.raises(PluginStateError, match="snapshot changed"):+ registry.approve(record.id, expected_digest="0" * 64)+ assert registry.state_path.read_bytes() == original+++async def test_unapproved_entry_point_never_imports_and_cached_tool_remains_revocable(+ tmp_path, monkeypatch+):+ import deeptutor.core.entry_points as loader+ from deeptutor.core.entry_points import load_entry_point_group+ import deeptutor.plugins.runtime as runtime++ registry = _plugin_registry(tmp_path)+ monkeypatch.setattr(runtime, "get_plugin_registry", lambda: registry)+ calls = []+ ep = SimpleNamespace(name="declared_tool", load=lambda: calls.append("import") or _EchoTool)+ monkeypatch.setattr(loader, "entry_points", lambda **kwargs: [ep])+ assert not load_entry_point_group("deeptutor.tools", lambda name, target: target())+ assert not calls+ registry.approve("org.author.gated")+ tool = load_entry_point_group("deeptutor.tools", lambda name, target: target())[0]+ assert (await tool.execute()).content == "ok"+ registry.set_enabled("org.author.gated", False)+ with pytest.raises(PluginRuntimeError, match="disabled"):+ await tool.execute()+++def test_corrupt_state_never_becomes_an_empty_writable_registry(tmp_path):+ manager = _manager(tmp_path)+ manager.registry.state_path.write_bytes(b"{broken")+ with pytest.raises(PluginStateError, match="preserved"):+ manager.install(_wheel(tmp_path, "1.0.0"))+ assert manager.registry.state_path.read_bytes() == b"{broken"+++def test_failed_same_version_reinstall_preserves_current_environment_and_artifact(tmp_path):+ manager = _manager(tmp_path)+ artifact = _wheel(tmp_path, "1.0.0")+ manager.install(artifact)+ manager.registry.approve("org.author.example")+ record = manager.registry.get_plugin("org.author.example")+ before = record.installation.artifact_path.read_bytes()+ sentinel = record.installation.venv_path / "retained.txt"+ sentinel.write_text("old environment")+ with pytest.raises(Exception, match="install exited"):+ _manager(tmp_path, fail_install=True).install(artifact, allow_reinstall=True)+ assert sentinel.read_text() == "old environment"+ assert record.installation.artifact_path.read_bytes() == before+ assert manager.registry.get_plugin(record.id).status == "enabled"+++def test_rollback_requires_the_retained_artifact_to_match_its_pin(tmp_path):+ manager = _manager(tmp_path)+ manager.install(_wheel(tmp_path, "1.0.0"))+ manager.install(_wheel(tmp_path, "1.1.0"))+ state = manager.registry.state_snapshot()+ original = manager.registry.state_path.read_bytes()+ Path(+ state["plugins"]["org.author.example"]["history"][0]["installation"]["artifact_path"]+ ).write_bytes(b"tampered")+ with pytest.raises(Exception, match="SHA-256"):+ manager.rollback("org.author.example")+ assert manager.registry.state_path.read_bytes() == original+++def test_worker_output_is_bounded_while_the_child_is_running(tmp_path):+ from deeptutor.plugins.runtime import _run_worker++ with pytest.raises(PluginRuntimeError, match="budget"):+ _run_worker(+ [sys.executable, "-c", "import sys; sys.stdout.write('x' * 3000000)"],+ input="{}",+ cwd=tmp_path,+ env={},+ )+++def test_frontend_total_size_is_checked_beyond_the_requested_asset(tmp_path):+ from deeptutor.plugins.frontend import (+ FrontendPageError,+ parse_frontend_page_manifest,+ resolve_frontend_page_asset,+ )++ page = parse_frontend_page_manifest(+ {+ "schema_version": "deeptutor.plugin-frontend-page/v1",+ "entry": "index.html",+ "assets": ["index.html", "huge.js"],+ }+ )+ (tmp_path / "index.html").write_text("ok")+ with (tmp_path / "huge.js").open("wb") as handle:+ handle.truncate(6 * 1024 * 1024)+ with pytest.raises(FrontendPageError, match="5 MiB"):+ resolve_frontend_page_asset(page, tmp_path, "index.html")+++def test_corrupt_plugin_state_blocks_plugins_without_hiding_builtins(tmp_path, monkeypatch):+ import deeptutor.plugins.runtime as runtime+ from deeptutor.runtime.registry.capability_registry import CapabilityRegistry++ registry = _plugin_registry(tmp_path)+ registry.state_path.write_text("{broken")+ monkeypatch.setattr(runtime, "get_plugin_registry", lambda: registry)+ capabilities = CapabilityRegistry()+ capabilities.load_builtins()+ assert "chat" in capabilities.list_capabilities()+ assert not runtime.load_enabled_workers(registry)+ assert registry.state_path.read_text() == "{broken"diff --git a/tests/plugins/test_registry.py b/tests/plugins/test_registry.pynew file mode 100644index 000000000..180b2e009--- /dev/null+++ b/tests/plugins/test_registry.py@@ -0,0 +1,244 @@+"""Registry tests use metadata-only fake distributions and never import plugins."""++from __future__ import annotations++import json+from pathlib import Path+from types import SimpleNamespace++from deeptutor.plugins.manifest import approval_digest+from deeptutor.plugins.registry import PluginRegistry+++def _manifest(plugin_id: str = "org.author.example", deeptutor: str = ">=1.6.0,<2") -> dict:+ return {+ "schema_version": "deeptutor.plugin/v1",+ "id": plugin_id,+ "name": "Example Plugin",+ "version": "1.0.0",+ "description_i18n": {"en": "Example extension package"},+ "author": "Author Name",+ "license": "Apache-2.0",+ "homepage": "https://example.com",+ "source_url": "https://github.com/author/example",+ "compatibility": {"deeptutor": deeptutor, "api": {"tool": "1"}},+ "permissions": {"network": ["https://api.example.com"]},+ "extensions": [{"type": "tool", "id": "example_tool", "entry_point": "example.tool:tool"}],+ }+++def _dist(tmp_path: Path, raw: dict | None = None, name: str = "example-plugin") -> SimpleNamespace:+ package_dir = tmp_path / name+ package_dir.mkdir()+ path = package_dir / "deeptutor.plugin.json"+ path.write_text(json.dumps(raw if raw is not None else _manifest()), encoding="utf-8")+ file_ref = SimpleNamespace(name=path.name, path=path.name)+ return SimpleNamespace(+ files=[file_ref],+ locate_file=lambda ref: package_dir / ref.path,+ metadata={"Name": name},+ )+++def test_registry_reads_manifest_without_importing_plugin(tmp_path) -> None:+ registry = PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[_dist(tmp_path)],+ deeptutor_version="1.6.0",+ )++ records = registry.list_plugins(include_catalog=False)++ assert [record.id for record in records] == ["org.author.example"]+ assert records[0].status == "approval-required"+ assert records[0].manifest is not None+ assert records[0].manifest.extensions[0].id == "example_tool"+++def test_registry_reports_incompatible_and_broken_plugins(tmp_path) -> None:+ incompatible = _dist(+ tmp_path,+ _manifest("org.author.future", deeptutor=">=2.0.0"),+ "future-plugin",+ )+ broken = _dist(tmp_path, {"id": "org.author.broken"}, "broken-plugin")+ registry = PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[incompatible, broken],+ deeptutor_version="1.6.0",+ )++ records = {record.id: record for record in registry.list_plugins(include_catalog=False)}++ assert records["org.author.future"].status == "incompatible"+ assert "requires DeepTutor" in records["org.author.future"].error+ assert records["org.author.broken"].status == "broken"+++def test_registry_gates_web_and_app_extension_api_contracts(tmp_path) -> None:+ raw = _manifest()+ raw["compatibility"]["api"] = {+ "http_route": "1",+ "frontend_page": "1",+ "persistence_schema": "1",+ "app_connector": "1",+ }+ raw["extensions"] = [+ {"type": extension_type, "id": f"example_{extension_type}", **declaration}+ for extension_type, declaration in (+ (+ "http_route",+ {+ "entry_point": "example.worker",+ "path": "/echo",+ "methods": ["GET"],+ "auth": "admin",+ },+ ),+ ("frontend_page", {"path": "/page", "auth": "authenticated"}),+ ("persistence_schema", {"schema": "schemas/example.json", "operations": ["read"]}),+ ("app_connector", {"operations": ["import"]}),+ )+ ]+ registry = PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[_dist(tmp_path, raw, "web-plugin")],+ deeptutor_version="1.6.0",+ )++ record = registry.get_plugin("org.author.example")+ assert record is not None+ assert record.status == "approval-required"++ raw["compatibility"]["api"]["http_route"] = "2"+ registry = PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[_dist(tmp_path, raw, "web-plugin-v2")],+ deeptutor_version="1.6.0",+ )+ record = registry.get_plugin("org.author.example")+ assert record is not None+ assert record.status == "incompatible"+ assert record.error == "requires http_route API newer than this build"+++def test_approve_enable_disable_persists_local_state(tmp_path) -> None:+ state_path = tmp_path / "plugins.json"+ registry = PluginRegistry(+ state_path=state_path,+ installed_distributions=[_dist(tmp_path)],+ deeptutor_version="1.6.0",+ )+ record = registry.get_plugin("org.author.example")+ assert record is not None and record.manifest is not None++ approved = registry.approve("org.author.example")+ disabled = registry.set_enabled("org.author.example", False)+ enabled = registry.set_enabled("org.author.example", True)++ assert approved.status == "enabled"+ assert disabled.status == "disabled"+ assert enabled.status == "enabled"+ state = json.loads(state_path.read_text(encoding="utf-8"))+ assert state == {+ "version": 2,+ "disabled": [],+ "plugins": {+ "org.author.example": {+ "manifest": record.manifest.to_dict(),+ "installation": None,+ "history": [],+ "approval": {+ "digest": approval_digest(record.manifest, record.artifact_identity),+ "approved_at": state["plugins"]["org.author.example"]["approval"][+ "approved_at"+ ],+ },+ }+ },+ }+++def test_registry_migrates_legacy_state(tmp_path) -> None:+ state_path = tmp_path / "plugins.json"+ state_path.write_text(json.dumps({"version": 1, "disabled": ["old"]}), encoding="utf-8")+ registry = PluginRegistry(+ state_path=state_path,+ installed_distributions=[],+ deeptutor_version="1.6.0",+ )++ migrated = registry.state_snapshot()++ assert migrated == {+ "version": 2,+ "disabled": ["old"],+ "plugins": {},+ }+ assert json.loads(state_path.read_text(encoding="utf-8")) == {+ "version": 1,+ "disabled": ["old"],+ }+++def test_registry_marks_managed_version_deprecated_from_catalog(tmp_path) -> None:+ manifest = _manifest()+ catalog_path = tmp_path / "catalog.json"+ catalog_path.write_text(+ json.dumps(+ {+ "schema_version": "deeptutor.plugin-catalog/v2",+ "meta": {+ "generated_at": "2026-09-08T00:00:00Z",+ "reviewed_at": "2026-09-08T00:00:00Z",+ "reviewers": ["maintainer"],+ },+ "entries": [+ {+ **{+ key: value+ for key, value in manifest.items()+ if key not in {"schema_version", "extensions"}+ },+ "status": "deprecated",+ "artifact": {+ "kind": "python-package",+ "requirement": "example-plugin==1.0.0",+ "sha256": "0" * 64,+ "url": "https://example.com/example-1.0.0.whl",+ "size_bytes": 128,+ "platform_tags": ["py3-none-any"],+ },+ }+ ],+ }+ ),+ encoding="utf-8",+ )+ state_path = tmp_path / "plugins.json"+ registry = PluginRegistry(+ state_path=state_path,+ catalog_path=catalog_path,+ installed_distributions=[],+ deeptutor_version="1.6.0",+ )+ state = registry.state_snapshot()+ state["plugins"]["org.author.example"] = {+ "manifest": manifest,+ "installation": {+ "version": "1.0.0",+ "artifact_path": str(tmp_path / "example.whl"),+ "artifact_sha256": "0" * 64,+ "venv_path": str(tmp_path / "venv"),+ "python_path": str(tmp_path / "venv" / "bin" / "python"),+ "installed_at": "2026-09-08T00:00:00Z",+ "dependencies": [],+ },+ "history": [],+ }+ registry.replace_state(state)++ record = registry.get_plugin("org.author.example")++ assert record is not None+ assert record.status == "deprecated"diff --git a/tests/plugins/test_registry_gating.py b/tests/plugins/test_registry_gating.pynew file mode 100644index 000000000..42a6d571d--- /dev/null+++ b/tests/plugins/test_registry_gating.py@@ -0,0 +1,194 @@+"""Entry-point loading must honor approved manifest state."""++from __future__ import annotations++import json+from pathlib import Path+from types import SimpleNamespace++import pytest++from deeptutor.capabilities.registry import discover_external_loop_capabilities+from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability+from deeptutor.core.context import UnifiedContext+import deeptutor.core.entry_points as entry_points+from deeptutor.core.tool_protocol import BaseTool, ToolDefinition, ToolResult+from deeptutor.plugins.registry import PluginRegistry+from deeptutor.reading.extensions import ReadingExtensionRegistry+from deeptutor.reading.translation import TranslationExtension+from deeptutor.runtime.registry.capability_registry import CapabilityRegistry+from deeptutor.runtime.registry.tool_registry import ToolRegistry+from deeptutor.runtime.stream_bus import StreamBus+++class _EchoTool(BaseTool):+ def get_definition(self) -> ToolDefinition:+ return ToolDefinition(name="declared_tool", description="Declared tool")++ async def execute(self, **kwargs) -> ToolResult:+ return ToolResult(content="ok")+++class _EchoCapability(TurnCapability):+ manifest = CapabilityManifest(name="declared_capability", description="Declared")++ async def run(self, context: UnifiedContext, stream: StreamBus) -> None:+ return None+++class _DemoLoop:+ name = "demo_loop"+ owned_tools = ()++ def is_active(self, _context) -> bool:+ return False++ def system_block(self, _context, *, language, prompts):+ return None++ def augment_kwargs(self, _tool_name, kwargs, _context):+ return kwargs++ def pre_loop_seed(self, _context):+ return ""+++def _plugin_registry(tmp_path: Path, extensions: list[dict] | None = None) -> PluginRegistry:+ manifest = {+ "schema_version": "deeptutor.plugin/v1",+ "id": "org.author.gated",+ "name": "Gated",+ "version": "1.0.0",+ "description_i18n": {"en": "Gated"},+ "author": "Author",+ "license": "Apache-2.0",+ "homepage": "https://example.com",+ "source_url": "https://example.com/source",+ "compatibility": {"deeptutor": ">=1.6,<3", "api": {"tool": "1", "capability": "1"}},+ "permissions": {"network": []},+ "dependencies": [],+ "extensions": [+ {"type": "tool", "id": "declared_tool", "entry_point": "declared_tool"},+ {+ "type": "capability",+ "id": "declared_capability",+ "entry_point": "declared_capability",+ },+ ],+ }+ package = tmp_path / "package"+ package.mkdir()+ if extensions is not None:+ manifest["extensions"] = extensions+ manifest["compatibility"]["api"] = {extension["type"]: "1" for extension in extensions}+ package.joinpath("deeptutor.plugin.json").write_text(json.dumps(manifest), encoding="utf-8")+ file_ref = SimpleNamespace(name="deeptutor.plugin.json", path="deeptutor.plugin.json")+ dist = SimpleNamespace(+ files=[file_ref],+ locate_file=lambda ref: package / ref.path,+ metadata={"Name": "gated-plugin"},+ )+ return PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[dist],+ deeptutor_version="1.6.0",+ )+++def _patch_plugin_registry(monkeypatch, registry: PluginRegistry) -> None:+ monkeypatch.setattr("deeptutor.plugins.registry.PluginRegistry", lambda: registry)+ monkeypatch.setattr("deeptutor.plugins.runtime.load_enabled_tools", lambda _registry: ())+ monkeypatch.setattr(+ "deeptutor.plugins.runtime.load_enabled_capabilities",+ lambda _registry: (),+ )+++def _patch_entry_points(monkeypatch, expected_group: str, name: str, loaded) -> None:+ def fake_entry_points(*, group: str):+ assert group == expected_group+ return [SimpleNamespace(name=name, load=lambda: loaded)]++ monkeypatch.setattr(entry_points, "entry_points", fake_entry_points)+++def test_tool_entry_point_waits_for_approval(monkeypatch, tmp_path) -> None:+ registry = _plugin_registry(tmp_path)+ _patch_plugin_registry(monkeypatch, registry)+ _patch_entry_points(monkeypatch, "deeptutor.tools", "declared_tool", _EchoTool)++ blocked = ToolRegistry()+ blocked.load_plugins()+ assert blocked.get("declared_tool") is None++ registry.approve("org.author.gated")+ allowed = ToolRegistry()+ allowed.load_plugins()+ assert isinstance(allowed.get("declared_tool"), _EchoTool)++ registry.set_enabled("org.author.gated", False)+ disabled = ToolRegistry()+ disabled.load_plugins()+ assert disabled.get("declared_tool") is None+++async def test_capability_entry_point_waits_for_approval(monkeypatch, tmp_path) -> None:+ registry = _plugin_registry(tmp_path)+ _patch_plugin_registry(monkeypatch, registry)+ _patch_entry_points(monkeypatch, "deeptutor.extensions", "declared_capability", _EchoCapability)++ blocked = CapabilityRegistry()+ blocked.load_plugins()+ assert blocked.get("declared_capability") is None++ registry.approve("org.author.gated")+ allowed = CapabilityRegistry()+ allowed.load_plugins()+ assert isinstance(allowed.get("declared_capability"), _EchoCapability)+++def test_loop_entry_point_waits_for_approval(monkeypatch, tmp_path) -> None:+ registry = _plugin_registry(+ tmp_path,+ [{"type": "loop_capability", "id": "demo_loop", "entry_point": "demo_loop"}],+ )+ monkeypatch.setattr("deeptutor.plugins.registry.PluginRegistry", lambda: registry)+ _patch_entry_points(+ monkeypatch,+ "deeptutor.loop_capabilities",+ "demo_loop",+ _DemoLoop,+ )+ discover_external_loop_capabilities.cache_clear()+ try:+ blocked = discover_external_loop_capabilities()+ assert not any(item[0] == "demo_loop" for item in blocked)++ registry.approve("org.author.gated")+ discover_external_loop_capabilities.cache_clear()+ allowed = discover_external_loop_capabilities()+ assert any(item[0] == "demo_loop" for item in allowed)+ finally:+ discover_external_loop_capabilities.cache_clear()+++def test_reading_entry_point_waits_for_approval(monkeypatch, tmp_path) -> None:+ registry = _plugin_registry(+ tmp_path,+ [{"type": "reading_extension", "id": "translation", "entry_point": "translation"}],+ )+ monkeypatch.setattr("deeptutor.plugins.registry.PluginRegistry", lambda: registry)+ _patch_entry_points(+ monkeypatch,+ "deeptutor.reading_extensions",+ "translation",+ TranslationExtension,+ )++ blocked = ReadingExtensionRegistry()+ assert blocked.get("translation") is None++ registry.approve("org.author.gated")+ allowed = ReadingExtensionRegistry()+ assert allowed.get("translation") is not Nonediff --git a/tests/plugins/test_runtime.py b/tests/plugins/test_runtime.pynew file mode 100644index 000000000..4b3339971--- /dev/null+++ b/tests/plugins/test_runtime.py@@ -0,0 +1,278 @@+"""Runtime gate and Tool/Capability worker contract tests."""++from __future__ import annotations++import os+from pathlib import Path+import sys+from types import SimpleNamespace++import pytest++from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability+from deeptutor.core.context import UnifiedContext+from deeptutor.plugins.manifest import parse_manifest+from deeptutor.plugins.registry import PluginInstallation, PluginRegistry+import deeptutor.plugins.runtime as runtime+from deeptutor.plugins.runtime import (+ PluginRuntimeError,+ PluginWorkerCapability,+ PluginWorkerTool,+ entry_point_allowed,+)+from deeptutor.runtime.stream_bus import StreamBus+++def _raw_manifest() -> dict:+ return {+ "schema_version": "deeptutor.plugin/v1",+ "id": "org.deeptutor.learning_echo",+ "name": "Learning Echo Example",+ "version": "1.0.0",+ "description_i18n": {"en": "Example"},+ "author": "DeepTutor",+ "license": "Apache-2.0",+ "homepage": "https://example.com",+ "source_url": "https://example.com/source",+ "compatibility": {+ "deeptutor": ">=1.6,<3",+ "api": {"tool": "1", "capability": "1", "http_route": "1"},+ },+ "permissions": {"network": []},+ "dependencies": [],+ "extensions": [+ {"type": "tool", "id": "learning_echo", "entry_point": "learning_echo.worker"},+ {+ "type": "capability",+ "id": "learning_echo_capability",+ "entry_point": "learning_echo.worker",+ },+ {+ "type": "http_route",+ "id": "learning_echo_http",+ "entry_point": "learning_echo.worker",+ "path": "/echo",+ "methods": ["POST"],+ "auth": "public",+ },+ ],+ }+++def _installation(tmp_path: Path) -> PluginInstallation:+ venv_path = tmp_path / "venv"+ venv_path.mkdir(exist_ok=True)+ return PluginInstallation(+ version="1.0.0",+ artifact_path=tmp_path / "artifact.whl",+ artifact_sha256="0" * 64,+ venv_path=venv_path,+ python_path=Path(sys.executable),+ installed_at="2026-09-07T00:00:00+00:00",+ )+++def _registry(tmp_path: Path) -> PluginRegistry:+ manifest = parse_manifest(_raw_manifest())+ registry = PluginRegistry(+ state_path=tmp_path / "plugins.json",+ installed_distributions=[],+ deeptutor_version="1.6.0",+ )+ installation = _installation(tmp_path)+ state = registry.state_snapshot()+ state["plugins"][manifest.id] = {+ "manifest": manifest.to_dict(),+ "installation": installation.to_dict(),+ "history": [],+ }+ registry.replace_state(state)+ return registry+++def test_entry_point_gate_requires_exact_permission_approval(tmp_path) -> None:+ registry = _registry(tmp_path)++ assert not entry_point_allowed(+ registry, extension_type="tool", entry_point="learning_echo.worker"+ )+ registry.approve("org.deeptutor.learning_echo")+ assert entry_point_allowed(registry, extension_type="tool", entry_point="learning_echo.worker")+ registry.set_enabled("org.deeptutor.learning_echo", False)+ assert not entry_point_allowed(+ registry, extension_type="tool", entry_point="learning_echo.worker"+ )+++async def test_example_worker_tool_and_capability(tmp_path, monkeypatch) -> None:+ registry = _registry(tmp_path)+ registry.approve("org.deeptutor.learning_echo")+ monkeypatch.setattr(runtime, "get_plugin_registry", lambda: registry)+ manifest = parse_manifest(_raw_manifest())+ installation = _installation(tmp_path)+ example_root = Path(__file__).parents[2] / "examples" / "plugins" / "learning_echo"+ monkeypatch.setattr(+ "deeptutor.plugins.runtime._clean_env",+ lambda: {+ **dict(os.environ),+ "PYTHONPATH": str(example_root),+ },+ )++ tool = PluginWorkerTool(+ manifest=manifest,+ installation=installation,+ extension_id="learning_echo",+ )+ result = await tool.execute(message="hello")+ assert result.content == "learning echo: hello"++ capability = PluginWorkerCapability(+ manifest=manifest,+ installation=installation,+ extension_id="learning_echo_capability",+ )+ bus = StreamBus()+ await capability.run(UnifiedContext(user_message="hello"), bus)+ await bus.close()+ events = [event async for event in bus.subscribe()]+ assert events[0].content == "learning capability echo: hello"+++def test_example_worker_http_route(tmp_path, monkeypatch) -> None:+ registry = _registry(tmp_path)+ registry.approve("org.deeptutor.learning_echo")+ monkeypatch.setattr(runtime, "get_plugin_registry", lambda: registry)+ manifest = parse_manifest(_raw_manifest())+ installation = _installation(tmp_path)+ example_root = Path(__file__).parents[2] / "examples" / "plugins" / "learning_echo"+ monkeypatch.setattr(+ "deeptutor.plugins.runtime._clean_env",+ lambda: {**dict(os.environ), "PYTHONPATH": str(example_root)},+ )++ route = runtime.PluginWorkerHttpRoute(+ manifest=manifest,+ installation=installation,+ extension_id="learning_echo_http",+ )+ response = route.handle(+ method="POST",+ path="/echo",+ query={"tags": ("math", "spaced-repetition")},+ body={"message": "hello"},+ )++ assert response.status == 200+ assert response.headers == {"Cache-Control": "no-store"}+ assert response.body == {+ "method": "POST",+ "path": "/echo",+ "message": "hello",+ "auth": "public",+ }+++def test_http_worker_response_status_and_headers_are_whitelisted(tmp_path, monkeypatch) -> None:+ manifest = parse_manifest(_raw_manifest())+ installation = _installation(tmp_path)++ class FixedClient:+ def __init__(self, response: dict) -> None:+ self.response = response+ self.payload: dict | None = None++ def request(self, operation: str, payload: dict | None = None) -> dict:+ assert operation == "handle_http"+ assert payload is not None and payload["http"]["auth"] == "public"+ self.payload = payload+ return self.response++ valid = runtime.PluginWorkerHttpRoute(+ manifest=manifest,+ installation=installation,+ extension_id="learning_echo_http",+ )+ client = FixedClient({"http": {"status": 201, "headers": {"cache-control": "no-store"}}})+ monkeypatch.setattr(valid, "_client", client)+ assert valid.handle(method="POST", path="/echo", query={}).body is None+ assert client.payload == {+ "http": {+ "method": "POST",+ "path": "/echo",+ "query": {},+ "body": None,+ "auth": "public",+ }+ }++ invalid_cases = [+ {"http": {"status": 301}},+ {"http": {"status": 200, "headers": {"Set-Cookie": "session=secret"}}},+ {"http": {"status": 200, "headers": {"Cache-Control": "public"}}},+ {"http": {"status": 204, "body": {}}},+ {"http": None},+ ]+ for response in invalid_cases:+ rejected = runtime.PluginWorkerHttpRoute(+ manifest=manifest,+ installation=installation,+ extension_id="learning_echo_http",+ )+ monkeypatch.setattr(rejected, "_client", FixedClient(response))+ with pytest.raises(PluginRuntimeError, match="handle_http"):+ rejected.handle(method="POST", path="/echo", query={})+++def test_worker_permission_declaration_cannot_exceed_manifest(tmp_path, monkeypatch) -> None:+ manifest = parse_manifest(_raw_manifest())+ client = runtime._WorkerClient(+ python_path=Path(sys.executable),+ venv_path=tmp_path / "venv",+ module="learning_echo.worker",+ permissions=dict(manifest.permissions.scopes),+ )++ with pytest.raises(PluginRuntimeError, match="unapproved network"):+ client.validate_permissions({"network": ["https://unapproved.example"]})+++def test_worker_error_response_is_rejected(tmp_path, monkeypatch) -> None:+ client = runtime._WorkerClient(+ python_path=Path(sys.executable),+ venv_path=tmp_path / "venv",+ module="learning_echo.worker",+ permissions={},+ )+ monkeypatch.setattr(+ runtime,+ "_run_worker",+ lambda *_args, **_kwargs: SimpleNamespace(+ returncode=0, stdout='{"error": "contract violation"}', stderr=""+ ),+ )++ with pytest.raises(PluginRuntimeError, match="contract violation"):+ client.request("describe_tool")+++def test_one_failed_worker_does_not_block_other_managed_extensions(tmp_path, monkeypatch) -> None:+ registry = _registry(tmp_path)+ registry.approve("org.deeptutor.learning_echo")++ class _Capability(TurnCapability):+ manifest = CapabilityManifest(name="learning_echo_capability", description="Echo")++ async def run(self, context: UnifiedContext, stream) -> None:+ return None++ def broken_tool(**_kwargs):+ raise runtime.PluginRuntimeError("worker unavailable")++ monkeypatch.setattr(runtime, "PluginWorkerTool", broken_tool)+ monkeypatch.setattr(runtime, "PluginWorkerCapability", lambda **_kwargs: _Capability())++ workers = runtime.load_enabled_workers(registry)++ assert isinstance(workers[0], _Capability)diff --git a/tests/test_packaging_metadata.py b/tests/test_packaging_metadata.pyindex 61fc55c2b..8b326a401 100644--- a/tests/test_packaging_metadata.py+++ b/tests/test_packaging_metadata.py@@ -190,6 +190,7 @@ def test_lightrag_extra_is_the_exact_native_sdk_without_parser_transitives() ->@pytest.mark.parametrize("expected",[+ "packaging>=24.2","loguru>=0.7.3,<1.0.0","json-repair>=0.57.0,<1.0.0","pyte>=0.8.1",diff --git a/web/contracts/generated/api.ts b/web/contracts/generated/api.tsindex 2fe002d3b..de7ca982f 100644--- a/web/contracts/generated/api.ts+++ b/web/contracts/generated/api.ts@@ -1967,6 +1967,60 @@ export interface paths {readonly patch?: never;readonly trace?: never;};+ readonly "/api/knowledge-bases/{kb_name}/indexing-readiness": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Get Indexing Readiness */+ readonly get: operations["get_indexing_readiness_api_knowledge_bases__kb_name__indexing_readiness_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/knowledge-bases/{kb_name}/indexing-run": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /**+ * Get Indexing Run+ * @description Pure durable diagnostics; reading never recreates a task or retries work.+ */+ readonly get: operations["get_indexing_run_api_knowledge_bases__kb_name__indexing_run_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/knowledge-bases/{kb_name}/indexing-run/{task_id}/cancel": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly get?: never;+ readonly put?: never;+ /** Cancel Indexing Run */+ readonly post: operations["cancel_indexing_run_api_knowledge_bases__kb_name__indexing_run__task_id__cancel_post"];+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };readonly "/api/knowledge-bases/{kb_name}/link-folder": {readonly parameters: {readonly query?: never;@@ -2139,6 +2193,23 @@ export interface paths {readonly patch?: never;readonly trace?: never;};+ readonly "/api/knowledge-bases/{kb_name}/source-page": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Kb Source Page */+ readonly get: operations["kb_source_page_api_knowledge_bases__kb_name__source_page_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };readonly "/api/knowledge-bases/{kb_name}/sync-folder/{folder_id}": {readonly parameters: {readonly query?: never;@@ -2245,6 +2316,23 @@ export interface paths {readonly patch?: never;readonly trace?: never;};+ readonly "/api/knowledge-bases/{kb_name}/visual-coverage": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Kb Visual Coverage */+ readonly get: operations["kb_visual_coverage_api_knowledge_bases__kb_name__visual_coverage_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };readonly "/api/knowledge-bases/{kb_name}/web-source": {readonly parameters: {readonly query?: never;@@ -3064,6 +3152,10 @@ export interface paths {/*** Get Llamaindex Pipeline Config* @description Read the LlamaIndex engine's retrieval + chunking knobs.+ *+ * ``retrieval_profile`` is what is *configured*; ``effective_retrieval_profile``+ * is what would actually run — a hybrid configuration degrades to vector-only+ * when the BM25 package is missing (e.g. Python 3.14 installs, #1792).*/readonly get: operations["get_llamaindex_pipeline_config_api_knowledge_bases_rag_pipelines_llamaindex_config_get"];/**@@ -3208,6 +3300,23 @@ export interface paths {readonly patch?: never;readonly trace?: never;};+ readonly "/api/learning-journal": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Overview */+ readonly get: operations["overview_api_learning_journal_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };readonly "/api/marginnote4/devices": {readonly parameters: {readonly query?: never;@@ -5841,31 +5950,28 @@ export interface paths {readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/categories": {+ readonly "/api/plugins/{plugin_id}/{plugin_path}": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /**- * List Categories- * @description Categories, with their counts scoped the same way the listing is.- *- * Without the scope the rail would offer "Address translation 3" inside a- * course holding none of those three.- */- readonly get: operations["list_categories_api_question_notebook_categories_get"];- readonly put?: never;- /** Create Category */- readonly post: operations["create_category_api_question_notebook_categories_post"];- readonly delete?: never;+ /** Dispatch Plugin Route */+ readonly get: operations["dispatch_plugin_route_get"];+ /** Dispatch Plugin Route */+ readonly put: operations["dispatch_plugin_route_put"];+ /** Dispatch Plugin Route */+ readonly post: operations["dispatch_plugin_route_post"];+ /** Dispatch Plugin Route */+ readonly delete: operations["dispatch_plugin_route_delete"];readonly options?: never;readonly head?: never;- readonly patch?: never;+ /** Dispatch Plugin Route */+ readonly patch: operations["dispatch_plugin_route_patch"];readonly trace?: never;};- readonly "/api/question-notebook/categories/{category_id}": {+ readonly "/api/plugins/{plugin_id}/approve": {readonly parameters: {readonly query?: never;readonly header?: never;@@ -5874,69 +5980,66 @@ export interface paths {};readonly get?: never;readonly put?: never;- readonly post?: never;- /** Delete Category */- readonly delete: operations["delete_category_api_question_notebook_categories__category_id__delete"];+ /** Approve Plugin */+ readonly post: operations["approve_plugin_api_plugins__plugin_id__approve_post"];+ readonly delete?: never;readonly options?: never;readonly head?: never;- /** Rename Category */- readonly patch: operations["rename_category_api_question_notebook_categories__category_id__patch"];+ readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/entries": {+ readonly "/api/plugins/{plugin_id}/disable": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /** List Entries */- readonly get: operations["list_entries_api_question_notebook_entries_get"];+ readonly get?: never;readonly put?: never;- readonly post?: never;+ /** Disable Plugin */+ readonly post: operations["disable_plugin_api_plugins__plugin_id__disable_post"];readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/entries/{entry_id}": {+ readonly "/api/plugins/{plugin_id}/enable": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /** Get Entry */- readonly get: operations["get_entry_api_question_notebook_entries__entry_id__get"];+ readonly get?: never;readonly put?: never;- readonly post?: never;- /** Delete Entry */- readonly delete: operations["delete_entry_api_question_notebook_entries__entry_id__delete"];+ /** Enable Plugin */+ readonly post: operations["enable_plugin_api_plugins__plugin_id__enable_post"];+ readonly delete?: never;readonly options?: never;readonly head?: never;- /** Update Entry */- readonly patch: operations["update_entry_api_question_notebook_entries__entry_id__patch"];+ readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/entries/{entry_id}/categories": {+ readonly "/api/plugins/{plugin_id}/info": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- readonly get?: never;+ /** Plugin Info */+ readonly get: operations["plugin_info_api_plugins__plugin_id__info_get"];readonly put?: never;- /** Add Entry To Category */- readonly post: operations["add_entry_to_category_api_question_notebook_entries__entry_id__categories_post"];+ readonly post?: never;readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/entries/{entry_id}/categories/{category_id}": {+ readonly "/api/plugins/{plugin_id}/install": {readonly parameters: {readonly query?: never;readonly header?: never;@@ -5945,15 +6048,15 @@ export interface paths {};readonly get?: never;readonly put?: never;- readonly post?: never;- /** Remove Entry From Category */- readonly delete: operations["remove_entry_from_category_api_question_notebook_entries__entry_id__categories__category_id__delete"];+ /** Install Plugin */+ readonly post: operations["install_plugin_api_plugins__plugin_id__install_post"];+ readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/entries/categories/bulk": {+ readonly "/api/plugins/{plugin_id}/installation": {readonly parameters: {readonly query?: never;readonly header?: never;@@ -5962,23 +6065,23 @@ export interface paths {};readonly get?: never;readonly put?: never;- /** Bulk Link Entries */- readonly post: operations["bulk_link_entries_api_question_notebook_entries_categories_bulk_post"];- readonly delete?: never;+ readonly post?: never;+ /** Uninstall Plugin */+ readonly delete: operations["uninstall_plugin_api_plugins__plugin_id__installation_delete"];readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/entries/lookup/by-question": {+ readonly "/api/plugins/{plugin_id}/pages/{extension_id}": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /** Lookup Entry */- readonly get: operations["lookup_entry_api_question_notebook_entries_lookup_by_question_get"];+ /** Redirect Plugin Frontend Page */+ readonly get: operations["redirect_plugin_frontend_page_api_plugins__plugin_id__pages__extension_id__get"];readonly put?: never;readonly post?: never;readonly delete?: never;@@ -5987,35 +6090,32 @@ export interface paths {readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/entries/upsert": {+ readonly "/api/plugins/{plugin_id}/pages/{extension_id}/": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- readonly get?: never;+ /** Get Plugin Frontend Page */+ readonly get: operations["get_plugin_frontend_page_api_plugins__plugin_id__pages__extension_id___get"];readonly put?: never;- /** Upsert Single Entry */- readonly post: operations["upsert_single_entry_api_question_notebook_entries_upsert_post"];+ readonly post?: never;readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/materials": {+ readonly "/api/plugins/{plugin_id}/pages/{extension_id}/assets/{asset_path}": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /**- * List Question Bank Materials- * @description Materials represented in the unified review history.- */- readonly get: operations["list_question_bank_materials_api_question_notebook_materials_get"];+ /** Get Plugin Frontend Asset */+ readonly get: operations["get_plugin_frontend_asset_api_plugins__plugin_id__pages__extension_id__assets__asset_path__get"];readonly put?: never;readonly post?: never;readonly delete?: never;@@ -6024,66 +6124,66 @@ export interface paths {readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/practice/analytics": {+ readonly "/api/plugins/{plugin_id}/rollback": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /** Practice Analytics */- readonly get: operations["practice_analytics_api_question_notebook_practice_analytics_get"];+ readonly get?: never;readonly put?: never;- readonly post?: never;+ /** Rollback Plugin */+ readonly post: operations["rollback_plugin_api_plugins__plugin_id__rollback_post"];readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/practice/import/commit": {+ readonly "/api/plugins/catalog": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- readonly get?: never;+ /** Plugin Catalog */+ readonly get: operations["plugin_catalog_api_plugins_catalog_get"];readonly put?: never;- /** Import Commit */- readonly post: operations["import_commit_api_question_notebook_practice_import_commit_post"];+ readonly post?: never;readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/practice/import/preview": {+ readonly "/api/plugins/extensions": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- readonly get?: never;+ /** List Extensions */+ readonly get: operations["list_extensions_api_plugins_extensions_get"];readonly put?: never;- /** Import Preview */- readonly post: operations["import_preview_api_question_notebook_practice_import_preview_post"];+ readonly post?: never;readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/practice/import/template": {+ readonly "/api/plugins/state": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /** Import Template */- readonly get: operations["import_template_api_question_notebook_practice_import_template_get"];+ /** Plugin State */+ readonly get: operations["plugin_state_api_plugins_state_get"];readonly put?: never;readonly post?: never;readonly delete?: never;@@ -6092,24 +6192,31 @@ export interface paths {readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/practice/questions/{entry_id}": {+ readonly "/api/question-notebook/categories": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /** Practice Question */- readonly get: operations["practice_question_api_question_notebook_practice_questions__entry_id__get"];+ /**+ * List Categories+ * @description Categories, with their counts scoped the same way the listing is.+ *+ * Without the scope the rail would offer "Address translation 3" inside a+ * course holding none of those three.+ */+ readonly get: operations["list_categories_api_question_notebook_categories_get"];readonly put?: never;- readonly post?: never;+ /** Create Category */+ readonly post: operations["create_category_api_question_notebook_categories_post"];readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/practice/questions/{entry_id}/check": {+ readonly "/api/question-notebook/categories/{category_id}": {readonly parameters: {readonly query?: never;readonly header?: never;@@ -6118,117 +6225,361 @@ export interface paths {};readonly get?: never;readonly put?: never;- /** Check */- readonly post: operations["check_api_question_notebook_practice_questions__entry_id__check_post"];- readonly delete?: never;+ readonly post?: never;+ /** Delete Category */+ readonly delete: operations["delete_category_api_question_notebook_categories__category_id__delete"];readonly options?: never;readonly head?: never;- readonly patch?: never;+ /** Rename Category */+ readonly patch: operations["rename_category_api_question_notebook_categories__category_id__patch"];readonly trace?: never;};- readonly "/api/question-notebook/practice/questions/{entry_id}/review": {+ readonly "/api/question-notebook/entries": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- readonly get?: never;+ /** List Entries */+ readonly get: operations["list_entries_api_question_notebook_entries_get"];readonly put?: never;- /** Review */- readonly post: operations["review_api_question_notebook_practice_questions__entry_id__review_post"];+ readonly post?: never;readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/practice/queue": {+ readonly "/api/question-notebook/entries/{entry_id}": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /** Queue */- readonly get: operations["queue_api_question_notebook_practice_queue_get"];+ /** Get Entry */+ readonly get: operations["get_entry_api_question_notebook_entries__entry_id__get"];readonly put?: never;readonly post?: never;- readonly delete?: never;+ /** Delete Entry */+ readonly delete: operations["delete_entry_api_question_notebook_entries__entry_id__delete"];readonly options?: never;readonly head?: never;- readonly patch?: never;+ /** Update Entry */+ readonly patch: operations["update_entry_api_question_notebook_entries__entry_id__patch"];readonly trace?: never;};- readonly "/api/question-notebook/practice/summary": {+ readonly "/api/question-notebook/entries/{entry_id}/categories": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /** Summary */- readonly get: operations["summary_api_question_notebook_practice_summary_get"];+ readonly get?: never;readonly put?: never;- readonly post?: never;+ /** Add Entry To Category */+ readonly post: operations["add_entry_to_category_api_question_notebook_entries__entry_id__categories_post"];readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/question-notebook/stats": {+ readonly "/api/question-notebook/entries/{entry_id}/categories/{category_id}": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /**- * Question Bank Stats- * @description Counts behind the filter chips; also the agent's one-call overview.- *- * Takes the same course scope as the listing: showing one course's questions- * next to whole-library counts would make the rail lie about how much is there.- */- readonly get: operations["question_bank_stats_api_question_notebook_stats_get"];+ readonly get?: never;readonly put?: never;readonly post?: never;- readonly delete?: never;+ /** Remove Entry From Category */+ readonly delete: operations["remove_entry_from_category_api_question_notebook_entries__entry_id__categories__category_id__delete"];readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/reading/epub-pairings": {+ readonly "/api/question-notebook/entries/categories/bulk": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- /** Epub Pairings */- readonly get: operations["epub_pairings_api_reading_epub_pairings_get"];+ readonly get?: never;readonly put?: never;- /** Create Epub Pairing */- readonly post: operations["create_epub_pairing_api_reading_epub_pairings_post"];+ /** Bulk Link Entries */+ readonly post: operations["bulk_link_entries_api_question_notebook_entries_categories_bulk_post"];readonly delete?: never;readonly options?: never;readonly head?: never;readonly patch?: never;readonly trace?: never;};- readonly "/api/reading/epub-pairings/{pairing_id}": {+ readonly "/api/question-notebook/entries/lookup/by-question": {readonly parameters: {readonly query?: never;readonly header?: never;readonly path?: never;readonly cookie?: never;};- readonly get?: never;+ /** Lookup Entry */+ readonly get: operations["lookup_entry_api_question_notebook_entries_lookup_by_question_get"];readonly put?: never;readonly post?: never;- /** Remove Epub Pairing */+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/entries/upsert": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly get?: never;+ readonly put?: never;+ /** Upsert Single Entry */+ readonly post: operations["upsert_single_entry_api_question_notebook_entries_upsert_post"];+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/materials": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /**+ * List Question Bank Materials+ * @description Materials represented in the unified review history.+ */+ readonly get: operations["list_question_bank_materials_api_question_notebook_materials_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/practice/analytics": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Practice Analytics */+ readonly get: operations["practice_analytics_api_question_notebook_practice_analytics_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/practice/import/commit": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly get?: never;+ readonly put?: never;+ /** Import Commit */+ readonly post: operations["import_commit_api_question_notebook_practice_import_commit_post"];+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/practice/import/preview": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly get?: never;+ readonly put?: never;+ /** Import Preview */+ readonly post: operations["import_preview_api_question_notebook_practice_import_preview_post"];+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/practice/import/template": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Import Template */+ readonly get: operations["import_template_api_question_notebook_practice_import_template_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/practice/questions/{entry_id}": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Practice Question */+ readonly get: operations["practice_question_api_question_notebook_practice_questions__entry_id__get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/practice/questions/{entry_id}/check": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly get?: never;+ readonly put?: never;+ /** Check */+ readonly post: operations["check_api_question_notebook_practice_questions__entry_id__check_post"];+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/practice/questions/{entry_id}/review": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly get?: never;+ readonly put?: never;+ /** Review */+ readonly post: operations["review_api_question_notebook_practice_questions__entry_id__review_post"];+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/practice/queue": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Queue */+ readonly get: operations["queue_api_question_notebook_practice_queue_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/practice/summary": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Summary */+ readonly get: operations["summary_api_question_notebook_practice_summary_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/question-notebook/stats": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /**+ * Question Bank Stats+ * @description Counts behind the filter chips; also the agent's one-call overview.+ *+ * Takes the same course scope as the listing: showing one course's questions+ * next to whole-library counts would make the rail lie about how much is there.+ */+ readonly get: operations["question_bank_stats_api_question_notebook_stats_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/reading/epub-pairings": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /** Epub Pairings */+ readonly get: operations["epub_pairings_api_reading_epub_pairings_get"];+ readonly put?: never;+ /** Create Epub Pairing */+ readonly post: operations["create_epub_pairing_api_reading_epub_pairings_post"];+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/reading/epub-pairings/{pairing_id}": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly get?: never;+ readonly put?: never;+ readonly post?: never;+ /** Remove Epub Pairing */readonly delete: operations["remove_epub_pairing_api_reading_epub_pairings__pairing_id__delete"];readonly options?: never;readonly head?: never;@@ -7188,7 +7539,7 @@ export interface paths {readonly patch?: never;readonly trace?: never;};- readonly "/api/sessions/{session_id}/organization": {+ readonly "/api/sessions/{session_id}/migrate-watching": {readonly parameters: {readonly query?: never;readonly header?: never;@@ -7197,15 +7548,15 @@ export interface paths {};readonly get?: never;readonly put?: never;- readonly post?: never;+ /** Migrate Watching Session */+ readonly post: operations["migrate_watching_session_api_sessions__session_id__migrate_watching_post"];readonly delete?: never;readonly options?: never;readonly head?: never;- /** Update Session Organization */- readonly patch: operations["update_session_organization_api_sessions__session_id__organization_patch"];+ readonly patch?: never;readonly trace?: never;};- readonly "/api/sessions/{session_id}/purge": {+ readonly "/api/sessions/{session_id}/organization": {readonly parameters: {readonly query?: never;readonly header?: never;@@ -7215,7 +7566,24 @@ export interface paths {readonly get?: never;readonly put?: never;readonly post?: never;- /** Purge Session */+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ /** Update Session Organization */+ readonly patch: operations["update_session_organization_api_sessions__session_id__organization_patch"];+ readonly trace?: never;+ };+ readonly "/api/sessions/{session_id}/purge": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly get?: never;+ readonly put?: never;+ readonly post?: never;+ /** Purge Session */readonly delete: operations["purge_session_api_sessions__session_id__purge_delete"];readonly options?: never;readonly head?: never;@@ -7730,11 +8098,11 @@ export interface paths {readonly put?: never;/*** Fetch Models From Provider- * @description List the model IDs an OpenAI-compatible provider exposes.+ * @description List selectable model IDs using the provider's own authentication.** Thin HTTP surface over ``factory.fetch_models`` so the settings UI can- * populate a model picker from ``base_url`` + ``api_key`` instead of making- * the user type model IDs by hand.+ * populate a model picker. Copilot uses the caller's owner-private CLI login,+ * not the profile's API key or base URL.*/readonly post: operations["fetch_models_from_provider_api_settings_fetch_models_post"];readonly delete?: never;@@ -10923,6 +11291,11 @@ export interface components {readonly [key: string]: unknown;}[];};+ /** ApprovalRequest */+ readonly ApprovalRequest: {+ /** Snapshot Digest */+ readonly snapshot_digest: string;+ };/** AssetAddRequest */readonly AssetAddRequest: {/** Knowledge Bases */@@ -11054,7 +11427,10 @@ export interface components {};/** Body_admin_import_users_api_auth_users_import_post */readonly Body_admin_import_users_api_auth_users_import_post: {- /** File */+ /**+ * File+ * Format: binary+ */readonly file: string;};/** Body_create_knowledge_base_api_knowledge_bases_post */@@ -11098,7 +11474,10 @@ export interface components {};/** Body_import_docx_api_documents_import_docx_post */readonly Body_import_docx_api_documents_import_docx_post: {- /** File */+ /**+ * File+ * Format: binary+ */readonly file: string;};/** Body_import_preview_api_question_notebook_practice_import_preview_post */@@ -11108,7 +11487,10 @@ export interface components {* @default*/readonly course_id: string;- /** File */+ /**+ * File+ * Format: binary+ */readonly file: string;/*** Target@@ -11119,13 +11501,17 @@ export interface components {};/** Body_import_visualizer_api_visualizers_import_post */readonly Body_import_visualizer_api_visualizers_import_post: {- /** File */+ /**+ * File+ * Format: binary+ */readonly file: string;};/** Body_library_add */readonly Body_library_add: {/*** File+ * Format: binary* @description Raw file bytes*/readonly file: string;@@ -11142,7 +11528,10 @@ export interface components {};/** Body_preview_office_upload_api_file_preview_pdf_post */readonly Body_preview_office_upload_api_file_preview_pdf_post: {- /** File */+ /**+ * File+ * Format: binary+ */readonly file: string;};/** Body_reindex_knowledge_base_api_knowledge_bases__kb_name__reindex_post */@@ -11165,14 +11554,20 @@ export interface components {};/** Body_speech_to_text_api_voice_stt_post */readonly Body_speech_to_text_api_voice_stt_post: {- /** File */+ /**+ * File+ * Format: binary+ */readonly file: string;/** Language */readonly language?: string | null;};/** Body_upload_avatar_api_auth_profile_avatar_put */readonly Body_upload_avatar_api_auth_profile_avatar_put: {- /** File */+ /**+ * File+ * Format: binary+ */readonly file: string;};/** Body_upload_files_api_knowledge_bases__kb_name__upload_post */@@ -11193,7 +11588,10 @@ export interface components {};/** Body_upload_material_api_reading_materials_post */readonly Body_upload_material_api_reading_materials_post: {- /** File */+ /**+ * File+ * Format: binary+ */readonly file: string;};/** BookmarkInfo */@@ -12672,6 +13070,19 @@ export interface components {readonly [key: string]: string;};};+ /** InstallRequest */+ readonly InstallRequest: {+ /**+ * Allow Deprecated+ * @default false+ */+ readonly allow_deprecated: boolean;+ /**+ * Version+ * @default latest+ */+ readonly version: string;+ };/*** InstallSkillRequest* @description Install a hub skill into the caller's own skill layer.@@ -16761,6 +17172,7 @@ export type SchemaAnswerImageUpload =components["schemas"]["AnswerImageUpload"];export type SchemaAnswerRequest = components["schemas"]["AnswerRequest"];export type SchemaApplyOpsRequest = components["schemas"]["ApplyOpsRequest"];+export type SchemaApprovalRequest = components["schemas"]["ApprovalRequest"];export type SchemaAssetAddRequest = components["schemas"]["AssetAddRequest"];export type SchemaAssetSpec = components["schemas"]["AssetSpec"];export type SchemaAttachCourseResourceRequest =@@ -16983,6 +17395,7 @@ export type SchemaInitModulesRequest =export type SchemaInsertBlockRequest =components["schemas"]["InsertBlockRequest"];export type SchemaInstallPayload = components["schemas"]["InstallPayload"];+export type SchemaInstallRequest = components["schemas"]["InstallRequest"];export type SchemaInstallSkillRequest =components["schemas"]["InstallSkillRequest"];export type SchemaInvidiousSettings =@@ -21710,6 +22123,112 @@ export interface operations {};};};+ readonly get_indexing_readiness_api_knowledge_bases__kb_name__indexing_readiness_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly kb_name: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly get_indexing_run_api_knowledge_bases__kb_name__indexing_run_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly kb_name: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly cancel_indexing_run_api_knowledge_bases__kb_name__indexing_run__task_id__cancel_post: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly kb_name: string;+ readonly task_id: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };readonly link_folder_api_knowledge_bases__kb_name__link_folder_post: {readonly parameters: {readonly query?: never;@@ -22007,6 +22526,46 @@ export interface operations {};};};+ readonly kb_source_page_api_knowledge_bases__kb_name__source_page_get: {+ readonly parameters: {+ readonly query: {+ readonly page: number;+ readonly region?: string;+ readonly source_hash?: string;+ readonly source_path: string;+ };+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly kb_name: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };readonly sync_folder_api_knowledge_bases__kb_name__sync_folder__folder_id__post: {readonly parameters: {readonly query?: never;@@ -22188,6 +22747,45 @@ export interface operations {};};};+ readonly kb_visual_coverage_api_knowledge_bases__kb_name__visual_coverage_get: {+ readonly parameters: {+ readonly query?: {+ readonly limit?: number;+ readonly offset?: number;+ readonly source_path?: string;+ };+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly kb_name: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };readonly add_web_source_api_knowledge_bases__kb_name__web_source_post: {readonly parameters: {readonly query?: never;@@ -24016,7 +24614,7 @@ export interface operations {};};};- readonly list_devices_api_marginnote4_devices_get: {+ readonly overview_api_learning_journal_get: {readonly parameters: {readonly query?: never;readonly header?: {@@ -24035,7 +24633,7 @@ export interface operations {readonly [name: string]: unknown;};content: {- readonly "application/json": readonly components["schemas"]["DeviceInfo"][];+ readonly "application/json": unknown;};};/** @description Validation Error */@@ -24049,15 +24647,13 @@ export interface operations {};};};- readonly revoke_device_api_marginnote4_devices__device_id__delete: {+ readonly list_devices_api_marginnote4_devices_get: {readonly parameters: {readonly query?: never;readonly header?: {readonly Authorization?: string | null;};- readonly path: {- readonly device_id: string;- };+ readonly path?: never;readonly cookie?: {readonly dt_token?: string | null;};@@ -24070,9 +24666,7 @@ export interface operations {readonly [name: string]: unknown;};content: {- readonly "application/json": {- readonly [key: string]: string;- };+ readonly "application/json": readonly components["schemas"]["DeviceInfo"][];};};/** @description Validation Error */@@ -24086,14 +24680,18 @@ export interface operations {};};};- readonly heartbeat_api_marginnote4_heartbeat_post: {+ readonly revoke_device_api_marginnote4_devices__device_id__delete: {readonly parameters: {readonly query?: never;readonly header?: {- readonly authorization?: string | null;+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly device_id: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;};- readonly path?: never;- readonly cookie?: never;};readonly requestBody?: never;readonly responses: {@@ -24104,7 +24702,7 @@ export interface operations {};content: {readonly "application/json": {- readonly [key: string]: unknown;+ readonly [key: string]: string;};};};@@ -24119,11 +24717,44 @@ export interface operations {};};};- readonly pair_device_api_marginnote4_pair_post: {+ readonly heartbeat_api_marginnote4_heartbeat_post: {readonly parameters: {readonly query?: never;readonly header?: {- readonly Authorization?: string | null;+ readonly authorization?: string | null;+ };+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": {+ readonly [key: string]: unknown;+ };+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly pair_device_api_marginnote4_pair_post: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;};readonly path?: never;readonly cookie?: {@@ -29735,23 +30366,561 @@ export interface operations {readonly [name: string]: unknown;};content: {- readonly "application/json": components["schemas"]["HTTPValidationError"];+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly soul_sources_api_partners_soul_sources_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path?: never;+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly list_souls_api_partners_souls_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path?: never;+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly create_soul_api_partners_souls_post: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path?: never;+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody: {+ readonly content: {+ readonly "application/json": components["schemas"]["SoulCreateRequest"];+ };+ };+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly get_soul_api_partners_souls__soul_id__get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly soul_id: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly update_soul_api_partners_souls__soul_id__put: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly soul_id: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody: {+ readonly content: {+ readonly "application/json": components["schemas"]["SoulTemplateUpdateRequest"];+ };+ };+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly delete_soul_api_partners_souls__soul_id__delete: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly soul_id: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly tool_options_api_partners_tool_options_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path?: never;+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly list_personas_api_personas_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path?: never;+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": {+ readonly [key: string]: readonly {+ readonly [key: string]: unknown;+ }[];+ };+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly create_persona_api_personas_post: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path?: never;+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody: {+ readonly content: {+ readonly "application/json": components["schemas"]["CreatePersonaRequest"];+ };+ };+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": {+ readonly [key: string]: unknown;+ };+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly get_persona_api_personas__name__get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly name: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": {+ readonly [key: string]: unknown;+ };+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly update_persona_api_personas__name__put: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly name: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody: {+ readonly content: {+ readonly "application/json": components["schemas"]["UpdatePersonaRequest"];+ };+ };+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": {+ readonly [key: string]: unknown;+ };+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly delete_persona_api_personas__name__delete: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly name: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": {+ readonly [key: string]: string;+ };+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };+ readonly dispatch_plugin_route_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ };+ };+ readonly dispatch_plugin_route_put: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ };+ };+ readonly dispatch_plugin_route_post: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ };+ };+ readonly dispatch_plugin_route_delete: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ };+ };+ readonly dispatch_plugin_route_patch: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;};};};};- readonly soul_sources_api_partners_soul_sources_get: {+ readonly approve_plugin_api_plugins__plugin_id__approve_post: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;+ readonly header?: never;+ readonly path: {+ readonly plugin_id: string;};- readonly path?: never;- readonly cookie?: {- readonly dt_token?: string | null;+ readonly cookie?: never;+ };+ readonly requestBody: {+ readonly content: {+ readonly "application/json": components["schemas"]["ApprovalRequest"];};};- readonly requestBody?: never;readonly responses: {/** @description Successful Response */readonly 200: {@@ -29773,16 +30942,14 @@ export interface operations {};};};- readonly list_souls_api_partners_souls_get: {+ readonly disable_plugin_api_plugins__plugin_id__disable_post: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };- readonly path?: never;- readonly cookie?: {- readonly dt_token?: string | null;+ readonly header?: never;+ readonly path: {+ readonly plugin_id: string;};+ readonly cookie?: never;};readonly requestBody?: never;readonly responses: {@@ -29806,22 +30973,16 @@ export interface operations {};};};- readonly create_soul_api_partners_souls_post: {+ readonly enable_plugin_api_plugins__plugin_id__enable_post: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };- readonly path?: never;- readonly cookie?: {- readonly dt_token?: string | null;- };- };- readonly requestBody: {- readonly content: {- readonly "application/json": components["schemas"]["SoulCreateRequest"];+ readonly header?: never;+ readonly path: {+ readonly plugin_id: string;};+ readonly cookie?: never;};+ readonly requestBody?: never;readonly responses: {/** @description Successful Response */readonly 200: {@@ -29843,18 +31004,14 @@ export interface operations {};};};- readonly get_soul_api_partners_souls__soul_id__get: {+ readonly plugin_info_api_plugins__plugin_id__info_get: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };+ readonly header?: never;readonly path: {- readonly soul_id: string;- };- readonly cookie?: {- readonly dt_token?: string | null;+ readonly plugin_id: string;};+ readonly cookie?: never;};readonly requestBody?: never;readonly responses: {@@ -29878,22 +31035,18 @@ export interface operations {};};};- readonly update_soul_api_partners_souls__soul_id__put: {+ readonly install_plugin_api_plugins__plugin_id__install_post: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };+ readonly header?: never;readonly path: {- readonly soul_id: string;- };- readonly cookie?: {- readonly dt_token?: string | null;+ readonly plugin_id: string;};+ readonly cookie?: never;};readonly requestBody: {readonly content: {- readonly "application/json": components["schemas"]["SoulTemplateUpdateRequest"];+ readonly "application/json": components["schemas"]["InstallRequest"];};};readonly responses: {@@ -29917,18 +31070,14 @@ export interface operations {};};};- readonly delete_soul_api_partners_souls__soul_id__delete: {+ readonly uninstall_plugin_api_plugins__plugin_id__installation_delete: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };+ readonly header?: never;readonly path: {- readonly soul_id: string;- };- readonly cookie?: {- readonly dt_token?: string | null;+ readonly plugin_id: string;};+ readonly cookie?: never;};readonly requestBody?: never;readonly responses: {@@ -29952,16 +31101,12 @@ export interface operations {};};};- readonly tool_options_api_partners_tool_options_get: {+ readonly redirect_plugin_frontend_page_api_plugins__plugin_id__pages__extension_id__get: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };+ readonly header?: never;readonly path?: never;- readonly cookie?: {- readonly dt_token?: string | null;- };+ readonly cookie?: never;};readonly requestBody?: never;readonly responses: {@@ -29974,27 +31119,14 @@ export interface operations {readonly "application/json": unknown;};};- /** @description Validation Error */- readonly 422: {- headers: {- readonly [name: string]: unknown;- };- content: {- readonly "application/json": components["schemas"]["HTTPValidationError"];- };- };};};- readonly list_personas_api_personas_get: {+ readonly get_plugin_frontend_page_api_plugins__plugin_id__pages__extension_id___get: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };+ readonly header?: never;readonly path?: never;- readonly cookie?: {- readonly dt_token?: string | null;- };+ readonly cookie?: never;};readonly requestBody?: never;readonly responses: {@@ -30004,40 +31136,19 @@ export interface operations {readonly [name: string]: unknown;};content: {- readonly "application/json": {- readonly [key: string]: readonly {- readonly [key: string]: unknown;- }[];- };- };- };- /** @description Validation Error */- readonly 422: {- headers: {- readonly [name: string]: unknown;- };- content: {- readonly "application/json": components["schemas"]["HTTPValidationError"];+ readonly "application/json": unknown;};};};};- readonly create_persona_api_personas_post: {+ readonly get_plugin_frontend_asset_api_plugins__plugin_id__pages__extension_id__assets__asset_path__get: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };+ readonly header?: never;readonly path?: never;- readonly cookie?: {- readonly dt_token?: string | null;- };- };- readonly requestBody: {- readonly content: {- readonly "application/json": components["schemas"]["CreatePersonaRequest"];- };+ readonly cookie?: never;};+ readonly requestBody?: never;readonly responses: {/** @description Successful Response */readonly 200: {@@ -30045,34 +31156,19 @@ export interface operations {readonly [name: string]: unknown;};content: {- readonly "application/json": {- readonly [key: string]: unknown;- };- };- };- /** @description Validation Error */- readonly 422: {- headers: {- readonly [name: string]: unknown;- };- content: {- readonly "application/json": components["schemas"]["HTTPValidationError"];+ readonly "application/json": unknown;};};};};- readonly get_persona_api_personas__name__get: {+ readonly rollback_plugin_api_plugins__plugin_id__rollback_post: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };+ readonly header?: never;readonly path: {- readonly name: string;- };- readonly cookie?: {- readonly dt_token?: string | null;+ readonly plugin_id: string;};+ readonly cookie?: never;};readonly requestBody?: never;readonly responses: {@@ -30082,9 +31178,7 @@ export interface operations {readonly [name: string]: unknown;};content: {- readonly "application/json": {- readonly [key: string]: unknown;- };+ readonly "application/json": unknown;};};/** @description Validation Error */@@ -30098,24 +31192,14 @@ export interface operations {};};};- readonly update_persona_api_personas__name__put: {+ readonly plugin_catalog_api_plugins_catalog_get: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };- readonly path: {- readonly name: string;- };- readonly cookie?: {- readonly dt_token?: string | null;- };- };- readonly requestBody: {- readonly content: {- readonly "application/json": components["schemas"]["UpdatePersonaRequest"];- };+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;};+ readonly requestBody?: never;readonly responses: {/** @description Successful Response */readonly 200: {@@ -30123,34 +31207,17 @@ export interface operations {readonly [name: string]: unknown;};content: {- readonly "application/json": {- readonly [key: string]: unknown;- };- };- };- /** @description Validation Error */- readonly 422: {- headers: {- readonly [name: string]: unknown;- };- content: {- readonly "application/json": components["schemas"]["HTTPValidationError"];+ readonly "application/json": unknown;};};};};- readonly delete_persona_api_personas__name__delete: {+ readonly list_extensions_api_plugins_extensions_get: {readonly parameters: {readonly query?: never;- readonly header?: {- readonly Authorization?: string | null;- };- readonly path: {- readonly name: string;- };- readonly cookie?: {- readonly dt_token?: string | null;- };+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;};readonly requestBody?: never;readonly responses: {@@ -30161,17 +31228,28 @@ export interface operations {};content: {readonly "application/json": {- readonly [key: string]: string;+ readonly [key: string]: unknown;};};};- /** @description Validation Error */- readonly 422: {+ };+ };+ readonly plugin_state_api_plugins_state_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {headers: {readonly [name: string]: unknown;};content: {- readonly "application/json": components["schemas"]["HTTPValidationError"];+ readonly "application/json": unknown;};};};@@ -33509,6 +34587,41 @@ export interface operations {};};};+ readonly migrate_watching_session_api_sessions__session_id__migrate_watching_post: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path: {+ readonly session_id: string;+ };+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": unknown;+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };readonly update_session_organization_api_sessions__session_id__organization_patch: {readonly parameters: {readonly query?: never;diff --git a/web/contracts/schema/openapi.json b/web/contracts/schema/openapi.jsonindex 55b81f02b..3e27d8be0 100644--- a/web/contracts/schema/openapi.json+++ b/web/contracts/schema/openapi.json@@ -473,6 +473,20 @@"title": "ApplyOpsRequest","type": "object"},+ "ApprovalRequest": {+ "properties": {+ "snapshot_digest": {+ "pattern": "^[0-9a-f]{64}$",+ "title": "Snapshot Digest",+ "type": "string"+ }+ },+ "required": [+ "snapshot_digest"+ ],+ "title": "ApprovalRequest",+ "type": "object"+ },"AssetAddRequest": {"properties": {"knowledge_bases": {@@ -770,7 +784,7 @@"Body_admin_import_users_api_auth_users_import_post": {"properties": {"file": {- "contentMediaType": "application/octet-stream",+ "format": "binary","title": "File","type": "string"}@@ -791,7 +805,7 @@"files": {"default": [],"items": {- "contentMediaType": "application/octet-stream",+ "format": "binary","type": "string"},"title": "Files",@@ -849,7 +863,7 @@"Body_import_docx_api_documents_import_docx_post": {"properties": {"file": {- "contentMediaType": "application/octet-stream",+ "format": "binary","title": "File","type": "string"}@@ -869,7 +883,7 @@"type": "string"},"file": {- "contentMediaType": "application/octet-stream",+ "format": "binary","title": "File","type": "string"},@@ -892,7 +906,7 @@"Body_import_visualizer_api_visualizers_import_post": {"properties": {"file": {- "contentMediaType": "application/octet-stream",+ "format": "binary","title": "File","type": "string"}@@ -906,8 +920,8 @@"Body_library_add": {"properties": {"file": {- "contentMediaType": "application/octet-stream","description": "Raw file bytes",+ "format": "binary","title": "File","type": "string"},@@ -932,7 +946,7 @@"Body_preview_office_upload_api_file_preview_pdf_post": {"properties": {"file": {- "contentMediaType": "application/octet-stream",+ "format": "binary","title": "File","type": "string"}@@ -967,7 +981,7 @@"Body_speech_to_text_api_voice_stt_post": {"properties": {"file": {- "contentMediaType": "application/octet-stream",+ "format": "binary","title": "File","type": "string"},@@ -992,7 +1006,7 @@"Body_upload_avatar_api_auth_profile_avatar_put": {"properties": {"file": {- "contentMediaType": "application/octet-stream",+ "format": "binary","title": "File","type": "string"}@@ -1011,7 +1025,7 @@},"files": {"items": {- "contentMediaType": "application/octet-stream",+ "format": "binary","type": "string"},"title": "Files",@@ -1050,7 +1064,7 @@"Body_upload_material_api_reading_materials_post": {"properties": {"file": {- "contentMediaType": "application/octet-stream",+ "format": "binary","title": "File","type": "string"}@@ -4348,6 +4362,23 @@"title": "InstallPayload","type": "object"},+ "InstallRequest": {+ "properties": {+ "allow_deprecated": {+ "default": false,+ "title": "Allow Deprecated",+ "type": "boolean"+ },+ "version": {+ "default": "latest",+ "maxLength": 64,+ "title": "Version",+ "type": "string"+ }+ },+ "title": "InstallRequest",+ "type": "object"+ },"InstallSkillRequest": {"description": "Install a hub skill into the caller's own skill layer.\n\n``ref`` is a ``<hub>:<slug>[@version]`` reference (the bare hub prefix\ndefaults to ``eduhub``). The web \"import from EduHub\" flow always builds an\n``eduhub:`` ref so a spoofed bridge message can't redirect the install to an\narbitrary registry.","properties": {@@ -23451,7 +23482,7 @@},"/api/knowledge-bases/rag-pipelines/llamaindex/config": {"get": {- "description": "Read the LlamaIndex engine's retrieval + chunking knobs.",+ "description": "Read the LlamaIndex engine's retrieval + chunking knobs.\n\n``retrieval_profile`` is what is *configured*; ``effective_retrieval_profile``\nis what would actually run — a hybrid configuration degrades to vector-only\nwhen the BM25 package is missing (e.g. Python 3.14 installs, #1792).","operationId": "get_llamaindex_pipeline_config_api_knowledge_bases_rag_pipelines_llamaindex_config_get","parameters": [{@@ -25275,10 +25306,9 @@]}},- "/api/knowledge-bases/{kb_name}/link-folder": {- "post": {- "description": "Link a local folder to a knowledge base.\n\nThis allows syncing documents from a local folder (which can be\nsynced with SharePoint, Google Drive, OneLake, etc.) to the KB.\n\nThe folder path supports:\n- Absolute paths: /Users/name/Documents or C:\\Users\\name\\Documents\n- Home directory: ~/Documents\n- Relative paths (resolved from server working directory)",- "operationId": "link_folder_api_knowledge_bases__kb_name__link_folder_post",+ "/api/knowledge-bases/{kb_name}/indexing-readiness": {+ "get": {+ "operationId": "get_indexing_readiness_api_knowledge_bases__kb_name__indexing_readiness_get","parameters": [{"in": "path",@@ -25322,23 +25352,11 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/LinkFolderRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {- "schema": {- "$ref": "#/components/schemas/LinkedFolderInfo"- }+ "schema": {}}},"description": "Successful Response"@@ -25354,16 +25372,16 @@"description": "Validation Error"}},- "summary": "Link Folder",+ "summary": "Get Indexing Readiness","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/linked-folders": {+ "/api/knowledge-bases/{kb_name}/indexing-run": {"get": {- "description": "Get list of linked folders for a knowledge base.",- "operationId": "get_linked_folders_api_knowledge_bases__kb_name__linked_folders_get",+ "description": "Pure durable diagnostics; reading never recreates a task or retries work.",+ "operationId": "get_indexing_run_api_knowledge_bases__kb_name__indexing_run_get","parameters": [{"in": "path",@@ -25411,13 +25429,7 @@"200": {"content": {"application/json": {- "schema": {- "items": {- "$ref": "#/components/schemas/LinkedFolderInfo"- },- "title": "Response Get Linked Folders Api Knowledge Bases Kb Name Linked Folders Get",- "type": "array"- }+ "schema": {}}},"description": "Successful Response"@@ -25433,16 +25445,15 @@"description": "Validation Error"}},- "summary": "Get Linked Folders",+ "summary": "Get Indexing Run","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/linked-folders/{folder_id}": {- "delete": {- "description": "Unlink a folder from a knowledge base.",- "operationId": "unlink_folder_api_knowledge_bases__kb_name__linked_folders__folder_id__delete",+ "/api/knowledge-bases/{kb_name}/indexing-run/{task_id}/cancel": {+ "post": {+ "operationId": "cancel_indexing_run_api_knowledge_bases__kb_name__indexing_run__task_id__cancel_post","parameters": [{"in": "path",@@ -25455,10 +25466,10 @@},{"in": "path",- "name": "folder_id",+ "name": "task_id","required": true,"schema": {- "title": "Folder Id",+ "title": "Task Id","type": "string"}},@@ -25515,16 +25526,16 @@"description": "Validation Error"}},- "summary": "Unlink Folder",+ "summary": "Cancel Indexing Run","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/progress": {- "get": {- "description": "Get initialization progress for a knowledge base",- "operationId": "get_progress_api_knowledge_bases__kb_name__progress_get",+ "/api/knowledge-bases/{kb_name}/link-folder": {+ "post": {+ "description": "Link a local folder to a knowledge base.\n\nThis allows syncing documents from a local folder (which can be\nsynced with SharePoint, Google Drive, OneLake, etc.) to the KB.\n\nThe folder path supports:\n- Absolute paths: /Users/name/Documents or C:\\Users\\name\\Documents\n- Home directory: ~/Documents\n- Relative paths (resolved from server working directory)",+ "operationId": "link_folder_api_knowledge_bases__kb_name__link_folder_post","parameters": [{"in": "path",@@ -25568,11 +25579,23 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/LinkFolderRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "$ref": "#/components/schemas/LinkedFolderInfo"+ }}},"description": "Successful Response"@@ -25588,16 +25611,16 @@"description": "Validation Error"}},- "summary": "Get Progress",+ "summary": "Link Folder","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/progress/clear": {- "post": {- "description": "Clear progress file for a knowledge base (useful for stuck states)",- "operationId": "clear_progress_api_knowledge_bases__kb_name__progress_clear_post",+ "/api/knowledge-bases/{kb_name}/linked-folders": {+ "get": {+ "description": "Get list of linked folders for a knowledge base.",+ "operationId": "get_linked_folders_api_knowledge_bases__kb_name__linked_folders_get","parameters": [{"in": "path",@@ -25645,7 +25668,13 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "items": {+ "$ref": "#/components/schemas/LinkedFolderInfo"+ },+ "title": "Response Get Linked Folders Api Knowledge Bases Kb Name Linked Folders Get",+ "type": "array"+ }}},"description": "Successful Response"@@ -25661,16 +25690,16 @@"description": "Validation Error"}},- "summary": "Clear Progress",+ "summary": "Get Linked Folders","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/reindex": {- "post": {- "description": "Re-index ``kb_name`` through its bound RAG provider.\n\nLlamaIndex keys versions by the selected embedding model. The other\nproviders keep synthetic provider-keyed versions, so they should rebuild\nwithout requiring an embedding-signature precheck.",- "operationId": "reindex_knowledge_base_api_knowledge_bases__kb_name__reindex_post",+ "/api/knowledge-bases/{kb_name}/linked-folders/{folder_id}": {+ "delete": {+ "description": "Unlink a folder from a knowledge base.",+ "operationId": "unlink_folder_api_knowledge_bases__kb_name__linked_folders__folder_id__delete","parameters": [{"in": "path",@@ -25681,6 +25710,15 @@"type": "string"}},+ {+ "in": "path",+ "name": "folder_id",+ "required": true,+ "schema": {+ "title": "Folder Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -25714,24 +25752,11 @@}}],- "requestBody": {- "content": {- "application/x-www-form-urlencoded": {- "schema": {- "$ref": "#/components/schemas/Body_reindex_knowledge_base_api_knowledge_bases__kb_name__reindex_post"- }- }- }- },"responses": {"200": {"content": {"application/json": {- "schema": {- "additionalProperties": true,- "title": "Response Reindex Knowledge Base Api Knowledge Bases Kb Name Reindex Post",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -25747,16 +25772,16 @@"description": "Validation Error"}},- "summary": "Reindex Knowledge Base",+ "summary": "Unlink Folder","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/reindex-config": {+ "/api/knowledge-bases/{kb_name}/progress": {"get": {- "description": "Read selected embedding and current role defaults for rebuild confirmation.",- "operationId": "get_reindex_config_api_knowledge_bases__kb_name__reindex_config_get",+ "description": "Get initialization progress for a knowledge base",+ "operationId": "get_progress_api_knowledge_bases__kb_name__progress_get","parameters": [{"in": "path",@@ -25768,12 +25793,75 @@}},{- "in": "query",- "name": "embedding_model",+ "in": "header",+ "name": "Authorization","required": false,"schema": {- "default": "",- "title": "Embedding Model",+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Get Progress",+ "tags": [+ "knowledge-bases"+ ]+ }+ },+ "/api/knowledge-bases/{kb_name}/progress/clear": {+ "post": {+ "description": "Clear progress file for a knowledge base (useful for stuck states)",+ "operationId": "clear_progress_api_knowledge_bases__kb_name__progress_clear_post",+ "parameters": [+ {+ "in": "path",+ "name": "kb_name",+ "required": true,+ "schema": {+ "title": "Kb Name","type": "string"}},@@ -25814,11 +25902,7 @@"200": {"content": {"application/json": {- "schema": {- "additionalProperties": true,- "title": "Response Get Reindex Config Api Knowledge Bases Kb Name Reindex Config Get",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -25834,16 +25918,16 @@"description": "Validation Error"}},- "summary": "Get Reindex Config",+ "summary": "Clear Progress","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/retry": {+ "/api/knowledge-bases/{kb_name}/reindex": {"post": {- "description": "Retry a failed KB initialization/indexing run from its stored raw files.",- "operationId": "retry_knowledge_base_api_knowledge_bases__kb_name__retry_post",+ "description": "Re-index ``kb_name`` through its bound RAG provider.\n\nLlamaIndex keys versions by the selected embedding model. The other\nproviders keep synthetic provider-keyed versions, so they should rebuild\nwithout requiring an embedding-signature precheck.",+ "operationId": "reindex_knowledge_base_api_knowledge_bases__kb_name__reindex_post","parameters": [{"in": "path",@@ -25887,13 +25971,22 @@}}],+ "requestBody": {+ "content": {+ "application/x-www-form-urlencoded": {+ "schema": {+ "$ref": "#/components/schemas/Body_reindex_knowledge_base_api_knowledge_bases__kb_name__reindex_post"+ }+ }+ }+ },"responses": {"200": {"content": {"application/json": {"schema": {"additionalProperties": true,- "title": "Response Retry Knowledge Base Api Knowledge Bases Kb Name Retry Post",+ "title": "Response Reindex Knowledge Base Api Knowledge Bases Kb Name Reindex Post","type": "object"}}@@ -25911,16 +26004,16 @@"description": "Validation Error"}},- "summary": "Retry Knowledge Base",+ "summary": "Reindex Knowledge Base","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/sync-folder/{folder_id}": {- "post": {- "description": "Sync files from a linked folder to the knowledge base.\n\nThis scans the linked folder for supported documents and processes\nany new files that haven't been added yet.",- "operationId": "sync_folder_api_knowledge_bases__kb_name__sync_folder__folder_id__post",+ "/api/knowledge-bases/{kb_name}/reindex-config": {+ "get": {+ "description": "Read selected embedding and current role defaults for rebuild confirmation.",+ "operationId": "get_reindex_config_api_knowledge_bases__kb_name__reindex_config_get","parameters": [{"in": "path",@@ -25932,11 +26025,12 @@}},{- "in": "path",- "name": "folder_id",- "required": true,+ "in": "query",+ "name": "embedding_model",+ "required": false,"schema": {- "title": "Folder Id",+ "default": "",+ "title": "Embedding Model","type": "string"}},@@ -25978,7 +26072,9 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/SyncFolderResponse"+ "additionalProperties": true,+ "title": "Response Get Reindex Config Api Knowledge Bases Kb Name Reindex Config Get",+ "type": "object"}}},@@ -25995,15 +26091,16 @@"description": "Validation Error"}},- "summary": "Sync Folder",+ "summary": "Get Reindex Config","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/sync-github": {+ "/api/knowledge-bases/{kb_name}/retry": {"post": {- "operationId": "sync_github_sources_api_knowledge_bases__kb_name__sync_github_post",+ "description": "Retry a failed KB initialization/indexing run from its stored raw files.",+ "operationId": "retry_knowledge_base_api_knowledge_bases__kb_name__retry_post","parameters": [{"in": "path",@@ -26051,7 +26148,11 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Retry Knowledge Base Api Knowledge Bases Kb Name Retry Post",+ "type": "object"+ }}},"description": "Successful Response"@@ -26067,16 +26168,15 @@"description": "Validation Error"}},- "summary": "Sync Github Sources",+ "summary": "Retry Knowledge Base","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/sync-web": {- "post": {- "description": "Run one bounded crawl-and-sync pass for every enabled web source.",- "operationId": "sync_web_sources_api_knowledge_bases__kb_name__sync_web_post",+ "/api/knowledge-bases/{kb_name}/source-page": {+ "get": {+ "operationId": "kb_source_page_api_knowledge_bases__kb_name__source_page_get","parameters": [{"in": "path",@@ -26088,75 +26188,41 @@}},{- "in": "header",- "name": "Authorization",- "required": false,+ "in": "query",+ "name": "source_path",+ "required": true,"schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Authorization"+ "title": "Source Path",+ "type": "string"}},{- "in": "cookie",- "name": "dt_token",+ "in": "query",+ "name": "page",+ "required": true,+ "schema": {+ "minimum": 1,+ "title": "Page",+ "type": "integer"+ }+ },+ {+ "in": "query",+ "name": "source_hash","required": false,"schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Dt Token"+ "default": "",+ "title": "Source Hash",+ "type": "string"}- }- ],- "responses": {- "200": {- "content": {- "application/json": {- "schema": {}- }- },- "description": "Successful Response"},- "422": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/HTTPValidationError"- }- }- },- "description": "Validation Error"- }- },- "summary": "Sync Web Sources",- "tags": [- "knowledge-bases"- ]- }- },- "/api/knowledge-bases/{kb_name}/upload": {- "post": {- "description": "Upload files to a knowledge base and process them in background.\n\n``dest_subdir`` places the whole batch under that folder inside the KB.\nA browser folder pick reports each file's path relative to the chosen\ndirectory, so the directory's own ancestors never reach the server; this\nis how a caller adding one subtree at a time re-attaches it where it\nbelongs instead of piling every batch at the root (#866).",- "operationId": "upload_files_api_knowledge_bases__kb_name__upload_post",- "parameters": [{- "in": "path",- "name": "kb_name",- "required": true,+ "in": "query",+ "name": "region",+ "required": false,"schema": {- "title": "Kb Name",+ "default": "",+ "title": "Region","type": "string"}},@@ -26193,16 +26259,6 @@}}],- "requestBody": {- "content": {- "multipart/form-data": {- "schema": {- "$ref": "#/components/schemas/Body_upload_files_api_knowledge_bases__kb_name__upload_post"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -26223,16 +26279,16 @@"description": "Validation Error"}},- "summary": "Upload Files",+ "summary": "Kb Source Page","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/visual-assets/{asset_id}": {- "get": {- "description": "Serve a verified source image from an access checked local KB.",- "operationId": "serve_kb_visual_asset_api_knowledge_bases__kb_name__visual_assets__asset_id__get",+ "/api/knowledge-bases/{kb_name}/sync-folder/{folder_id}": {+ "post": {+ "description": "Sync files from a linked folder to the knowledge base.\n\nThis scans the linked folder for supported documents and processes\nany new files that haven't been added yet.",+ "operationId": "sync_folder_api_knowledge_bases__kb_name__sync_folder__folder_id__post","parameters": [{"in": "path",@@ -26245,10 +26301,10 @@},{"in": "path",- "name": "asset_id",+ "name": "folder_id","required": true,"schema": {- "title": "Asset Id",+ "title": "Folder Id","type": "string"}},@@ -26289,7 +26345,9 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "$ref": "#/components/schemas/SyncFolderResponse"+ }}},"description": "Successful Response"@@ -26305,15 +26363,15 @@"description": "Validation Error"}},- "summary": "Serve Kb Visual Asset",+ "summary": "Sync Folder","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/web-source": {+ "/api/knowledge-bases/{kb_name}/sync-github": {"post": {- "operationId": "add_web_source_api_knowledge_bases__kb_name__web_source_post",+ "operationId": "sync_github_sources_api_knowledge_bases__kb_name__sync_github_post","parameters": [{"in": "path",@@ -26357,23 +26415,11 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/AddWebSourceRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {- "schema": {- "$ref": "#/components/schemas/WebSourceInfo"- }+ "schema": {}}},"description": "Successful Response"@@ -26389,15 +26435,16 @@"description": "Validation Error"}},- "summary": "Add Web Source",+ "summary": "Sync Github Sources","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/web-source-sync": {- "get": {- "operationId": "get_web_source_sync_jobs_api_knowledge_bases__kb_name__web_source_sync_get",+ "/api/knowledge-bases/{kb_name}/sync-web": {+ "post": {+ "description": "Run one bounded crawl-and-sync pass for every enabled web source.",+ "operationId": "sync_web_sources_api_knowledge_bases__kb_name__sync_web_post","parameters": [{"in": "path",@@ -26445,13 +26492,7 @@"200": {"content": {"application/json": {- "schema": {- "items": {- "$ref": "#/components/schemas/WebSourceSyncJobInfo"- },- "title": "Response Get Web Source Sync Jobs Api Knowledge Bases Kb Name Web Source Sync Get",- "type": "array"- }+ "schema": {}}},"description": "Successful Response"@@ -26467,15 +26508,16 @@"description": "Validation Error"}},- "summary": "Get Web Source Sync Jobs",+ "summary": "Sync Web Sources","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/web-source/{source_id}": {- "delete": {- "operationId": "remove_web_source_api_knowledge_bases__kb_name__web_source__source_id__delete",+ "/api/knowledge-bases/{kb_name}/upload": {+ "post": {+ "description": "Upload files to a knowledge base and process them in background.\n\n``dest_subdir`` places the whole batch under that folder inside the KB.\nA browser folder pick reports each file's path relative to the chosen\ndirectory, so the directory's own ancestors never reach the server; this\nis how a caller adding one subtree at a time re-attaches it where it\nbelongs instead of piling every batch at the root (#866).",+ "operationId": "upload_files_api_knowledge_bases__kb_name__upload_post","parameters": [{"in": "path",@@ -26486,15 +26528,6 @@"type": "string"}},- {- "in": "path",- "name": "source_id",- "required": true,- "schema": {- "title": "Source Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -26528,6 +26561,16 @@}}],+ "requestBody": {+ "content": {+ "multipart/form-data": {+ "schema": {+ "$ref": "#/components/schemas/Body_upload_files_api_knowledge_bases__kb_name__upload_post"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -26548,15 +26591,16 @@"description": "Validation Error"}},- "summary": "Remove Web Source",+ "summary": "Upload Files","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/web-source/{source_id}/cancel": {- "post": {- "operationId": "cancel_web_source_sync_api_knowledge_bases__kb_name__web_source__source_id__cancel_post",+ "/api/knowledge-bases/{kb_name}/visual-assets/{asset_id}": {+ "get": {+ "description": "Serve a verified source image from an access checked local KB.",+ "operationId": "serve_kb_visual_asset_api_knowledge_bases__kb_name__visual_assets__asset_id__get","parameters": [{"in": "path",@@ -26569,10 +26613,10 @@},{"in": "path",- "name": "source_id",+ "name": "asset_id","required": true,"schema": {- "title": "Source Id",+ "title": "Asset Id","type": "string"}},@@ -26629,15 +26673,15 @@"description": "Validation Error"}},- "summary": "Cancel Web Source Sync",+ "summary": "Serve Kb Visual Asset","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/web-source/{source_id}/pairings": {+ "/api/knowledge-bases/{kb_name}/visual-coverage": {"get": {- "operationId": "get_web_source_pairings_api_knowledge_bases__kb_name__web_source__source_id__pairings_get",+ "operationId": "kb_visual_coverage_api_knowledge_bases__kb_name__visual_coverage_get","parameters": [{"in": "path",@@ -26649,14 +26693,38 @@}},{- "in": "path",- "name": "source_id",- "required": true,+ "in": "query",+ "name": "source_path",+ "required": false,"schema": {- "title": "Source Id",+ "default": "",+ "title": "Source Path","type": "string"}},+ {+ "in": "query",+ "name": "offset",+ "required": false,+ "schema": {+ "default": 0,+ "minimum": 0,+ "title": "Offset",+ "type": "integer"+ }+ },+ {+ "in": "query",+ "name": "limit",+ "required": false,+ "schema": {+ "default": 100,+ "maximum": 200,+ "minimum": 1,+ "title": "Limit",+ "type": "integer"+ }+ },{"in": "header","name": "Authorization",@@ -26694,13 +26762,7 @@"200": {"content": {"application/json": {- "schema": {- "items": {- "$ref": "#/components/schemas/BilingualPairingInfo"- },- "title": "Response Get Web Source Pairings Api Knowledge Bases Kb Name Web Source Source Id Pairings Get",- "type": "array"- }+ "schema": {}}},"description": "Successful Response"@@ -26716,15 +26778,15 @@"description": "Validation Error"}},- "summary": "Get Web Source Pairings",+ "summary": "Kb Visual Coverage","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/web-source/{source_id}/retry": {+ "/api/knowledge-bases/{kb_name}/web-source": {"post": {- "operationId": "retry_web_source_sync_api_knowledge_bases__kb_name__web_source__source_id__retry_post",+ "operationId": "add_web_source_api_knowledge_bases__kb_name__web_source_post","parameters": [{"in": "path",@@ -26735,15 +26797,6 @@"type": "string"}},- {- "in": "path",- "name": "source_id",- "required": true,- "schema": {- "title": "Source Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -26777,11 +26830,23 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AddWebSourceRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "$ref": "#/components/schemas/WebSourceInfo"+ }}},"description": "Successful Response"@@ -26797,15 +26862,15 @@"description": "Validation Error"}},- "summary": "Retry Web Source Sync",+ "summary": "Add Web Source","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/web-source/{source_id}/schedule": {- "put": {- "operationId": "update_web_source_schedule_api_knowledge_bases__kb_name__web_source__source_id__schedule_put",+ "/api/knowledge-bases/{kb_name}/web-source-sync": {+ "get": {+ "operationId": "get_web_source_sync_jobs_api_knowledge_bases__kb_name__web_source_sync_get","parameters": [{"in": "path",@@ -26816,15 +26881,6 @@"type": "string"}},- {- "in": "path",- "name": "source_id",- "required": true,- "schema": {- "title": "Source Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -26858,22 +26914,16 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/WebSourceScheduleUpdate"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/WebSourceInfo"+ "items": {+ "$ref": "#/components/schemas/WebSourceSyncJobInfo"+ },+ "title": "Response Get Web Source Sync Jobs Api Knowledge Bases Kb Name Web Source Sync Get",+ "type": "array"}}},@@ -26890,15 +26940,15 @@"description": "Validation Error"}},- "summary": "Update Web Source Schedule",+ "summary": "Get Web Source Sync Jobs","tags": ["knowledge-bases"]}},- "/api/knowledge-bases/{kb_name}/web-sources": {- "get": {- "operationId": "get_web_sources_api_knowledge_bases__kb_name__web_sources_get",+ "/api/knowledge-bases/{kb_name}/web-source/{source_id}": {+ "delete": {+ "operationId": "remove_web_source_api_knowledge_bases__kb_name__web_source__source_id__delete","parameters": [{"in": "path",@@ -26909,6 +26959,15 @@"type": "string"}},+ {+ "in": "path",+ "name": "source_id",+ "required": true,+ "schema": {+ "title": "Source Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -26946,13 +27005,7 @@"200": {"content": {"application/json": {- "schema": {- "items": {- "$ref": "#/components/schemas/WebSourceInfo"- },- "title": "Response Get Web Sources Api Knowledge Bases Kb Name Web Sources Get",- "type": "array"- }+ "schema": {}}},"description": "Successful Response"@@ -26968,17 +27021,34 @@"description": "Validation Error"}},- "summary": "Get Web Sources",+ "summary": "Remove Web Source","tags": ["knowledge-bases"]}},- "/api/marginnote4/devices": {- "get": {- "description": "List all paired devices.",- "operationId": "list_devices_api_marginnote4_devices_get",+ "/api/knowledge-bases/{kb_name}/web-source/{source_id}/cancel": {+ "post": {+ "operationId": "cancel_web_source_sync_api_knowledge_bases__kb_name__web_source__source_id__cancel_post","parameters": [+ {+ "in": "path",+ "name": "kb_name",+ "required": true,+ "schema": {+ "title": "Kb Name",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "source_id",+ "required": true,+ "schema": {+ "title": "Source Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -27016,13 +27086,7 @@"200": {"content": {"application/json": {- "schema": {- "items": {- "$ref": "#/components/schemas/DeviceInfo"- },- "title": "Response List Devices Api Marginnote4 Devices Get",- "type": "array"- }+ "schema": {}}},"description": "Successful Response"@@ -27038,23 +27102,31 @@"description": "Validation Error"}},- "summary": "List Devices",+ "summary": "Cancel Web Source Sync","tags": [- "marginnote4"+ "knowledge-bases"]}},- "/api/marginnote4/devices/{device_id}": {- "delete": {- "description": "Revoke a paired device.",- "operationId": "revoke_device_api_marginnote4_devices__device_id__delete",+ "/api/knowledge-bases/{kb_name}/web-source/{source_id}/pairings": {+ "get": {+ "operationId": "get_web_source_pairings_api_knowledge_bases__kb_name__web_source__source_id__pairings_get","parameters": [{"in": "path",- "name": "device_id",+ "name": "kb_name","required": true,"schema": {- "title": "Device Id",+ "title": "Kb Name",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "source_id",+ "required": true,+ "schema": {+ "title": "Source Id","type": "string"}},@@ -27096,11 +27168,11 @@"content": {"application/json": {"schema": {- "additionalProperties": {- "type": "string"+ "items": {+ "$ref": "#/components/schemas/BilingualPairingInfo"},- "title": "Response Revoke Device Api Marginnote4 Devices Device Id Delete",- "type": "object"+ "title": "Response Get Web Source Pairings Api Knowledge Bases Kb Name Web Source Source Id Pairings Get",+ "type": "array"}}},@@ -27117,20 +27189,37 @@"description": "Validation Error"}},- "summary": "Revoke Device",+ "summary": "Get Web Source Pairings","tags": [- "marginnote4"+ "knowledge-bases"]}},- "/api/marginnote4/heartbeat": {+ "/api/knowledge-bases/{kb_name}/web-source/{source_id}/retry": {"post": {- "description": "Lightweight liveness check. Updates last_seen for the device.",- "operationId": "heartbeat_api_marginnote4_heartbeat_post",+ "operationId": "retry_web_source_sync_api_knowledge_bases__kb_name__web_source__source_id__retry_post","parameters": [+ {+ "in": "path",+ "name": "kb_name",+ "required": true,+ "schema": {+ "title": "Kb Name",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "source_id",+ "required": true,+ "schema": {+ "title": "Source Id",+ "type": "string"+ }+ },{"in": "header",- "name": "authorization",+ "name": "Authorization","required": false,"schema": {"anyOf": [@@ -27143,17 +27232,29 @@],"title": "Authorization"}+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }}],"responses": {"200": {"content": {"application/json": {- "schema": {- "additionalProperties": true,- "title": "Response Heartbeat Api Marginnote4 Heartbeat Post",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -27169,17 +27270,34 @@"description": "Validation Error"}},- "summary": "Heartbeat",+ "summary": "Retry Web Source Sync","tags": [- "marginnote4"+ "knowledge-bases"]}},- "/api/marginnote4/pair": {- "post": {- "description": "Pair a new MN4 device. Requires a DeepTutor session.\n\nReturns a one-time token the Add-on stores and presents on every sync.",- "operationId": "pair_device_api_marginnote4_pair_post",+ "/api/knowledge-bases/{kb_name}/web-source/{source_id}/schedule": {+ "put": {+ "operationId": "update_web_source_schedule_api_knowledge_bases__kb_name__web_source__source_id__schedule_put","parameters": [+ {+ "in": "path",+ "name": "kb_name",+ "required": true,+ "schema": {+ "title": "Kb Name",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "source_id",+ "required": true,+ "schema": {+ "title": "Source Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -27217,7 +27335,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/PairRequest"+ "$ref": "#/components/schemas/WebSourceScheduleUpdate"}}},@@ -27228,7 +27346,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/PairResponse"+ "$ref": "#/components/schemas/WebSourceInfo"}}},@@ -27245,17 +27363,25 @@"description": "Validation Error"}},- "summary": "Pair Device",+ "summary": "Update Web Source Schedule","tags": [- "marginnote4"+ "knowledge-bases"]}},- "/api/marginnote4/status": {+ "/api/knowledge-bases/{kb_name}/web-sources": {"get": {- "description": "Health check and summary stats.",- "operationId": "status_api_marginnote4_status_get",+ "operationId": "get_web_sources_api_knowledge_bases__kb_name__web_sources_get","parameters": [+ {+ "in": "path",+ "name": "kb_name",+ "required": true,+ "schema": {+ "title": "Kb Name",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -27294,9 +27420,11 @@"content": {"application/json": {"schema": {- "additionalProperties": true,- "title": "Response Status Api Marginnote4 Status Get",- "type": "object"+ "items": {+ "$ref": "#/components/schemas/WebSourceInfo"+ },+ "title": "Response Get Web Sources Api Knowledge Bases Kb Name Web Sources Get",+ "type": "array"}}},@@ -27313,20 +27441,19 @@"description": "Validation Error"}},- "summary": "Status",+ "summary": "Get Web Sources","tags": [- "marginnote4"+ "knowledge-bases"]}},- "/api/marginnote4/sync": {- "post": {- "description": "Receive an incremental sync batch from a paired MN4 device.",- "operationId": "sync_objects_api_marginnote4_sync_post",+ "/api/learning-journal": {+ "get": {+ "operationId": "overview_api_learning_journal_get","parameters": [{"in": "header",- "name": "authorization",+ "name": "Authorization","required": false,"schema": {"anyOf": [@@ -27339,25 +27466,29 @@],"title": "Authorization"}+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/SyncRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {- "schema": {- "$ref": "#/components/schemas/SyncResponse"- }+ "schema": {}}},"description": "Successful Response"@@ -27373,15 +27504,16 @@"description": "Validation Error"}},- "summary": "Sync Objects",+ "summary": "Overview","tags": [- "marginnote4"+ "learning-journal"]}},- "/api/mastery-paths/progress": {+ "/api/marginnote4/devices": {"get": {- "operationId": "list_all_progress_api_mastery_paths_progress_get",+ "description": "List all paired devices.",+ "operationId": "list_devices_api_marginnote4_devices_get","parameters": [{"in": "header",@@ -27420,7 +27552,13 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "items": {+ "$ref": "#/components/schemas/DeviceInfo"+ },+ "title": "Response List Devices Api Marginnote4 Devices Get",+ "type": "array"+ }}},"description": "Successful Response"@@ -27436,22 +27574,23 @@"description": "Validation Error"}},- "summary": "List All Progress",+ "summary": "List Devices","tags": [- "mastery-path"+ "marginnote4"]}},- "/api/mastery-paths/progress/{book_id}": {+ "/api/marginnote4/devices/{device_id}": {"delete": {- "operationId": "delete_progress_api_mastery_paths_progress__book_id__delete",+ "description": "Revoke a paired device.",+ "operationId": "revoke_device_api_marginnote4_devices__device_id__delete","parameters": [{"in": "path",- "name": "book_id",+ "name": "device_id","required": true,"schema": {- "title": "Book Id",+ "title": "Device Id","type": "string"}},@@ -27492,7 +27631,13 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": {+ "type": "string"+ },+ "title": "Response Revoke Device Api Marginnote4 Devices Device Id Delete",+ "type": "object"+ }}},"description": "Successful Response"@@ -27508,26 +27653,20 @@"description": "Validation Error"}},- "summary": "Delete Progress",+ "summary": "Revoke Device","tags": [- "mastery-path"+ "marginnote4"]- },- "get": {- "operationId": "get_progress_api_mastery_paths_progress__book_id__get",+ }+ },+ "/api/marginnote4/heartbeat": {+ "post": {+ "description": "Lightweight liveness check. Updates last_seen for the device.",+ "operationId": "heartbeat_api_marginnote4_heartbeat_post","parameters": [- {- "in": "path",- "name": "book_id",- "required": true,- "schema": {- "title": "Book Id",- "type": "string"- }- },{"in": "header",- "name": "Authorization",+ "name": "authorization","required": false,"schema": {"anyOf": [@@ -27540,29 +27679,17 @@],"title": "Authorization"}- },- {- "in": "cookie",- "name": "dt_token",- "required": false,- "schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Dt Token"- }}],"responses": {"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Heartbeat Api Marginnote4 Heartbeat Post",+ "type": "object"+ }}},"description": "Successful Response"@@ -27578,24 +27705,17 @@"description": "Validation Error"}},- "summary": "Get Progress",+ "summary": "Heartbeat","tags": [- "mastery-path"+ "marginnote4"]- },- "patch": {- "description": "Rename a path — the only edit that is the learner's rather than the tutor's.\n\nGuarded like every other path mutation so a rename cannot interleave with a\ntutoring turn's own commit, and emitted as an event so the activity feed\nrecords who called it what.",- "operationId": "rename_progress_api_mastery_paths_progress__book_id__patch",+ }+ },+ "/api/marginnote4/pair": {+ "post": {+ "description": "Pair a new MN4 device. Requires a DeepTutor session.\n\nReturns a one-time token the Add-on stores and presents on every sync.",+ "operationId": "pair_device_api_marginnote4_pair_post","parameters": [- {- "in": "path",- "name": "book_id",- "required": true,- "schema": {- "title": "Book Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -27633,7 +27753,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/RenamePathRequest"+ "$ref": "#/components/schemas/PairRequest"}}},@@ -27643,7 +27763,9 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "$ref": "#/components/schemas/PairResponse"+ }}},"description": "Successful Response"@@ -27659,26 +27781,17 @@"description": "Validation Error"}},- "summary": "Rename Progress",+ "summary": "Pair Device","tags": [- "mastery-path"+ "marginnote4"]}},- "/api/mastery-paths/progress/{book_id}/board": {+ "/api/marginnote4/status": {"get": {- "description": "The visual learning board: every knowledge point as a card, enriched\nwith its next review time and a deterministic grid position derived from\nthe module order. A read-only projection of the same mastery data the\ntutor and the map view use.",- "operationId": "get_progress_board_api_mastery_paths_progress__book_id__board_get",+ "description": "Health check and summary stats.",+ "operationId": "status_api_marginnote4_status_get","parameters": [- {- "in": "path",- "name": "book_id",- "required": true,- "schema": {- "title": "Book Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -27716,7 +27829,11 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Status Api Marginnote4 Status Get",+ "type": "object"+ }}},"description": "Successful Response"@@ -27732,36 +27849,76 @@"description": "Validation Error"}},- "summary": "Get Progress Board",+ "summary": "Status","tags": [- "mastery-path"+ "marginnote4"]}},- "/api/mastery-paths/progress/{book_id}/events": {- "get": {- "description": "Ordered, redacted domain events for reconnect and incremental UI sync.",- "operationId": "get_progress_events_api_mastery_paths_progress__book_id__events_get",+ "/api/marginnote4/sync": {+ "post": {+ "description": "Receive an incremental sync batch from a paired MN4 device.",+ "operationId": "sync_objects_api_marginnote4_sync_post","parameters": [{- "in": "path",- "name": "book_id",- "required": true,- "schema": {- "title": "Book Id",- "type": "string"- }- },- {- "in": "query",- "name": "after_revision",+ "in": "header",+ "name": "authorization","required": false,"schema": {- "default": 0,- "title": "After Revision",- "type": "integer"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SyncRequest"+ }}},+ "required": true+ },+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SyncResponse"+ }+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Sync Objects",+ "tags": [+ "marginnote4"+ ]+ }+ },+ "/api/mastery-paths/progress": {+ "get": {+ "operationId": "list_all_progress_api_mastery_paths_progress_get",+ "parameters": [{"in": "header","name": "Authorization",@@ -27815,15 +27972,15 @@"description": "Validation Error"}},- "summary": "Get Progress Events",+ "summary": "List All Progress","tags": ["mastery-path"]}},- "/api/mastery-paths/progress/{book_id}/generate-from-notebook": {- "post": {- "operationId": "generate_from_notebook_api_mastery_paths_progress__book_id__generate_from_notebook_post",+ "/api/mastery-paths/progress/{book_id}": {+ "delete": {+ "operationId": "delete_progress_api_mastery_paths_progress__book_id__delete","parameters": [{"in": "path",@@ -27867,16 +28024,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/GenerateFromNotebookRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -27897,16 +28044,13 @@"description": "Validation Error"}},- "summary": "Generate From Notebook",+ "summary": "Delete Progress","tags": ["mastery-path"]- }- },- "/api/mastery-paths/progress/{book_id}/generate-from-reading": {- "post": {- "description": "Create a mastery curriculum from a private reading workspace.",- "operationId": "generate_from_reading_api_mastery_paths_progress__book_id__generate_from_reading_post",+ },+ "get": {+ "operationId": "get_progress_api_mastery_paths_progress__book_id__get","parameters": [{"in": "path",@@ -27950,16 +28094,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/GenerateFromReadingRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -27980,15 +28114,14 @@"description": "Validation Error"}},- "summary": "Generate From Reading",+ "summary": "Get Progress","tags": ["mastery-path"]- }- },- "/api/mastery-paths/progress/{book_id}/import-from-book": {- "post": {- "operationId": "import_from_book_api_mastery_paths_progress__book_id__import_from_book_post",+ },+ "patch": {+ "description": "Rename a path — the only edit that is the learner's rather than the tutor's.\n\nGuarded like every other path mutation so a rename cannot interleave with a\ntutoring turn's own commit, and emitted as an event so the activity feed\nrecords who called it what.",+ "operationId": "rename_progress_api_mastery_paths_progress__book_id__patch","parameters": [{"in": "path",@@ -28036,7 +28169,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/ImportFromBookRequest"+ "$ref": "#/components/schemas/RenamePathRequest"}}},@@ -28062,15 +28195,16 @@"description": "Validation Error"}},- "summary": "Import From Book",+ "summary": "Rename Progress","tags": ["mastery-path"]}},- "/api/mastery-paths/progress/{book_id}/init-modules": {- "post": {- "operationId": "init_modules_api_mastery_paths_progress__book_id__init_modules_post",+ "/api/mastery-paths/progress/{book_id}/board": {+ "get": {+ "description": "The visual learning board: every knowledge point as a card, enriched\nwith its next review time and a deterministic grid position derived from\nthe module order. A read-only projection of the same mastery data the\ntutor and the map view use.",+ "operationId": "get_progress_board_api_mastery_paths_progress__book_id__board_get","parameters": [{"in": "path",@@ -28114,16 +28248,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/InitModulesRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -28144,16 +28268,16 @@"description": "Validation Error"}},- "summary": "Init Modules",+ "summary": "Get Progress Board","tags": ["mastery-path"]}},- "/api/mastery-paths/progress/{book_id}/map": {+ "/api/mastery-paths/progress/{book_id}/events": {"get": {- "description": "The dashboard view of a path: the gate-decided next step plus a map of\nevery objective's status (new / learning / mastered). The per-type gate\nlives in ``learning.policy`` so the dashboard and the tutor agree.",- "operationId": "get_progress_map_api_mastery_paths_progress__book_id__map_get",+ "description": "Ordered, redacted domain events for reconnect and incremental UI sync.",+ "operationId": "get_progress_events_api_mastery_paths_progress__book_id__events_get","parameters": [{"in": "path",@@ -28164,6 +28288,16 @@"type": "string"}},+ {+ "in": "query",+ "name": "after_revision",+ "required": false,+ "schema": {+ "default": 0,+ "title": "After Revision",+ "type": "integer"+ }+ },{"in": "header","name": "Authorization",@@ -28217,16 +28351,15 @@"description": "Validation Error"}},- "summary": "Get Progress Map",+ "summary": "Get Progress Events","tags": ["mastery-path"]}},- "/api/mastery-paths/progress/{book_id}/objectives/{kp_id}": {- "get": {- "description": "The evidence behind one objective: attempts, schedule, errors, prompts.\n\n``policy.objective_report`` is pure over the aggregate, so the questions\nthemselves — which live in the durable interaction log, not the aggregate —\nare joined on here, redacted of their answer keys.",- "operationId": "get_objective_report_api_mastery_paths_progress__book_id__objectives__kp_id__get",+ "/api/mastery-paths/progress/{book_id}/generate-from-notebook": {+ "post": {+ "operationId": "generate_from_notebook_api_mastery_paths_progress__book_id__generate_from_notebook_post","parameters": [{"in": "path",@@ -28237,15 +28370,6 @@"type": "string"}},- {- "in": "path",- "name": "kp_id",- "required": true,- "schema": {- "title": "Kp Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -28279,6 +28403,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/GenerateFromNotebookRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -28299,15 +28433,16 @@"description": "Validation Error"}},- "summary": "Get Objective Report",+ "summary": "Generate From Notebook","tags": ["mastery-path"]}},- "/api/mastery-paths/progress/{book_id}/redo": {+ "/api/mastery-paths/progress/{book_id}/generate-from-reading": {"post": {- "operationId": "redo_progress_api_mastery_paths_progress__book_id__redo_post",+ "description": "Create a mastery curriculum from a private reading workspace.",+ "operationId": "generate_from_reading_api_mastery_paths_progress__book_id__generate_from_reading_post","parameters": [{"in": "path",@@ -28351,6 +28486,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/GenerateFromReadingRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -28371,16 +28516,15 @@"description": "Validation Error"}},- "summary": "Redo Progress",+ "summary": "Generate From Reading","tags": ["mastery-path"]}},- "/api/mastery-paths/progress/{book_id}/sessions": {- "get": {- "description": "Expose the explicit conversation associations for this path.",- "operationId": "get_progress_sessions_api_mastery_paths_progress__book_id__sessions_get",+ "/api/mastery-paths/progress/{book_id}/import-from-book": {+ "post": {+ "operationId": "import_from_book_api_mastery_paths_progress__book_id__import_from_book_post","parameters": [{"in": "path",@@ -28424,6 +28568,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ImportFromBookRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -28444,16 +28598,15 @@"description": "Validation Error"}},- "summary": "Get Progress Sessions",+ "summary": "Import From Book","tags": ["mastery-path"]}},- "/api/mastery-paths/progress/{book_id}/skip-question": {+ "/api/mastery-paths/progress/{book_id}/init-modules": {"post": {- "description": "Drop an outstanding question the learner can no longer answer.\n\nThe narrow escape hatch for a path stalled on ``answer_pending``; unlike\n``redo`` it keeps every mastery level and review the learner has earned.",- "operationId": "skip_pending_question_api_mastery_paths_progress__book_id__skip_question_post",+ "operationId": "init_modules_api_mastery_paths_progress__book_id__init_modules_post","parameters": [{"in": "path",@@ -28497,77 +28650,21 @@}}],- "responses": {- "200": {- "content": {- "application/json": {- "schema": {}- }- },- "description": "Successful Response"- },- "422": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/HTTPValidationError"- }+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/InitModulesRequest"}- },- "description": "Validation Error"- }- },- "summary": "Skip Pending Question",- "tags": [- "mastery-path"- ]- }- },- "/api/mastery-paths/reading/records": {- "get": {- "description": "Reading progress and extension activity for the current account.",- "operationId": "list_reading_learning_records_api_mastery_paths_reading_records_get",- "parameters": [- {- "in": "header",- "name": "Authorization",- "required": false,- "schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Authorization"}},- {- "in": "cookie",- "name": "dt_token",- "required": false,- "schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Dt Token"- }- }- ],+ "required": true+ },"responses": {"200": {"content": {"application/json": {- "schema": {- "$ref": "#/components/schemas/ReadingLearningRecords"- }+ "schema": {}}},"description": "Successful Response"@@ -28583,77 +28680,26 @@"description": "Validation Error"}},- "summary": "List Reading Learning Records",+ "summary": "Init Modules","tags": ["mastery-path"]}},- "/api/mastery-paths/topics": {+ "/api/mastery-paths/progress/{book_id}/map": {"get": {- "operationId": "list_topics_api_mastery_paths_topics_get",+ "description": "The dashboard view of a path: the gate-decided next step plus a map of\nevery objective's status (new / learning / mastered). The per-type gate\nlives in ``learning.policy`` so the dashboard and the tutor agree.",+ "operationId": "get_progress_map_api_mastery_paths_progress__book_id__map_get","parameters": [{- "in": "header",- "name": "Authorization",- "required": false,- "schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Authorization"- }- },- {- "in": "cookie",- "name": "dt_token",- "required": false,+ "in": "path",+ "name": "book_id",+ "required": true,"schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Dt Token"+ "title": "Book Id",+ "type": "string"}- }- ],- "responses": {- "200": {- "content": {- "application/json": {- "schema": {}- }- },- "description": "Successful Response"},- "422": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/HTTPValidationError"- }- }- },- "description": "Validation Error"- }- },- "summary": "List Topics",- "tags": [- "mastery-path"- ]- },- "post": {- "operationId": "create_topic_api_mastery_paths_topics_post",- "parameters": [{"in": "header","name": "Authorization",@@ -28687,16 +28733,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/ConfirmTopicRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -28717,16 +28753,35 @@"description": "Validation Error"}},- "summary": "Create Topic",+ "summary": "Get Progress Map","tags": ["mastery-path"]}},- "/api/mastery-paths/topics/draft": {- "post": {- "operationId": "generate_topic_route_api_mastery_paths_topics_draft_post",+ "/api/mastery-paths/progress/{book_id}/objectives/{kp_id}": {+ "get": {+ "description": "The evidence behind one objective: attempts, schedule, errors, prompts.\n\n``policy.objective_report`` is pure over the aggregate, so the questions\nthemselves — which live in the durable interaction log, not the aggregate —\nare joined on here, redacted of their answer keys.",+ "operationId": "get_objective_report_api_mastery_paths_progress__book_id__objectives__kp_id__get","parameters": [+ {+ "in": "path",+ "name": "book_id",+ "required": true,+ "schema": {+ "title": "Book Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "kp_id",+ "required": true,+ "schema": {+ "title": "Kp Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -28760,16 +28815,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/GenerateTopicDraftRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -28790,17 +28835,25 @@"description": "Validation Error"}},- "summary": "Generate Topic Route",+ "summary": "Get Objective Report","tags": ["mastery-path"]}},- "/api/mastery-paths/topics/index": {- "get": {- "description": "Just enough to *name* a topic: id, title, emoji.\n\nThe sidebar groups study conversations under their topic, and it refreshes\non every stream end. ``/topics`` answers with each path's whole knowledge\nmap, review queue and source excerpts — kilobytes per topic, none of which\na group header renders. This is the same walk with the payload cut to what\na label needs.\n\nDeclared above ``/topics/{path_id}``: that route matches any single\nsegment, so a literal path below it would never be reached.",- "operationId": "list_topic_index_api_mastery_paths_topics_index_get",+ "/api/mastery-paths/progress/{book_id}/redo": {+ "post": {+ "operationId": "redo_progress_api_mastery_paths_progress__book_id__redo_post","parameters": [+ {+ "in": "path",+ "name": "book_id",+ "required": true,+ "schema": {+ "title": "Book Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -28854,22 +28907,23 @@"description": "Validation Error"}},- "summary": "List Topic Index",+ "summary": "Redo Progress","tags": ["mastery-path"]}},- "/api/mastery-paths/topics/{path_id}": {+ "/api/mastery-paths/progress/{book_id}/sessions": {"get": {- "operationId": "get_topic_api_mastery_paths_topics__path_id__get",+ "description": "Expose the explicit conversation associations for this path.",+ "operationId": "get_progress_sessions_api_mastery_paths_progress__book_id__sessions_get","parameters": [{"in": "path",- "name": "path_id",+ "name": "book_id","required": true,"schema": {- "title": "Path Id",+ "title": "Book Id","type": "string"}},@@ -28926,33 +28980,23 @@"description": "Validation Error"}},- "summary": "Get Topic",+ "summary": "Get Progress Sessions","tags": ["mastery-path"]}},- "/api/mastery-paths/topics/{path_id}/ask-hint": {- "get": {- "description": "One question the learner could ask here, for the composer placeholder.\n\nWritten by the task model, never blocking: an empty ``hint`` means the\ncomposer keeps the static placeholder it has always had.",- "operationId": "get_topic_ask_hint_api_mastery_paths_topics__path_id__ask_hint_get",+ "/api/mastery-paths/progress/{book_id}/skip-question": {+ "post": {+ "description": "Drop an outstanding question the learner can no longer answer.\n\nThe narrow escape hatch for a path stalled on ``answer_pending``; unlike\n``redo`` it keeps every mastery level and review the learner has earned.",+ "operationId": "skip_pending_question_api_mastery_paths_progress__book_id__skip_question_post","parameters": [{"in": "path",- "name": "path_id",+ "name": "book_id","required": true,"schema": {- "title": "Path Id",- "type": "string"- }- },- {- "in": "query",- "name": "session_id",- "required": false,- "schema": {- "default": "",- "title": "Session Id",+ "title": "Book Id","type": "string"}},@@ -29009,25 +29053,17 @@"description": "Validation Error"}},- "summary": "Get Topic Ask Hint",+ "summary": "Skip Pending Question","tags": ["mastery-path"]}},- "/api/mastery-paths/topics/{path_id}/map": {- "put": {- "operationId": "edit_topic_map_api_mastery_paths_topics__path_id__map_put",+ "/api/mastery-paths/reading/records": {+ "get": {+ "description": "Reading progress and extension activity for the current account.",+ "operationId": "list_reading_learning_records_api_mastery_paths_reading_records_get","parameters": [- {- "in": "path",- "name": "path_id",- "required": true,- "schema": {- "title": "Path Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -29061,21 +29097,13 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/EditTopicMapRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "$ref": "#/components/schemas/ReadingLearningRecords"+ }}},"description": "Successful Response"@@ -29091,34 +29119,77 @@"description": "Validation Error"}},- "summary": "Edit Topic Map",+ "summary": "List Reading Learning Records","tags": ["mastery-path"]}},- "/api/mastery-paths/topics/{path_id}/objectives/{kp_id}/override": {- "post": {- "operationId": "set_learner_override_api_mastery_paths_topics__path_id__objectives__kp_id__override_post",+ "/api/mastery-paths/topics": {+ "get": {+ "operationId": "list_topics_api_mastery_paths_topics_get","parameters": [{- "in": "path",- "name": "path_id",- "required": true,+ "in": "header",+ "name": "Authorization",+ "required": false,"schema": {- "title": "Path Id",- "type": "string"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"}},{- "in": "path",- "name": "kp_id",- "required": true,+ "in": "cookie",+ "name": "dt_token",+ "required": false,"schema": {- "title": "Kp Id",- "type": "string"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"}+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"},+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "List Topics",+ "tags": [+ "mastery-path"+ ]+ },+ "post": {+ "operationId": "create_topic_api_mastery_paths_topics_post",+ "parameters": [{"in": "header","name": "Authorization",@@ -29156,7 +29227,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/LearnerOverrideRequest"+ "$ref": "#/components/schemas/ConfirmTopicRequest"}}},@@ -29182,25 +29253,16 @@"description": "Validation Error"}},- "summary": "Set Learner Override",+ "summary": "Create Topic","tags": ["mastery-path"]}},- "/api/mastery-paths/topics/{path_id}/review-settings": {- "get": {- "operationId": "get_review_settings_api_mastery_paths_topics__path_id__review_settings_get",+ "/api/mastery-paths/topics/draft": {+ "post": {+ "operationId": "generate_topic_route_api_mastery_paths_topics_draft_post","parameters": [- {- "in": "path",- "name": "path_id",- "required": true,- "schema": {- "title": "Path Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -29234,6 +29296,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/GenerateTopicDraftRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -29254,23 +29326,17 @@"description": "Validation Error"}},- "summary": "Get Review Settings",+ "summary": "Generate Topic Route","tags": ["mastery-path"]- },- "put": {- "operationId": "update_review_settings_api_mastery_paths_topics__path_id__review_settings_put",+ }+ },+ "/api/mastery-paths/topics/index": {+ "get": {+ "description": "Just enough to *name* a topic: id, title, emoji.\n\nThe sidebar groups study conversations under their topic, and it refreshes\non every stream end. ``/topics`` answers with each path's whole knowledge\nmap, review queue and source excerpts — kilobytes per topic, none of which\na group header renders. This is the same walk with the payload cut to what\na label needs.\n\nDeclared above ``/topics/{path_id}``: that route matches any single\nsegment, so a literal path below it would never be reached.",+ "operationId": "list_topic_index_api_mastery_paths_topics_index_get","parameters": [- {- "in": "path",- "name": "path_id",- "required": true,- "schema": {- "title": "Path Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -29304,16 +29370,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/ReviewSettingsRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -29334,15 +29390,15 @@"description": "Validation Error"}},- "summary": "Update Review Settings",+ "summary": "List Topic Index","tags": ["mastery-path"]}},- "/api/mastery-paths/topics/{path_id}/sessions": {+ "/api/mastery-paths/topics/{path_id}": {"get": {- "operationId": "list_topic_sessions_api_mastery_paths_topics__path_id__sessions_get",+ "operationId": "get_topic_api_mastery_paths_topics__path_id__get","parameters": [{"in": "path",@@ -29406,16 +29462,16 @@"description": "Validation Error"}},- "summary": "List Topic Sessions",+ "summary": "Get Topic","tags": ["mastery-path"]}},- "/api/mastery-paths/topics/{path_id}/sessions/{session_id}/mode": {- "put": {- "description": "Change what a conversation is doing, from the learner's own buttons.\n\nThe same move the tutor makes with ``mastery_mode``, through the same\nadmission rule — so pressing \"Study\" on a goal with no outline is refused\nwith the sentence the tutor would have said, rather than silently putting\nthe conversation somewhere its tools will then refuse to work.",- "operationId": "set_session_mode_api_mastery_paths_topics__path_id__sessions__session_id__mode_put",+ "/api/mastery-paths/topics/{path_id}/ask-hint": {+ "get": {+ "description": "One question the learner could ask here, for the composer placeholder.\n\nWritten by the task model, never blocking: an empty ``hint`` means the\ncomposer keeps the static placeholder it has always had.",+ "operationId": "get_topic_ask_hint_api_mastery_paths_topics__path_id__ask_hint_get","parameters": [{"in": "path",@@ -29427,10 +29483,11 @@}},{- "in": "path",+ "in": "query","name": "session_id",- "required": true,+ "required": false,"schema": {+ "default": "","title": "Session Id","type": "string"}@@ -29468,16 +29525,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/SetSessionModeRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -29498,16 +29545,25 @@"description": "Validation Error"}},- "summary": "Set Session Mode",+ "summary": "Get Topic Ask Hint","tags": ["mastery-path"]}},- "/api/memory/backup": {- "get": {- "operationId": "list_backups_api_memory_backup_get",+ "/api/mastery-paths/topics/{path_id}/map": {+ "put": {+ "operationId": "edit_topic_map_api_mastery_paths_topics__path_id__map_put","parameters": [+ {+ "in": "path",+ "name": "path_id",+ "required": true,+ "schema": {+ "title": "Path Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -29541,6 +29597,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/EditTopicMapRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -29561,31 +29627,31 @@"description": "Validation Error"}},- "summary": "List Backups",+ "summary": "Edit Topic Map","tags": [- "memory"+ "mastery-path"]}},- "/api/memory/doc/{layer}/{key}": {- "get": {- "operationId": "get_doc_api_memory_doc__layer___key__get",+ "/api/mastery-paths/topics/{path_id}/objectives/{kp_id}/override": {+ "post": {+ "operationId": "set_learner_override_api_mastery_paths_topics__path_id__objectives__kp_id__override_post","parameters": [{"in": "path",- "name": "layer",+ "name": "path_id","required": true,"schema": {- "title": "Layer",+ "title": "Path Id","type": "string"}},{"in": "path",- "name": "key",+ "name": "kp_id","required": true,"schema": {- "title": "Key",+ "title": "Kp Id","type": "string"}},@@ -29622,6 +29688,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/LearnerOverrideRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -29642,29 +29718,92 @@"description": "Validation Error"}},- "summary": "Get Doc",+ "summary": "Set Learner Override","tags": [- "memory"+ "mastery-path"]- },- "put": {- "operationId": "put_doc_api_memory_doc__layer___key__put",+ }+ },+ "/api/mastery-paths/topics/{path_id}/review-settings": {+ "get": {+ "operationId": "get_review_settings_api_mastery_paths_topics__path_id__review_settings_get","parameters": [{"in": "path",- "name": "layer",+ "name": "path_id","required": true,"schema": {- "title": "Layer",+ "title": "Path Id","type": "string"}},+ {+ "in": "header",+ "name": "Authorization",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Get Review Settings",+ "tags": [+ "mastery-path"+ ]+ },+ "put": {+ "operationId": "update_review_settings_api_mastery_paths_topics__path_id__review_settings_put",+ "parameters": [{"in": "path",- "name": "key",+ "name": "path_id","required": true,"schema": {- "title": "Key",+ "title": "Path Id","type": "string"}},@@ -29705,7 +29844,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/DocWriteRequest"+ "$ref": "#/components/schemas/ReviewSettingsRequest"}}},@@ -29731,32 +29870,22 @@"description": "Validation Error"}},- "summary": "Put Doc",+ "summary": "Update Review Settings","tags": [- "memory"+ "mastery-path"]}},- "/api/memory/doc/{layer}/{key}/apply": {- "post": {- "description": "Commit a list of previously-previewed ops to a doc atomically.",- "operationId": "apply_doc_ops_api_memory_doc__layer___key__apply_post",+ "/api/mastery-paths/topics/{path_id}/sessions": {+ "get": {+ "operationId": "list_topic_sessions_api_mastery_paths_topics__path_id__sessions_get","parameters": [{"in": "path",- "name": "layer",- "required": true,- "schema": {- "title": "Layer",- "type": "string"- }- },- {- "in": "path",- "name": "key",+ "name": "path_id","required": true,"schema": {- "title": "Key",+ "title": "Path Id","type": "string"}},@@ -29793,16 +29922,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/ApplyOpsRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -29823,31 +29942,32 @@"description": "Validation Error"}},- "summary": "Apply Doc Ops",+ "summary": "List Topic Sessions","tags": [- "memory"+ "mastery-path"]}},- "/api/memory/doc/{layer}/{key}/audit": {- "post": {- "operationId": "audit_doc_api_memory_doc__layer___key__audit_post",+ "/api/mastery-paths/topics/{path_id}/sessions/{session_id}/mode": {+ "put": {+ "description": "Change what a conversation is doing, from the learner's own buttons.\n\nThe same move the tutor makes with ``mastery_mode``, through the same\nadmission rule — so pressing \"Study\" on a goal with no outline is refused\nwith the sentence the tutor would have said, rather than silently putting\nthe conversation somewhere its tools will then refuse to work.",+ "operationId": "set_session_mode_api_mastery_paths_topics__path_id__sessions__session_id__mode_put","parameters": [{"in": "path",- "name": "layer",+ "name": "path_id","required": true,"schema": {- "title": "Layer",+ "title": "Path Id","type": "string"}},{"in": "path",- "name": "key",+ "name": "session_id","required": true,"schema": {- "title": "Key",+ "title": "Session Id","type": "string"}},@@ -29888,18 +30008,11 @@"content": {"application/json": {"schema": {- "anyOf": [- {- "$ref": "#/components/schemas/AuditRequest"- },- {- "type": "null"- }- ],- "title": "Payload"+ "$ref": "#/components/schemas/SetSessionModeRequest"}}- }+ },+ "required": true},"responses": {"200": {@@ -29921,34 +30034,16 @@"description": "Validation Error"}},- "summary": "Audit Doc",+ "summary": "Set Session Mode","tags": [- "memory"+ "mastery-path"]}},- "/api/memory/doc/{layer}/{key}/dedup": {- "post": {- "operationId": "dedup_doc_api_memory_doc__layer___key__dedup_post",+ "/api/memory/backup": {+ "get": {+ "operationId": "list_backups_api_memory_backup_get","parameters": [- {- "in": "path",- "name": "layer",- "required": true,- "schema": {- "title": "Layer",- "type": "string"- }- },- {- "in": "path",- "name": "key",- "required": true,- "schema": {- "title": "Key",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -29982,23 +30077,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "anyOf": [- {- "$ref": "#/components/schemas/DedupRequest"- },- {- "type": "null"- }- ],- "title": "Payload"- }- }- }- },"responses": {"200": {"content": {@@ -30019,15 +30097,15 @@"description": "Validation Error"}},- "summary": "Dedup Doc",+ "summary": "List Backups","tags": ["memory"]}},- "/api/memory/doc/{layer}/{key}/entry/{entry_id}": {- "delete": {- "operationId": "delete_entry_api_memory_doc__layer___key__entry__entry_id__delete",+ "/api/memory/doc/{layer}/{key}": {+ "get": {+ "operationId": "get_doc_api_memory_doc__layer___key__get","parameters": [{"in": "path",@@ -30047,15 +30125,6 @@"type": "string"}},- {- "in": "path",- "name": "entry_id",- "required": true,- "schema": {- "title": "Entry Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -30109,16 +30178,13 @@"description": "Validation Error"}},- "summary": "Delete Entry",+ "summary": "Get Doc","tags": ["memory"]- }- },- "/api/memory/doc/{layer}/{key}/lines": {- "get": {- "description": "Return the line-numbered, footnote-stripped view of a doc.\n\nUsed by the workbench's \"show line numbers\" toggle so the same line\nindices the audit/dedup LLMs see are visible to the user. Footnote\nblock is omitted because edit ops never reference it directly.",- "operationId": "get_doc_lines_api_memory_doc__layer___key__lines_get",+ },+ "put": {+ "operationId": "put_doc_api_memory_doc__layer___key__put","parameters": [{"in": "path",@@ -30171,6 +30237,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/DocWriteRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -30191,16 +30267,16 @@"description": "Validation Error"}},- "summary": "Get Doc Lines",+ "summary": "Put Doc","tags": ["memory"]}},- "/api/memory/doc/{layer}/{key}/reset": {+ "/api/memory/doc/{layer}/{key}/apply": {"post": {- "description": "Wipe the doc + its meta sidecar so the next update starts fresh.\n\nDestructive — the caller has confirmed. After this returns the .md\nfile is gone *and* the ``seen_entity_refs`` set is cleared, so a\nsubsequent ``run_update`` re-ingests every L1 entity instead of\ntreating them as already-seen.\n\nRefuses while a consolidator run is active on this doc; the caller\ncan cancel first.",- "operationId": "reset_doc_api_memory_doc__layer___key__reset_post",+ "description": "Commit a list of previously-previewed ops to a doc atomically.",+ "operationId": "apply_doc_ops_api_memory_doc__layer___key__apply_post","parameters": [{"in": "path",@@ -30253,6 +30329,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApplyOpsRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -30273,15 +30359,15 @@"description": "Validation Error"}},- "summary": "Reset Doc",+ "summary": "Apply Doc Ops","tags": ["memory"]}},- "/api/memory/doc/{layer}/{key}/update": {+ "/api/memory/doc/{layer}/{key}/audit": {"post": {- "operationId": "update_doc_api_memory_doc__layer___key__update_post",+ "operationId": "audit_doc_api_memory_doc__layer___key__audit_post","parameters": [{"in": "path",@@ -30340,7 +30426,7 @@"schema": {"anyOf": [{- "$ref": "#/components/schemas/UpdateRequest"+ "$ref": "#/components/schemas/AuditRequest"},{"type": "null"@@ -30371,16 +30457,34 @@"description": "Validation Error"}},- "summary": "Update Doc",+ "summary": "Audit Doc","tags": ["memory"]}},- "/api/memory/overview": {- "get": {- "operationId": "get_overview_api_memory_overview_get",+ "/api/memory/doc/{layer}/{key}/dedup": {+ "post": {+ "operationId": "dedup_doc_api_memory_doc__layer___key__dedup_post","parameters": [+ {+ "in": "path",+ "name": "layer",+ "required": true,+ "schema": {+ "title": "Layer",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "key",+ "required": true,+ "schema": {+ "title": "Key",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -30414,6 +30518,23 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/DedupRequest"+ },+ {+ "type": "null"+ }+ ],+ "title": "Payload"+ }+ }+ }+ },"responses": {"200": {"content": {@@ -30434,17 +30555,34 @@"description": "Validation Error"}},- "summary": "Get Overview",+ "summary": "Dedup Doc","tags": ["memory"]}},- "/api/memory/resolve_entry/{entry_id}": {- "get": {- "description": "Find which L2 doc owns this entry id.\n\nL3 docs cite L2 entries by their ``m_<ULID>`` entry id; the workbench\nUI uses this resolver to turn an L3 footnote click into a navigation\nto the right L2 surface + scroll-to anchor.\n\nScans the seven L2 mds in order; first hit wins. 404 if no L2 doc\ncontains the id (e.g. the entry was deleted or the id is stale).",- "operationId": "resolve_entry_api_memory_resolve_entry__entry_id__get",+ "/api/memory/doc/{layer}/{key}/entry/{entry_id}": {+ "delete": {+ "operationId": "delete_entry_api_memory_doc__layer___key__entry__entry_id__delete","parameters": [+ {+ "in": "path",+ "name": "layer",+ "required": true,+ "schema": {+ "title": "Layer",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "key",+ "required": true,+ "schema": {+ "title": "Key",+ "type": "string"+ }+ },{"in": "path","name": "entry_id",@@ -30507,19 +30645,38 @@"description": "Validation Error"}},- "summary": "Resolve Entry",+ "summary": "Delete Entry","tags": ["memory"]}},- "/api/memory/runs": {+ "/api/memory/doc/{layer}/{key}/lines": {"get": {- "operationId": "list_runs_api_memory_runs_get",+ "description": "Return the line-numbered, footnote-stripped view of a doc.\n\nUsed by the workbench's \"show line numbers\" toggle so the same line\nindices the audit/dedup LLMs see are visible to the user. Footnote\nblock is omitted because edit ops never reference it directly.",+ "operationId": "get_doc_lines_api_memory_doc__layer___key__lines_get","parameters": [{- "in": "query",+ "in": "path","name": "layer",+ "required": true,+ "schema": {+ "title": "Layer",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "key",+ "required": true,+ "schema": {+ "title": "Key",+ "type": "string"+ }+ },+ {+ "in": "header",+ "name": "Authorization","required": false,"schema": {"anyOf": [@@ -30530,12 +30687,12 @@"type": "null"}],- "title": "Layer"+ "title": "Authorization"}},{- "in": "query",- "name": "key",+ "in": "cookie",+ "name": "dt_token","required": false,"schema": {"anyOf": [@@ -30546,7 +30703,57 @@"type": "null"}],- "title": "Key"+ "title": "Dt Token"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Get Doc Lines",+ "tags": [+ "memory"+ ]+ }+ },+ "/api/memory/doc/{layer}/{key}/reset": {+ "post": {+ "description": "Wipe the doc + its meta sidecar so the next update starts fresh.\n\nDestructive — the caller has confirmed. After this returns the .md\nfile is gone *and* the ``seen_entity_refs`` set is cleared, so a\nsubsequent ``run_update`` re-ingests every L1 entity instead of\ntreating them as already-seen.\n\nRefuses while a consolidator run is active on this doc; the caller\ncan cancel first.",+ "operationId": "reset_doc_api_memory_doc__layer___key__reset_post",+ "parameters": [+ {+ "in": "path",+ "name": "layer",+ "required": true,+ "schema": {+ "title": "Layer",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "key",+ "required": true,+ "schema": {+ "title": "Key",+ "type": "string"}},{@@ -30602,17 +30809,34 @@"description": "Validation Error"}},- "summary": "List Runs",+ "summary": "Reset Doc","tags": ["memory"]}},- "/api/memory/runs/start": {+ "/api/memory/doc/{layer}/{key}/update": {"post": {- "description": "Start one consolidator mode and return a run handle.\n\nThe run survives client disconnects; reconnect via\n``GET /runs/{id}/events?since=N``.",- "operationId": "start_run_api_memory_runs_start_post",+ "operationId": "update_doc_api_memory_doc__layer___key__update_post","parameters": [+ {+ "in": "path",+ "name": "layer",+ "required": true,+ "schema": {+ "title": "Layer",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "key",+ "required": true,+ "schema": {+ "title": "Key",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -30650,11 +30874,18 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/RunStartRequest"+ "anyOf": [+ {+ "$ref": "#/components/schemas/UpdateRequest"+ },+ {+ "type": "null"+ }+ ],+ "title": "Payload"}}- },- "required": true+ }},"responses": {"200": {@@ -30676,25 +30907,16 @@"description": "Validation Error"}},- "summary": "Start Run",+ "summary": "Update Doc","tags": ["memory"]}},- "/api/memory/runs/{run_id}": {+ "/api/memory/overview": {"get": {- "operationId": "get_run_api_memory_runs__run_id__get",+ "operationId": "get_overview_api_memory_overview_get","parameters": [- {- "in": "path",- "name": "run_id",- "required": true,- "schema": {- "title": "Run Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -30748,22 +30970,23 @@"description": "Validation Error"}},- "summary": "Get Run",+ "summary": "Get Overview","tags": ["memory"]}},- "/api/memory/runs/{run_id}/cancel": {- "post": {- "operationId": "cancel_run_api_memory_runs__run_id__cancel_post",+ "/api/memory/resolve_entry/{entry_id}": {+ "get": {+ "description": "Find which L2 doc owns this entry id.\n\nL3 docs cite L2 entries by their ``m_<ULID>`` entry id; the workbench\nUI uses this resolver to turn an L3 footnote click into a navigation\nto the right L2 surface + scroll-to anchor.\n\nScans the seven L2 mds in order; first hit wins. 404 if no L2 doc\ncontains the id (e.g. the entry was deleted or the id is stale).",+ "operationId": "resolve_entry_api_memory_resolve_entry__entry_id__get","parameters": [{"in": "path",- "name": "run_id",+ "name": "entry_id","required": true,"schema": {- "title": "Run Id",+ "title": "Entry Id","type": "string"}},@@ -30820,34 +31043,46 @@"description": "Validation Error"}},- "summary": "Cancel Run",+ "summary": "Resolve Entry","tags": ["memory"]}},- "/api/memory/runs/{run_id}/events": {+ "/api/memory/runs": {"get": {- "description": "SSE-replay events from the next sequence cursor until the run ends.\n\nReconnecting after a refresh: pass ``last_seen_seq + 1``. The manager\nreplays the buffered tail, then blocks on new events until the run reaches\na terminal state.",- "operationId": "stream_run_events_api_memory_runs__run_id__events_get",+ "operationId": "list_runs_api_memory_runs_get","parameters": [{- "in": "path",- "name": "run_id",- "required": true,+ "in": "query",+ "name": "layer",+ "required": false,"schema": {- "title": "Run Id",- "type": "string"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Layer"}},{"in": "query",- "name": "since",+ "name": "key","required": false,"schema": {- "default": 0,- "title": "Since",- "type": "integer"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Key"}},{@@ -30903,25 +31138,17 @@"description": "Validation Error"}},- "summary": "Stream Run Events",+ "summary": "List Runs","tags": ["memory"]}},- "/api/memory/runs/{run_id}/undo": {+ "/api/memory/runs/start": {"post": {- "operationId": "undo_run_edit_api_memory_runs__run_id__undo_post",+ "description": "Start one consolidator mode and return a run handle.\n\nThe run survives client disconnects; reconnect via\n``GET /runs/{id}/events?since=N``.",+ "operationId": "start_run_api_memory_runs_start_post","parameters": [- {- "in": "path",- "name": "run_id",- "required": true,- "schema": {- "title": "Run Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -30955,6 +31182,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/RunStartRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -30975,17 +31212,25 @@"description": "Validation Error"}},- "summary": "Undo Run Edit",+ "summary": "Start Run","tags": ["memory"]}},- "/api/memory/settings": {+ "/api/memory/runs/{run_id}": {"get": {- "description": "Return the current ``memory:`` subtree (defaults merged in).",- "operationId": "get_memory_settings_endpoint_api_memory_settings_get",+ "operationId": "get_run_api_memory_runs__run_id__get","parameters": [+ {+ "in": "path",+ "name": "run_id",+ "required": true,+ "schema": {+ "title": "Run Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -31039,15 +31284,25 @@"description": "Validation Error"}},- "summary": "Get Memory Settings Endpoint",+ "summary": "Get Run","tags": ["memory"]- },- "put": {- "description": "Merge the payload into the ``memory:`` subtree and persist.",- "operationId": "put_memory_settings_api_memory_settings_put",+ }+ },+ "/api/memory/runs/{run_id}/cancel": {+ "post": {+ "operationId": "cancel_run_api_memory_runs__run_id__cancel_post","parameters": [+ {+ "in": "path",+ "name": "run_id",+ "required": true,+ "schema": {+ "title": "Run Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -31081,18 +31336,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "additionalProperties": true,- "title": "Payload",- "type": "object"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -31113,26 +31356,36 @@"description": "Validation Error"}},- "summary": "Put Memory Settings",+ "summary": "Cancel Run","tags": ["memory"]}},- "/api/memory/snapshot/{surface}": {+ "/api/memory/runs/{run_id}/events": {"get": {- "description": "Return the current entity list for ``surface`` from workspace.\n\nSnapshot is always derived live from workspace at call time. The response\nalso includes ``pending_changes`` — the diff vs the last persisted state.\nRefresh commits these pending changes into ``changes.jsonl``.",- "operationId": "get_snapshot_api_memory_snapshot__surface__get",+ "description": "SSE-replay events from the next sequence cursor until the run ends.\n\nReconnecting after a refresh: pass ``last_seen_seq + 1``. The manager\nreplays the buffered tail, then blocks on new events until the run reaches\na terminal state.",+ "operationId": "stream_run_events_api_memory_runs__run_id__events_get","parameters": [{"in": "path",- "name": "surface",+ "name": "run_id","required": true,"schema": {- "title": "Surface",+ "title": "Run Id","type": "string"}},+ {+ "in": "query",+ "name": "since",+ "required": false,+ "schema": {+ "default": 0,+ "title": "Since",+ "type": "integer"+ }+ },{"in": "header","name": "Authorization",@@ -31186,22 +31439,22 @@"description": "Validation Error"}},- "summary": "Get Snapshot",+ "summary": "Stream Run Events","tags": ["memory"]}},- "/api/memory/snapshot/{surface}/changes": {- "delete": {- "operationId": "clear_snapshot_changes_api_memory_snapshot__surface__changes_delete",+ "/api/memory/runs/{run_id}/undo": {+ "post": {+ "operationId": "undo_run_edit_api_memory_runs__run_id__undo_post","parameters": [{"in": "path",- "name": "surface",+ "name": "run_id","required": true,"schema": {- "title": "Surface",+ "title": "Run Id","type": "string"}},@@ -31258,43 +31511,17 @@"description": "Validation Error"}},- "summary": "Clear Snapshot Changes",+ "summary": "Undo Run Edit","tags": ["memory"]- },+ }+ },+ "/api/memory/settings": {"get": {- "operationId": "get_changes_api_memory_snapshot__surface__changes_get",+ "description": "Return the current ``memory:`` subtree (defaults merged in).",+ "operationId": "get_memory_settings_endpoint_api_memory_settings_get","parameters": [- {- "in": "path",- "name": "surface",- "required": true,- "schema": {- "title": "Surface",- "type": "string"- }- },- {- "in": "query",- "name": "limit",- "required": false,- "schema": {- "default": 200,- "title": "Limit",- "type": "integer"- }- },- {- "in": "query",- "name": "offset",- "required": false,- "schema": {- "default": 0,- "title": "Offset",- "type": "integer"- }- },{"in": "header","name": "Authorization",@@ -31348,26 +31575,15 @@"description": "Validation Error"}},- "summary": "Get Changes",+ "summary": "Get Memory Settings Endpoint","tags": ["memory"]- }- },- "/api/memory/snapshot/{surface}/refresh": {- "post": {- "description": "Reconcile persisted state with current workspace; record diffs.",- "operationId": "refresh_snapshot_api_memory_snapshot__surface__refresh_post",+ },+ "put": {+ "description": "Merge the payload into the ``memory:`` subtree and persist.",+ "operationId": "put_memory_settings_api_memory_settings_put","parameters": [- {- "in": "path",- "name": "surface",- "required": true,- "schema": {- "title": "Surface",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -31401,6 +31617,18 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "additionalProperties": true,+ "title": "Payload",+ "type": "object"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -31421,15 +31649,16 @@"description": "Validation Error"}},- "summary": "Refresh Snapshot",+ "summary": "Put Memory Settings","tags": ["memory"]}},- "/api/memory/trace/{surface}": {- "delete": {- "operationId": "clear_trace_api_memory_trace__surface__delete",+ "/api/memory/snapshot/{surface}": {+ "get": {+ "description": "Return the current entity list for ``surface`` from workspace.\n\nSnapshot is always derived live from workspace at call time. The response\nalso includes ``pending_changes`` — the diff vs the last persisted state.\nRefresh commits these pending changes into ``changes.jsonl``.",+ "operationId": "get_snapshot_api_memory_snapshot__surface__get","parameters": [{"in": "path",@@ -31493,13 +31722,15 @@"description": "Validation Error"}},- "summary": "Clear Trace",+ "summary": "Get Snapshot","tags": ["memory"]- },- "get": {- "operationId": "get_trace_api_memory_trace__surface__get",+ }+ },+ "/api/memory/snapshot/{surface}/changes": {+ "delete": {+ "operationId": "clear_snapshot_changes_api_memory_snapshot__surface__changes_delete","parameters": [{"in": "path",@@ -31510,26 +31741,6 @@"type": "string"}},- {- "in": "query",- "name": "limit",- "required": false,- "schema": {- "default": 200,- "title": "Limit",- "type": "integer"- }- },- {- "in": "query",- "name": "offset",- "required": false,- "schema": {- "default": 0,- "title": "Offset",- "type": "integer"- }- },{"in": "header","name": "Authorization",@@ -31583,15 +31794,13 @@"description": "Validation Error"}},- "summary": "Get Trace",+ "summary": "Clear Snapshot Changes","tags": ["memory"]- }- },- "/api/memory/trace/{surface}/day/{day}": {- "delete": {- "operationId": "clear_trace_day_api_memory_trace__surface__day__day__delete",+ },+ "get": {+ "operationId": "get_changes_api_memory_snapshot__surface__changes_get","parameters": [{"in": "path",@@ -31603,12 +31812,23 @@}},{- "in": "path",- "name": "day",- "required": true,+ "in": "query",+ "name": "limit",+ "required": false,"schema": {- "title": "Day",- "type": "string"+ "default": 200,+ "title": "Limit",+ "type": "integer"+ }+ },+ {+ "in": "query",+ "name": "offset",+ "required": false,+ "schema": {+ "default": 0,+ "title": "Offset",+ "type": "integer"}},{@@ -31664,16 +31884,26 @@"description": "Validation Error"}},- "summary": "Clear Trace Day",+ "summary": "Get Changes","tags": ["memory"]}},- "/api/multi-user/admin/books": {- "get": {- "operationId": "admin_books_api_multi_user_admin_books_get",+ "/api/memory/snapshot/{surface}/refresh": {+ "post": {+ "description": "Reconcile persisted state with current workspace; record diffs.",+ "operationId": "refresh_snapshot_api_memory_snapshot__surface__refresh_post","parameters": [+ {+ "in": "path",+ "name": "surface",+ "required": true,+ "schema": {+ "title": "Surface",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -31711,11 +31941,7 @@"200": {"content": {"application/json": {- "schema": {- "additionalProperties": true,- "title": "Response Admin Books Api Multi User Admin Books Get",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -31731,17 +31957,25 @@"description": "Validation Error"}},- "summary": "Admin Books",+ "summary": "Refresh Snapshot","tags": [- "multi-user"+ "memory"]}},- "/api/multi-user/admin/resources": {- "get": {- "description": "Everything an admin can assign to a user: models, KBs, skills, and\nthe tool surface (system tools + MCP tools, same pool partners use).",- "operationId": "admin_resources_api_multi_user_admin_resources_get",+ "/api/memory/trace/{surface}": {+ "delete": {+ "operationId": "clear_trace_api_memory_trace__surface__delete","parameters": [+ {+ "in": "path",+ "name": "surface",+ "required": true,+ "schema": {+ "title": "Surface",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -31779,11 +32013,7 @@"200": {"content": {"application/json": {- "schema": {- "additionalProperties": true,- "title": "Response Admin Resources Api Multi User Admin Resources Get",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -31799,17 +32029,43 @@"description": "Validation Error"}},- "summary": "Admin Resources",+ "summary": "Clear Trace","tags": [- "multi-user"+ "memory"]- }- },- "/api/multi-user/admin/skills/install": {- "post": {- "description": "Install a hub skill into the admin catalog (``<hub>:<slug>[@version]``).\n\nThe skill lands in the admin workspace — the same pool ``/admin/resources``\nlists — so it stays invisible to non-admin users until a grant assigns it.\nThe install pipeline (verdict gate, safe extraction, ``always`` stripping)\nlives in :func:`deeptutor.services.skill.hub.install_from_hub`; this\nendpoint only chooses the target root and audits the action.",- "operationId": "admin_install_skill_api_multi_user_admin_skills_install_post",+ },+ "get": {+ "operationId": "get_trace_api_memory_trace__surface__get","parameters": [+ {+ "in": "path",+ "name": "surface",+ "required": true,+ "schema": {+ "title": "Surface",+ "type": "string"+ }+ },+ {+ "in": "query",+ "name": "limit",+ "required": false,+ "schema": {+ "default": 200,+ "title": "Limit",+ "type": "integer"+ }+ },+ {+ "in": "query",+ "name": "offset",+ "required": false,+ "schema": {+ "default": 0,+ "title": "Offset",+ "type": "integer"+ }+ },{"in": "header","name": "Authorization",@@ -31843,25 +32099,11 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/SkillInstallPayload"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {- "schema": {- "additionalProperties": true,- "title": "Response Admin Install Skill Api Multi User Admin Skills Install Post",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -31877,24 +32119,32 @@"description": "Validation Error"}},- "summary": "Admin Install Skill",+ "summary": "Get Trace","tags": [- "multi-user"+ "memory"]}},- "/api/multi-user/guardians": {- "get": {- "operationId": "list_guardian_relationships_api_multi_user_guardians_get",+ "/api/memory/trace/{surface}/day/{day}": {+ "delete": {+ "operationId": "clear_trace_day_api_memory_trace__surface__day__day__delete","parameters": [{- "in": "query",- "name": "include_revoked",- "required": false,+ "in": "path",+ "name": "surface",+ "required": true,"schema": {- "default": false,- "title": "Include Revoked",- "type": "boolean"+ "title": "Surface",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "day",+ "required": true,+ "schema": {+ "title": "Day",+ "type": "string"}},{@@ -31934,11 +32184,7 @@"200": {"content": {"application/json": {- "schema": {- "additionalProperties": true,- "title": "Response List Guardian Relationships Api Multi User Guardians Get",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -31954,13 +32200,15 @@"description": "Validation Error"}},- "summary": "List Guardian Relationships",+ "summary": "Clear Trace Day","tags": [- "multi-user"+ "memory"]- },- "post": {- "operationId": "authorize_guardian_relationship_api_multi_user_guardians_post",+ }+ },+ "/api/multi-user/admin/books": {+ "get": {+ "operationId": "admin_books_api_multi_user_admin_books_get","parameters": [{"in": "header",@@ -31995,23 +32243,13 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/GuardianAuthorizationPayload"- }- }- },- "required": true- },"responses": {- "201": {+ "200": {"content": {"application/json": {"schema": {"additionalProperties": true,- "title": "Response Authorize Guardian Relationship Api Multi User Guardians Post",+ "title": "Response Admin Books Api Multi User Admin Books Get","type": "object"}}@@ -32029,25 +32267,17 @@"description": "Validation Error"}},- "summary": "Authorize Guardian Relationship",+ "summary": "Admin Books","tags": ["multi-user"]}},- "/api/multi-user/guardians/{relationship_id}": {- "delete": {- "operationId": "revoke_guardian_relationship_api_multi_user_guardians__relationship_id__delete",+ "/api/multi-user/admin/resources": {+ "get": {+ "description": "Everything an admin can assign to a user: models, KBs, skills, and\nthe tool surface (system tools + MCP tools, same pool partners use).",+ "operationId": "admin_resources_api_multi_user_admin_resources_get","parameters": [- {- "in": "path",- "name": "relationship_id",- "required": true,- "schema": {- "title": "Relationship Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -32087,7 +32317,7 @@"application/json": {"schema": {"additionalProperties": true,- "title": "Response Revoke Guardian Relationship Api Multi User Guardians Relationship Id Delete",+ "title": "Response Admin Resources Api Multi User Admin Resources Get","type": "object"}}@@ -32105,25 +32335,17 @@"description": "Validation Error"}},- "summary": "Revoke Guardian Relationship",+ "summary": "Admin Resources","tags": ["multi-user"]}},- "/api/multi-user/learners/{learner_user_id}/credentials/reset": {+ "/api/multi-user/admin/skills/install": {"post": {- "operationId": "reset_learner_credentials_api_multi_user_learners__learner_user_id__credentials_reset_post",+ "description": "Install a hub skill into the admin catalog (``<hub>:<slug>[@version]``).\n\nThe skill lands in the admin workspace — the same pool ``/admin/resources``\nlists — so it stays invisible to non-admin users until a grant assigns it.\nThe install pipeline (verdict gate, safe extraction, ``always`` stripping)\nlives in :func:`deeptutor.services.skill.hub.install_from_hub`; this\nendpoint only chooses the target root and audits the action.",+ "operationId": "admin_install_skill_api_multi_user_admin_skills_install_post","parameters": [- {- "in": "path",- "name": "learner_user_id",- "required": true,- "schema": {- "title": "Learner User Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -32161,7 +32383,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/GuardianCredentialResetPayload"+ "$ref": "#/components/schemas/SkillInstallPayload"}}},@@ -32173,7 +32395,7 @@"application/json": {"schema": {"additionalProperties": true,- "title": "Response Reset Learner Credentials Api Multi User Learners Learner User Id Credentials Reset Post",+ "title": "Response Admin Install Skill Api Multi User Admin Skills Install Post","type": "object"}}@@ -32191,99 +32413,24 @@"description": "Validation Error"}},- "summary": "Reset Learner Credentials",+ "summary": "Admin Install Skill","tags": ["multi-user"]}},- "/api/multi-user/learners/{learner_user_id}/guardian-report": {+ "/api/multi-user/guardians": {"get": {- "operationId": "guardian_report_api_multi_user_learners__learner_user_id__guardian_report_get",+ "operationId": "list_guardian_relationships_api_multi_user_guardians_get","parameters": [{- "in": "path",- "name": "learner_user_id",- "required": true,- "schema": {- "title": "Learner User Id",- "type": "string"- }- },- {- "in": "header",- "name": "Authorization",- "required": false,- "schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Authorization"- }- },- {- "in": "cookie",- "name": "dt_token",+ "in": "query",+ "name": "include_revoked","required": false,"schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Dt Token"- }- }- ],- "responses": {- "200": {- "content": {- "application/json": {- "schema": {- "additionalProperties": true,- "title": "Response Guardian Report Api Multi User Learners Learner User Id Guardian Report Get",- "type": "object"- }- }- },- "description": "Successful Response"- },- "422": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/HTTPValidationError"- }- }- },- "description": "Validation Error"- }- },- "summary": "Guardian Report",- "tags": [- "multi-user"- ]- }- },- "/api/multi-user/learners/{learner_user_id}/materials": {- "get": {- "operationId": "guardian_material_catalog_api_multi_user_learners__learner_user_id__materials_get",- "parameters": [- {- "in": "path",- "name": "learner_user_id",- "required": true,- "schema": {- "title": "Learner User Id",- "type": "string"+ "default": false,+ "title": "Include Revoked",+ "type": "boolean"}},{@@ -32325,7 +32472,7 @@"application/json": {"schema": {"additionalProperties": true,- "title": "Response Guardian Material Catalog Api Multi User Learners Learner User Id Materials Get",+ "title": "Response List Guardian Relationships Api Multi User Guardians Get","type": "object"}}@@ -32343,23 +32490,14 @@"description": "Validation Error"}},- "summary": "Guardian Material Catalog",+ "summary": "List Guardian Relationships","tags": ["multi-user"]},- "put": {- "operationId": "assign_guardian_materials_api_multi_user_learners__learner_user_id__materials_put",+ "post": {+ "operationId": "authorize_guardian_relationship_api_multi_user_guardians_post","parameters": [- {- "in": "path",- "name": "learner_user_id",- "required": true,- "schema": {- "title": "Learner User Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -32397,19 +32535,19 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/GuardianMaterialsPayload"+ "$ref": "#/components/schemas/GuardianAuthorizationPayload"}}},"required": true},"responses": {- "200": {+ "201": {"content": {"application/json": {"schema": {"additionalProperties": true,- "title": "Response Assign Guardian Materials Api Multi User Learners Learner User Id Materials Put",+ "title": "Response Authorize Guardian Relationship Api Multi User Guardians Post","type": "object"}}@@ -32427,22 +32565,22 @@"description": "Validation Error"}},- "summary": "Assign Guardian Materials",+ "summary": "Authorize Guardian Relationship","tags": ["multi-user"]}},- "/api/multi-user/learners/{learner_user_id}/restrictions": {- "get": {- "operationId": "get_guardian_restrictions_api_multi_user_learners__learner_user_id__restrictions_get",+ "/api/multi-user/guardians/{relationship_id}": {+ "delete": {+ "operationId": "revoke_guardian_relationship_api_multi_user_guardians__relationship_id__delete","parameters": [{"in": "path",- "name": "learner_user_id",+ "name": "relationship_id","required": true,"schema": {- "title": "Learner User Id",+ "title": "Relationship Id","type": "string"}},@@ -32485,7 +32623,7 @@"application/json": {"schema": {"additionalProperties": true,- "title": "Response Get Guardian Restrictions Api Multi User Learners Learner User Id Restrictions Get",+ "title": "Response Revoke Guardian Relationship Api Multi User Guardians Relationship Id Delete","type": "object"}}@@ -32503,13 +32641,15 @@"description": "Validation Error"}},- "summary": "Get Guardian Restrictions",+ "summary": "Revoke Guardian Relationship","tags": ["multi-user"]- },- "put": {- "operationId": "put_guardian_restrictions_api_multi_user_learners__learner_user_id__restrictions_put",+ }+ },+ "/api/multi-user/learners/{learner_user_id}/credentials/reset": {+ "post": {+ "operationId": "reset_learner_credentials_api_multi_user_learners__learner_user_id__credentials_reset_post","parameters": [{"in": "path",@@ -32557,7 +32697,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/GuardianRestrictionsPayload"+ "$ref": "#/components/schemas/GuardianCredentialResetPayload"}}},@@ -32569,7 +32709,7 @@"application/json": {"schema": {"additionalProperties": true,- "title": "Response Put Guardian Restrictions Api Multi User Learners Learner User Id Restrictions Put",+ "title": "Response Reset Learner Credentials Api Multi User Learners Learner User Id Credentials Reset Post","type": "object"}}@@ -32587,89 +32727,22 @@"description": "Validation Error"}},- "summary": "Put Guardian Restrictions",+ "summary": "Reset Learner Credentials","tags": ["multi-user"]}},- "/api/multi-user/me/guardianships": {+ "/api/multi-user/learners/{learner_user_id}/guardian-report": {"get": {- "operationId": "my_guardianships_api_multi_user_me_guardianships_get",- "parameters": [- {- "in": "header",- "name": "Authorization",- "required": false,- "schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Authorization"- }- },- {- "in": "cookie",- "name": "dt_token",- "required": false,- "schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Dt Token"- }- }- ],- "responses": {- "200": {- "content": {- "application/json": {- "schema": {- "additionalProperties": true,- "title": "Response My Guardianships Api Multi User Me Guardianships Get",- "type": "object"- }- }- },- "description": "Successful Response"- },- "422": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/HTTPValidationError"- }- }- },- "description": "Validation Error"- }- },- "summary": "My Guardianships",- "tags": [- "multi-user"- ]- }- },- "/api/multi-user/me/guardianships/{relationship_id}": {- "delete": {- "operationId": "revoke_my_guardianship_api_multi_user_me_guardianships__relationship_id__delete",+ "operationId": "guardian_report_api_multi_user_learners__learner_user_id__guardian_report_get","parameters": [{"in": "path",- "name": "relationship_id",+ "name": "learner_user_id","required": true,"schema": {- "title": "Relationship Id",+ "title": "Learner User Id","type": "string"}},@@ -32712,7 +32785,7 @@"application/json": {"schema": {"additionalProperties": true,- "title": "Response Revoke My Guardianship Api Multi User Me Guardianships Relationship Id Delete",+ "title": "Response Guardian Report Api Multi User Learners Learner User Id Guardian Report Get","type": "object"}}@@ -32730,16 +32803,25 @@"description": "Validation Error"}},- "summary": "Revoke My Guardianship",+ "summary": "Guardian Report","tags": ["multi-user"]}},- "/api/multi-user/users": {+ "/api/multi-user/learners/{learner_user_id}/materials": {"get": {- "operationId": "multi_user_list_users_api_multi_user_users_get",+ "operationId": "guardian_material_catalog_api_multi_user_learners__learner_user_id__materials_get","parameters": [+ {+ "in": "path",+ "name": "learner_user_id",+ "required": true,+ "schema": {+ "title": "Learner User Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -32779,7 +32861,7 @@"application/json": {"schema": {"additionalProperties": true,- "title": "Response Multi User List Users Api Multi User Users Get",+ "title": "Response Guardian Material Catalog Api Multi User Learners Learner User Id Materials Get","type": "object"}}@@ -32797,22 +32879,20 @@"description": "Validation Error"}},- "summary": "Multi User List Users",+ "summary": "Guardian Material Catalog","tags": ["multi-user"]- }- },- "/api/multi-user/users/{user_id}/book-permission": {- "get": {- "operationId": "get_user_book_permission_api_multi_user_users__user_id__book_permission_get",+ },+ "put": {+ "operationId": "assign_guardian_materials_api_multi_user_learners__learner_user_id__materials_put","parameters": [{"in": "path",- "name": "user_id",+ "name": "learner_user_id","required": true,"schema": {- "title": "User Id",+ "title": "Learner User Id","type": "string"}},@@ -32849,13 +32929,23 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/GuardianMaterialsPayload"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {"application/json": {"schema": {"additionalProperties": true,- "title": "Response Get User Book Permission Api Multi User Users User Id Book Permission Get",+ "title": "Response Assign Guardian Materials Api Multi User Learners Learner User Id Materials Put","type": "object"}}@@ -32873,20 +32963,22 @@"description": "Validation Error"}},- "summary": "Get User Book Permission",+ "summary": "Assign Guardian Materials","tags": ["multi-user"]- },- "put": {- "operationId": "put_user_book_permission_api_multi_user_users__user_id__book_permission_put",+ }+ },+ "/api/multi-user/learners/{learner_user_id}/restrictions": {+ "get": {+ "operationId": "get_guardian_restrictions_api_multi_user_learners__learner_user_id__restrictions_get","parameters": [{"in": "path",- "name": "user_id",+ "name": "learner_user_id","required": true,"schema": {- "title": "User Id",+ "title": "Learner User Id","type": "string"}},@@ -32923,23 +33015,13 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/BookPermissionPayload"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {"schema": {"additionalProperties": true,- "title": "Response Put User Book Permission Api Multi User Users User Id Book Permission Put",+ "title": "Response Get Guardian Restrictions Api Multi User Learners Learner User Id Restrictions Get","type": "object"}}@@ -32957,22 +33039,20 @@"description": "Validation Error"}},- "summary": "Put User Book Permission",+ "summary": "Get Guardian Restrictions","tags": ["multi-user"]- }- },- "/api/multi-user/users/{user_id}/grants": {- "get": {- "operationId": "get_user_grants_api_multi_user_users__user_id__grants_get",+ },+ "put": {+ "operationId": "put_guardian_restrictions_api_multi_user_learners__learner_user_id__restrictions_put","parameters": [{"in": "path",- "name": "user_id",+ "name": "learner_user_id","required": true,"schema": {- "title": "User Id",+ "title": "Learner User Id","type": "string"}},@@ -33009,13 +33089,23 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/GuardianRestrictionsPayload"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {"application/json": {"schema": {"additionalProperties": true,- "title": "Response Get User Grants Api Multi User Users User Id Grants Get",+ "title": "Response Put Guardian Restrictions Api Multi User Learners Learner User Id Restrictions Put","type": "object"}}@@ -33033,23 +33123,16 @@"description": "Validation Error"}},- "summary": "Get User Grants",+ "summary": "Put Guardian Restrictions","tags": ["multi-user"]- },- "put": {- "operationId": "put_user_grants_api_multi_user_users__user_id__grants_put",+ }+ },+ "/api/multi-user/me/guardianships": {+ "get": {+ "operationId": "my_guardianships_api_multi_user_me_guardianships_get","parameters": [- {- "in": "path",- "name": "user_id",- "required": true,- "schema": {- "title": "User Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -33083,23 +33166,13 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/GrantPayload"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {"schema": {"additionalProperties": true,- "title": "Response Put User Grants Api Multi User Users User Id Grants Put",+ "title": "Response My Guardianships Api Multi User Me Guardianships Get","type": "object"}}@@ -33117,17 +33190,25 @@"description": "Validation Error"}},- "summary": "Put User Grants",+ "summary": "My Guardianships","tags": ["multi-user"]}},- "/api/notebooks": {- "get": {- "description": "Get all notebook list\n\nReturns:\n Notebook list (includes summary information)",- "operationId": "list_notebooks_api_notebooks_get",+ "/api/multi-user/me/guardianships/{relationship_id}": {+ "delete": {+ "operationId": "revoke_my_guardianship_api_multi_user_me_guardianships__relationship_id__delete","parameters": [+ {+ "in": "path",+ "name": "relationship_id",+ "required": true,+ "schema": {+ "title": "Relationship Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -33165,7 +33246,11 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Revoke My Guardianship Api Multi User Me Guardianships Relationship Id Delete",+ "type": "object"+ }}},"description": "Successful Response"@@ -33181,14 +33266,15 @@"description": "Validation Error"}},- "summary": "List Notebooks",+ "summary": "Revoke My Guardianship","tags": [- "notebooks"+ "multi-user"]- },- "post": {- "description": "Create new notebook\n\nArgs:\n request: Create request\n\nReturns:\n Created notebook information",- "operationId": "create_notebook_api_notebooks_post",+ }+ },+ "/api/multi-user/users": {+ "get": {+ "operationId": "multi_user_list_users_api_multi_user_users_get","parameters": [{"in": "header",@@ -33223,21 +33309,15 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/CreateNotebookRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Multi User List Users Api Multi User Users Get",+ "type": "object"+ }}},"description": "Successful Response"@@ -33253,17 +33333,25 @@"description": "Validation Error"}},- "summary": "Create Notebook",+ "summary": "Multi User List Users","tags": [- "notebooks"+ "multi-user"]}},- "/api/notebooks/actions/add-record": {- "post": {- "description": "Add record to notebook\n\nArgs:\n request: Add record request\n\nReturns:\n Addition result",- "operationId": "add_record_api_notebooks_actions_add_record_post",+ "/api/multi-user/users/{user_id}/book-permission": {+ "get": {+ "operationId": "get_user_book_permission_api_multi_user_users__user_id__book_permission_get","parameters": [+ {+ "in": "path",+ "name": "user_id",+ "required": true,+ "schema": {+ "title": "User Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -33297,21 +33385,15 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/AddRecordRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Get User Book Permission Api Multi User Users User Id Book Permission Get",+ "type": "object"+ }}},"description": "Successful Response"@@ -33327,17 +33409,23 @@"description": "Validation Error"}},- "summary": "Add Record",+ "summary": "Get User Book Permission","tags": [- "notebooks"+ "multi-user"]- }- },- "/api/notebooks/actions/add-record-with-summary": {- "post": {- "description": "Add record to notebook and stream generated summary.",- "operationId": "add_record_with_summary_api_notebooks_actions_add_record_with_summary_post",+ },+ "put": {+ "operationId": "put_user_book_permission_api_multi_user_users__user_id__book_permission_put","parameters": [+ {+ "in": "path",+ "name": "user_id",+ "required": true,+ "schema": {+ "title": "User Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -33375,7 +33463,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/AddRecordRequest"+ "$ref": "#/components/schemas/BookPermissionPayload"}}},@@ -33385,7 +33473,11 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Put User Book Permission Api Multi User Users User Id Book Permission Put",+ "type": "object"+ }}},"description": "Successful Response"@@ -33401,17 +33493,25 @@"description": "Validation Error"}},- "summary": "Add Record With Summary",+ "summary": "Put User Book Permission","tags": [- "notebooks"+ "multi-user"]}},- "/api/notebooks/health": {+ "/api/multi-user/users/{user_id}/grants": {"get": {- "description": "Health check",- "operationId": "health_check_api_notebooks_health_get",+ "operationId": "get_user_grants_api_multi_user_users__user_id__grants_get","parameters": [+ {+ "in": "path",+ "name": "user_id",+ "required": true,+ "schema": {+ "title": "User Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -33449,7 +33549,11 @@"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Get User Grants Api Multi User Users User Id Grants Get",+ "type": "object"+ }}},"description": "Successful Response"@@ -33465,17 +33569,23 @@"description": "Validation Error"}},- "summary": "Health Check",+ "summary": "Get User Grants","tags": [- "notebooks"+ "multi-user"]- }- },- "/api/notebooks/statistics": {- "get": {- "description": "Get notebook statistics\n\nReturns:\n Statistics information",- "operationId": "get_statistics_api_notebooks_statistics_get",+ },+ "put": {+ "operationId": "put_user_grants_api_multi_user_users__user_id__grants_put","parameters": [+ {+ "in": "path",+ "name": "user_id",+ "required": true,+ "schema": {+ "title": "User Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -33509,11 +33619,25 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/GrantPayload"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Put User Grants Api Multi User Users User Id Grants Put",+ "type": "object"+ }}},"description": "Successful Response"@@ -33529,26 +33653,17 @@"description": "Validation Error"}},- "summary": "Get Statistics",+ "summary": "Put User Grants","tags": [- "notebooks"+ "multi-user"]}},- "/api/notebooks/{notebook_id}": {- "delete": {- "description": "Delete notebook\n\nArgs:\n notebook_id: Notebook ID\n\nReturns:\n Deletion result",- "operationId": "delete_notebook_api_notebooks__notebook_id__delete",+ "/api/notebooks": {+ "get": {+ "description": "Get all notebook list\n\nReturns:\n Notebook list (includes summary information)",+ "operationId": "list_notebooks_api_notebooks_get","parameters": [- {- "in": "path",- "name": "notebook_id",- "required": true,- "schema": {- "title": "Notebook Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -33602,24 +33717,15 @@"description": "Validation Error"}},- "summary": "Delete Notebook",+ "summary": "List Notebooks","tags": ["notebooks"]},- "get": {- "description": "Get notebook details\n\nArgs:\n notebook_id: Notebook ID\n\nReturns:\n Notebook details (includes all records)",- "operationId": "get_notebook_api_notebooks__notebook_id__get",+ "post": {+ "description": "Create new notebook\n\nArgs:\n request: Create request\n\nReturns:\n Created notebook information",+ "operationId": "create_notebook_api_notebooks_post","parameters": [- {- "in": "path",- "name": "notebook_id",- "required": true,- "schema": {- "title": "Notebook Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -33653,6 +33759,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/CreateNotebookRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -33673,24 +33789,17 @@"description": "Validation Error"}},- "summary": "Get Notebook",+ "summary": "Create Notebook","tags": ["notebooks"]- },- "put": {- "description": "Update notebook information\n\nArgs:\n notebook_id: Notebook ID\n request: Update request\n\nReturns:\n Updated notebook information",- "operationId": "update_notebook_api_notebooks__notebook_id__put",+ }+ },+ "/api/notebooks/actions/add-record": {+ "post": {+ "description": "Add record to notebook\n\nArgs:\n request: Add record request\n\nReturns:\n Addition result",+ "operationId": "add_record_api_notebooks_actions_add_record_post","parameters": [- {- "in": "path",- "name": "notebook_id",- "required": true,- "schema": {- "title": "Notebook Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -33728,7 +33837,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/UpdateNotebookRequest"+ "$ref": "#/components/schemas/AddRecordRequest"}}},@@ -33754,26 +33863,17 @@"description": "Validation Error"}},- "summary": "Update Notebook",+ "summary": "Add Record","tags": ["notebooks"]}},- "/api/notebooks/{notebook_id}/export": {- "get": {- "description": "Render the whole notebook as a single Markdown document.",- "operationId": "export_notebook_api_notebooks__notebook_id__export_get",+ "/api/notebooks/actions/add-record-with-summary": {+ "post": {+ "description": "Add record to notebook and stream generated summary.",+ "operationId": "add_record_with_summary_api_notebooks_actions_add_record_with_summary_post","parameters": [- {- "in": "path",- "name": "notebook_id",- "required": true,- "schema": {- "title": "Notebook Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -33807,13 +33907,21 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AddRecordRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {- "text/plain": {- "schema": {- "type": "string"- }+ "application/json": {+ "schema": {}}},"description": "Successful Response"@@ -33829,35 +33937,81 @@"description": "Validation Error"}},- "summary": "Export Notebook",+ "summary": "Add Record With Summary","tags": ["notebooks"]}},- "/api/notebooks/{notebook_id}/records/{record_id}": {- "delete": {- "description": "Remove record from notebook\n\nArgs:\n notebook_id: Notebook ID\n record_id: Record ID\n\nReturns:\n Deletion result",- "operationId": "remove_record_api_notebooks__notebook_id__records__record_id__delete",+ "/api/notebooks/health": {+ "get": {+ "description": "Health check",+ "operationId": "health_check_api_notebooks_health_get","parameters": [{- "in": "path",- "name": "notebook_id",- "required": true,+ "in": "header",+ "name": "Authorization",+ "required": false,"schema": {- "title": "Notebook Id",- "type": "string"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"}},{- "in": "path",- "name": "record_id",- "required": true,+ "in": "cookie",+ "name": "dt_token",+ "required": false,"schema": {- "title": "Record Id",- "type": "string"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"}+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"},+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Health Check",+ "tags": [+ "notebooks"+ ]+ }+ },+ "/api/notebooks/statistics": {+ "get": {+ "description": "Get notebook statistics\n\nReturns:\n Statistics information",+ "operationId": "get_statistics_api_notebooks_statistics_get",+ "parameters": [{"in": "header","name": "Authorization",@@ -33911,14 +34065,16 @@"description": "Validation Error"}},- "summary": "Remove Record",+ "summary": "Get Statistics","tags": ["notebooks"]- },- "put": {- "description": "Update an existing notebook record in place.",- "operationId": "update_record_api_notebooks__notebook_id__records__record_id__put",+ }+ },+ "/api/notebooks/{notebook_id}": {+ "delete": {+ "description": "Delete notebook\n\nArgs:\n notebook_id: Notebook ID\n\nReturns:\n Deletion result",+ "operationId": "delete_notebook_api_notebooks__notebook_id__delete","parameters": [{"in": "path",@@ -33929,15 +34085,6 @@"type": "string"}},- {- "in": "path",- "name": "record_id",- "required": true,- "schema": {- "title": "Record Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -33971,16 +34118,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/UpdateRecordRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -34001,16 +34138,14 @@"description": "Validation Error"}},- "summary": "Update Record",+ "summary": "Delete Notebook","tags": ["notebooks"]- }- },- "/api/notebooks/{notebook_id}/records/{record_id}/actions/copy": {- "post": {- "description": "Duplicate a record into another notebook under a fresh id.",- "operationId": "copy_record_api_notebooks__notebook_id__records__record_id__actions_copy_post",+ },+ "get": {+ "description": "Get notebook details\n\nArgs:\n notebook_id: Notebook ID\n\nReturns:\n Notebook details (includes all records)",+ "operationId": "get_notebook_api_notebooks__notebook_id__get","parameters": [{"in": "path",@@ -34021,15 +34156,6 @@"type": "string"}},- {- "in": "path",- "name": "record_id",- "required": true,- "schema": {- "title": "Record Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -34063,16 +34189,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/MoveRecordRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -34093,16 +34209,14 @@"description": "Validation Error"}},- "summary": "Copy Record",+ "summary": "Get Notebook","tags": ["notebooks"]- }- },- "/api/notebooks/{notebook_id}/records/{record_id}/actions/move": {- "post": {- "description": "Move a record from this notebook into another one.",- "operationId": "move_record_api_notebooks__notebook_id__records__record_id__actions_move_post",+ },+ "put": {+ "description": "Update notebook information\n\nArgs:\n notebook_id: Notebook ID\n request: Update request\n\nReturns:\n Updated notebook information",+ "operationId": "update_notebook_api_notebooks__notebook_id__put","parameters": [{"in": "path",@@ -34113,15 +34227,6 @@"type": "string"}},- {- "in": "path",- "name": "record_id",- "required": true,- "schema": {- "title": "Record Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -34159,7 +34264,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/MoveRecordRequest"+ "$ref": "#/components/schemas/UpdateNotebookRequest"}}},@@ -34185,16 +34290,26 @@"description": "Validation Error"}},- "summary": "Move Record",+ "summary": "Update Notebook","tags": ["notebooks"]}},- "/api/partner-groups": {+ "/api/notebooks/{notebook_id}/export": {"get": {- "operationId": "list_partner_groups_api_partner_groups_get",+ "description": "Render the whole notebook as a single Markdown document.",+ "operationId": "export_notebook_api_notebooks__notebook_id__export_get","parameters": [+ {+ "in": "path",+ "name": "notebook_id",+ "required": true,+ "schema": {+ "title": "Notebook Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -34231,8 +34346,10 @@"responses": {"200": {"content": {- "application/json": {- "schema": {}+ "text/plain": {+ "schema": {+ "type": "string"+ }}},"description": "Successful Response"@@ -34248,87 +34365,35 @@"description": "Validation Error"}},- "summary": "List Partner Groups",+ "summary": "Export Notebook","tags": [- "partner-groups"+ "notebooks"]- },- "post": {- "operationId": "create_partner_group_api_partner_groups_post",+ }+ },+ "/api/notebooks/{notebook_id}/records/{record_id}": {+ "delete": {+ "description": "Remove record from notebook\n\nArgs:\n notebook_id: Notebook ID\n record_id: Record ID\n\nReturns:\n Deletion result",+ "operationId": "remove_record_api_notebooks__notebook_id__records__record_id__delete","parameters": [{- "in": "header",- "name": "Authorization",- "required": false,+ "in": "path",+ "name": "notebook_id",+ "required": true,"schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Authorization"+ "title": "Notebook Id",+ "type": "string"}},{- "in": "cookie",- "name": "dt_token",- "required": false,+ "in": "path",+ "name": "record_id",+ "required": true,"schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Dt Token"- }- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/CreatePartnerGroupRequest"- }+ "title": "Record Id",+ "type": "string"}},- "required": true- },- "responses": {- "200": {- "content": {- "application/json": {- "schema": {}- }- },- "description": "Successful Response"- },- "422": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/HTTPValidationError"- }- }- },- "description": "Validation Error"- }- },- "summary": "Create Partner Group",- "tags": [- "partner-groups"- ]- }- },- "/api/partner-groups/discussion-modes": {- "get": {- "operationId": "list_discussion_modes_api_partner_groups_discussion_modes_get",- "parameters": [{"in": "header","name": "Authorization",@@ -34382,16 +34447,33 @@"description": "Validation Error"}},- "summary": "List Discussion Modes",+ "summary": "Remove Record","tags": [- "partner-groups"+ "notebooks"]- }- },- "/api/partner-groups/shared-memory-types": {- "get": {- "operationId": "list_shared_memory_types_api_partner_groups_shared_memory_types_get",+ },+ "put": {+ "description": "Update an existing notebook record in place.",+ "operationId": "update_record_api_notebooks__notebook_id__records__record_id__put","parameters": [+ {+ "in": "path",+ "name": "notebook_id",+ "required": true,+ "schema": {+ "title": "Notebook Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "record_id",+ "required": true,+ "schema": {+ "title": "Record Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -34425,6 +34507,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/UpdateRecordRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -34445,22 +34537,32 @@"description": "Validation Error"}},- "summary": "List Shared Memory Types",+ "summary": "Update Record","tags": [- "partner-groups"+ "notebooks"]}},- "/api/partner-groups/{group_id}": {- "delete": {- "operationId": "delete_partner_group_api_partner_groups__group_id__delete",+ "/api/notebooks/{notebook_id}/records/{record_id}/actions/copy": {+ "post": {+ "description": "Duplicate a record into another notebook under a fresh id.",+ "operationId": "copy_record_api_notebooks__notebook_id__records__record_id__actions_copy_post","parameters": [{"in": "path",- "name": "group_id",+ "name": "notebook_id","required": true,"schema": {- "title": "Group Id",+ "title": "Notebook Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "record_id",+ "required": true,+ "schema": {+ "title": "Record Id","type": "string"}},@@ -34497,6 +34599,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MoveRecordRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -34517,20 +34629,32 @@"description": "Validation Error"}},- "summary": "Delete Partner Group",+ "summary": "Copy Record","tags": [- "partner-groups"+ "notebooks"]- },- "get": {- "operationId": "get_partner_group_api_partner_groups__group_id__get",+ }+ },+ "/api/notebooks/{notebook_id}/records/{record_id}/actions/move": {+ "post": {+ "description": "Move a record from this notebook into another one.",+ "operationId": "move_record_api_notebooks__notebook_id__records__record_id__actions_move_post","parameters": [{"in": "path",- "name": "group_id",+ "name": "notebook_id","required": true,"schema": {- "title": "Group Id",+ "title": "Notebook Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "record_id",+ "required": true,+ "schema": {+ "title": "Record Id","type": "string"}},@@ -34567,6 +34691,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MoveRecordRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -34587,23 +34721,16 @@"description": "Validation Error"}},- "summary": "Get Partner Group",+ "summary": "Move Record","tags": [- "partner-groups"+ "notebooks"]- },- "patch": {- "operationId": "update_partner_group_api_partner_groups__group_id__patch",+ }+ },+ "/api/partner-groups": {+ "get": {+ "operationId": "list_partner_groups_api_partner_groups_get","parameters": [- {- "in": "path",- "name": "group_id",- "required": true,- "schema": {- "title": "Group Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -34637,16 +34764,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/UpdatePartnerGroupRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -34667,49 +34784,14 @@"description": "Validation Error"}},- "summary": "Update Partner Group",+ "summary": "List Partner Groups","tags": ["partner-groups"]- }- },- "/api/partner-groups/{group_id}/history": {- "get": {- "operationId": "partner_group_history_api_partner_groups__group_id__history_get",+ },+ "post": {+ "operationId": "create_partner_group_api_partner_groups_post","parameters": [- {- "in": "path",- "name": "group_id",- "required": true,- "schema": {- "title": "Group Id",- "type": "string"- }- },- {- "in": "query",- "name": "session_key",- "required": false,- "schema": {- "default": "default",- "maxLength": 120,- "minLength": 1,- "title": "Session Key",- "type": "string"- }- },- {- "in": "query",- "name": "limit",- "required": false,- "schema": {- "default": 200,- "maximum": 500,- "minimum": 1,- "title": "Limit",- "type": "integer"- }- },{"in": "header","name": "Authorization",@@ -34743,6 +34825,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/CreatePartnerGroupRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -34763,49 +34855,16 @@"description": "Validation Error"}},- "summary": "Partner Group History",+ "summary": "Create Partner Group","tags": ["partner-groups"]}},- "/api/partner-groups/{group_id}/invocations": {+ "/api/partner-groups/discussion-modes": {"get": {- "operationId": "partner_group_invocations_api_partner_groups__group_id__invocations_get",+ "operationId": "list_discussion_modes_api_partner_groups_discussion_modes_get","parameters": [- {- "in": "path",- "name": "group_id",- "required": true,- "schema": {- "title": "Group Id",- "type": "string"- }- },- {- "in": "query",- "name": "session_key",- "required": false,- "schema": {- "default": "default",- "maxLength": 120,- "minLength": 1,- "title": "Session Key",- "type": "string"- }- },- {- "in": "query",- "name": "limit",- "required": false,- "schema": {- "default": 200,- "maximum": 500,- "minimum": 1,- "title": "Limit",- "type": "integer"- }- },{"in": "header","name": "Authorization",@@ -34859,23 +34918,16 @@"description": "Validation Error"}},- "summary": "Partner Group Invocations",+ "summary": "List Discussion Modes","tags": ["partner-groups"]- },- "post": {- "operationId": "create_partner_invocation_api_partner_groups__group_id__invocations_post",+ }+ },+ "/api/partner-groups/shared-memory-types": {+ "get": {+ "operationId": "list_shared_memory_types_api_partner_groups_shared_memory_types_get","parameters": [- {- "in": "path",- "name": "group_id",- "required": true,- "schema": {- "title": "Group Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -34909,16 +34961,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/CreatePartnerInvocationRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -34939,15 +34981,15 @@"description": "Validation Error"}},- "summary": "Create Partner Invocation",+ "summary": "List Shared Memory Types","tags": ["partner-groups"]}},- "/api/partner-groups/{group_id}/invocations/{invocation_id}/approve": {- "post": {- "operationId": "approve_partner_invocation_api_partner_groups__group_id__invocations__invocation_id__approve_post",+ "/api/partner-groups/{group_id}": {+ "delete": {+ "operationId": "delete_partner_group_api_partner_groups__group_id__delete","parameters": [{"in": "path",@@ -34958,15 +35000,6 @@"type": "string"}},- {- "in": "path",- "name": "invocation_id",- "required": true,- "schema": {- "title": "Invocation Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -35000,16 +35033,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/PartnerInvocationActionRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -35030,15 +35053,13 @@"description": "Validation Error"}},- "summary": "Approve Partner Invocation",+ "summary": "Delete Partner Group","tags": ["partner-groups"]- }- },- "/api/partner-groups/{group_id}/invocations/{invocation_id}/reject": {- "post": {- "operationId": "reject_partner_invocation_api_partner_groups__group_id__invocations__invocation_id__reject_post",+ },+ "get": {+ "operationId": "get_partner_group_api_partner_groups__group_id__get","parameters": [{"in": "path",@@ -35049,15 +35070,6 @@"type": "string"}},- {- "in": "path",- "name": "invocation_id",- "required": true,- "schema": {- "title": "Invocation Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -35091,16 +35103,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/PartnerInvocationActionRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -35121,15 +35123,13 @@"description": "Validation Error"}},- "summary": "Reject Partner Invocation",+ "summary": "Get Partner Group","tags": ["partner-groups"]- }- },- "/api/partner-groups/{group_id}/messages": {- "post": {- "operationId": "send_partner_group_message_api_partner_groups__group_id__messages_post",+ },+ "patch": {+ "operationId": "update_partner_group_api_partner_groups__group_id__patch","parameters": [{"in": "path",@@ -35177,7 +35177,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/PartnerGroupMessageRequest"+ "$ref": "#/components/schemas/UpdatePartnerGroupRequest"}}},@@ -35203,15 +35203,15 @@"description": "Validation Error"}},- "summary": "Send Partner Group Message",+ "summary": "Update Partner Group","tags": ["partner-groups"]}},- "/api/partner-groups/{group_id}/rounds/{turn_id}/summary": {- "post": {- "operationId": "summarize_partner_group_round_api_partner_groups__group_id__rounds__turn_id__summary_post",+ "/api/partner-groups/{group_id}/history": {+ "get": {+ "operationId": "partner_group_history_api_partner_groups__group_id__history_get","parameters": [{"in": "path",@@ -35223,14 +35223,29 @@}},{- "in": "path",- "name": "turn_id",- "required": true,+ "in": "query",+ "name": "session_key",+ "required": false,"schema": {- "title": "Turn Id",+ "default": "default",+ "maxLength": 120,+ "minLength": 1,+ "title": "Session Key","type": "string"}},+ {+ "in": "query",+ "name": "limit",+ "required": false,+ "schema": {+ "default": 200,+ "maximum": 500,+ "minimum": 1,+ "title": "Limit",+ "type": "integer"+ }+ },{"in": "header","name": "Authorization",@@ -35264,16 +35279,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/RoundSummaryRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -35294,15 +35299,15 @@"description": "Validation Error"}},- "summary": "Summarize Partner Group Round",+ "summary": "Partner Group History","tags": ["partner-groups"]}},- "/api/partner-groups/{group_id}/sessions": {+ "/api/partner-groups/{group_id}/invocations": {"get": {- "operationId": "list_partner_group_sessions_api_partner_groups__group_id__sessions_get",+ "operationId": "partner_group_invocations_api_partner_groups__group_id__invocations_get","parameters": [{"in": "path",@@ -35313,6 +35318,30 @@"type": "string"}},+ {+ "in": "query",+ "name": "session_key",+ "required": false,+ "schema": {+ "default": "default",+ "maxLength": 120,+ "minLength": 1,+ "title": "Session Key",+ "type": "string"+ }+ },+ {+ "in": "query",+ "name": "limit",+ "required": false,+ "schema": {+ "default": 200,+ "maximum": 500,+ "minimum": 1,+ "title": "Limit",+ "type": "integer"+ }+ },{"in": "header","name": "Authorization",@@ -35366,13 +35395,13 @@"description": "Validation Error"}},- "summary": "List Partner Group Sessions",+ "summary": "Partner Group Invocations","tags": ["partner-groups"]},"post": {- "operationId": "create_partner_group_session_api_partner_groups__group_id__sessions_post",+ "operationId": "create_partner_invocation_api_partner_groups__group_id__invocations_post","parameters": [{"in": "path",@@ -35416,8 +35445,18 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/CreatePartnerInvocationRequest"+ }+ }+ },+ "required": true+ },"responses": {- "201": {+ "200": {"content": {"application/json": {"schema": {}@@ -35436,15 +35475,15 @@"description": "Validation Error"}},- "summary": "Create Partner Group Session",+ "summary": "Create Partner Invocation","tags": ["partner-groups"]}},- "/api/partner-groups/{group_id}/sessions/{session_key}": {- "delete": {- "operationId": "delete_partner_group_session_api_partner_groups__group_id__sessions__session_key__delete",+ "/api/partner-groups/{group_id}/invocations/{invocation_id}/approve": {+ "post": {+ "operationId": "approve_partner_invocation_api_partner_groups__group_id__invocations__invocation_id__approve_post","parameters": [{"in": "path",@@ -35457,10 +35496,10 @@},{"in": "path",- "name": "session_key",+ "name": "invocation_id","required": true,"schema": {- "title": "Session Key",+ "title": "Invocation Id","type": "string"}},@@ -35497,6 +35536,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/PartnerInvocationActionRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -35517,15 +35566,15 @@"description": "Validation Error"}},- "summary": "Delete Partner Group Session",+ "summary": "Approve Partner Invocation","tags": ["partner-groups"]}},- "/api/partner-groups/{group_id}/turns/{turn_id}/partners/{partner_id}/retry": {+ "/api/partner-groups/{group_id}/invocations/{invocation_id}/reject": {"post": {- "operationId": "retry_partner_group_seat_api_partner_groups__group_id__turns__turn_id__partners__partner_id__retry_post",+ "operationId": "reject_partner_invocation_api_partner_groups__group_id__invocations__invocation_id__reject_post","parameters": [{"in": "path",@@ -35538,19 +35587,10 @@},{"in": "path",- "name": "turn_id",- "required": true,- "schema": {- "title": "Turn Id",- "type": "string"- }- },- {- "in": "path",- "name": "partner_id",+ "name": "invocation_id","required": true,"schema": {- "title": "Partner Id",+ "title": "Invocation Id","type": "string"}},@@ -35591,7 +35631,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/PartnerSeatRetryRequest"+ "$ref": "#/components/schemas/PartnerInvocationActionRequest"}}},@@ -35617,15 +35657,15 @@"description": "Validation Error"}},- "summary": "Retry Partner Group Seat",+ "summary": "Reject Partner Invocation","tags": ["partner-groups"]}},- "/api/partner-groups/{group_id}/whiteboard": {- "get": {- "operationId": "partner_group_whiteboard_api_partner_groups__group_id__whiteboard_get",+ "/api/partner-groups/{group_id}/messages": {+ "post": {+ "operationId": "send_partner_group_message_api_partner_groups__group_id__messages_post","parameters": [{"in": "path",@@ -35636,18 +35676,6 @@"type": "string"}},- {- "in": "query",- "name": "limit",- "required": false,- "schema": {- "default": 200,- "maximum": 500,- "minimum": 1,- "title": "Limit",- "type": "integer"- }- },{"in": "header","name": "Authorization",@@ -35681,6 +35709,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/PartnerGroupMessageRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -35701,15 +35739,15 @@"description": "Validation Error"}},- "summary": "Partner Group Whiteboard",+ "summary": "Send Partner Group Message","tags": ["partner-groups"]}},- "/api/partner-groups/{group_id}/whiteboard/pins": {+ "/api/partner-groups/{group_id}/rounds/{turn_id}/summary": {"post": {- "operationId": "pin_partner_group_whiteboard_api_partner_groups__group_id__whiteboard_pins_post",+ "operationId": "summarize_partner_group_round_api_partner_groups__group_id__rounds__turn_id__summary_post","parameters": [{"in": "path",@@ -35720,6 +35758,15 @@"type": "string"}},+ {+ "in": "path",+ "name": "turn_id",+ "required": true,+ "schema": {+ "title": "Turn Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -35757,7 +35804,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/WhiteboardPinRequest"+ "$ref": "#/components/schemas/RoundSummaryRequest"}}},@@ -35783,15 +35830,15 @@"description": "Validation Error"}},- "summary": "Pin Partner Group Whiteboard",+ "summary": "Summarize Partner Group Round","tags": ["partner-groups"]}},- "/api/partner-groups/{group_id}/whiteboard/pins/{event_id}": {- "delete": {- "operationId": "unpin_partner_group_whiteboard_api_partner_groups__group_id__whiteboard_pins__event_id__delete",+ "/api/partner-groups/{group_id}/sessions": {+ "get": {+ "operationId": "list_partner_group_sessions_api_partner_groups__group_id__sessions_get","parameters": [{"in": "path",@@ -35802,15 +35849,6 @@"type": "string"}},- {- "in": "path",- "name": "event_id",- "required": true,- "schema": {- "title": "Event Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -35864,17 +35902,23 @@"description": "Validation Error"}},- "summary": "Unpin Partner Group Whiteboard",+ "summary": "List Partner Group Sessions","tags": ["partner-groups"]- }- },- "/api/partners": {- "get": {- "description": "Partners the caller may talk to — theirs in full, assigned ones as cards.",- "operationId": "list_partners_api_partners_get",+ },+ "post": {+ "operationId": "create_partner_group_session_api_partner_groups__group_id__sessions_post","parameters": [+ {+ "in": "path",+ "name": "group_id",+ "required": true,+ "schema": {+ "title": "Group Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -35909,7 +35953,7 @@}],"responses": {- "200": {+ "201": {"content": {"application/json": {"schema": {}@@ -35928,15 +35972,34 @@"description": "Validation Error"}},- "summary": "List Partners",+ "summary": "Create Partner Group Session","tags": [- "partners"+ "partner-groups"]- },- "post": {- "description": "Create a partner owned by the caller.\n\nAnyone may build their own companion; the assets it is provisioned with are\nresolved against the creator's own permissions (see ``provision_assets``),\nso this hands nobody access they did not already have.",- "operationId": "create_partner_api_partners_post",+ }+ },+ "/api/partner-groups/{group_id}/sessions/{session_key}": {+ "delete": {+ "operationId": "delete_partner_group_session_api_partner_groups__group_id__sessions__session_key__delete","parameters": [+ {+ "in": "path",+ "name": "group_id",+ "required": true,+ "schema": {+ "title": "Group Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "session_key",+ "required": true,+ "schema": {+ "title": "Session Key",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -35970,16 +36033,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/CreatePartnerRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -36000,17 +36053,43 @@"description": "Validation Error"}},- "summary": "Create Partner",+ "summary": "Delete Partner Group Session","tags": [- "partners"+ "partner-groups"]}},- "/api/partners/channels/schema": {- "get": {- "description": "JSON-Schema metadata for every available channel (schema-driven UI).",- "operationId": "list_channel_schemas_api_partners_channels_schema_get",+ "/api/partner-groups/{group_id}/turns/{turn_id}/partners/{partner_id}/retry": {+ "post": {+ "operationId": "retry_partner_group_seat_api_partner_groups__group_id__turns__turn_id__partners__partner_id__retry_post","parameters": [+ {+ "in": "path",+ "name": "group_id",+ "required": true,+ "schema": {+ "title": "Group Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "turn_id",+ "required": true,+ "schema": {+ "title": "Turn Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "partner_id",+ "required": true,+ "schema": {+ "title": "Partner Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -36044,6 +36123,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/PartnerSeatRetryRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -36064,16 +36153,37 @@"description": "Validation Error"}},- "summary": "List Channel Schemas",+ "summary": "Retry Partner Group Seat","tags": [- "partners"+ "partner-groups"]}},- "/api/partners/commands/palette": {+ "/api/partner-groups/{group_id}/whiteboard": {"get": {- "operationId": "partner_command_palette_api_partners_commands_palette_get",+ "operationId": "partner_group_whiteboard_api_partner_groups__group_id__whiteboard_get","parameters": [+ {+ "in": "path",+ "name": "group_id",+ "required": true,+ "schema": {+ "title": "Group Id",+ "type": "string"+ }+ },+ {+ "in": "query",+ "name": "limit",+ "required": false,+ "schema": {+ "default": 200,+ "maximum": 500,+ "minimum": 1,+ "title": "Limit",+ "type": "integer"+ }+ },{"in": "header","name": "Authorization",@@ -36127,32 +36237,22 @@"description": "Validation Error"}},- "summary": "Partner Command Palette",+ "summary": "Partner Group Whiteboard","tags": [- "partners"+ "partner-groups"]}},- "/api/partners/consultation-session": {- "get": {- "description": "Recover native identity for older consultation traces in this user's registry.",- "operationId": "get_partner_consultation_session_api_partners_consultation_session_get",+ "/api/partner-groups/{group_id}/whiteboard/pins": {+ "post": {+ "operationId": "pin_partner_group_whiteboard_api_partner_groups__group_id__whiteboard_pins_post","parameters": [{- "in": "query",- "name": "chat_session_id",- "required": true,- "schema": {- "title": "Chat Session Id",- "type": "string"- }- },- {- "in": "query",- "name": "partner_name",+ "in": "path",+ "name": "group_id","required": true,"schema": {- "title": "Partner Name",+ "title": "Group Id","type": "string"}},@@ -36189,6 +36289,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/WhiteboardPinRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -36209,23 +36319,31 @@"description": "Validation Error"}},- "summary": "Get Partner Consultation Session",+ "summary": "Pin Partner Group Whiteboard","tags": [- "partners"+ "partner-groups"]}},- "/api/partners/drafts/{draft_id}": {- "get": {- "description": "Reload one pending/created draft for the authenticated user.",- "operationId": "get_partner_draft_api_partners_drafts__draft_id__get",+ "/api/partner-groups/{group_id}/whiteboard/pins/{event_id}": {+ "delete": {+ "operationId": "unpin_partner_group_whiteboard_api_partner_groups__group_id__whiteboard_pins__event_id__delete","parameters": [{"in": "path",- "name": "draft_id",+ "name": "group_id","required": true,"schema": {- "title": "Draft Id",+ "title": "Group Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "event_id",+ "required": true,+ "schema": {+ "title": "Event Id","type": "string"}},@@ -36282,26 +36400,79 @@"description": "Validation Error"}},- "summary": "Get Partner Draft",+ "summary": "Unpin Partner Group Whiteboard","tags": [- "partners"+ "partner-groups"]}},- "/api/partners/drafts/{draft_id}/confirm": {- "post": {- "description": "Promote a reviewable Chat draft into a real Partner exactly once.",- "operationId": "confirm_partner_draft_api_partners_drafts__draft_id__confirm_post",+ "/api/partners": {+ "get": {+ "description": "Partners the caller may talk to — theirs in full, assigned ones as cards.",+ "operationId": "list_partners_api_partners_get","parameters": [{- "in": "path",- "name": "draft_id",- "required": true,+ "in": "header",+ "name": "Authorization",+ "required": false,"schema": {- "title": "Draft Id",- "type": "string"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"}+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"},+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "List Partners",+ "tags": [+ "partners"+ ]+ },+ "post": {+ "description": "Create a partner owned by the caller.\n\nAnyone may build their own companion; the assets it is provisioned with are\nresolved against the creator's own permissions (see ``provision_assets``),\nso this hands nobody access they did not already have.",+ "operationId": "create_partner_api_partners_post",+ "parameters": [{"in": "header","name": "Authorization",@@ -36339,7 +36510,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/ConfirmPartnerDraftRequest"+ "$ref": "#/components/schemas/CreatePartnerRequest"}}},@@ -36365,26 +36536,17 @@"description": "Validation Error"}},- "summary": "Confirm Partner Draft",+ "summary": "Create Partner","tags": ["partners"]}},- "/api/partners/recent": {+ "/api/partners/channels/schema": {"get": {- "operationId": "recent_partners_api_partners_recent_get",+ "description": "JSON-Schema metadata for every available channel (schema-driven UI).",+ "operationId": "list_channel_schemas_api_partners_channels_schema_get","parameters": [- {- "in": "query",- "name": "limit",- "required": false,- "schema": {- "default": 3,- "title": "Limit",- "type": "integer"- }- },{"in": "header","name": "Authorization",@@ -36438,16 +36600,15 @@"description": "Validation Error"}},- "summary": "Recent Partners",+ "summary": "List Channel Schemas","tags": ["partners"]}},- "/api/partners/soul-sources": {+ "/api/partners/commands/palette": {"get": {- "description": "Everything the create-wizard's soul step can start from.",- "operationId": "soul_sources_api_partners_soul_sources_get",+ "operationId": "partner_command_palette_api_partners_commands_palette_get","parameters": [{"in": "header",@@ -36502,16 +36663,35 @@"description": "Validation Error"}},- "summary": "Soul Sources",+ "summary": "Partner Command Palette","tags": ["partners"]}},- "/api/partners/souls": {+ "/api/partners/consultation-session": {"get": {- "operationId": "list_souls_api_partners_souls_get",+ "description": "Recover native identity for older consultation traces in this user's registry.",+ "operationId": "get_partner_consultation_session_api_partners_consultation_session_get","parameters": [+ {+ "in": "query",+ "name": "chat_session_id",+ "required": true,+ "schema": {+ "title": "Chat Session Id",+ "type": "string"+ }+ },+ {+ "in": "query",+ "name": "partner_name",+ "required": true,+ "schema": {+ "title": "Partner Name",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -36565,14 +36745,26 @@"description": "Validation Error"}},- "summary": "List Souls",+ "summary": "Get Partner Consultation Session","tags": ["partners"]- },- "post": {- "operationId": "create_soul_api_partners_souls_post",+ }+ },+ "/api/partners/drafts/{draft_id}": {+ "get": {+ "description": "Reload one pending/created draft for the authenticated user.",+ "operationId": "get_partner_draft_api_partners_drafts__draft_id__get","parameters": [+ {+ "in": "path",+ "name": "draft_id",+ "required": true,+ "schema": {+ "title": "Draft Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -36606,16 +36798,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/SoulCreateRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -36636,22 +36818,23 @@"description": "Validation Error"}},- "summary": "Create Soul",+ "summary": "Get Partner Draft","tags": ["partners"]}},- "/api/partners/souls/{soul_id}": {- "delete": {- "operationId": "delete_soul_api_partners_souls__soul_id__delete",+ "/api/partners/drafts/{draft_id}/confirm": {+ "post": {+ "description": "Promote a reviewable Chat draft into a real Partner exactly once.",+ "operationId": "confirm_partner_draft_api_partners_drafts__draft_id__confirm_post","parameters": [{"in": "path",- "name": "soul_id",+ "name": "draft_id","required": true,"schema": {- "title": "Soul Id",+ "title": "Draft Id","type": "string"}},@@ -36688,6 +36871,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ConfirmPartnerDraftRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -36708,21 +36901,24 @@"description": "Validation Error"}},- "summary": "Delete Soul",+ "summary": "Confirm Partner Draft","tags": ["partners"]- },+ }+ },+ "/api/partners/recent": {"get": {- "operationId": "get_soul_api_partners_souls__soul_id__get",+ "operationId": "recent_partners_api_partners_recent_get","parameters": [{- "in": "path",- "name": "soul_id",- "required": true,+ "in": "query",+ "name": "limit",+ "required": false,"schema": {- "title": "Soul Id",- "type": "string"+ "default": 3,+ "title": "Limit",+ "type": "integer"}},{@@ -36778,23 +36974,80 @@"description": "Validation Error"}},- "summary": "Get Soul",+ "summary": "Recent Partners","tags": ["partners"]- },- "put": {- "operationId": "update_soul_api_partners_souls__soul_id__put",+ }+ },+ "/api/partners/soul-sources": {+ "get": {+ "description": "Everything the create-wizard's soul step can start from.",+ "operationId": "soul_sources_api_partners_soul_sources_get","parameters": [{- "in": "path",- "name": "soul_id",- "required": true,+ "in": "header",+ "name": "Authorization",+ "required": false,"schema": {- "title": "Soul Id",- "type": "string"+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"}},+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Soul Sources",+ "tags": [+ "partners"+ ]+ }+ },+ "/api/partners/souls": {+ "get": {+ "operationId": "list_souls_api_partners_souls_get",+ "parameters": [{"in": "header","name": "Authorization",@@ -36828,16 +37081,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/SoulTemplateUpdateRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -36858,16 +37101,13 @@"description": "Validation Error"}},- "summary": "Update Soul",+ "summary": "List Souls","tags": ["partners"]- }- },- "/api/partners/tool-options": {- "get": {- "description": "The configurable tool surface for a partner.\n\n``tools`` mirrors the user-toggleable system tools (the same pool the\nchat composer / settings expose); ``builtin_tools`` lists the auto-mounted\nbuilt-in tools (rag / web_fetch / …) the owner can allow or deny;\n``mcp_tools`` lists every configured MCP tool the partner could be allowed\nto load. ``read_memory`` / ``write_memory`` are excluded: partners use the\nmandatory ``partner_read`` / ``partner_memorize`` / ``partner_search`` tools\ninstead, which are always on and not owner-configurable.",- "operationId": "tool_options_api_partners_tool_options_get",+ },+ "post": {+ "operationId": "create_soul_api_partners_souls_post","parameters": [{"in": "header",@@ -36902,6 +37142,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SoulCreateRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -36922,22 +37172,22 @@"description": "Validation Error"}},- "summary": "Tool Options",+ "summary": "Create Soul","tags": ["partners"]}},- "/api/partners/{partner_id}": {+ "/api/partners/souls/{soul_id}": {"delete": {- "operationId": "destroy_partner_api_partners__partner_id__delete",+ "operationId": "delete_soul_api_partners_souls__soul_id__delete","parameters": [{"in": "path",- "name": "partner_id",+ "name": "soul_id","required": true,"schema": {- "title": "Partner Id",+ "title": "Soul Id","type": "string"}},@@ -36994,36 +37244,23 @@"description": "Validation Error"}},- "summary": "Destroy Partner",+ "summary": "Delete Soul","tags": ["partners"]},"get": {- "description": "One partner, projected by what the caller may do with it.\n\nSomeone who merely *uses* the partner gets its identity card — enough to\nrender a conversation header — while its owner gets the configuration.",- "operationId": "get_partner_api_partners__partner_id__get",+ "operationId": "get_soul_api_partners_souls__soul_id__get","parameters": [{"in": "path",- "name": "partner_id",+ "name": "soul_id","required": true,"schema": {- "title": "Partner Id",+ "title": "Soul Id","type": "string"}},- {- "description": "Return raw channel secrets (tokens, passwords). Required by the edit form; default response masks all secret-looking fields.",- "in": "query",- "name": "include_secrets",- "required": false,- "schema": {- "default": false,- "description": "Return raw channel secrets (tokens, passwords). Required by the edit form; default response masks all secret-looking fields.",- "title": "Include Secrets",- "type": "boolean"- }- },{"in": "header","name": "Authorization",@@ -37077,20 +37314,20 @@"description": "Validation Error"}},- "summary": "Get Partner",+ "summary": "Get Soul","tags": ["partners"]},- "patch": {- "operationId": "update_partner_api_partners__partner_id__patch",+ "put": {+ "operationId": "update_soul_api_partners_souls__soul_id__put","parameters": [{"in": "path",- "name": "partner_id",+ "name": "soul_id","required": true,"schema": {- "title": "Partner Id",+ "title": "Soul Id","type": "string"}},@@ -37131,7 +37368,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/UpdatePartnerRequest"+ "$ref": "#/components/schemas/SoulTemplateUpdateRequest"}}},@@ -37157,25 +37394,17 @@"description": "Validation Error"}},- "summary": "Update Partner",+ "summary": "Update Soul","tags": ["partners"]}},- "/api/partners/{partner_id}/assets": {+ "/api/partners/tool-options": {"get": {- "operationId": "get_partner_assets_api_partners__partner_id__assets_get",+ "description": "The configurable tool surface for a partner.\n\n``tools`` mirrors the user-toggleable system tools (the same pool the\nchat composer / settings expose); ``builtin_tools`` lists the auto-mounted\nbuilt-in tools (rag / web_fetch / …) the owner can allow or deny;\n``mcp_tools`` lists every configured MCP tool the partner could be allowed\nto load. ``read_memory`` / ``write_memory`` are excluded: partners use the\nmandatory ``partner_read`` / ``partner_memorize`` / ``partner_search`` tools\ninstead, which are always on and not owner-configurable.",+ "operationId": "tool_options_api_partners_tool_options_get","parameters": [- {- "in": "path",- "name": "partner_id",- "required": true,- "schema": {- "title": "Partner Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -37229,13 +37458,15 @@"description": "Validation Error"}},- "summary": "Get Partner Assets",+ "summary": "Tool Options","tags": ["partners"]- },- "post": {- "operationId": "add_partner_assets_api_partners__partner_id__assets_post",+ }+ },+ "/api/partners/{partner_id}": {+ "delete": {+ "operationId": "destroy_partner_api_partners__partner_id__delete","parameters": [{"in": "path",@@ -37279,16 +37510,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/AssetAddRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -37309,15 +37530,14 @@"description": "Validation Error"}},- "summary": "Add Partner Assets",+ "summary": "Destroy Partner","tags": ["partners"]- }- },- "/api/partners/{partner_id}/assets/{asset_type}/{name}": {- "delete": {- "operationId": "delete_partner_asset_api_partners__partner_id__assets__asset_type___name__delete",+ },+ "get": {+ "description": "One partner, projected by what the caller may do with it.\n\nSomeone who merely *uses* the partner gets its identity card — enough to\nrender a conversation header — while its owner gets the configuration.",+ "operationId": "get_partner_api_partners__partner_id__get","parameters": [{"in": "path",@@ -37329,21 +37549,15 @@}},{- "in": "path",- "name": "asset_type",- "required": true,- "schema": {- "title": "Asset Type",- "type": "string"- }- },- {- "in": "path",- "name": "name",- "required": true,+ "description": "Return raw channel secrets (tokens, passwords). Required by the edit form; default response masks all secret-looking fields.",+ "in": "query",+ "name": "include_secrets",+ "required": false,"schema": {- "title": "Name",- "type": "string"+ "default": false,+ "description": "Return raw channel secrets (tokens, passwords). Required by the edit form; default response masks all secret-looking fields.",+ "title": "Include Secrets",+ "type": "boolean"}},{@@ -37399,15 +37613,13 @@"description": "Validation Error"}},- "summary": "Delete Partner Asset",+ "summary": "Get Partner","tags": ["partners"]- }- },- "/api/partners/{partner_id}/channel-onboarding/start": {- "post": {- "operationId": "start_partner_channel_onboarding_api_partners__partner_id__channel_onboarding_start_post",+ },+ "patch": {+ "operationId": "update_partner_api_partners__partner_id__patch","parameters": [{"in": "path",@@ -37455,7 +37667,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/ChannelOnboardingStartRequest"+ "$ref": "#/components/schemas/UpdatePartnerRequest"}}},@@ -37481,15 +37693,15 @@"description": "Validation Error"}},- "summary": "Start Partner Channel Onboarding",+ "summary": "Update Partner","tags": ["partners"]}},- "/api/partners/{partner_id}/channel-onboarding/{session_id}": {- "delete": {- "operationId": "cancel_partner_channel_onboarding_api_partners__partner_id__channel_onboarding__session_id__delete",+ "/api/partners/{partner_id}/assets": {+ "get": {+ "operationId": "get_partner_assets_api_partners__partner_id__assets_get","parameters": [{"in": "path",@@ -37500,15 +37712,6 @@"type": "string"}},- {- "in": "path",- "name": "session_id",- "required": true,- "schema": {- "title": "Session Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -37562,13 +37765,13 @@"description": "Validation Error"}},- "summary": "Cancel Partner Channel Onboarding",+ "summary": "Get Partner Assets","tags": ["partners"]},- "get": {- "operationId": "get_partner_channel_onboarding_api_partners__partner_id__channel_onboarding__session_id__get",+ "post": {+ "operationId": "add_partner_assets_api_partners__partner_id__assets_post","parameters": [{"in": "path",@@ -37579,15 +37782,6 @@"type": "string"}},- {- "in": "path",- "name": "session_id",- "required": true,- "schema": {- "title": "Session Id",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -37621,6 +37815,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AssetAddRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -37641,15 +37845,15 @@"description": "Validation Error"}},- "summary": "Get Partner Channel Onboarding",+ "summary": "Add Partner Assets","tags": ["partners"]}},- "/api/partners/{partner_id}/channel-onboarding/{session_id}/apply": {- "post": {- "operationId": "apply_partner_channel_onboarding_api_partners__partner_id__channel_onboarding__session_id__apply_post",+ "/api/partners/{partner_id}/assets/{asset_type}/{name}": {+ "delete": {+ "operationId": "delete_partner_asset_api_partners__partner_id__assets__asset_type___name__delete","parameters": [{"in": "path",@@ -37662,10 +37866,19 @@},{"in": "path",- "name": "session_id",+ "name": "asset_type","required": true,"schema": {- "title": "Session Id",+ "title": "Asset Type",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "name",+ "required": true,+ "schema": {+ "title": "Name","type": "string"}},@@ -37722,15 +37935,15 @@"description": "Validation Error"}},- "summary": "Apply Partner Channel Onboarding",+ "summary": "Delete Partner Asset","tags": ["partners"]}},- "/api/partners/{partner_id}/channels/reload": {+ "/api/partners/{partner_id}/channel-onboarding/start": {"post": {- "operationId": "reload_partner_channels_api_partners__partner_id__channels_reload_post",+ "operationId": "start_partner_channel_onboarding_api_partners__partner_id__channel_onboarding_start_post","parameters": [{"in": "path",@@ -37774,6 +37987,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ChannelOnboardingStartRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -37794,16 +38017,15 @@"description": "Validation Error"}},- "summary": "Reload Partner Channels",+ "summary": "Start Partner Channel Onboarding","tags": ["partners"]}},- "/api/partners/{partner_id}/channels/status": {- "get": {- "description": "User-facing listener/setup state, including QR output when available.",- "operationId": "get_partner_channel_status_api_partners__partner_id__channels_status_get",+ "/api/partners/{partner_id}/channel-onboarding/{session_id}": {+ "delete": {+ "operationId": "cancel_partner_channel_onboarding_api_partners__partner_id__channel_onboarding__session_id__delete","parameters": [{"in": "path",@@ -37814,6 +38036,15 @@"type": "string"}},+ {+ "in": "path",+ "name": "session_id",+ "required": true,+ "schema": {+ "title": "Session Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -37867,16 +38098,13 @@"description": "Validation Error"}},- "summary": "Get Partner Channel Status",+ "summary": "Cancel Partner Channel Onboarding","tags": ["partners"]- }- },- "/api/partners/{partner_id}/channels/weixin/qr": {- "post": {- "description": "Issue a QR code for this partner and return what to render.",- "operationId": "start_weixin_qr_api_partners__partner_id__channels_weixin_qr_post",+ },+ "get": {+ "operationId": "get_partner_channel_onboarding_api_partners__partner_id__channel_onboarding__session_id__get","parameters": [{"in": "path",@@ -37887,6 +38115,15 @@"type": "string"}},+ {+ "in": "path",+ "name": "session_id",+ "required": true,+ "schema": {+ "title": "Session Id",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -37940,16 +38177,15 @@"description": "Validation Error"}},- "summary": "Start Weixin Qr",+ "summary": "Get Partner Channel Onboarding","tags": ["partners"]}},- "/api/partners/{partner_id}/channels/weixin/qr/{session_id}": {- "get": {- "description": "Advance the scan and report its state (never the token).",- "operationId": "poll_weixin_qr_api_partners__partner_id__channels_weixin_qr__session_id__get",+ "/api/partners/{partner_id}/channel-onboarding/{session_id}/apply": {+ "post": {+ "operationId": "apply_partner_channel_onboarding_api_partners__partner_id__channel_onboarding__session_id__apply_post","parameters": [{"in": "path",@@ -38022,16 +38258,15 @@"description": "Validation Error"}},- "summary": "Poll Weixin Qr",+ "summary": "Apply Partner Channel Onboarding","tags": ["partners"]}},- "/api/partners/{partner_id}/chat": {+ "/api/partners/{partner_id}/channels/reload": {"post": {- "description": "Send one HTTP message to a partner with persistent session context.",- "operationId": "partner_chat_http_api_partners__partner_id__chat_post",+ "operationId": "reload_partner_channels_api_partners__partner_id__channels_reload_post","parameters": [{"in": "path",@@ -38075,25 +38310,11 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/ChatMessageRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {"application/json": {- "schema": {- "additionalProperties": true,- "title": "Response Partner Chat Http Api Partners Partner Id Chat Post",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -38109,16 +38330,16 @@"description": "Validation Error"}},- "summary": "Partner Chat Http",+ "summary": "Reload Partner Channels","tags": ["partners"]}},- "/api/partners/{partner_id}/chat/execute-stream": {- "post": {- "description": "Stream one HTTP message to a partner as server-sent events.",- "operationId": "partner_chat_http_stream_api_partners__partner_id__chat_execute_stream_post",+ "/api/partners/{partner_id}/channels/status": {+ "get": {+ "description": "User-facing listener/setup state, including QR output when available.",+ "operationId": "get_partner_channel_status_api_partners__partner_id__channels_status_get","parameters": [{"in": "path",@@ -38162,16 +38383,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/ChatMessageRequest"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -38192,16 +38403,16 @@"description": "Validation Error"}},- "summary": "Partner Chat Http Stream",+ "summary": "Get Partner Channel Status","tags": ["partners"]}},- "/api/partners/{partner_id}/history": {- "get": {- "description": "Conversation history. Pass ``session_key`` for an exact key, or\n``session_id`` for a web session (mapped through ``web_session_key``);\nwith neither, all non-archived sessions are merged.",- "operationId": "get_partner_history_api_partners__partner_id__history_get",+ "/api/partners/{partner_id}/channels/weixin/qr": {+ "post": {+ "description": "Issue a QR code for this partner and return what to render.",+ "operationId": "start_weixin_qr_api_partners__partner_id__channels_weixin_qr_post","parameters": [{"in": "path",@@ -38213,8 +38424,8 @@}},{- "in": "query",- "name": "session_key",+ "in": "header",+ "name": "Authorization","required": false,"schema": {"anyOf": [@@ -38225,12 +38436,12 @@"type": "null"}],- "title": "Session Key"+ "title": "Authorization"}},{- "in": "query",- "name": "session_id",+ "in": "cookie",+ "name": "dt_token","required": false,"schema": {"anyOf": [@@ -38241,17 +38452,57 @@"type": "null"}],- "title": "Session Id"+ "title": "Dt Token"}+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"},+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Start Weixin Qr",+ "tags": [+ "partners"+ ]+ }+ },+ "/api/partners/{partner_id}/channels/weixin/qr/{session_id}": {+ "get": {+ "description": "Advance the scan and report its state (never the token).",+ "operationId": "poll_weixin_qr_api_partners__partner_id__channels_weixin_qr__session_id__get",+ "parameters": [{- "in": "query",- "name": "limit",- "required": false,+ "in": "path",+ "name": "partner_id",+ "required": true,"schema": {- "default": 100,- "title": "Limit",- "type": "integer"+ "title": "Partner Id",+ "type": "string"+ }+ },+ {+ "in": "path",+ "name": "session_id",+ "required": true,+ "schema": {+ "title": "Session Id",+ "type": "string"}},{@@ -38307,16 +38558,16 @@"description": "Validation Error"}},- "summary": "Get Partner History",+ "summary": "Poll Weixin Qr","tags": ["partners"]}},- "/api/partners/{partner_id}/history/page": {- "get": {- "description": "Read older turns of one actor-scoped conversation in bounded pages.",- "operationId": "get_partner_history_page_api_partners__partner_id__history_page_get",+ "/api/partners/{partner_id}/chat": {+ "post": {+ "description": "Send one HTTP message to a partner with persistent session context.",+ "operationId": "partner_chat_http_api_partners__partner_id__chat_post","parameters": [{"in": "path",@@ -38327,44 +38578,6 @@"type": "string"}},- {- "in": "query",- "name": "session_key",- "required": true,- "schema": {- "title": "Session Key",- "type": "string"- }- },- {- "in": "query",- "name": "before",- "required": false,- "schema": {- "anyOf": [- {- "minimum": 0,- "type": "integer"- },- {- "type": "null"- }- ],- "title": "Before"- }- },- {- "in": "query",- "name": "limit",- "required": false,- "schema": {- "default": 60,- "maximum": 200,- "minimum": 1,- "title": "Limit",- "type": "integer"- }- },{"in": "header","name": "Authorization",@@ -38398,11 +38611,25 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ChatMessageRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {"application/json": {- "schema": {}+ "schema": {+ "additionalProperties": true,+ "title": "Response Partner Chat Http Api Partners Partner Id Chat Post",+ "type": "object"+ }}},"description": "Successful Response"@@ -38418,16 +38645,16 @@"description": "Validation Error"}},- "summary": "Get Partner History Page",+ "summary": "Partner Chat Http","tags": ["partners"]}},- "/api/partners/{partner_id}/links": {- "get": {- "description": "Your own linked chat accounts for this partner — never anyone else's.",- "operationId": "list_partner_links_api_partners__partner_id__links_get",+ "/api/partners/{partner_id}/chat/execute-stream": {+ "post": {+ "description": "Stream one HTTP message to a partner as server-sent events.",+ "operationId": "partner_chat_http_stream_api_partners__partner_id__chat_execute_stream_post","parameters": [{"in": "path",@@ -38471,6 +38698,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ChatMessageRequest"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -38491,16 +38728,16 @@"description": "Validation Error"}},- "summary": "List Partner Links",+ "summary": "Partner Chat Http Stream","tags": ["partners"]}},- "/api/partners/{partner_id}/links/code": {- "post": {- "description": "Mint a code for connecting one of your chat accounts to this partner.\n\nSend ``/link <code>`` to the partner as a direct message from the chat\naccount you want connected; that account then speaks as you.",- "operationId": "create_partner_link_code_api_partners__partner_id__links_code_post",+ "/api/partners/{partner_id}/history": {+ "get": {+ "description": "Conversation history. Pass ``session_key`` for an exact key, or\n``session_id`` for a web session (mapped through ``web_session_key``);\nwith neither, all non-archived sessions are merged.",+ "operationId": "get_partner_history_api_partners__partner_id__history_get","parameters": [{"in": "path",@@ -38511,6 +38748,48 @@"type": "string"}},+ {+ "in": "query",+ "name": "session_key",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Session Key"+ }+ },+ {+ "in": "query",+ "name": "session_id",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Session Id"+ }+ },+ {+ "in": "query",+ "name": "limit",+ "required": false,+ "schema": {+ "default": 100,+ "title": "Limit",+ "type": "integer"+ }+ },{"in": "header","name": "Authorization",@@ -38564,16 +38843,16 @@"description": "Validation Error"}},- "summary": "Create Partner Link Code",+ "summary": "Get Partner History","tags": ["partners"]}},- "/api/partners/{partner_id}/links/{key}": {- "delete": {- "description": "Disconnect one of your chat accounts; its past messages stay yours.",- "operationId": "delete_partner_link_api_partners__partner_id__links__key__delete",+ "/api/partners/{partner_id}/history/page": {+ "get": {+ "description": "Read older turns of one actor-scoped conversation in bounded pages.",+ "operationId": "get_partner_history_page_api_partners__partner_id__history_page_get","parameters": [{"in": "path",@@ -38585,14 +38864,43 @@}},{- "in": "path",- "name": "key",+ "in": "query",+ "name": "session_key","required": true,"schema": {- "title": "Key",+ "title": "Session Key","type": "string"}},+ {+ "in": "query",+ "name": "before",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "minimum": 0,+ "type": "integer"+ },+ {+ "type": "null"+ }+ ],+ "title": "Before"+ }+ },+ {+ "in": "query",+ "name": "limit",+ "required": false,+ "schema": {+ "default": 60,+ "maximum": 200,+ "minimum": 1,+ "title": "Limit",+ "type": "integer"+ }+ },{"in": "header","name": "Authorization",@@ -38646,15 +38954,16 @@"description": "Validation Error"}},- "summary": "Delete Partner Link",+ "summary": "Get Partner History Page","tags": ["partners"]}},- "/api/partners/{partner_id}/sessions": {+ "/api/partners/{partner_id}/links": {"get": {- "operationId": "get_partner_sessions_api_partners__partner_id__sessions_get",+ "description": "Your own linked chat accounts for this partner — never anyone else's.",+ "operationId": "list_partner_links_api_partners__partner_id__links_get","parameters": [{"in": "path",@@ -38718,16 +39027,16 @@"description": "Validation Error"}},- "summary": "Get Partner Sessions",+ "summary": "List Partner Links","tags": ["partners"]}},- "/api/partners/{partner_id}/sessions/archive": {+ "/api/partners/{partner_id}/links/code": {"post": {- "description": "Soft-archive a session (web /new) — it stays resumable, file untouched.",- "operationId": "archive_partner_session_api_partners__partner_id__sessions_archive_post",+ "description": "Mint a code for connecting one of your chat accounts to this partner.\n\nSend ``/link <code>`` to the partner as a direct message from the chat\naccount you want connected; that account then speaks as you.",+ "operationId": "create_partner_link_code_api_partners__partner_id__links_code_post","parameters": [{"in": "path",@@ -38771,16 +39080,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/SessionKeyBody"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -38801,16 +39100,16 @@"description": "Validation Error"}},- "summary": "Archive Partner Session",+ "summary": "Create Partner Link Code","tags": ["partners"]}},- "/api/partners/{partner_id}/sessions/branch": {- "post": {- "description": "Copy a session's full history into a new key and archive the source.",- "operationId": "branch_partner_session_api_partners__partner_id__sessions_branch_post",+ "/api/partners/{partner_id}/links/{key}": {+ "delete": {+ "description": "Disconnect one of your chat accounts; its past messages stay yours.",+ "operationId": "delete_partner_link_api_partners__partner_id__links__key__delete","parameters": [{"in": "path",@@ -38821,6 +39120,15 @@"type": "string"}},+ {+ "in": "path",+ "name": "key",+ "required": true,+ "schema": {+ "title": "Key",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -38854,16 +39162,78 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/SessionBranchBody"+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}}- }+ },+ "description": "Successful Response"},- "required": true+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }},+ "summary": "Delete Partner Link",+ "tags": [+ "partners"+ ]+ }+ },+ "/api/partners/{partner_id}/sessions": {+ "get": {+ "operationId": "get_partner_sessions_api_partners__partner_id__sessions_get",+ "parameters": [+ {+ "in": "path",+ "name": "partner_id",+ "required": true,+ "schema": {+ "title": "Partner Id",+ "type": "string"+ }+ },+ {+ "in": "header",+ "name": "Authorization",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],"responses": {"200": {"content": {@@ -38884,15 +39254,16 @@"description": "Validation Error"}},- "summary": "Branch Partner Session",+ "summary": "Get Partner Sessions","tags": ["partners"]}},- "/api/partners/{partner_id}/sessions/delete": {+ "/api/partners/{partner_id}/sessions/archive": {"post": {- "operationId": "delete_partner_session_api_partners__partner_id__sessions_delete_post",+ "description": "Soft-archive a session (web /new) — it stays resumable, file untouched.",+ "operationId": "archive_partner_session_api_partners__partner_id__sessions_archive_post","parameters": [{"in": "path",@@ -38966,16 +39337,16 @@"description": "Validation Error"}},- "summary": "Delete Partner Session",+ "summary": "Archive Partner Session","tags": ["partners"]}},- "/api/partners/{partner_id}/sessions/resume": {+ "/api/partners/{partner_id}/sessions/branch": {"post": {- "description": "Clear a session's archived flag so the web app can continue it.",- "operationId": "resume_partner_session_api_partners__partner_id__sessions_resume_post",+ "description": "Copy a session's full history into a new key and archive the source.",+ "operationId": "branch_partner_session_api_partners__partner_id__sessions_branch_post","parameters": [{"in": "path",@@ -39023,7 +39394,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/SessionKeyBody"+ "$ref": "#/components/schemas/SessionBranchBody"}}},@@ -39049,15 +39420,15 @@"description": "Validation Error"}},- "summary": "Resume Partner Session",+ "summary": "Branch Partner Session","tags": ["partners"]}},- "/api/partners/{partner_id}/soul": {- "get": {- "operationId": "get_partner_soul_api_partners__partner_id__soul_get",+ "/api/partners/{partner_id}/sessions/delete": {+ "post": {+ "operationId": "delete_partner_session_api_partners__partner_id__sessions_delete_post","parameters": [{"in": "path",@@ -39101,6 +39472,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SessionKeyBody"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -39121,13 +39502,16 @@"description": "Validation Error"}},- "summary": "Get Partner Soul",+ "summary": "Delete Partner Session","tags": ["partners"]- },- "put": {- "operationId": "put_partner_soul_api_partners__partner_id__soul_put",+ }+ },+ "/api/partners/{partner_id}/sessions/resume": {+ "post": {+ "description": "Clear a session's archived flag so the web app can continue it.",+ "operationId": "resume_partner_session_api_partners__partner_id__sessions_resume_post","parameters": [{"in": "path",@@ -39175,7 +39559,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/SoulUpdateBody"+ "$ref": "#/components/schemas/SessionKeyBody"}}},@@ -39201,15 +39585,15 @@"description": "Validation Error"}},- "summary": "Put Partner Soul",+ "summary": "Resume Partner Session","tags": ["partners"]}},- "/api/partners/{partner_id}/start": {- "post": {- "operationId": "start_partner_api_partners__partner_id__start_post",+ "/api/partners/{partner_id}/soul": {+ "get": {+ "operationId": "get_partner_soul_api_partners__partner_id__soul_get","parameters": [{"in": "path",@@ -39273,15 +39657,13 @@"description": "Validation Error"}},- "summary": "Start Partner",+ "summary": "Get Partner Soul","tags": ["partners"]- }- },- "/api/partners/{partner_id}/stop": {- "post": {- "operationId": "stop_partner_api_partners__partner_id__stop_post",+ },+ "put": {+ "operationId": "put_partner_soul_api_partners__partner_id__soul_put","parameters": [{"in": "path",@@ -39325,6 +39707,16 @@}}],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SoulUpdateBody"+ }+ }+ },+ "required": true+ },"responses": {"200": {"content": {@@ -39345,15 +39737,15 @@"description": "Validation Error"}},- "summary": "Stop Partner",+ "summary": "Put Partner Soul","tags": ["partners"]}},- "/api/partners/{partner_id}/web-continuity": {- "get": {- "operationId": "get_partner_web_continuity_api_partners__partner_id__web_continuity_get",+ "/api/partners/{partner_id}/start": {+ "post": {+ "operationId": "start_partner_api_partners__partner_id__start_post","parameters": [{"in": "path",@@ -39417,13 +39809,15 @@"description": "Validation Error"}},- "summary": "Get Partner Web Continuity",+ "summary": "Start Partner","tags": ["partners"]- },- "put": {- "operationId": "put_partner_web_continuity_api_partners__partner_id__web_continuity_put",+ }+ },+ "/api/partners/{partner_id}/stop": {+ "post": {+ "operationId": "stop_partner_api_partners__partner_id__stop_post","parameters": [{"in": "path",@@ -39467,16 +39861,6 @@}}],- "requestBody": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/WebContinuityBody"- }- }- },- "required": true- },"responses": {"200": {"content": {@@ -39497,16 +39881,15 @@"description": "Validation Error"}},- "summary": "Put Partner Web Continuity",+ "summary": "Stop Partner","tags": ["partners"]}},- "/api/partners/{partner_id}/workspaces": {+ "/api/partners/{partner_id}/web-continuity": {"get": {- "description": "Configuration choices belong to the Partner owner, including admin edits.",- "operationId": "get_partner_workspaces_api_partners__partner_id__workspaces_get",+ "operationId": "get_partner_web_continuity_api_partners__partner_id__web_continuity_get","parameters": [{"in": "path",@@ -39570,87 +39953,23 @@"description": "Validation Error"}},- "summary": "Get Partner Workspaces",+ "summary": "Get Partner Web Continuity","tags": ["partners"]- }- },- "/api/personas": {- "get": {- "operationId": "list_personas_api_personas_get",+ },+ "put": {+ "operationId": "put_partner_web_continuity_api_partners__partner_id__web_continuity_put","parameters": [{- "in": "header",- "name": "Authorization",- "required": false,- "schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Authorization"- }- },- {- "in": "cookie",- "name": "dt_token",- "required": false,+ "in": "path",+ "name": "partner_id",+ "required": true,"schema": {- "anyOf": [- {- "type": "string"- },- {- "type": "null"- }- ],- "title": "Dt Token"+ "title": "Partner Id",+ "type": "string"}- }- ],- "responses": {- "200": {- "content": {- "application/json": {- "schema": {- "additionalProperties": {- "items": {- "additionalProperties": true,- "type": "object"- },- "type": "array"- },- "title": "Response List Personas Api Personas Get",- "type": "object"- }- }- },- "description": "Successful Response"},- "422": {- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/HTTPValidationError"- }- }- },- "description": "Validation Error"- }- },- "summary": "List Personas",- "tags": [- "personas"- ]- },- "post": {- "operationId": "create_persona_api_personas_post",- "parameters": [{"in": "header","name": "Authorization",@@ -39688,7 +40007,7 @@"content": {"application/json": {"schema": {- "$ref": "#/components/schemas/CreatePersonaRequest"+ "$ref": "#/components/schemas/WebContinuityBody"}}},@@ -39698,11 +40017,7 @@"200": {"content": {"application/json": {- "schema": {- "additionalProperties": true,- "title": "Response Create Persona Api Personas Post",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -39718,22 +40033,23 @@"description": "Validation Error"}},- "summary": "Create Persona",+ "summary": "Put Partner Web Continuity","tags": [- "personas"+ "partners"]}},- "/api/personas/{name}": {- "delete": {- "operationId": "delete_persona_api_personas__name__delete",+ "/api/partners/{partner_id}/workspaces": {+ "get": {+ "description": "Configuration choices belong to the Partner owner, including admin edits.",+ "operationId": "get_partner_workspaces_api_partners__partner_id__workspaces_get","parameters": [{"in": "path",- "name": "name",+ "name": "partner_id","required": true,"schema": {- "title": "Name",+ "title": "Partner Id","type": "string"}},@@ -39774,13 +40090,7 @@"200": {"content": {"application/json": {- "schema": {- "additionalProperties": {- "type": "string"- },- "title": "Response Delete Persona Api Personas Name Delete",- "type": "object"- }+ "schema": {}}},"description": "Successful Response"@@ -39796,23 +40106,16 @@"description": "Validation Error"}},- "summary": "Delete Persona",+ "summary": "Get Partner Workspaces","tags": [- "personas"+ "partners"]- },+ }+ },+ "/api/personas": {"get": {- "operationId": "get_persona_api_personas__name__get",+ "operationId": "list_personas_api_personas_get","parameters": [- {- "in": "path",- "name": "name",- "required": true,- "schema": {- "title": "Name",- "type": "string"- }- },{"in": "header","name": "Authorization",@@ -39851,8 +40154,14 @@"content": {"application/json": {"schema": {- "additionalProperties": true,- "title": "Response Get Persona Api Personas Name Get",+ "additionalProperties": {+ "items": {+ "additionalProperties": true,+ "type": "object"+ },+ "type": "array"+ },+ "title": "Response List Personas Api Personas Get","type": "object"}}@@ -39870,23 +40179,250 @@"description": "Validation Error"}},- "summary": "Get Persona",+ "summary": "List Personas","tags": ["personas"]},- "put": {- "operationId": "update_persona_api_personas__name__put",+ "post": {+ "operationId": "create_persona_api_personas_post","parameters": [- {- "in": "path",- "name": "name",- "required": true,- "schema": {- "title": "Name",- "type": "string"- }- },+ {+ "in": "header",+ "name": "Authorization",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/CreatePersonaRequest"+ }+ }+ },+ "required": true+ },+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {+ "additionalProperties": true,+ "title": "Response Create Persona Api Personas Post",+ "type": "object"+ }+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Create Persona",+ "tags": [+ "personas"+ ]+ }+ },+ "/api/personas/{name}": {+ "delete": {+ "operationId": "delete_persona_api_personas__name__delete",+ "parameters": [+ {+ "in": "path",+ "name": "name",+ "required": true,+ "schema": {+ "title": "Name",+ "type": "string"+ }+ },+ {+ "in": "header",+ "name": "Authorization",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {+ "additionalProperties": {+ "type": "string"+ },+ "title": "Response Delete Persona Api Personas Name Delete",+ "type": "object"+ }+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Delete Persona",+ "tags": [+ "personas"+ ]+ },+ "get": {+ "operationId": "get_persona_api_personas__name__get",+ "parameters": [+ {+ "in": "path",+ "name": "name",+ "required": true,+ "schema": {+ "title": "Name",+ "type": "string"+ }+ },+ {+ "in": "header",+ "name": "Authorization",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {+ "additionalProperties": true,+ "title": "Response Get Persona Api Personas Name Get",+ "type": "object"+ }+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Get Persona",+ "tags": [+ "personas"+ ]+ },+ "put": {+ "operationId": "update_persona_api_personas__name__put",+ "parameters": [+ {+ "in": "path",+ "name": "name",+ "required": true,+ "schema": {+ "title": "Name",+ "type": "string"+ }+ },{"in": "header","name": "Authorization",@@ -39960,6 +40496,511 @@]}},+ "/api/plugins/catalog": {+ "get": {+ "operationId": "plugin_catalog_api_plugins_catalog_get",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Plugin Catalog",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/extensions": {+ "get": {+ "operationId": "list_extensions_api_plugins_extensions_get",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {+ "additionalProperties": true,+ "title": "Response List Extensions Api Plugins Extensions Get",+ "type": "object"+ }+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "List Extensions",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/state": {+ "get": {+ "operationId": "plugin_state_api_plugins_state_get",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Plugin State",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/approve": {+ "post": {+ "operationId": "approve_plugin_api_plugins__plugin_id__approve_post",+ "parameters": [+ {+ "in": "path",+ "name": "plugin_id",+ "required": true,+ "schema": {+ "title": "Plugin Id",+ "type": "string"+ }+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApprovalRequest"+ }+ }+ },+ "required": true+ },+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Approve Plugin",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/disable": {+ "post": {+ "operationId": "disable_plugin_api_plugins__plugin_id__disable_post",+ "parameters": [+ {+ "in": "path",+ "name": "plugin_id",+ "required": true,+ "schema": {+ "title": "Plugin Id",+ "type": "string"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Disable Plugin",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/enable": {+ "post": {+ "operationId": "enable_plugin_api_plugins__plugin_id__enable_post",+ "parameters": [+ {+ "in": "path",+ "name": "plugin_id",+ "required": true,+ "schema": {+ "title": "Plugin Id",+ "type": "string"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Enable Plugin",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/info": {+ "get": {+ "operationId": "plugin_info_api_plugins__plugin_id__info_get",+ "parameters": [+ {+ "in": "path",+ "name": "plugin_id",+ "required": true,+ "schema": {+ "title": "Plugin Id",+ "type": "string"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Plugin Info",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/install": {+ "post": {+ "operationId": "install_plugin_api_plugins__plugin_id__install_post",+ "parameters": [+ {+ "in": "path",+ "name": "plugin_id",+ "required": true,+ "schema": {+ "title": "Plugin Id",+ "type": "string"+ }+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/InstallRequest"+ }+ }+ },+ "required": true+ },+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Install Plugin",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/installation": {+ "delete": {+ "operationId": "uninstall_plugin_api_plugins__plugin_id__installation_delete",+ "parameters": [+ {+ "in": "path",+ "name": "plugin_id",+ "required": true,+ "schema": {+ "title": "Plugin Id",+ "type": "string"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Uninstall Plugin",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/pages/{extension_id}": {+ "get": {+ "operationId": "redirect_plugin_frontend_page_api_plugins__plugin_id__pages__extension_id__get",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Redirect Plugin Frontend Page",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/pages/{extension_id}/": {+ "get": {+ "operationId": "get_plugin_frontend_page_api_plugins__plugin_id__pages__extension_id___get",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Get Plugin Frontend Page",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/pages/{extension_id}/assets/{asset_path}": {+ "get": {+ "operationId": "get_plugin_frontend_asset_api_plugins__plugin_id__pages__extension_id__assets__asset_path__get",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Get Plugin Frontend Asset",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/rollback": {+ "post": {+ "operationId": "rollback_plugin_api_plugins__plugin_id__rollback_post",+ "parameters": [+ {+ "in": "path",+ "name": "plugin_id",+ "required": true,+ "schema": {+ "title": "Plugin Id",+ "type": "string"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Rollback Plugin",+ "tags": [+ "plugins"+ ]+ }+ },+ "/api/plugins/{plugin_id}/{plugin_path}": {+ "delete": {+ "operationId": "dispatch_plugin_route_delete",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Dispatch Plugin Route",+ "tags": [+ "plugins"+ ]+ },+ "get": {+ "operationId": "dispatch_plugin_route_get",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Dispatch Plugin Route",+ "tags": [+ "plugins"+ ]+ },+ "patch": {+ "operationId": "dispatch_plugin_route_patch",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Dispatch Plugin Route",+ "tags": [+ "plugins"+ ]+ },+ "post": {+ "operationId": "dispatch_plugin_route_post",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Dispatch Plugin Route",+ "tags": [+ "plugins"+ ]+ },+ "put": {+ "operationId": "dispatch_plugin_route_put",+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ }+ },+ "summary": "Dispatch Plugin Route",+ "tags": [+ "plugins"+ ]+ }+ },"/api/question-notebook/categories": {"get": {"description": "Categories, with their counts scoped the same way the listing is.\n\nWithout the scope the rail would offer \"Address translation 3\" inside a\ncourse holding none of those three.",@@ -47640,6 +48681,78 @@]}},+ "/api/sessions/{session_id}/migrate-watching": {+ "post": {+ "operationId": "migrate_watching_session_api_sessions__session_id__migrate_watching_post",+ "parameters": [+ {+ "in": "path",+ "name": "session_id",+ "required": true,+ "schema": {+ "title": "Session Id",+ "type": "string"+ }+ },+ {+ "in": "header",+ "name": "Authorization",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Authorization"+ }+ },+ {+ "in": "cookie",+ "name": "dt_token",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "title": "Dt Token"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {}+ }+ },+ "description": "Successful Response"+ },+ "422": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ },+ "description": "Validation Error"+ }+ },+ "summary": "Migrate Watching Session",+ "tags": [+ "sessions"+ ]+ }+ },"/api/sessions/{session_id}/organization": {"patch": {"operationId": "update_session_organization_api_sessions__session_id__organization_patch",@@ -49786,7 +50899,7 @@},"/api/settings/fetch-models": {"post": {- "description": "List the model IDs an OpenAI-compatible provider exposes.\n\nThin HTTP surface over ``factory.fetch_models`` so the settings UI can\npopulate a model picker from ``base_url`` + ``api_key`` instead of making\nthe user type model IDs by hand.",+ "description": "List selectable model IDs using the provider's own authentication.\n\nThin HTTP surface over ``factory.fetch_models`` so the settings UI can\npopulate a model picker. Copilot uses the caller's owner-private CLI login,\nnot the profile's API key or base URL.","operationId": "fetch_models_from_provider_api_settings_fetch_models_post","parameters": [{