KohakuTerrarium 2.0.0.dev7__tar.gz → 2.0.0.dev8__tar.gz

{kohakuterrarium-2.0.0.dev7/src/KohakuTerrarium.egg-info → kohakuterrarium-2.0.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: KohakuTerrarium
-Version: 2.0.0.dev7
+Version: 2.0.0.dev8
 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
@@ -37,6 +37,7 @@ Requires-Dist: kohakuvault>=0.8.6
 Requires-Dist: textual>=8.0.0
 Requires-Dist: html2text>=2025.0.0
 Requires-Dist: gitpython>=3.1.0
+Requires-Dist: dulwich>=0.22
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn[standard]>=0.34.0
 Requires-Dist: websockets>=10.4
@@ -52,7 +53,7 @@ Requires-Dist: jiter<1,>=0.10.0
 Requires-Dist: primp>=1.3.0
 Requires-Dist: model2vec>=0.8.0
 Requires-Dist: safetensors>=0.7.0
-Requires-Dist: tokenizers>=0.23.1
+Requires-Dist: tokenizers<0.24,>=0.20
 Requires-Dist: pywinpty>=2.0.0; sys_platform == "win32"
 Provides-Extra: host
 Provides-Extra: client

{kohakuterrarium-2.0.0.dev7 → kohakuterrarium-2.0.0.dev8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "KohakuTerrarium"
-version = "2.0.0.dev7"
+version = "2.0.0.dev8"
 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" },
@@ -92,6 +92,15 @@ dependencies = [
     "textual>=8.0.0",
     "html2text>=2025.0.0",
     "gitpython>=3.1.0",
+    # dulwich: pure-Python git impl used as the Android fallback for
+    # ``kt install <url>`` when no system ``git`` binary is on PATH.
+    # On Chaquopy Android there's no shellable ``git``; dulwich's
+    # ``py3-none-any`` wheel installs cleanly and the
+    # ``packages/git_backend.py`` shim auto-selects it when
+    # ``shutil.which('git')`` returns None.  Slightly slower than
+    # native git for big repos but fine for creature / terrarium /
+    # plugin package sizes.
+    "dulwich>=0.22",
     # API server
     "fastapi>=0.115.0",
     # ``[standard]`` pulls in uvloop + httptools + watchfiles for
@@ -147,10 +156,19 @@ dependencies = [
     # safetensors + tokenizers: hard transitives via model2vec.
     # Declared as direct deps so Briefcase emits the lines and
     # postcreate's URL refs fire on Android.  On desktop / PyPI
-    # both packages have manylinux wheels, so the redundancy is
-    # harmless.
+    # both packages have manylinux wheels.
+    #
+    # ``tokenizers`` floor must match what ``sentence-transformers``
+    # (in the ``full`` extra) can satisfy: it pulls
+    # ``transformers>=4.41.0`` which only accepts
+    # ``tokenizers<=0.23.0``.  Using ``>=0.23.1`` here makes
+    # ``uv pip install -e .[full]`` unsolvable.  Floor 0.20 matches
+    # model2vec's own pin and is satisfied by both PyPI's manylinux
+    # wheel chain AND our Android wheel (0.23.1 — version constraint
+    # on the wheel-filename URL ref is independent of the dep-spec
+    # range we accept here).
     "safetensors>=0.7.0",
-    "tokenizers>=0.23.1",
+    "tokenizers>=0.20,<0.24",
     # Windows PTY for terminal panel (Nerd Font / PowerShell theme support)
     "pywinpty>=2.0.0; sys_platform == 'win32'",
 ]
@@ -273,7 +291,7 @@ select = ["F401", "F841"]
 [tool.briefcase]
 project_name = "KohakuTerrarium"
 bundle = "com.kohaku.terrarium"
-version = "2.0.0.dev7"
+version = "2.0.0.dev8"
 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.dev7 → kohakuterrarium-2.0.0.dev8/src/KohakuTerrarium.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: KohakuTerrarium
-Version: 2.0.0.dev7
+Version: 2.0.0.dev8
 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
@@ -37,6 +37,7 @@ Requires-Dist: kohakuvault>=0.8.6
 Requires-Dist: textual>=8.0.0
 Requires-Dist: html2text>=2025.0.0
 Requires-Dist: gitpython>=3.1.0
+Requires-Dist: dulwich>=0.22
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn[standard]>=0.34.0
 Requires-Dist: websockets>=10.4
@@ -52,7 +53,7 @@ Requires-Dist: jiter<1,>=0.10.0
 Requires-Dist: primp>=1.3.0
 Requires-Dist: model2vec>=0.8.0
 Requires-Dist: safetensors>=0.7.0
-Requires-Dist: tokenizers>=0.23.1
+Requires-Dist: tokenizers<0.24,>=0.20
 Requires-Dist: pywinpty>=2.0.0; sys_platform == "win32"
 Provides-Extra: host
 Provides-Extra: client

{kohakuterrarium-2.0.0.dev7 → kohakuterrarium-2.0.0.dev8}/src/KohakuTerrarium.egg-info/SOURCES.txt

@@ -116,6 +116,16 @@ src/kohakuterrarium/api/ws/runtime_graph.py
 src/kohakuterrarium/api/ws/trace.py
 src/kohakuterrarium/app_icons/app.ico
 src/kohakuterrarium/app_icons/app.png
+src/kohakuterrarium/app_icons/app.round-icon-144.png
+src/kohakuterrarium/app_icons/app.round-icon-192.png
+src/kohakuterrarium/app_icons/app.round-icon-48.png
+src/kohakuterrarium/app_icons/app.round-icon-72.png
+src/kohakuterrarium/app_icons/app.round-icon-96.png
+src/kohakuterrarium/app_icons/app.square-icon-144.png
+src/kohakuterrarium/app_icons/app.square-icon-192.png
+src/kohakuterrarium/app_icons/app.square-icon-48.png
+src/kohakuterrarium/app_icons/app.square-icon-72.png
+src/kohakuterrarium/app_icons/app.square-icon-96.png
 src/kohakuterrarium/app_icons/window.ico
 src/kohakuterrarium/app_icons/window.png
 src/kohakuterrarium/bootstrap/__init__.py
@@ -511,6 +521,7 @@ src/kohakuterrarium/modules/trigger/universal.py
 src/kohakuterrarium/modules/user_command/__init__.py
 src/kohakuterrarium/modules/user_command/base.py
 src/kohakuterrarium/packages/__init__.py
+src/kohakuterrarium/packages/git_backend.py
 src/kohakuterrarium/packages/install.py
 src/kohakuterrarium/packages/locations.py
 src/kohakuterrarium/packages/manifest.py
@@ -790,12 +801,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_-uBFoVSR-.js
-src/kohakuterrarium/web_dist/assets/_key_-DNOvxKYU.js
+src/kohakuterrarium/web_dist/assets/_id_-DdMcU1a1.js
+src/kohakuterrarium/web_dist/assets/_key_-ZVnthKlZ.js
 src/kohakuterrarium/web_dist/assets/abap-DNgBPGRI.js
 src/kohakuterrarium/web_dist/assets/apex-B4r7dYl2.js
-src/kohakuterrarium/web_dist/assets/api-6WpGvpdH.js
-src/kohakuterrarium/web_dist/assets/axios-DkY6n9a-.js
+src/kohakuterrarium/web_dist/assets/api-D4YjBzA7.js
+src/kohakuterrarium/web_dist/assets/axios-Dad_bxaI.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
@@ -814,8 +825,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-Bl9PS9H7.css
-src/kohakuterrarium/web_dist/assets/element-plus-Dy9KxKFU.js
+src/kohakuterrarium/web_dist/assets/element-plus-BmQ7cnZ3.css
+src/kohakuterrarium/web_dist/assets/element-plus-DadrrCeP.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
@@ -829,10 +840,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-CPPu7zHj.css
-src/kohakuterrarium/web_dist/assets/index-CrlVAR7v.js
+src/kohakuterrarium/web_dist/assets/index-CuB7PtQi.css
+src/kohakuterrarium/web_dist/assets/index-D_yDy4pp.js
 src/kohakuterrarium/web_dist/assets/ini-BeMa714h.js
-src/kohakuterrarium/web_dist/assets/instances-BQRxJfAx.js
+src/kohakuterrarium/web_dist/assets/instances-DUn3OudZ.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
@@ -852,8 +863,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-tbxF8vvv.js
-src/kohakuterrarium/web_dist/assets/panel-debug-CdERMccn.js
+src/kohakuterrarium/web_dist/assets/pages-BBjSTdTz.js
+src/kohakuterrarium/web_dist/assets/panel-debug-D_rSsx0a.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
@@ -894,7 +905,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-GLcKlkIp.js
+src/kohakuterrarium/web_dist/assets/vue-vendor-DroPwbFZ.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.dev7 → kohakuterrarium-2.0.0.dev8}/src/KohakuTerrarium.egg-info/requires.txt

@@ -15,6 +15,7 @@ kohakuvault>=0.8.6
 textual>=8.0.0
 html2text>=2025.0.0
 gitpython>=3.1.0
+dulwich>=0.22
 fastapi>=0.115.0
 uvicorn[standard]>=0.34.0
 websockets>=10.4
@@ -30,7 +31,7 @@ jiter<1,>=0.10.0
 primp>=1.3.0
 model2vec>=0.8.0
 safetensors>=0.7.0
-tokenizers>=0.23.1
+tokenizers<0.24,>=0.20
 
 [:sys_platform == "win32"]
 pywinpty>=2.0.0

kohakuterrarium-2.0.0.dev8/src/kohakuterrarium/api/routes/identity/codex.py

@@ -0,0 +1,147 @@
+"""Identity codex — OAuth login/status/usage.
+
+Accepts a ``?node=<id>`` query param: when set to a connected worker,
+the OAuth flow runs ON THAT WORKER (browser opens on the worker's
+machine, tokens land in the worker's ``<config_dir>/codex-auth.json``).
+This is the ONLY sound way to use Codex from a worker — OAuth tokens
+are process-bound so the host's token cannot be reused remotely.
+"""
+
+import asyncio
+import json
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+
+from kohakuterrarium.api.auth import verify_admin_token
+from kohakuterrarium.api.deps import get_service
+from kohakuterrarium.api.routes.identity.node_routing import (
+    call_node_identity,
+    is_host_target,
+)
+from kohakuterrarium.studio.identity.codex_oauth import (
+    get_status,
+    get_usage_async,
+    login_async,
+)
+from kohakuterrarium.terrarium.service import TerrariumService
+
+router = APIRouter()
+
+
+@router.post("/codex-login", dependencies=[Depends(verify_admin_token)])
+async def codex_login(
+    node: str = "",
+    service: TerrariumService = Depends(get_service),
+):
+    """Run the Codex OAuth flow on the targeted node."""
+    if is_host_target(node):
+        try:
+            return await login_async()
+        except Exception as e:
+            raise HTTPException(500, f"Codex login failed: {e}") from e
+    # Worker-side login: long-running (waits for user OAuth callback or
+    # device-code entry). Bump the lab-request timeout so the user has
+    # time to complete the flow.
+    return await call_node_identity(service, node, "codex_login", timeout=300.0)
+
+
+@router.post(
+    "/codex-login-stream",
+    dependencies=[Depends(verify_admin_token)],
+)
+async def codex_login_stream(node: str = ""):
+    """Run Codex login while streaming progress events to the client.
+
+    The frontend ``CodexLoginModal`` consumes this endpoint as a
+    line-delimited JSON stream (one JSON object per line).  Events:
+
+      * ``{"event": "device_code", "verification_url": ..., "user_code": ..., "expires_in": int}``
+        — fired as soon as the device-code branch obtains the user
+        code, BEFORE the poll loop starts.  The modal renders this
+        so the user can manually open the URL + enter the code on
+        any device.
+      * ``{"event": "completed", "expires_at": float}`` — final
+        success.  Modal closes itself with a success toast.
+      * ``{"event": "error", "message": str}`` — terminal failure.
+
+    Only the host path streams events directly.  Worker-side login
+    falls back to the existing one-shot ``/codex-login`` route since
+    cross-node event streaming isn't wired in 1.5.0; this leaves the
+    modal-based UX functional in the common case (local Codex login
+    on the host's own machine) and the host-router lab path for the
+    rare worker case.
+    """
+    if not is_host_target(node):
+        raise HTTPException(
+            400,
+            (
+                "Streaming Codex login is only supported on the host node "
+                '(node=""); for worker-side login use POST /codex-login.'
+            ),
+        )
+
+    queue: asyncio.Queue = asyncio.Queue()
+
+    async def emit_device_code(verification_url: str, user_code: str, expires_in: int):
+        await queue.put(
+            {
+                "event": "device_code",
+                "verification_url": verification_url,
+                "user_code": user_code,
+                "expires_in": expires_in,
+            }
+        )
+
+    async def run_login():
+        try:
+            result = await login_async(on_device_code=emit_device_code)
+            await queue.put(
+                {
+                    "event": "completed",
+                    "expires_at": result.get("expires_at"),
+                }
+            )
+        except Exception as exc:
+            await queue.put(
+                {"event": "error", "message": f"{type(exc).__name__}: {exc}"}
+            )
+        finally:
+            await queue.put(None)  # sentinel — close the stream
+
+    async def stream():
+        task = asyncio.create_task(run_login())
+        try:
+            while True:
+                event = await queue.get()
+                if event is None:
+                    break
+                yield json.dumps(event) + "\n"
+        finally:
+            if not task.done():
+                task.cancel()
+                try:
+                    await task
+                except (asyncio.CancelledError, Exception):
+                    pass
+
+    return StreamingResponse(stream(), media_type="application/x-ndjson")
+
+
+@router.get("/codex-status")
+async def codex_status(
+    node: str = "",
+    service: TerrariumService = Depends(get_service),
+):
+    if is_host_target(node):
+        return get_status()
+    return await call_node_identity(service, node, "codex_status")
+
+
+@router.get("/codex-usage")
+async def get_codex_usage():
+    """Return the most-recent captured Codex rate-limit / credits snapshot."""
+    try:
+        return await get_usage_async()
+    except Exception as e:
+        raise HTTPException(401, f"Failed to refresh Codex tokens: {e}") from e

{kohakuterrarium-2.0.0.dev7 → kohakuterrarium-2.0.0.dev8}/src/kohakuterrarium/llm/codex_auth.py

@@ -328,7 +328,9 @@ async def _browser_flow() -> CodexTokens:
 # =========================================================================
 
 
-async def _device_code_flow() -> CodexTokens:
+async def _device_code_flow(
+    on_device_code: "callable | None" = None,
+) -> CodexTokens:
     """OAuth device code flow for headless environments.
 
     Uses OpenAI's Codex-specific device auth endpoints:
@@ -337,6 +339,14 @@ async def _device_code_flow() -> CodexTokens:
     3. Poll /api/accounts/deviceauth/token until user completes auth
     4. Server returns authorization_code + PKCE codes
     5. Exchange at /oauth/token for access + refresh tokens
+
+    ``on_device_code`` is an optional async callback ``(verification_url,
+    user_code, expires_in) -> None`` invoked AS SOON AS the user code
+    is obtained — before we start polling.  The SSE / WebSocket layer
+    uses this to push the code to the frontend modal so the user can
+    paste it on another device while the server polls in background.
+    Tests and the CLI invoker pass ``None`` to keep the existing
+    print-only behaviour.
     """
     async with httpx.AsyncClient(timeout=30) as client:
         resp = await client.post(
@@ -362,6 +372,21 @@ async def _device_code_flow() -> CodexTokens:
     print()
     print("Waiting for authentication (either method)...")
 
+    # Push the user code + URL to any subscribed event sink (SSE /
+    # WebSocket modal) so the frontend can show them immediately
+    # instead of waiting for the entire poll-and-exchange to finish.
+    if on_device_code is not None:
+        try:
+            res = on_device_code(DEVICE_VERIFY_URL, user_code, expires_in)
+            if asyncio.iscoroutine(res):
+                await res
+        except Exception as exc:
+            logger.warning(
+                "on_device_code callback raised",
+                error_type=type(exc).__name__,
+                error=str(exc),
+            )
+
     deadline = time.time() + expires_in
     async with httpx.AsyncClient(timeout=30) as client:
         while time.time() < deadline:
@@ -479,7 +504,9 @@ async def _exchange_code(
 # =========================================================================
 
 
-async def oauth_login() -> CodexTokens:
+async def oauth_login(
+    on_device_code: "callable | None" = None,
+) -> CodexTokens:
     """
     Authenticate with OpenAI Codex OAuth.
 
@@ -489,10 +516,16 @@ async def oauth_login() -> CodexTokens:
     - SSH/headless: user visits URL on another device, enters code
     - Remote desktop: either flow may work
     - Windows reserved port: browser fails fast, device code continues
+    - **Android / WebView frontend**: no browser opener available,
+      ``on_device_code`` callback pushes the verification URL + code
+      to the UI modal so the user can paste them on another device.
+
+    ``on_device_code`` is forwarded verbatim to the device-code branch;
+    pass ``None`` (default) for the original print-only behaviour.
     """
     # Start both flows as concurrent tasks
     browser_task = asyncio.create_task(_browser_flow_safe())
-    device_task = asyncio.create_task(_device_code_flow())
+    device_task = asyncio.create_task(_device_code_flow(on_device_code=on_device_code))
 
     tasks = {browser_task, device_task}
     last_error: Exception | None = None

kohakuterrarium-2.0.0.dev8/src/kohakuterrarium/packages/git_backend.py

@@ -0,0 +1,150 @@
+"""Git clone / pull backend abstraction.
+
+Two implementations, picked at call time:
+
+    1. **Native ``git`` binary** — fast, full feature set, the default
+       when ``git`` is discoverable on ``$PATH``.  Used on desktop /
+       CI / Linux server installs.
+
+    2. **Pure-Python ``dulwich``** — pulled in as a hard dep so it's
+       always available on Chaquopy Android (no system ``git``
+       binary ships in the APK and one can't be shelled out to).
+       Slower than native ``git`` for large repos but covers the
+       creature / terrarium / plugin package sizes ``kt install``
+       deals with (a few MB at most).
+
+The public API is just two functions:
+
+    ``clone_repo(url, target)``
+    ``pull_repo(target)``
+
+Both raise :class:`RuntimeError` on any failure.  Callers can rely on
+the abstraction to handle backend selection — they don't need to know
+which one ran.
+"""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from kohakuterrarium.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _has_native_git() -> bool:
+    """True iff the system ``git`` binary is on ``$PATH`` and callable.
+
+    We probe once and cache.  Cache invalidates on a process restart;
+    a long-running daemon that gets ``git`` installed mid-session
+    would still pick up the new binary on next restart, which is fine
+    for an install path.
+    """
+    global _NATIVE_GIT_CACHE
+    if _NATIVE_GIT_CACHE is not None:
+        return _NATIVE_GIT_CACHE
+    found = shutil.which("git") is not None
+    _NATIVE_GIT_CACHE = found
+    if not found:
+        logger.info("Native git not found on PATH; using dulwich pure-Python backend")
+    return found
+
+
+_NATIVE_GIT_CACHE: bool | None = None
+
+
+def clone_repo(url: str, target: Path) -> None:
+    """Clone ``url`` into ``target`` directory.
+
+    Selects the native git binary when available, otherwise falls
+    back to dulwich.  Both code paths raise :class:`RuntimeError` on
+    failure with a one-line diagnostic message.
+    """
+    if _has_native_git():
+        _clone_native(url, target)
+    else:
+        _clone_dulwich(url, target)
+
+
+def pull_repo(target: Path) -> None:
+    """Pull (fast-forward only) the existing clone at ``target``.
+
+    Same backend-selection rule as :func:`clone_repo`.
+    """
+    if _has_native_git():
+        _pull_native(target)
+    else:
+        _pull_dulwich(target)
+
+
+# ─── native git binary ────────────────────────────────────────────
+
+
+def _clone_native(url: str, target: Path) -> None:
+    try:
+        subprocess.run(
+            ["git", "clone", url, str(target)],
+            check=True,
+            capture_output=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.decode(errors="replace").strip() if exc.stderr else str(exc)
+        raise RuntimeError(f"Git clone failed: {stderr}") from exc
+
+
+def _pull_native(target: Path) -> None:
+    try:
+        subprocess.run(
+            ["git", "-C", str(target), "pull", "--ff-only"],
+            check=True,
+            capture_output=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.decode(errors="replace").strip() if exc.stderr else str(exc)
+        raise RuntimeError(f"Git pull failed: {stderr}") from exc
+
+
+# ─── pure-Python dulwich ──────────────────────────────────────────
+#
+# Dulwich is imported lazily so that:
+#   * the module loads on systems where dulwich isn't installed yet
+#     (only fails when actually invoked without native git);
+#   * import cost is paid once per process, on first call.
+
+
+def _import_dulwich():
+    try:
+        from dulwich import porcelain  # noqa: PLC0415  — lazy by design
+
+        return porcelain
+    except ImportError as exc:
+        raise RuntimeError(
+            "No git available — install ``git`` on PATH or "
+            "``pip install dulwich`` (dulwich is a hard dep so this "
+            "should never trigger in production builds)."
+        ) from exc
+
+
+def _clone_dulwich(url: str, target: Path) -> None:
+    porcelain = _import_dulwich()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        porcelain.clone(url, str(target), depth=1)
+    except Exception as exc:
+        raise RuntimeError(f"Git clone failed (dulwich): {exc}") from exc
+
+
+def _pull_dulwich(target: Path) -> None:
+    porcelain = _import_dulwich()
+    if not (target / ".git").exists():
+        raise RuntimeError(f"Not a git clone: {target}")
+    try:
+        porcelain.pull(str(target))
+    except Exception as exc:
+        raise RuntimeError(f"Git pull failed (dulwich): {exc}") from exc
+
+
+def _reset_backend_cache_for_tests() -> None:
+    """Force re-probe of the native git binary on the next call."""
+    global _NATIVE_GIT_CACHE
+    _NATIVE_GIT_CACHE = None