ztestoctop 10.0.0__py3-none-any.whl

octop/__init__.py

@@ -0,0 +1,11 @@
+"""Octop — smarter self-hosted AI assistant (multi-user, multi-agent)."""
+
+from __future__ import annotations
+
+from octop.infra.utils.httpx_proxy import install_httpx_cidr_no_proxy
+
+__version__ = "10.0.0"
+
+# httpx 0.28 treats NO_PROXY CIDR as an exact IP (see issue #1347). Patch once
+# at import so CLI, ``octop run``, and in-process harness clients all honor it.
+install_httpx_cidr_no_proxy()

octop/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point: ``python -m octop`` → CLI."""
+
+from __future__ import annotations
+
+from octop.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

octop/api/__init__.py

@@ -0,0 +1 @@
+

octop/api/app.py

@@ -0,0 +1,341 @@
+"""FastAPI app factory."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, PlainTextResponse
+from scalar_fastapi import get_scalar_api_reference
+
+from octop.api.middleware.jwt_auth import install as install_jwt_auth
+from octop.api.middleware.setup_lockdown import install as install_setup_lockdown
+from octop.api.openapi_meta import API_DESCRIPTION, OPENAPI_TAGS, configure_openapi
+from octop.infra.errors import ErrorCode, OctopError
+from octop.infra.server import OctopServer
+from octop.infra.utils.locale import resolve_request_locale
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class _RouterMount:
+    router: Any
+    prefix: str
+    tags: Sequence[str]
+
+
+_NO_CACHE_DASHBOARD_NAMES = frozenset({"sw.js", "manifest.json", "index.html"})
+
+
+def dashboard_cache_control(full_path: str) -> str | None:
+    """Cache-Control for a dashboard SPA path, or ``None`` to leave unset."""
+    name = Path(full_path).name.lower() if full_path else "index.html"
+    if not full_path or name in _NO_CACHE_DASHBOARD_NAMES:
+        return "no-cache"
+    # Vite emits content-hashed files under assets/ — safe to pin forever.
+    if full_path.startswith("assets/"):
+        return "public, max-age=31536000, immutable"
+    return None
+
+
+def _dashboard_response(path: Path, full_path: str) -> FileResponse:
+    response = FileResponse(path)
+    cache_control = dashboard_cache_control(full_path)
+    if cache_control is not None:
+        response.headers["Cache-Control"] = cache_control
+    return response
+
+
+def is_dashboard_asset_path(full_path: str) -> bool:
+    """True for hashed build artifacts that must 404 instead of falling back."""
+    return full_path.startswith("assets/")
+
+
+def _dashboard_fallback(index_file: Path, full_path: str) -> FileResponse:
+    """Serve the SPA shell for routes; 404 for a missing hashed asset.
+
+    Answering ``/assets/index.<old-hash>.js`` with ``index.html`` makes the
+    browser reject HTML as a module script ("not a valid JavaScript MIME
+    type"), which hides the real cause — a stale shell after an upgrade.
+    """
+    if is_dashboard_asset_path(full_path):
+        raise HTTPException(status_code=404, detail="Not Found")
+    return _dashboard_response(index_file, "")
+
+
+def _mount_routers(app: FastAPI, mounts: Sequence[_RouterMount]) -> None:
+    for spec in mounts:
+        app.include_router(spec.router, prefix=spec.prefix, tags=list(spec.tags))
+
+
+def _install_exception_handlers(app: FastAPI) -> None:
+    @app.exception_handler(OctopError)
+    async def _octop(request: Request, exc: OctopError) -> JSONResponse:
+        # Client responses are locale-localized; log the original English message
+        # so INTERNAL_ERROR (and other 5xx) remain diagnosable in ~/.octop/logs.
+        if exc.status >= 500:
+            logger.error(
+                "OctopError %s in %s: %s",
+                exc.code.value,
+                request.url.path,
+                exc.message,
+                exc_info=exc,
+            )
+        locale = resolve_request_locale(request)
+        return JSONResponse(status_code=exc.status, content=exc.to_envelope(locale=locale))
+
+    @app.exception_handler(Exception)
+    async def _unhandled(request: Request, exc: Exception) -> JSONResponse:
+        logger.exception("unhandled exception in %s", request.url.path)
+        locale = resolve_request_locale(request)
+        err = OctopError.localized(ErrorCode.INTERNAL_ERROR, locale)
+        return JSONResponse(status_code=err.status, content=err.to_envelope())
+
+
+def build_app(server: OctopServer) -> FastAPI:
+    cfg = server.services.config if server.services else getattr(server, "config", None)
+    enable_dashboard = cfg.enable_dashboard if cfg else True
+    enable_api_docs = cfg.enable_api_docs if cfg else False
+    enable_mobile = (
+        cfg.capabilities.mobile.enabled if cfg and cfg.capabilities.mobile.enabled else False
+    )
+
+    app = FastAPI(
+        title="Octop API",
+        version="0.1.0",
+        description=API_DESCRIPTION,
+        openapi_url="/api/openapi.json" if enable_api_docs else None,
+        openapi_tags=OPENAPI_TAGS,
+    )
+    configure_openapi(app)
+    app.state.octop_server = server
+    _install_exception_handlers(app)
+
+    if cfg and cfg.cors_origins:
+        from octop.api.deps import ACCESS_TOKEN_RESPONSE_HEADER
+
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cfg.cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+            expose_headers=[ACCESS_TOKEN_RESPONSE_HEADER],
+        )
+
+    from octop.api.middleware.bridge_proxy import install as install_bridge_proxy
+
+    # Bridge proxy must sit inside JWT auth so ``request.state.octop_user`` is set
+    # (Starlette runs the last-added middleware first).
+    install_bridge_proxy(app, server)
+    install_jwt_auth(app, server)
+    install_setup_lockdown(app, server)
+
+    if server.app_runtime is not None and server.app_runtime.bridge_manager is not None:
+        from octop.api.bridge_peer import prepare_peer_dashboard_turn
+        from octop.api.routers.browser.stream import run_browser_stream_session
+
+        server.app_runtime.bridge_manager.bind_asgi_app(
+            app,
+            peer_turn_runner=prepare_peer_dashboard_turn,
+            peer_browser_runner=run_browser_stream_session,
+        )
+
+    from octop.infra.setup.tls.challenge import challenge_store
+
+    @app.get("/.well-known/acme-challenge/{token}", include_in_schema=False)
+    async def acme_http01_challenge(token: str) -> PlainTextResponse:
+        body = challenge_store.get(token)
+        if body is None:
+            raise HTTPException(status_code=404, detail="challenge not found")
+        return PlainTextResponse(body)
+
+    from octop.api.routers import (
+        acp,
+        admin,
+        agent_files,
+        agent_mcp,
+        agent_tools,
+        agents,
+        auth,
+        auth_ldap,
+        auth_oauth,
+        auth_oidc,
+        backup,
+        bridge,
+        browser,
+        channels,
+        chat,
+        connectors,
+        cron,
+        desktop,
+        envs,
+        experts,
+        health,
+        i18n,
+        internal_mcp,
+        invites,
+        knowledge_bases,
+        mbti,
+        media_generation,
+        memory,
+        memory_portable,
+        memory_storage,
+        mobile,
+        ollama_models,
+        onnx_models,
+        plugins,
+        preferences,
+        proactive_care,
+        providers,
+        search,
+        settings,
+        setup,
+        skill_packages,
+        skills,
+        slash,
+        subagents,
+        teams,
+        terminal,
+        update,
+        uploads,
+        usage,
+        user_roles,
+        users,
+        voice,
+        workspace,
+    )
+    from octop.api.routers.decision import router as decision_router
+    from octop.api.routers.filesystem import router as filesystem_router
+    from octop.api.routers.observability import router as observability_router
+    from octop.api.routers.providers import admin_router as admin_providers_router
+    from octop.api.routers.security import router as security_router
+    from octop.api.routers.storage_backends import admin_router as admin_storage_router
+    from octop.api.routers.storage_backends import user_router as storage_backends_user_router
+    from octop.api.routers.tls import router as tls_router
+    from octop.api.routers.voice import admin_router as admin_voice_router
+
+    _mount_routers(
+        app,
+        [
+            _RouterMount(setup.router, "/api", ["setup"]),
+            _RouterMount(auth.router, "/api/auth", ["auth"]),
+            _RouterMount(auth_oidc.router, "/api/auth", ["auth"]),
+            _RouterMount(auth_oauth.router, "/api/auth", ["auth"]),
+            _RouterMount(auth_ldap.router, "/api/auth", ["auth"]),
+            _RouterMount(invites.public_router, "/api/auth/invite", ["auth"]),
+            _RouterMount(preferences.router, "/api", ["auth"]),
+            _RouterMount(i18n.router, "/api", ["i18n"]),
+            _RouterMount(health.router, "/api/health", ["health"]),
+            _RouterMount(invites.admin_router, "/api/users/invites", ["users"]),
+            _RouterMount(user_roles.router, "/api/users/roles", ["users"]),
+            _RouterMount(users.router, "/api/users", ["users"]),
+            _RouterMount(agents.router, "/api/agents", ["agents"]),
+            _RouterMount(agent_tools.router, "/api", ["agents"]),
+            _RouterMount(acp.router, "/api", ["agents"]),
+            _RouterMount(agent_mcp.router, "/api", ["agent-mcp"]),
+            _RouterMount(chat.router, "/api", ["chat"]),
+            _RouterMount(slash.router, "/api", ["slash"]),
+            _RouterMount(connectors.router, "/api", ["connectors"]),
+            _RouterMount(bridge.router, "/api", ["bridge"]),
+            _RouterMount(knowledge_bases.router, "/api", ["knowledge"]),
+            _RouterMount(internal_mcp.router, "/api", ["internal-mcp"]),
+            _RouterMount(channels.router, "/api", ["channels"]),
+            _RouterMount(cron.router, "/api", ["cron"]),
+            _RouterMount(settings.router, "/api", ["settings"]),
+            _RouterMount(decision_router, "/api", ["settings"]),
+            _RouterMount(envs.router, "/api", ["envs"]),
+            _RouterMount(search.router, "/api", ["search"]),
+            _RouterMount(providers.router, "/api/providers", ["providers"]),
+            _RouterMount(voice.router, "/api/voice", ["voice"]),
+            _RouterMount(admin.router, "/api/admin", ["admin"]),
+            _RouterMount(backup.router, "/api/admin", ["admin"]),
+            _RouterMount(admin_providers_router, "/api/admin/providers", ["admin"]),
+            _RouterMount(admin_voice_router, "/api/admin/voice/providers", ["admin"]),
+            _RouterMount(observability_router, "/api/admin/observability", ["observability"]),
+            _RouterMount(
+                media_generation.router,
+                "/api/admin/media-generation",
+                ["providers"],
+            ),
+            _RouterMount(tls_router, "/api/admin/tls", ["tls"]),
+            _RouterMount(security_router, "/api/admin/security", ["security"]),
+            _RouterMount(admin_storage_router, "/api/admin/storage-backends", ["admin"]),
+            _RouterMount(
+                storage_backends_user_router, "/api/storage-backends", ["storage-backends"]
+            ),
+            _RouterMount(filesystem_router, "/api/filesystem", ["filesystem"]),
+            _RouterMount(mbti.router, "/api", ["mbti"]),
+            _RouterMount(experts.router, "/api", ["experts"]),
+            _RouterMount(teams.router, "/api", ["teams"]),
+            _RouterMount(workspace.router, "/api", ["workspace"]),
+            _RouterMount(agent_files.router, "/api", ["agent_files"]),
+            _RouterMount(memory.router, "/api", ["memory"]),
+            _RouterMount(memory_portable.router, "/api", ["memory"]),
+            _RouterMount(memory_storage.router, "/api", ["memory"]),
+            _RouterMount(proactive_care.router, "/api", ["proactive-care"]),
+            _RouterMount(usage.router, "/api", ["usage"]),
+            _RouterMount(usage.admin_router, "/api/admin", ["admin"]),
+            _RouterMount(skill_packages.router, "/api", ["skill-packages"]),
+            _RouterMount(skills.router, "/api", ["skills"]),
+            _RouterMount(subagents.router, "/api", ["subagents"]),
+            _RouterMount(terminal.router, "/api", ["terminal"]),
+            _RouterMount(uploads.router, "/api", ["chat"]),
+            _RouterMount(update.router, "/api", ["update"]),
+            _RouterMount(browser.router, "/api", ["browser"]),
+            _RouterMount(desktop.router, "/api", ["desktop"]),
+            _RouterMount(ollama_models.router, "/api", ["ollama"]),
+            _RouterMount(onnx_models.router, "/api", ["onnx"]),
+            _RouterMount(plugins.router, "/api", ["plugins"]),
+        ],
+    )
+
+    if enable_mobile:
+        _mount_routers(
+            app,
+            [
+                _RouterMount(mobile.router, "/api", ["mobile"]),
+            ],
+        )
+
+    if enable_api_docs:
+
+        @app.get("/api/docs", include_in_schema=False)
+        async def api_docs() -> HTMLResponse:
+            return get_scalar_api_reference(
+                openapi_url=app.openapi_url,
+                title="Octop API",
+            )
+
+    if enable_dashboard:
+        dashboard_dir = Path(__file__).parent.parent / "dashboard"
+        index_file = dashboard_dir / "index.html"
+        if index_file.exists():
+
+            @app.get("/{full_path:path}", include_in_schema=False)
+            async def spa_fallback(full_path: str) -> FileResponse:
+                if full_path.startswith(("api/", "ws/")):
+                    raise HTTPException(status_code=404, detail="Not Found")
+
+                if full_path:
+                    raw_path = Path(full_path)
+                    # Reject absolute paths and parent-dir references before
+                    # joining, so user input never drives a path expression.
+                    if raw_path.is_absolute() or ".." in raw_path.parts:
+                        return _dashboard_fallback(index_file, full_path)
+                    candidate = (dashboard_dir / Path(*raw_path.parts)).resolve()
+                    try:
+                        candidate.relative_to(dashboard_dir.resolve())
+                    except ValueError:
+                        return _dashboard_fallback(index_file, full_path)
+                    if candidate.is_file():
+                        return _dashboard_response(candidate, full_path)
+                return _dashboard_fallback(index_file, full_path)
+
+    return app

octop/api/bridge_peer.py

@@ -0,0 +1,111 @@
+"""ASGI-layer helpers that Bridge calls for local dashboard turns.
+
+Wired from ``build_app`` so ``infra.bridge`` never imports ``api/``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from octop.api.routers.chat.models import UserTurnWsFrame
+from octop.api.routers.chat.turn import (
+    build_dashboard_inbound,
+    prepare_dashboard_turn,
+    turn_has_content,
+)
+from octop.infra.bridge.peer_turn import PeerTurnRejected, bridge_turn_ws_payload
+
+
+@dataclass(frozen=True)
+class PreparedPeerTurn:
+    thread_id: str
+    inbound: Any
+
+
+async def prepare_peer_dashboard_turn(
+    *,
+    server: Any,
+    user: Any,
+    agent_id: str,
+    payload: dict[str, Any],
+    ws_connection_id: str,
+) -> PreparedPeerTurn:
+    """Validate a peer ``turn.start`` and build the gateway inbound.
+
+    When the room is already busy, admit a mid-turn steer and return
+    ``inbound=None`` so the peer does not enqueue a second turn.
+    """
+    frame = UserTurnWsFrame.model_validate(bridge_turn_ws_payload(payload))
+    turn = frame.to_turn_body()
+    if not turn_has_content(turn):
+        raise PeerTurnRejected("empty message")
+    prepared = await prepare_dashboard_turn(
+        server,
+        agent_id=agent_id,
+        user=user,
+        turn=turn,
+    )
+    if await _admit_peer_steer(
+        server,
+        agent_id=agent_id,
+        thread_id=prepared.thread_id,
+        turn=turn,
+    ):
+        return PreparedPeerTurn(thread_id=prepared.thread_id, inbound=None)
+    inbound = build_dashboard_inbound(
+        agent_id=agent_id,
+        user_id=user.id,
+        prepared=prepared,
+        turn=turn,
+        ws_connection_id=ws_connection_id,
+        user_is_admin=bool(getattr(user, "is_admin", False)),
+    )
+    return PreparedPeerTurn(thread_id=prepared.thread_id, inbound=inbound)
+
+
+async def _admit_peer_steer(
+    server: Any,
+    *,
+    agent_id: str,
+    thread_id: str,
+    turn: Any,
+) -> bool:
+    """Push steer.ack / queued onto the live turn subscriber when busy."""
+    rt = getattr(server, "app_runtime", None)
+    gateway = getattr(rt, "gateway", None) if rt is not None else None
+    if gateway is None:
+        return False
+    from octop.api.routers.chat.ws import (  # noqa: PLC0415
+        _maybe_admit_steer,
+        _plain_text_from_turn,
+        _steer_blocks_from_turn,
+        _thread_hitl_paused,
+    )
+
+    hub = gateway.ws_hub
+    delivery = turn.delivery or "auto"
+    # Team members speak after the host WS turn goes idle. A leftover steer
+    # coordinator row must not swallow the next user_turn as a queued insert.
+    if (
+        delivery != "steer"
+        and not hub.is_turn_active(thread_id)
+        and not _thread_hitl_paused(gateway, thread_id, agent_id)
+    ):
+        return False
+
+    async def send_via_hub(steer_frame: dict[str, Any]) -> None:
+        await hub.push_to_thread(thread_id, steer_frame)
+
+    return await _maybe_admit_steer(
+        text=(turn.text or "").strip() or _plain_text_from_turn(turn),
+        thread_id=thread_id,
+        delivery=delivery,
+        client_pending_id=turn.client_pending_id,
+        expected_turn_id=turn.expected_turn_id,
+        steer=gateway.steer,
+        hub=hub,
+        send_frame=send_via_hub,
+        hitl_paused=_thread_hitl_paused(gateway, thread_id, agent_id),
+        content_blocks=_steer_blocks_from_turn(turn),
+    )

octop/api/common/__init__.py

@@ -0,0 +1 @@
+"""Shared router helpers — agent access, workspace glue, request validation."""

octop/api/common/agent.py

@@ -0,0 +1,79 @@
+"""Shared agent ownership / existence checks for HTTP routers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from octop.infra.errors import ErrorCode, OctopError
+
+
+def agent_is_shared(row: Any) -> bool:
+    return int(getattr(row, "is_shared", 0) or 0) == 1
+
+
+def user_owns_agent(row: Any, user: Any) -> bool:
+    return row.user_id is not None and row.user_id == user.id
+
+
+def assert_agent_owner(row: Any, user: Any) -> None:
+    """Raise if the user may not mutate this agent row (admin bypasses)."""
+    if user.is_admin:
+        return
+    if row.user_id is None or row.user_id != user.id:
+        raise OctopError(ErrorCode.FORBIDDEN, "agent not owned by user")
+
+
+def _user_may_access(row: Any, user: Any) -> bool:
+    if user.is_admin:
+        return True
+    if row.user_id is not None and row.user_id == user.id:
+        return True
+    return bool(agent_is_shared(row))
+
+
+def assert_agent_access_row(row: Any, user: Any) -> None:
+    if not _user_may_access(row, user):
+        raise OctopError(ErrorCode.FORBIDDEN, "agent not accessible to user")
+
+
+def require_agent_row(
+    agent_id: str,
+    *,
+    user: Any,
+    as_user: int | None,
+    server: Any,
+) -> Any:
+    """Load an agent row after owner / shared-agent / admin ``as_user`` checks."""
+    assert server.app_runtime is not None
+    row = server.app_runtime.agent_registry.get_row(agent_id)
+    if row is None:
+        raise OctopError(ErrorCode.AGENT_NOT_FOUND, f"agent {agent_id!r} not found")
+    if as_user is not None and as_user != user.id:
+        if not user.is_admin:
+            raise OctopError(ErrorCode.FORBIDDEN, "as_user requires admin")
+        target = server.user_manager.get_by_id(as_user)
+        if target is None:
+            raise OctopError(ErrorCode.NOT_FOUND, f"user {as_user} not found")
+        if row.user_id is not None and row.user_id != as_user:
+            raise OctopError(ErrorCode.FORBIDDEN, "agent not owned by as_user")
+    else:
+        assert_agent_access_row(row, user)
+    return row
+
+
+def require_agent_owner_row(
+    agent_id: str,
+    *,
+    user: Any,
+    as_user: int | None,
+    server: Any,
+) -> Any:
+    """Load an agent row and require owner-level access."""
+    row = require_agent_row(agent_id, user=user, as_user=as_user, server=server)
+    assert_agent_owner(row, user)
+    return row
+
+
+def assert_agent_access(server: Any, agent_id: str, user: Any) -> None:
+    """Ensure agent exists and is accessible to the current user."""
+    require_agent_row(agent_id, user=user, as_user=None, server=server)

octop/api/common/agent_runtime.py

@@ -0,0 +1,32 @@
+"""Typed API fields for per-agent runtime and model settings."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from octop.infra.agents.settings.runtime_limits import AGENT_RUNTIME_CONFIG_KEYS
+
+
+class AgentRuntimeFields(BaseModel):
+    """First-class create/edit fields persisted in the agent's config storage."""
+
+    max_iters: int | None = Field(default=None, ge=1)
+    max_input_length: int | None = Field(default=None, ge=1_000)
+    temperature: float | None = Field(default=None, ge=0, le=2)
+    top_p: float | None = Field(default=None, ge=0, le=1)
+    max_tokens: int | None = Field(default=None, ge=1)
+
+
+def runtime_field_updates(
+    model: BaseModel,
+    *,
+    exclude_unset: bool,
+) -> dict[str, Any]:
+    """Extract runtime fields from an API body without leaking unrelated fields."""
+    dumped = model.model_dump(exclude_unset=exclude_unset)
+    return {key: dumped[key] for key in AGENT_RUNTIME_CONFIG_KEYS if key in dumped}
+
+
+__all__ = ["AgentRuntimeFields", "runtime_field_updates"]

octop/api/common/agent_workspace.py

@@ -0,0 +1,19 @@
+"""Resolve agent ``workspace_dir`` for API handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+
+def resolve_agent_workspace_dir(server: Any, agent_id: str) -> Path:
+    """Prefer ``config.workspace_dir`` via agent registry; else Octop default layout."""
+    runtime = getattr(server, "app_runtime", None)
+    registry = getattr(runtime, "agent_registry", None) if runtime is not None else None
+    if registry is not None and hasattr(registry, "resolve_workspace_dir"):
+        return cast(Path, registry.resolve_workspace_dir(agent_id))
+    paths = getattr(server, "paths", None) or server.services.paths
+    return cast(Path, paths.ensure_agent_workspace(agent_id))
+
+
+__all__ = ["resolve_agent_workspace_dir"]

octop/api/common/attachments.py

@@ -0,0 +1,69 @@
+"""Chat attachment HTTP helpers — thin wrappers over :mod:`inbound_store`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+from octop.infra.gateway.media.attachment_hints import is_preview_media_type
+from octop.infra.gateway.media.inbound_store import InboundFile, write_inbound
+
+if TYPE_CHECKING:
+    from octop_harness.backends.workspace import BackendWorkspace
+
+
+@dataclass(frozen=True)
+class StoredAttachment:
+    filename: str
+    media_type: str
+    size: int
+    data_path: str
+    owner_id: int = 0
+
+
+def _stored_from_inbound(inbound: InboundFile, *, owner_id: int = 0) -> StoredAttachment:
+    return StoredAttachment(
+        owner_id=owner_id,
+        filename=inbound.filename,
+        media_type=inbound.media_type,
+        size=inbound.size,
+        data_path=inbound.path,
+    )
+
+
+def dashboard_inbound_preview_url(
+    agent_id: str,
+    workspace_path: str,
+    *,
+    media_type: str = "",
+) -> str:
+    """JWT-protected preview/download URL for dashboard UI (not for LLM)."""
+    rel = workspace_path.lstrip("/")
+    aid = quote(agent_id, safe="")
+    if is_preview_media_type(media_type):
+        params = f"source={quote(rel, safe='')}"
+        if media_type:
+            params += f"&mime_type={quote(media_type, safe='')}"
+        return f"/api/agents/{aid}/media/preview?{params}"
+    return f"/api/agents/{aid}/workspace/download?path={quote(rel, safe='')}"
+
+
+async def save_attachment(
+    workspace: BackendWorkspace,
+    *,
+    owner_id: int,
+    filename: str,
+    media_type: str,
+    data: bytes,
+    max_bytes: int | None = None,
+) -> StoredAttachment:
+    del owner_id  # access control is JWT + agent scope at download time
+    inbound = await write_inbound(
+        workspace,
+        data,
+        filename=filename,
+        media_type=media_type,
+        max_bytes=max_bytes,
+    )
+    return _stored_from_inbound(inbound)