Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

fix(backend/copilot): Repair `get_doc_page` path resolution and stale docs URLs (#13598)

Reinier van der Leerc53922e5cda8
diff --git a/autogpt_platform/backend/Dockerfile b/autogpt_platform/backend/Dockerfile
index 77f6b9619e..810333d2a2 100644
--- a/autogpt_platform/backend/Dockerfile
+++ b/autogpt_platform/backend/Dockerfile
@@ -91,6 +91,14 @@ COPY autogpt_platform/backend/migrations ./migrations
# ============================== BACKEND SERVER ============================== #
+FROM debian:13-slim AS docs-filter
+# The copilot docs tools read markdown only — strip everything else
+# (images, scripts, configs) so no unused or untrusted files ship in the
+# server image or its layer history.
+COPY docs /docs
+RUN find /docs -type f ! -name '*.md' ! -name '*.mdx' -delete \
+ && find /docs -type d -empty -delete
+
FROM debian:13-slim AS server
WORKDIR /app
@@ -152,9 +160,9 @@ ENV PATH="/app/autogpt_platform/backend/.venv/bin:$PATH"
COPY autogpt_platform/autogpt_libs /app/autogpt_platform/autogpt_libs
COPY autogpt_platform/backend/poetry.lock autogpt_platform/backend/pyproject.toml ./
-# Copy backend code + docs (for Copilot docs search)
+# Copy backend code + docs (markdown only — see docs-filter stage)
COPY autogpt_platform/backend ./
-COPY docs /app/docs
+COPY --from=docs-filter /docs /app/docs
# Install the project package to create entry point scripts in .venv/bin/
# (e.g., rest, executor, ws, db, scheduler, notification - see [tool.poetry.scripts])
RUN POETRY_VIRTUALENVS_CREATE=true POETRY_VIRTUALENVS_IN_PROJECT=true \
diff --git a/autogpt_platform/backend/backend/api/features/search/content_handlers.py b/autogpt_platform/backend/backend/api/features/search/content_handlers.py
index 6f84b65c61..7dad60ebbc 100644
--- a/autogpt_platform/backend/backend/api/features/search/content_handlers.py
+++ b/autogpt_platform/backend/backend/api/features/search/content_handlers.py
@@ -20,6 +20,7 @@ from prisma.enums import ContentType
from backend.blocks import get_blocks
from backend.blocks.llm import LlmModel
from backend.data.db import query_raw_with_schema
+from backend.util.docs import get_docs_root
from backend.util.text import split_camelcase
if TYPE_CHECKING:
@@ -404,20 +405,12 @@ class DocumentationHandler(ContentHandler):
def content_type(self) -> ContentType:
return ContentType.DOCUMENTATION
- def _get_docs_root(self) -> Path:
- """Get the documentation root directory."""
- # content_handlers.py is at: backend/backend/api/features/store/content_handlers.py
- # Need to go up to project root then into docs/
- # In container: /app/autogpt_platform/backend/backend/api/features/store -> /app/docs
- # In development: /repo/autogpt_platform/backend/backend/api/features/store -> /repo/docs
- this_file = Path(
- __file__
- ) # .../backend/backend/api/features/store/content_handlers.py
- project_root = (
- this_file.parent.parent.parent.parent.parent.parent.parent
- ) # -> /app or /repo
- docs_root = project_root / "docs"
- return docs_root
+ def _get_docs_root(self) -> Path | None:
+ """Get the documentation root directory (shared with the copilot
+ docs tools so indexed paths and page reads always agree), or None
+ when this deployment didn't bundle the docs — the indexer degrades
+ to empty results instead of crashing."""
+ return get_docs_root()
def _extract_doc_title(self, file_path: Path) -> str:
"""Extract the document title from a markdown file."""
@@ -577,8 +570,8 @@ class DocumentationHandler(ContentHandler):
"""
docs_root = self._get_docs_root()
- if not docs_root.exists():
- logger.warning(f"Documentation root not found: {docs_root}")
+ if docs_root is None:
+ logger.warning("Documentation root not found")
return []
# Find all .md and .mdx files
@@ -682,7 +675,7 @@ class DocumentationHandler(ContentHandler):
"""
docs_root = self._get_docs_root()
- if not docs_root.exists():
+ if docs_root is None:
return {"total": 0, "with_embeddings": 0, "without_embeddings": 0}
# Get all section content IDs
@@ -714,7 +707,7 @@ class DocumentationHandler(ContentHandler):
# or removed section drops from this set and its embedding gets
# cleaned up.
docs_root = self._get_docs_root()
- if not docs_root.exists():
+ if docs_root is None:
return set()
# Filesystem walk is sync; keep it off the event loop.
return await asyncio.to_thread(self._get_all_section_content_ids, docs_root)
diff --git a/autogpt_platform/backend/backend/api/features/search/content_handlers_test.py b/autogpt_platform/backend/backend/api/features/search/content_handlers_test.py
index d4909cddb8..d4ea2dd81d 100644
--- a/autogpt_platform/backend/backend/api/features/search/content_handlers_test.py
+++ b/autogpt_platform/backend/backend/api/features/search/content_handlers_test.py
@@ -676,3 +676,19 @@ async def test_library_agent_handler_stats():
assert stats["total"] == 10
assert stats["with_embeddings"] == 4
assert stats["without_embeddings"] == 6
+
+
+async def test_documentation_handler_degrades_without_bundled_docs():
+ """A docs-less deployment must no-op (empty results), not crash the
+ indexer — get_docs_root returns None and every consumer guards."""
+ handler = DocumentationHandler()
+ with patch(
+ "backend.api.features.search.content_handlers.get_docs_root",
+ return_value=None,
+ ):
+ assert handler._get_docs_root() is None
+ assert await handler.get_missing_items(batch_size=10) == []
+ assert await handler.get_valid_content_ids() == set()
+ stats = await handler.get_stats()
+ assert stats == {"total": 0, "with_embeddings": 0, "without_embeddings": 0}
diff --git a/autogpt_platform/backend/backend/copilot/tools/get_doc_page.py b/autogpt_platform/backend/backend/copilot/tools/get_doc_page.py
index 6d4a2b53bc..193872af3d 100644
--- a/autogpt_platform/backend/backend/copilot/tools/get_doc_page.py
+++ b/autogpt_platform/backend/backend/copilot/tools/get_doc_page.py
@@ -1,19 +1,17 @@
"""GetDocPageTool - Fetch full content of a documentation page."""
+import asyncio
import logging
-from pathlib import Path
from typing import Any
from backend.copilot.model import ChatSession
+from backend.util.docs import get_docs_root, make_doc_url
from .base import BaseTool
from .models import DocPageResponse, ErrorResponse, ToolResponseBase
logger = logging.getLogger(__name__)
-# Base URL for documentation (can be configured)
-DOCS_BASE_URL = "https://docs.agpt.co"
-
class GetDocPageTool(BaseTool):
"""Tool for fetching full content of a documentation page."""
@@ -45,12 +43,6 @@ class GetDocPageTool(BaseTool):
def requires_auth(self) -> bool:
return False # Documentation is public
- def _get_docs_root(self) -> Path:
- """Get the documentation root directory."""
- this_file = Path(__file__)
- project_root = this_file.parent.parent.parent.parent.parent.parent.parent.parent
- return project_root / "docs"
-
def _extract_title(self, content: str, fallback: str) -> str:
"""Extract title from markdown content."""
lines = content.split("\n")
@@ -59,11 +51,6 @@ class GetDocPageTool(BaseTool):
return line[2:].strip()
return fallback
- def _make_doc_url(self, path: str) -> str:
- """Create a URL for a documentation page."""
- url_path = path.rsplit(".", 1)[0] if "." in path else path
- return f"{DOCS_BASE_URL}/{url_path}"
-
async def _execute(
self,
user_id: str | None,
@@ -100,19 +87,23 @@ class GetDocPageTool(BaseTool):
session_id=session_id,
)
- docs_root = self._get_docs_root()
- full_path = docs_root / path
-
- if not full_path.exists():
+ docs_root = get_docs_root()
+ if docs_root is None:
return ErrorResponse(
- message=f"Documentation page not found: {path}",
- error="not_found",
+ message="Documentation is not available in this deployment.",
+ error="docs_unavailable",
session_id=session_id,
)
-
- # Ensure the path is within docs root
+ # Containment before existence: a uniform error for out-of-root
+ # paths avoids leaking whether a file exists outside docs_root.
try:
- full_path.resolve().relative_to(docs_root.resolve())
+ # resolve() both sides: get_docs_root guarantees a resolved root,
+ # but the guard stays self-contained rather than coupling a
+ # security boundary to another module's invariant (idempotent,
+ # one metadata syscall). All later access goes through the
+ # resolved path so the validated path is the one read.
+ full_path = (docs_root / path).resolve()
+ full_path.relative_to(docs_root.resolve())
except ValueError:
return ErrorResponse(
message="Invalid documentation path.",
@@ -120,8 +111,15 @@ class GetDocPageTool(BaseTool):
session_id=session_id,
)
+ if not full_path.exists():
+ return ErrorResponse(
+ message=f"Documentation page not found: {path}",
+ error="not_found",
+ session_id=session_id,
+ )
+
try:
- content = full_path.read_text(encoding="utf-8")
+ content = await asyncio.to_thread(full_path.read_text, encoding="utf-8")
title = self._extract_title(content, path)
return DocPageResponse(
@@ -129,7 +127,7 @@ class GetDocPageTool(BaseTool):
title=title,
path=path,
content=content,
- doc_url=self._make_doc_url(path),
+ doc_url=make_doc_url(path),
session_id=session_id,
)
diff --git a/autogpt_platform/backend/backend/copilot/tools/get_doc_page_test.py b/autogpt_platform/backend/backend/copilot/tools/get_doc_page_test.py
new file mode 100644
index 0000000000..da968fc0a5
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/get_doc_page_test.py
@@ -0,0 +1,158 @@
+"""Tests for GetDocPageTool (and the shared docs-root resolution)."""
+
+import pytest
+
+from backend.copilot.tools.get_doc_page import GetDocPageTool
+from backend.copilot.tools.models import DocPageResponse, ErrorResponse
+from backend.util.docs import DOCS_BASE_URL, get_docs_root
+
+from ._test_data import make_session
+
+_TEST_USER_ID = "test-user-get-doc-page"
+
+
+def tool():
+ return GetDocPageTool()
+
+
+def session():
+ return make_session(_TEST_USER_ID)
+
+
+requires_docs_bundle = pytest.mark.skipif(
+ get_docs_root() is None,
+ reason="integration: needs the repo/image docs bundle on disk",
+)
+
+
+@requires_docs_bundle
+def test_docs_root_resolves_to_bundled_docs():
+ """Regression: the old parent-chain arithmetic resolved OUTSIDE the repo
+ (two levels too far), making every page read 404 in dev and cloud."""
+ root = get_docs_root()
+ assert root.is_dir()
+ assert root.name == "docs"
+ assert any(root.rglob("*.md"))
+
+
+@requires_docs_bundle
+async def test_fetches_real_doc_page(tool, session):
+ """Any indexed-style relative path under docs/ must be readable."""
+ root = get_docs_root()
+ doc_file = next(f for f in root.rglob("*.md") if f.stat().st_size > 0)
+ rel_path = str(doc_file.relative_to(root))
+
+ result = await tool._execute(user_id=None, session=session, path=rel_path)
+
+ assert isinstance(result, DocPageResponse)
+ assert result.content
+ assert result.path == rel_path
+ # The docs site serves rendered pages at the extension-less path;
+ # the .md variant is a soft-404 (HTTP 200 + "Page Not Found" body).
+ expected_slug = rel_path.removesuffix(".md").replace("_", "-")
+ assert result.doc_url == f"{DOCS_BASE_URL}/{expected_slug}"
+
+
+async def test_happy_path_hermetic(tool, session, tmp_path, mocker):
+ """Unconditional (mocked tmp docs root, no bundle needed): a valid
+ in-root path returns a DocPageResponse with content, title, and a
+ canonicalized doc_url — locks the repaired resolution regression in
+ even on docs-less environments."""
+ docs = tmp_path / "docs"
+ (docs / "platform").mkdir(parents=True)
+ (docs / "platform" / "getting_started.md").write_text("# Getting Started\n\nHello.")
+ mocker.patch(
+ "backend.copilot.tools.get_doc_page.get_docs_root",
+ return_value=docs.resolve(),
+ )
+
+ result = await tool._execute(
+ user_id=None, session=session, path="platform/getting_started.md"
+ )
+
+ assert isinstance(result, DocPageResponse)
+ assert result.title == "Getting Started"
+ assert result.content == "# Getting Started\n\nHello."
+ assert result.path == "platform/getting_started.md"
+ assert result.doc_url == f"{DOCS_BASE_URL}/platform/getting-started"
+
+
+@requires_docs_bundle
+async def test_missing_page_returns_not_found(tool, session):
+ result = await tool._execute(user_id=None, session=session, path="no/such/page.md")
+ assert isinstance(result, ErrorResponse)
+ assert result.error == "not_found"
+
+
+async def test_traversal_is_blocked(tool, session, tmp_path, mocker):
+ """Unconditional (mocked tmp docs root, no bundle needed): a ../ path
+ targeting a real out-of-root file is rejected before existence leaks."""
+ docs = tmp_path / "docs"
+ (docs / "platform").mkdir(parents=True)
+ (tmp_path / "secret.toml").write_text("nope")
+ mocker.patch(
+ "backend.copilot.tools.get_doc_page.get_docs_root",
+ return_value=docs.resolve(),
+ )
+ result = await tool._execute(user_id=None, session=session, path="../secret.toml")
+ assert isinstance(result, ErrorResponse)
+ assert result.error == "invalid_path"
+
+
+async def test_docs_unavailable_returns_dedicated_error(tool, session, mocker):
+ """A deployment without bundled docs degrades to a clear error instead
+ of a misleading not_found."""
+ mocker.patch(
+ "backend.copilot.tools.get_doc_page.get_docs_root",
+ return_value=None,
+ )
+ result = await tool._execute(
+ user_id=None, session=session, path="platform/getting-started.md"
+ )
+ assert isinstance(result, ErrorResponse)
+ assert result.error == "docs_unavailable"
+
+
+async def test_symlink_escape_blocked_by_containment(tool, session, tmp_path, mocker):
+ """A path with no ../ that resolves OUTSIDE docs_root via an in-tree
+ symlink must hit the containment check (the string guard can't see it)."""
+ docs = tmp_path / "docs"
+ (docs / "platform").mkdir(parents=True)
+ outside = tmp_path / "secret.txt"
+ outside.write_text("nope")
+ (docs / "platform" / "leak.md").symlink_to(outside)
+ mocker.patch(
+ "backend.copilot.tools.get_doc_page.get_docs_root",
+ return_value=docs.resolve(),
+ )
+ result = await tool._execute(user_id=None, session=session, path="platform/leak.md")
+ assert isinstance(result, ErrorResponse)
+ assert result.error == "invalid_path"
+
+
+async def test_directory_path_returns_read_failed(tool, session, tmp_path, mocker):
+ docs = tmp_path / "docs"
+ (docs / "platform").mkdir(parents=True)
+ mocker.patch(
+ "backend.copilot.tools.get_doc_page.get_docs_root",
+ return_value=docs.resolve(),
+ )
+ result = await tool._execute(user_id=None, session=session, path="platform")
+ assert isinstance(result, ErrorResponse)
+ assert result.error == "read_failed"
+
+
+async def test_empty_path_rejected(tool, session):
+ result = await tool._execute(user_id=None, session=session, path=" ")
+ assert isinstance(result, ErrorResponse)
+ assert "path" in result.message.lower()
diff --git a/autogpt_platform/backend/backend/copilot/tools/search_docs.py b/autogpt_platform/backend/backend/copilot/tools/search_docs.py
index 693361a2fd..77ac51c343 100644
--- a/autogpt_platform/backend/backend/copilot/tools/search_docs.py
+++ b/autogpt_platform/backend/backend/copilot/tools/search_docs.py
@@ -8,6 +8,7 @@ from prisma.enums import ContentType
from backend.api.features.search.hybrid_search import HybridSearchRow
from backend.copilot.model import ChatSession
from backend.data.db_accessors import search
+from backend.util.docs import make_doc_url
from .base import BaseTool
from .models import (
@@ -20,9 +21,6 @@ from .models import (
logger = logging.getLogger(__name__)
-# Base URL for documentation (can be configured)
-DOCS_BASE_URL = "https://docs.agpt.co"
-
# Maximum number of results to return
MAX_RESULTS = 5
@@ -76,12 +74,6 @@ class SearchDocsTool(BaseTool):
return truncated + "..."
- def _make_doc_url(self, path: str) -> str:
- """Create a URL for a documentation page."""
- # Remove file extension for URL
- url_path = path.rsplit(".", 1)[0] if "." in path else path
- return f"{DOCS_BASE_URL}/{url_path}"
-
async def _execute(
self,
user_id: str | None,
@@ -183,7 +175,7 @@ class SearchDocsTool(BaseTool):
section=section_title,
snippet=self._create_snippet(searchable_text),
score=round(score, 3),
- doc_url=self._make_doc_url(doc_path),
+ doc_url=make_doc_url(doc_path),
)
)
diff --git a/autogpt_platform/backend/backend/copilot/tools/search_docs_test.py b/autogpt_platform/backend/backend/copilot/tools/search_docs_test.py
new file mode 100644
index 0000000000..2083a0e213
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/search_docs_test.py
@@ -0,0 +1,47 @@
+"""Tests for SearchDocsTool URL construction.
+
+The doc URL shape (extension STRIPPED) is load-bearing: agpt.co serves
+rendered pages at the extension-less path, while the .md variant returns a
+soft-404 (HTTP 200 + "Page Not Found" body). A regression re-introducing
+the extension must not ship silently.
+"""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from backend.copilot.tools.search_docs import SearchDocsTool
+from backend.util.docs import DOCS_BASE_URL, make_doc_url
+
+
+def test_doc_url_strips_md_extension():
+ url = make_doc_url("platform/block-sdk-guide.md")
+ assert url == f"{DOCS_BASE_URL}/platform/block-sdk-guide"
+
+
+async def test_search_result_doc_url_shape(mocker):
+ """Behavioral check through the tool: a search hit's doc_url must be the
+ extension-less rendered-page URL."""
+ row = {
+ "metadata": {
+ "path": "platform/block-sdk-guide.md",
+ "doc_title": "Block SDK Guide",
+ "section_title": "Intro",
+ },
+ "searchable_text": "how to build blocks",
+ "combined_score": 0.9,
+ }
+ db = MagicMock()
+ db.unified_hybrid_search = AsyncMock(return_value=([row], 1))
+ mocker.patch(
+ "backend.copilot.tools.search_docs.search",
+ return_value=db,
+ )
+ tool = SearchDocsTool()
+ session = MagicMock()
+ session.session_id = "sess-1"
+ result = await tool._execute(user_id="user-1", session=session, query="blocks")
+
+ assert result.results, getattr(result, "message", result)
+ assert result.results[0].doc_url == f"{DOCS_BASE_URL}/platform/block-sdk-guide"
diff --git a/autogpt_platform/backend/backend/util/docs.py b/autogpt_platform/backend/backend/util/docs.py
new file mode 100644
index 0000000000..80abf13fce
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/docs.py
@@ -0,0 +1,51 @@
+"""Locate the platform's bundled documentation and its public URLs."""
+
+from functools import cache
+from pathlib import Path
+
+# Public docs site. It serves rendered pages at the EXTENSION-LESS repo path
+# (https://agpt.co/docs/<repo-relative-path-without-.md>); the .md variant
+# returns a soft-404 ("Page Not Found" with HTTP 200), so status-code checks
+# alone cannot validate these URLs — grep the body when re-verifying.
+DOCS_BASE_URL = "https://agpt.co/docs"
+
+
+def make_doc_url(path: str) -> str:
+ """Public URL for a documentation page (extension stripped, underscores
+ canonicalized to hyphens — the site's edge worker rewrites ``_`` to
+ ``-``, see ``autogpt_platform/cloudflare_worker.js``). Shared by
+ search_docs and get_doc_page so the URL shape can't drift between the
+ two tools."""
+ clean = path.lstrip("/")
+ for ext in (".md", ".mdx"):
+ if clean.endswith(ext):
+ clean = clean[: -len(ext)]
+ break
+ return f"{DOCS_BASE_URL}/{clean.replace('_', '-')}"
+
+
+@cache
+def get_docs_root(start: Path | None = None) -> Path | None:
+ """Walk up from *start* (default: this file) to the bundled docs root,
+ or ``None`` when this deployment didn't bundle the docs.
+
+ One implementation covers both layouts without fragile parent counting:
+ the dev checkout (``<repo>/docs``) and the container image
+ (``/app/docs``, see ``COPY docs /app/docs`` in the backend Dockerfile).
+ ``docs/platform`` is required as a sentinel so an unrelated ``docs``
+ folder closer to this package (e.g. a future ``backend/docs/``) can't
+ shadow the real documentation root.
+
+ *start* exists for testability (point the walk at a tmp tree). Both the
+ found path (already resolved — derived from resolved parents) and the
+ not-found ``None`` are memoized, so docs-less deployments don't re-walk
+ the filesystem on every call.
+ """
+ origin = (start or Path(__file__)).resolve()
+ for parent in origin.parents:
+ candidate = parent / "docs"
+ if (candidate / "platform").is_dir():
+ # Final resolve: robustness if docs/ itself is a symlink, so the
+ # containment check in get_doc_page compares real paths.
+ return candidate.resolve()
+ return None
diff --git a/autogpt_platform/backend/backend/util/docs_test.py b/autogpt_platform/backend/backend/util/docs_test.py
new file mode 100644
index 0000000000..539c07ed0e
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/docs_test.py
@@ -0,0 +1,98 @@
+"""Tests for the docs-root walk-up resolution."""
+
+from pathlib import Path
+
+import pytest
+
+from backend.util.docs import DOCS_BASE_URL, get_docs_root, make_doc_url
+
+
[email protected](autouse=True)
+def _clear_cache():
+ get_docs_root.cache_clear()
+ yield
+ get_docs_root.cache_clear()
+
+
+def _make_docs_tree(root: Path) -> Path:
+ docs = root / "docs" / "platform"
+ docs.mkdir(parents=True)
+ return root / "docs"
+
+
+def test_walks_up_to_docs_root(tmp_path: Path):
+ docs = _make_docs_tree(tmp_path)
+ start = tmp_path / "app" / "backend" / "util" / "docs.py"
+ start.parent.mkdir(parents=True)
+ start.touch()
+ assert get_docs_root(start) == docs
+
+
+def test_sentinel_skips_shadowing_docs_dir(tmp_path: Path):
+ """A closer docs/ WITHOUT the platform sentinel must not shadow the
+ real documentation root further up."""
+ real_docs = _make_docs_tree(tmp_path)
+ shadow = tmp_path / "app" / "backend" / "docs"
+ shadow.mkdir(parents=True)
+ start = tmp_path / "app" / "backend" / "util" / "docs.py"
+ start.parent.mkdir(parents=True)
+ start.touch()
+ assert get_docs_root(start) == real_docs
+
+
+def test_missing_docs_returns_none(tmp_path: Path):
+ start = tmp_path / "app" / "backend" / "util" / "docs.py"
+ start.parent.mkdir(parents=True)
+ start.touch()
+ assert get_docs_root(start) is None
+
+
+def test_negative_result_memoized(tmp_path: Path):
+ start = tmp_path / "app" / "backend" / "util" / "docs.py"
+ start.parent.mkdir(parents=True)
+ start.touch()
+ assert get_docs_root(start) is None
+ assert get_docs_root.cache_info().misses == 1
+ # Negative result is cached — a second identical call must not re-walk.
+ assert get_docs_root(start) is None
+ assert get_docs_root.cache_info().hits == 1
+ assert get_docs_root.cache_info().misses == 1
+
+
+def test_make_doc_url_strips_extension_and_leading_slash():
+ """agpt.co serves rendered pages extension-less; the .md variant is a
+ soft-404 (HTTP 200 + "Page Not Found" body)."""
+ assert make_doc_url("a/b.md").endswith("/docs/a/b")
+ assert make_doc_url("a/b.mdx").endswith("/docs/a/b")
+ assert make_doc_url("/a/b.md") == make_doc_url("a/b.md")
+
+
+def test_docs_base_url_pins_live_host():
+ """Guards against a silent revert to the dead docs.agpt.co host — the
+ shape tests are all relative to this constant."""
+ assert DOCS_BASE_URL == "https://agpt.co/docs"
+
+
+def test_make_doc_url_passthrough_without_extension():
+ assert make_doc_url("a/b").endswith("/docs/a/b")
+ # Dots inside names are not extensions — only .md/.mdx strip.
+ assert make_doc_url("platform/v1.2").endswith("/docs/platform/v1.2")
+ assert make_doc_url("platform/v1.2-guide.md").endswith("/docs/platform/v1.2-guide")
+
+
+def test_sentinel_rejects_platform_file(tmp_path: Path):
+ """docs/platform must be a DIRECTORY — a stray file must not satisfy
+ the sentinel."""
+ fake = tmp_path / "docs"
+ fake.mkdir()
+ (fake / "platform").touch()
+ start = tmp_path / "app" / "backend" / "util" / "docs.py"
+ start.parent.mkdir(parents=True)
+ start.touch()
+ assert get_docs_root(start) is None
+
+
+def test_make_doc_url_canonicalizes_underscores():
+ """The site's edge worker rewrites _ to - (cloudflare_worker.js);
+ verified live: platform/new-blocks renders, platform/new_blocks 404s."""
+ assert make_doc_url("platform/new_blocks.md").endswith("/docs/platform/new-blocks")
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/SearchDocs/helpers.test.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/SearchDocs/helpers.test.ts
new file mode 100644
index 0000000000..5ef1662459
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/SearchDocs/helpers.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { toDocsUrl } from "./helpers";
+
+describe("toDocsUrl", () => {
+ it("builds extension-less rendered-page URLs on the live host", () => {
+ expect(toDocsUrl("platform/block-sdk-guide.md")).toBe(
+ "https://agpt.co/docs/platform/block-sdk-guide",
+ );
+ expect(toDocsUrl("a/b.mdx")).toBe("https://agpt.co/docs/a/b");
+ });
+
+ it("canonicalizes underscores to hyphens like the site's edge worker", () => {
+ expect(toDocsUrl("platform/new_blocks.md")).toBe(
+ "https://agpt.co/docs/platform/new-blocks",
+ );
+ });
+
+ it("only strips markdown extensions, not dots inside names", () => {
+ expect(toDocsUrl("platform/v1.2-guide.md")).toBe(
+ "https://agpt.co/docs/platform/v1.2-guide",
+ );
+ });
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/SearchDocs/helpers.tsx b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/SearchDocs/helpers.tsx
index 50a84edceb..eb59e1cefc 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/SearchDocs/helpers.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/SearchDocs/helpers.tsx
@@ -208,8 +208,13 @@ export function AccordionIcon({ toolType }: { toolType: DocsToolType }) {
}
export function toDocsUrl(path: string): string {
- const urlPath = path.includes(".")
- ? path.slice(0, path.lastIndexOf("."))
- : path;
- return `https://docs.agpt.co/${urlPath}`;
+ // Mirrors backend.util.docs.make_doc_url: extension-less rendered-page
+ // path on agpt.co with underscores canonicalized to hyphens (the site's
+ // edge worker rewrites _ to -; the .md variant is a soft-404 and
+ // docs.agpt.co is dead).
+ const clean = path
+ .replace(/^\/+/, "")
+ .replace(/\.mdx?$/, "")
+ .replace(/_/g, "-");
+ return `https://agpt.co/docs/${clean}`;
}