doctor + adapter docs: surface the /graphql-over-HTTP gap (#21)#22
Merged
Conversation
Smoke-tested the devagentic-docs client against the canonical devagentic deployment on devbox while preparing the next iteration and found every GraphQL call silently 404s — the schema exists in-process but isn't exposed at <host>/graphql on any of 6070/ 6071/6072/8000/8080/8888/4000/5000. Verified via curl + via the introspection-over-SSH path which still works. Three hermes adapters depend on /graphql (skills, memory, the just-merged devagentic-docs plugin). All three silently degrade. This PR is the hermes-side DX delta only — no transport refactor (that's devagentic-side): - doctor's 404 detail now points at #21 and shows the curl probe operators can run, so they don't chase env-var mismatches before checking whether /graphql is exposed at all. - agent/devagentic_skills.py + agent/devagentic_memory.py docstrings call out the transport caveat + point at #21. - plugins/devagentic-docs/README.md adds a dedicated section above Configuration with the same curl probe + #21 link. Tests: tightened test_reports_not_found_on_404 to assert the detail references #21 so the documentation stays linked to the diagnostic going forward. Closes #21.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #21. Smoke-tested my just-merged devagentic-docs client (#19/#20) against the canonical devagentic deployment on devbox and confirmed every GraphQL request silently 404s — the schema exists in-process but isn't exposed over HTTP at any of the ports I probed (6070, 6071, 6072, 8000, 8080, 8888, 4000, 5000).
Three hermes adapters depend on
<host>/graphql: skills (#52), memory (#54), the just-shipped devagentic-docs plugin (#12). All three silently fall back to None against this deployment.This PR is hermes-side DX only — no transport refactor. Devagentic-side decisions (expose /graphql, or document the alternative) are out of scope.
Changes
hermes_cli/doctor.py: the 404 detail in_check_devagentic_graph()now points operators at [synergy] Devagentic GraphQL adapters silently 404 — /graphql isn't exposed over HTTP on the canonical deployment #21 and surfaces the exactcurl -X POST <url>/graphql -d '{"query":"{__typename}"}'probe, so they can confirm whether/graphqlis actually exposed before chasing env-var mismatches.agent/devagentic_skills.py+agent/devagentic_memory.py: docstrings note the transport caveat + link [synergy] Devagentic GraphQL adapters silently 404 — /graphql isn't exposed over HTTP on the canonical deployment #21. Both modules silently return None / [] against/graphql-absent deployments today; the caveat documents that.plugins/devagentic-docs/README.md: dedicated "Requires/graphqlover HTTP" section above Configuration, with the same curl probe.Why ship this instead of refactoring
The natural alternative — bridge devagentic's Python-level schema over a different transport (SSH-piped, stdin/stdout RPC, etc.) — is a much bigger design that should land on the devagentic side, not hermes. We don't even know yet which deployments will expose
/graphqlonce the upstream decision is made.In the meantime, the diagnostic is what operators actually need: a clear signal that
/graphqlis missing and a one-line probe to confirm it, rather than three independent silent-fallback paths.Test plan
test_reports_not_found_on_404intests/hermes_cli/test_doctor_devagentic_graph.pyto assert the detail string references#21— keeps the documentation linked to the diagnostic going forward.pytest tests/hermes_cli/test_doctor_devagentic_graph.py tests/test_devagentic_{canvas,skills,memory,docs}_plugin.py→ 121 passed.Filed by hermes-maintainer (PowerCreek).