Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

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.py
index 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.py
index 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.py
new file mode 100644
index 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.py
index 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 = obj
else:
instance = obj
factory = 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.py
index 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)
continue
diff --git a/deeptutor/plugins/catalog.json b/deeptutor/plugins/catalog.json
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 None
obj = _resolve_entry(manifest.entry)
return _instantiate_capability(obj)
diff --git a/deeptutor/plugins/manifest.py b/deeptutor/plugins/manifest.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 None
def 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.py
index 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 = produced
else:
instance = produced
- factory = type(produced)
+ factory = obj
else:
instance = obj
factory = type(obj)
@@ -107,7 +107,11 @@ class CapabilityRegistry:
if resolved is None:
return None
instance, _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 None
self.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 None
capability = self.catalog.create("turn", name)
return capability if isinstance(capability, TurnCapability) else None
def 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 = None
diff --git a/deeptutor/runtime/registry/tool_registry.py b/deeptutor/runtime/registry/tool_registry.py
index 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 inspect
import logging
from typing import Any
+from deeptutor.core.entry_points import load_entry_point_group
from deeptutor.core.tool_protocol import BaseTool, ToolDefinition, ToolPromptHints
from 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 = None
def 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_registry
diff --git a/deeptutor_cli/plugin.py b/deeptutor_cli/plugin.py
index 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 annotations
from dataclasses import asdict
+import json
+from pathlib import Path
from rich.console import Console
from 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_registry
from deeptutor.runtime.registry.capability_registry import get_capability_registry
from 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_registry
from deeptutor.runtime.registry.capability_registry import get_capability_registry
from 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 DeepTutorApp
availability = 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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__.py
new file mode 100644
index 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.json
new file mode 100644
index 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.js
new file mode 100644
index 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.html
new file mode 100644
index 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.json
new file mode 100644
index 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.py
new file mode 100644
index 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.toml
new file mode 100644
index 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.toml
index 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.toml
index 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.txt
index 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.0
pydantic-settings>=2.0.0
+packaging>=24.2
jsonschema>=4.20.0,<5.0.0
aiosqlite>=0.19.0
diff --git a/tests/api/test_plugins_router.py b/tests/api/test_plugins_router.py
new file mode 100644
index 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 == 200
diff --git a/tests/plugins/test_catalog.py b/tests/plugins/test_catalog.py
new file mode 100644
index 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 path
diff --git a/tests/plugins/test_cli.py b/tests/plugins/test_cli.py
new file mode 100644
index 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.output
diff --git a/tests/plugins/test_distribution.py b/tests/plugins/test_distribution.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 None
diff --git a/tests/plugins/test_runtime.py b/tests/plugins/test_runtime.py
new file mode 100644
index 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.py
index 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.ts
index 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.json
index 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": [
{