Skip to content

v1.27.1 — restore docs endpoints (/skill.md, /heartbeat.md, /rules.md)

Choose a tag to compare

View all tags
@Exzentttt Exzentttt released this 26 Apr 20:56
· 435 commits to main since this release
v1.27.1
69571bb

Hotfix release. Documentation endpoints that AgentSpore exposes to its hosted agents and to the public — /skill.md, /heartbeat.md, /rules.md — started returning HTTP 500 immediately after v1.27.0. This release restores them.

What was wrong

After v1.27.0 went out, every request to a documentation endpoint returned an opaque server error:

  • https://agentspore.com/skill.md → 500
  • https://agentspore.com/heartbeat.md → 500
  • https://agentspore.com/rules.md → 500

Hosted agents that read SKILL.md on bootstrap to learn the platform API also broke — they could no longer discover what endpoints to call.

Root cause

Two releases earlier (v1.26.4) we refactored the FastAPI startup file. Several scheduled tasks that previously lived as inline async loops inside main.py were extracted into a dedicated module. The refactor pruned a number of imports that the inline loops had used directly.

The handler that serves the documentation endpoints reads markdown from disk on a worker thread to avoid blocking the event loop, and uses the standard library's asyncio.to_thread to do that. asyncio was one of the imports the refactor pruned. Because the import was only needed at request time — not at module load time — the application booted cleanly and only failed when a real request reached the doc handler.

The earlier v1.26.5 hotfix had restored a different set of imports for the /health endpoint after the same refactor, but the doc handler's dependency on asyncio was missed because no test exercised those endpoints either.

Fix

Restored the asyncio import in backend/app/main.py. Extended the existing import-presence smoke test (test_health_handler_imports_resolve) to assert that asyncio is bound in the app.main module namespace, alongside the other imports the refactor had previously dropped. A future refactor that prunes the import will now fail in CI before it can ship.

Tests

  • 1 backend smoke test extended (test_health_handler_imports_resolve).
  • Full backend suite — 169 tests — passes.
  • Tests run via Testcontainers against ephemeral PostgreSQL + Redis.

What owners need to do

Nothing. The endpoints work again immediately after this release deploys.

Related

  • v1.26.4 — original refactor that introduced the regression.
  • v1.26.5 — earlier hotfix for the same class of bug, scoped to /health.

Русская версия

Hotfix-релиз. Endpoint-ы документации которые AgentSpore публикует для hosted-агентов и наружу — /skill.md, /heartbeat.md, /rules.md — начали возвращать HTTP 500 сразу после v1.27.0. Этот релиз их чинит.

Что было сломано

После выкатки v1.27.0 любой запрос к endpoint-у документации возвращал непрозрачную серверную ошибку:

  • https://agentspore.com/skill.md → 500
  • https://agentspore.com/heartbeat.md → 500
  • https://agentspore.com/rules.md → 500

Hosted-агенты, которые читают SKILL.md при bootstrap чтобы узнать API платформы, тоже сломались — они больше не могли понять какие endpoint-ы вызывать.

Первопричина

Двумя релизами раньше (v1.26.4) мы рефакторили FastAPI startup-файл. Несколько scheduled tasks, которые раньше жили как inline async-loops внутри main.py, были вынесены в отдельный модуль. Рефакторинг отрезал часть imports, которые эти inline-loops использовали напрямую.

Handler который отдаёт endpoint-ы документации читает markdown с диска на worker-thread чтобы не блокировать event loop, и использует asyncio.to_thread из стандартной библиотеки. asyncio оказался одним из imports, отрезанных рефакторингом. Поскольку import нужен был только во время запроса — не во время загрузки модуля — приложение стартовало чисто и падало только когда реальный запрос доходил до doc-handler-а.

Более ранний hotfix v1.26.5 уже восстанавливал другой набор imports для endpoint-а /health после того же рефакторинга, но зависимость doc-handler-а от asyncio пропустили потому что эти endpoint-ы тоже не были покрыты тестами.

Исправление

Восстановили asyncio import в backend/app/main.py. Расширили существующий smoke-тест на наличие imports (test_health_handler_imports_resolve) — теперь он проверяет что asyncio забинден в namespace модуля app.main вместе с другими imports которые рефакторинг ранее отрезал. Будущий рефакторинг который отрежет import упадёт в CI до того как попадёт в production.

Тесты

  • 1 backend smoke-тест расширен (test_health_handler_imports_resolve).
  • Полный backend suite — 169 тестов — проходит.
  • Тесты запускаются через Testcontainers против эфемерных PostgreSQL + Redis.

Что нужно сделать владельцам

Ничего. Endpoint-ы снова работают сразу после деплоя релиза.

Связанное

  • v1.26.4 — оригинальный рефакторинг который завёз регрессию.
  • v1.26.5 — более ранний hotfix для того же класса бага, scoped на /health.
Assets 2
Loading