KohakuTerrarium 2.0.0.dev11__tar.gz → 2.0.0.dev13__tar.gz

{kohakuterrarium-2.0.0.dev11/src/KohakuTerrarium.egg-info → kohakuterrarium-2.0.0.dev13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: KohakuTerrarium
-Version: 2.0.0.dev11
+Version: 2.0.0.dev13
 Summary: A universal agent framework for building self-driven AI agents and multi-agent teams
 Author-email: "Shih-Ying Yeh (KohakuBlueLeaf)" <apolloyeh0123@gmail.com>
 License-Expression: LicenseRef-KohakuTerrarium-1.0
@@ -106,8 +106,8 @@ Dynamic: license-file
 ```bash
 pip install kohakuterrarium                                         # install
 kt login codex                                                      # authenticate
-kt install https://github.com/Kohaku-Lab/kt-biome.git            # get OOTB creatures
-kt run @kt-biome/creatures/swe --mode cli                        # run one
+kt install @kt-biome                                                # get OOTB creatures (via marketplace)
+kt run @kt-biome/creatures/swe --mode cli                           # run one
 ```
 
 You get an interactive shell with a full coding agent — file tools, shell access, web search, sub-agents, resumable sessions. `Ctrl+D` exits; `kt resume --last` picks back up.
@@ -192,14 +192,20 @@ npm run build --prefix src/kohakuterrarium-frontend
 ### 2. Install OOTB creatures and plugins
 
 ```bash
-# Official showcase pack
-kt install https://github.com/Kohaku-Lab/kt-biome.git
+# Official showcase pack — via the TerrariumMarket marketplace
+kt install @kt-biome
 
-# Any third-party package
+# Browse what else is available
+kt marketplace search                # all listed packages
+kt marketplace search swe            # substring + tag filter
+
+# Or install any third-party package by URL / local path
 kt install <git-url>
-kt install ./my-creatures -e        # editable install
+kt install ./my-creatures -e         # editable install
 ```
 
+The `@<name>` form resolves through [TerrariumMarket](https://github.com/Kohaku-Lab/TerrariumMarket); direct git URLs still work and bypass it.  See [`docs/en/guides/packages.md`](docs/en/guides/packages.md) for the full marketplace walkthrough (sources, version pinning, env-var overrides).
+
 ### 3. Authenticate a model provider
 
 ```bash

{kohakuterrarium-2.0.0.dev11 → kohakuterrarium-2.0.0.dev13}/README.md

@@ -24,8 +24,8 @@
 ```bash
 pip install kohakuterrarium                                         # install
 kt login codex                                                      # authenticate
-kt install https://github.com/Kohaku-Lab/kt-biome.git            # get OOTB creatures
-kt run @kt-biome/creatures/swe --mode cli                        # run one
+kt install @kt-biome                                                # get OOTB creatures (via marketplace)
+kt run @kt-biome/creatures/swe --mode cli                           # run one
 ```
 
 You get an interactive shell with a full coding agent — file tools, shell access, web search, sub-agents, resumable sessions. `Ctrl+D` exits; `kt resume --last` picks back up.
@@ -110,14 +110,20 @@ npm run build --prefix src/kohakuterrarium-frontend
 ### 2. Install OOTB creatures and plugins
 
 ```bash
-# Official showcase pack
-kt install https://github.com/Kohaku-Lab/kt-biome.git
+# Official showcase pack — via the TerrariumMarket marketplace
+kt install @kt-biome
 
-# Any third-party package
+# Browse what else is available
+kt marketplace search                # all listed packages
+kt marketplace search swe            # substring + tag filter
+
+# Or install any third-party package by URL / local path
 kt install <git-url>
-kt install ./my-creatures -e        # editable install
+kt install ./my-creatures -e         # editable install
 ```
 
+The `@<name>` form resolves through [TerrariumMarket](https://github.com/Kohaku-Lab/TerrariumMarket); direct git URLs still work and bypass it.  See [`docs/en/guides/packages.md`](docs/en/guides/packages.md) for the full marketplace walkthrough (sources, version pinning, env-var overrides).
+
 ### 3. Authenticate a model provider
 
 ```bash

{kohakuterrarium-2.0.0.dev11 → kohakuterrarium-2.0.0.dev13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "KohakuTerrarium"
-version = "2.0.0.dev11"
+version = "2.0.0.dev13"
 description = "A universal agent framework for building self-driven AI agents and multi-agent teams"
 authors = [
     { name = "Shih-Ying Yeh (KohakuBlueLeaf)", email = "apolloyeh0123@gmail.com" },
@@ -291,7 +291,7 @@ select = ["F401", "F841"]
 [tool.briefcase]
 project_name = "KohakuTerrarium"
 bundle = "com.kohaku.terrarium"
-version = "2.0.0.dev11"
+version = "2.0.0.dev13"
 url = "https://github.com/Kohaku-Lab/KohakuTerrarium"
 # License is read from PEP 639 ``[project]`` above; Briefcase
 # 0.3.21+ no longer accepts ``license.file`` here.

{kohakuterrarium-2.0.0.dev11 → kohakuterrarium-2.0.0.dev13/src/KohakuTerrarium.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: KohakuTerrarium
-Version: 2.0.0.dev11
+Version: 2.0.0.dev13
 Summary: A universal agent framework for building self-driven AI agents and multi-agent teams
 Author-email: "Shih-Ying Yeh (KohakuBlueLeaf)" <apolloyeh0123@gmail.com>
 License-Expression: LicenseRef-KohakuTerrarium-1.0
@@ -106,8 +106,8 @@ Dynamic: license-file
 ```bash
 pip install kohakuterrarium                                         # install
 kt login codex                                                      # authenticate
-kt install https://github.com/Kohaku-Lab/kt-biome.git            # get OOTB creatures
-kt run @kt-biome/creatures/swe --mode cli                        # run one
+kt install @kt-biome                                                # get OOTB creatures (via marketplace)
+kt run @kt-biome/creatures/swe --mode cli                           # run one
 ```
 
 You get an interactive shell with a full coding agent — file tools, shell access, web search, sub-agents, resumable sessions. `Ctrl+D` exits; `kt resume --last` picks back up.
@@ -192,14 +192,20 @@ npm run build --prefix src/kohakuterrarium-frontend
 ### 2. Install OOTB creatures and plugins
 
 ```bash
-# Official showcase pack
-kt install https://github.com/Kohaku-Lab/kt-biome.git
+# Official showcase pack — via the TerrariumMarket marketplace
+kt install @kt-biome
 
-# Any third-party package
+# Browse what else is available
+kt marketplace search                # all listed packages
+kt marketplace search swe            # substring + tag filter
+
+# Or install any third-party package by URL / local path
 kt install <git-url>
-kt install ./my-creatures -e        # editable install
+kt install ./my-creatures -e         # editable install
 ```
 
+The `@<name>` form resolves through [TerrariumMarket](https://github.com/Kohaku-Lab/TerrariumMarket); direct git URLs still work and bypass it.  See [`docs/en/guides/packages.md`](docs/en/guides/packages.md) for the full marketplace walkthrough (sources, version pinning, env-var overrides).
+
 ### 3. Authenticate a model provider
 
 ```bash

{kohakuterrarium-2.0.0.dev11 → kohakuterrarium-2.0.0.dev13}/src/KohakuTerrarium.egg-info/SOURCES.txt

@@ -54,6 +54,7 @@ src/kohakuterrarium/api/routes/catalog/creatures.py
 src/kohakuterrarium/api/routes/catalog/creatures_scan.py
 src/kohakuterrarium/api/routes/catalog/extensions.py
 src/kohakuterrarium/api/routes/catalog/manifest.py
+src/kohakuterrarium/api/routes/catalog/marketplace.py
 src/kohakuterrarium/api/routes/catalog/models.py
 src/kohakuterrarium/api/routes/catalog/modules.py
 src/kohakuterrarium/api/routes/catalog/packages.py
@@ -344,6 +345,7 @@ src/kohakuterrarium/cli/identity_llm.py
 src/kohakuterrarium/cli/identity_mcp.py
 src/kohakuterrarium/cli/identity_settings.py
 src/kohakuterrarium/cli/lab_client.py
+src/kohakuterrarium/cli/marketplace.py
 src/kohakuterrarium/cli/memory.py
 src/kohakuterrarium/cli/model.py
 src/kohakuterrarium/cli/packages.py
@@ -535,6 +537,8 @@ src/kohakuterrarium/packages/git_backend.py
 src/kohakuterrarium/packages/install.py
 src/kohakuterrarium/packages/locations.py
 src/kohakuterrarium/packages/manifest.py
+src/kohakuterrarium/packages/marketplace.py
+src/kohakuterrarium/packages/marketplace_types.py
 src/kohakuterrarium/packages/resolve.py
 src/kohakuterrarium/packages/slots.py
 src/kohakuterrarium/packages/walk.py
@@ -665,6 +669,12 @@ src/kohakuterrarium/studio/persistence/fork.py
 src/kohakuterrarium/studio/persistence/history.py
 src/kohakuterrarium/studio/persistence/resume.py
 src/kohakuterrarium/studio/persistence/store.py
+src/kohakuterrarium/studio/persistence/session_index/__init__.py
+src/kohakuterrarium/studio/persistence/session_index/entry.py
+src/kohakuterrarium/studio/persistence/session_index/hooks.py
+src/kohakuterrarium/studio/persistence/session_index/reconcile.py
+src/kohakuterrarium/studio/persistence/session_index/stats.py
+src/kohakuterrarium/studio/persistence/session_index/store.py
 src/kohakuterrarium/studio/persistence/viewer/__init__.py
 src/kohakuterrarium/studio/persistence/viewer/diff.py
 src/kohakuterrarium/studio/persistence/viewer/events.py
@@ -686,6 +696,7 @@ src/kohakuterrarium/studio/sessions/creature_plugins.py
 src/kohakuterrarium/studio/sessions/creature_state.py
 src/kohakuterrarium/studio/sessions/find.py
 src/kohakuterrarium/studio/sessions/handles.py
+src/kohakuterrarium/studio/sessions/index_hooks.py
 src/kohakuterrarium/studio/sessions/lifecycle.py
 src/kohakuterrarium/studio/sessions/memory_build.py
 src/kohakuterrarium/studio/sessions/memory_search.py
@@ -811,12 +822,12 @@ src/kohakuterrarium/web_dist/assets/KaTeX_Size4-Regular-Dl5lxZxV.woff2
 src/kohakuterrarium/web_dist/assets/KaTeX_Typewriter-Regular-C0xS9mPB.woff
 src/kohakuterrarium/web_dist/assets/KaTeX_Typewriter-Regular-CO6r4hn1.woff2
 src/kohakuterrarium/web_dist/assets/KaTeX_Typewriter-Regular-D3Ib7_Hf.ttf
-src/kohakuterrarium/web_dist/assets/_id_-C4sMjQFE.js
-src/kohakuterrarium/web_dist/assets/_key_-CXi3dOT_.js
+src/kohakuterrarium/web_dist/assets/_id_-DE8lvoHr.js
+src/kohakuterrarium/web_dist/assets/_key_-CqzU_wl4.js
 src/kohakuterrarium/web_dist/assets/abap-DNgBPGRI.js
 src/kohakuterrarium/web_dist/assets/apex-B4r7dYl2.js
-src/kohakuterrarium/web_dist/assets/api-Bz2eaDbk.js
-src/kohakuterrarium/web_dist/assets/axios-COLhni8v.js
+src/kohakuterrarium/web_dist/assets/api-sedbTigW.js
+src/kohakuterrarium/web_dist/assets/axios-KN4Hnuwy.js
 src/kohakuterrarium/web_dist/assets/azcli-BKm6S2Cw.js
 src/kohakuterrarium/web_dist/assets/bat-BSxnouuk.js
 src/kohakuterrarium/web_dist/assets/bicep-B_GZ-wpx.js
@@ -835,8 +846,8 @@ src/kohakuterrarium/web_dist/assets/dart-CLzO6BZf.js
 src/kohakuterrarium/web_dist/assets/dockerfile-Bt15Hhqr.js
 src/kohakuterrarium/web_dist/assets/ecl-DLgnzhBc.js
 src/kohakuterrarium/web_dist/assets/editor.main-D4M8mfOA.js
-src/kohakuterrarium/web_dist/assets/element-plus-BmQ7cnZ3.css
-src/kohakuterrarium/web_dist/assets/element-plus-DadrrCeP.js
+src/kohakuterrarium/web_dist/assets/element-plus-Dj1UGbbM.css
+src/kohakuterrarium/web_dist/assets/element-plus-lylrwQnV.js
 src/kohakuterrarium/web_dist/assets/elixir-Dc0k6n94.js
 src/kohakuterrarium/web_dist/assets/flow9-Cmb0SGvr.js
 src/kohakuterrarium/web_dist/assets/freemarker2-Dz8yjL95.js
@@ -850,10 +861,10 @@ src/kohakuterrarium/web_dist/assets/highlight-C8LL_u4z.css
 src/kohakuterrarium/web_dist/assets/html-DVGxM4pJ.js
 src/kohakuterrarium/web_dist/assets/html.worker-wsVgX3gp.js
 src/kohakuterrarium/web_dist/assets/htmlMode-C5KOTPV1.js
-src/kohakuterrarium/web_dist/assets/index-BoUWOr2Q.js
-src/kohakuterrarium/web_dist/assets/index-CuB7PtQi.css
+src/kohakuterrarium/web_dist/assets/index-CLtAvAja.css
+src/kohakuterrarium/web_dist/assets/index-DwzF8aP9.js
 src/kohakuterrarium/web_dist/assets/ini-BeMa714h.js
-src/kohakuterrarium/web_dist/assets/instances-uey62TBM.js
+src/kohakuterrarium/web_dist/assets/instances-Be1CKYRp.js
 src/kohakuterrarium/web_dist/assets/java-Dq86Qznf.js
 src/kohakuterrarium/web_dist/assets/javascript-BOm_W1Jn.js
 src/kohakuterrarium/web_dist/assets/json.worker-CcNiYOcv.js
@@ -873,8 +884,8 @@ src/kohakuterrarium/web_dist/assets/monaco-editor-Br_kD0ds.css
 src/kohakuterrarium/web_dist/assets/msdax-_4dmgZQ-.js
 src/kohakuterrarium/web_dist/assets/mysql-P77yJQsH.js
 src/kohakuterrarium/web_dist/assets/objective-c-ClnQjoXg.js
-src/kohakuterrarium/web_dist/assets/pages-MXpFNTpi.js
-src/kohakuterrarium/web_dist/assets/panel-debug-CR4EE1o5.js
+src/kohakuterrarium/web_dist/assets/pages-Bi_S_ReD.js
+src/kohakuterrarium/web_dist/assets/panel-debug-BhPV0Skl.js
 src/kohakuterrarium/web_dist/assets/pascal-Bc7vQ0ww.js
 src/kohakuterrarium/web_dist/assets/pascaligo-CU0Jj3mr.js
 src/kohakuterrarium/web_dist/assets/perl-DUQq7oYb.js
@@ -915,7 +926,7 @@ src/kohakuterrarium/web_dist/assets/twig-tgVGZ8a3.js
 src/kohakuterrarium/web_dist/assets/typescript-fw_MGe8q.js
 src/kohakuterrarium/web_dist/assets/typespec-C5xfuswf.js
 src/kohakuterrarium/web_dist/assets/vb-BMkNQk3p.js
-src/kohakuterrarium/web_dist/assets/vue-vendor-DroPwbFZ.js
+src/kohakuterrarium/web_dist/assets/vue-vendor-DCj1mY-Y.js
 src/kohakuterrarium/web_dist/assets/wgsl-Borzlq4p.js
 src/kohakuterrarium/web_dist/assets/xml-zEmrWqLn.js
 src/kohakuterrarium/web_dist/assets/yaml-Bnn6I1fK.js

{kohakuterrarium-2.0.0.dev11 → kohakuterrarium-2.0.0.dev13}/src/kohakuterrarium/__init__.py

@@ -16,7 +16,7 @@ from kohakuterrarium.terrarium import (
     Terrarium,
 )
 
-__version__ = "2.0.0.dev2"
+__version__ = "2.0.0.dev13"
 
 __all__ = [
     "ConnectionResult",

{kohakuterrarium-2.0.0.dev11 → kohakuterrarium-2.0.0.dev13}/src/kohakuterrarium/api/app.py

@@ -53,6 +53,7 @@ from kohakuterrarium.api.routes.catalog import creatures as catalog_creatures
 from kohakuterrarium.api.routes.catalog import creatures_scan as catalog_creatures_scan
 from kohakuterrarium.api.routes.catalog import extensions as catalog_extensions
 from kohakuterrarium.api.routes.catalog import manifest as catalog_manifest
+from kohakuterrarium.api.routes.catalog import marketplace as catalog_marketplace
 from kohakuterrarium.api.routes.catalog import models as catalog_models
 from kohakuterrarium.api.routes.catalog import modules as catalog_modules
 from kohakuterrarium.api.routes.catalog import packages as catalog_packages
@@ -109,6 +110,7 @@ from kohakuterrarium.api.routes.sessions_v2 import memory as sessions_memory
 from kohakuterrarium.api.routes.sessions_v2 import topology as sessions_topology
 from kohakuterrarium.api.routes.sessions_v2 import wiring as sessions_wiring
 from kohakuterrarium.api.studio import build_studio_router
+from kohakuterrarium.studio.persistence.session_index import close_session_index
 from kohakuterrarium.api.ws import daemon_logs as ws_daemon_logs
 from kohakuterrarium.api.ws import files as ws_files
 from kohakuterrarium.api.ws import io as ws_io
@@ -329,6 +331,15 @@ async def lifespan(app: FastAPI):
             except Exception:  # pragma: no cover - defensive
                 logger.exception("host_engine.stop failed")
 
+        # Release the session-index sidecar's native SQLite handles.
+        # Doing it here (last) means any other shutdown step that
+        # touches the listing endpoint (e.g. a final reconcile) still
+        # has the index open.
+        try:
+            close_session_index()
+        except Exception:  # pragma: no cover - defensive
+            logger.exception("close_session_index failed")
+
 
 def _parse_bind(bind: str) -> tuple[str, int]:
     """Parse ``host:port`` into a tuple; ``port == 0`` selects ephemeral."""
@@ -606,6 +617,15 @@ def _mount_phase0_stubs(app: FastAPI) -> None:
     app.include_router(
         catalog_registry.router, prefix="/api/catalog/registry", tags=["catalog"]
     )
+    # Marketplace — TerrariumMarket-backed browse + install + source mgmt.
+    # Separate from /api/catalog/registry (which is the legacy bundled
+    # static index) — this one hits live remote sources via
+    # ``packages/marketplace.py``.
+    app.include_router(
+        catalog_marketplace.router,
+        prefix="/api/catalog/marketplace",
+        tags=["catalog"],
+    )
     app.include_router(
         catalog_creatures_scan.router,
         prefix="/api/catalog/creatures-scan",

kohakuterrarium-2.0.0.dev13/src/kohakuterrarium/api/routes/catalog/marketplace.py

@@ -0,0 +1,232 @@
+"""Catalog marketplace — read-only browse + admin-gated source mgmt + install.
+
+Wraps :mod:`kohakuterrarium.packages.marketplace` for the frontend.
+Source-list reads are public; mutating routes (add/remove sources,
+install) require the L3 admin token when L3 is enabled.
+
+``POST /install`` resolves the spec then delegates to the existing
+``install_package_op`` (which is what ``/api/catalog/packages/install``
+already calls), so the WebSocket-streaming install UX from topic 05
+is reused unchanged.
+
+Mounted by ``api/app.py`` at ``/api/catalog/marketplace``.
+"""
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from kohakuterrarium.api._io_executor import run_in_io_executor
+from kohakuterrarium.api.auth import verify_admin_token
+from kohakuterrarium.packages import marketplace
+from kohakuterrarium.packages.marketplace_types import (
+    IncompatibleFrameworkError,
+    InvalidSpecError,
+    MarketplaceEntry,
+    MarketplaceNotFoundError,
+    MarketplaceUnavailableError,
+)
+from kohakuterrarium.studio.catalog.packages import install_package_op
+from kohakuterrarium.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+router = APIRouter()
+
+
+# ──────────────────────────────────────────────────────────────────
+# Schemas
+# ──────────────────────────────────────────────────────────────────
+
+
+class AddSourceRequest(BaseModel):
+    url: str
+    alias: str | None = None
+
+
+class InstallSpecRequest(BaseModel):
+    spec: str
+    name: str | None = None
+    # Editable installs apply only to local paths.  Marketplace specs
+    # raise ValueError → 400 here (mirroring ``install_package_spec``).
+    editable: bool = False
+
+
+# ──────────────────────────────────────────────────────────────────
+# Projection
+# ──────────────────────────────────────────────────────────────────
+
+
+def _entry_to_dict(entry: MarketplaceEntry) -> dict[str, Any]:
+    return {
+        "name": entry.name,
+        "repo": entry.repo,
+        "description": entry.description,
+        "tags": list(entry.tags),
+        "author": entry.author,
+        "license": entry.license,
+        "framework": entry.framework,
+        "homepage": entry.homepage,
+        "source_alias": entry.source_alias,
+        "source_url": entry.source_url,
+        "versions": [
+            {
+                "tag": v.tag,
+                "released": v.released,
+                "framework": v.framework,
+                "notes": v.notes,
+                "notes_url": v.notes_url,
+                "yanked": v.yanked,
+                "commit": v.commit,
+            }
+            for v in entry.versions
+        ],
+    }
+
+
+# ──────────────────────────────────────────────────────────────────
+# Reads
+# ──────────────────────────────────────────────────────────────────
+
+
+@router.get("/packages")
+async def list_packages() -> dict[str, Any]:
+    """List every package across all configured marketplace sources.
+
+    Routes through :func:`marketplace.search` (with no filter) so the
+    user-facing first-source-wins dedup applies — the frontend card
+    grid otherwise would render shadowed duplicates as separate
+    rows.  The detail route below calls :func:`marketplace.resolve`
+    against the un-deduped raw list so explicit ``@source/name``
+    resolution still works.
+    """
+    try:
+        entries = await marketplace.search()
+    except MarketplaceUnavailableError as exc:
+        raise HTTPException(503, str(exc)) from exc
+    return {
+        "packages": [_entry_to_dict(e) for e in entries],
+        "sources": [s.to_dict() for s in marketplace.list_sources()],
+    }
+
+
+@router.get("/packages/{name}")
+async def get_package(name: str) -> dict[str, Any]:
+    """Detail view for a single package (resolves to newest non-yanked version)."""
+    try:
+        entry, version = await marketplace.resolve(f"@{name}")
+    except (MarketplaceNotFoundError, IncompatibleFrameworkError) as exc:
+        raise HTTPException(404, str(exc)) from exc
+    except MarketplaceUnavailableError as exc:
+        raise HTTPException(503, str(exc)) from exc
+    return {
+        "entry": _entry_to_dict(entry),
+        "resolved_version": version.tag,
+    }
+
+
+@router.get("/search")
+async def search(
+    q: str = "", tag: str | None = None, author: str | None = None
+) -> dict[str, Any]:
+    """Substring + tag + author filter."""
+    try:
+        results = await marketplace.search(q, tag=tag, author=author)
+    except MarketplaceUnavailableError as exc:
+        raise HTTPException(503, str(exc)) from exc
+    return {"packages": [_entry_to_dict(e) for e in results]}
+
+
+@router.post("/refresh", dependencies=[Depends(verify_admin_token)])
+async def refresh() -> dict[str, Any]:
+    """Force cache bust + re-fetch every source.
+
+    Admin-gated when L3 is on: refresh triggers an outbound network
+    round-trip and mutates the on-disk cache.  An anonymous caller
+    could otherwise DoS the upstream by spamming this route on a
+    multi-user host; the gate matches the other state-mutating
+    routes (sources + install).
+    """
+    try:
+        entries = await marketplace.fetch_marketplace(force=True)
+    except MarketplaceUnavailableError as exc:
+        raise HTTPException(503, str(exc)) from exc
+    return {"ok": True, "packages": len(entries)}
+
+
+# ──────────────────────────────────────────────────────────────────
+# Source management
+# ──────────────────────────────────────────────────────────────────
+
+
+@router.get("/sources")
+async def get_sources() -> dict[str, Any]:
+    """Configured source list (in lookup order)."""
+    return {"sources": [s.to_dict() for s in marketplace.list_sources()]}
+
+
+@router.post("/sources", dependencies=[Depends(verify_admin_token)])
+async def add_source(req: AddSourceRequest) -> dict[str, Any]:
+    try:
+        added = marketplace.add_source(req.url, alias=req.alias)
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+    return {
+        "added": added.to_dict(),
+        "sources": [s.to_dict() for s in marketplace.list_sources()],
+    }
+
+
+@router.delete("/sources", dependencies=[Depends(verify_admin_token)])
+async def remove_source(target: str) -> dict[str, Any]:
+    """Remove a source by URL or alias (passed via ``?target=...``).
+
+    The query-param shape (rather than a path param) is deliberate:
+    URL sources contain slashes that FastAPI's path-param routing
+    does not handle cleanly even with ``{target:path}``.  Aliases
+    work either way; URLs only work via query.  Frontend always
+    sends ``target=`` so both cases route through the same shape.
+    """
+    if not marketplace.remove_source(target):
+        raise HTTPException(404, f"No source matches {target!r}")
+    return {"sources": [s.to_dict() for s in marketplace.list_sources()]}
+
+
+# ──────────────────────────────────────────────────────────────────
+# Install
+# ──────────────────────────────────────────────────────────────────
+
+
+@router.post("/install", dependencies=[Depends(verify_admin_token)])
+async def install_by_spec(req: InstallSpecRequest) -> dict[str, Any]:
+    """Resolve ``@name`` spec then install (delegates to install_package_op).
+
+    For streaming progress, callers should use the existing WebSocket
+    endpoint on ``/api/registry/install`` instead — this REST route
+    blocks until the install completes (or fails).
+    """
+    spec = req.spec.strip()
+    if not spec:
+        raise HTTPException(400, "spec is required")
+    try:
+        name = await run_in_io_executor(
+            install_package_op,
+            source=spec,
+            name=req.name,
+            editable=req.editable,
+        )
+    except (MarketplaceNotFoundError, InvalidSpecError) as exc:
+        raise HTTPException(404, str(exc)) from exc
+    except IncompatibleFrameworkError as exc:
+        raise HTTPException(409, str(exc)) from exc
+    except MarketplaceUnavailableError as exc:
+        raise HTTPException(503, str(exc)) from exc
+    except ValueError as exc:
+        # ``install_package_spec`` raises ValueError when ``editable``
+        # is requested on a marketplace spec (git clones can't be -e).
+        raise HTTPException(400, str(exc)) from exc
+    except Exception as exc:
+        logger.error("Marketplace install failed", spec=spec, error=str(exc))
+        raise HTTPException(500, f"Install failed: {exc}") from exc
+    return {"status": "installed", "name": name, "spec": spec}