Repository navigation
Hermes: run Floorplan as a native Hermes plugin - #114
Open
leonardsellem wants to merge 6 commits into
Open
leonardsellem wants to merge 6 commits into
leonardsellem wants to merge 6 commits into
Conversation
Floorplan now installs into Hermes Agent as a native plugin, next to Claude Code and Codex: a root plugin.yaml and __init__.py register the same shared skill (/floorplan:floorplan) and one on-demand `hermes floorplan` command. Maps are built, refreshed and opened with --agent hermes; the map's Ask bar, guided flows and blueprint Change run through the selected Hermes profile. - Ask: a Python worker with no tools asks the map's server for one lookup at a time. The server lets it read only files in the map's own scan, through a confined no-follow reader with hash-bound single-use tickets, and validates every answer against the existing schemas. Stop kills the request's process group. - Change: staged, preserve-first publication of map-owned files, with the existing validators, one retry and Undo. - Lifecycle: install, upgrade, rollback and uninstall are documented in docs/hermes.md; the checksum and supply-chain tests cover the new Python/YAML files; CI adds Linux Node 24 and the POSIX Python tests. Claude Code and Codex behaviour is unchanged. Windows-native Hermes Ask reports unsupported_runtime; the map still works offline there.
- Ask: when a provider can't enforce the decision schema, Hermes sends the request without one and the model may add text after a valid decision (seen with DeepSeek as `...}</index>`). The worker now takes the first JSON object in the reply and checks it like any other decision, instead of ending the request with invalid_decision. - Install: Hermes scans plugins from outside its catalog, rates Floorplan CAUTION and blocks the install until --force. README.md and docs/hermes.md say so. - serve.mjs keeps only the first line of `<cli> --version` (Hermes prints its install folder, Python and SDK versions after it), and its header names Hermes and the --profile and --hermes flags. - docs/hermes.md: a request without an Origin is accepted, as the code does.
Trying the Ask on a profile that had fallen back to DeepSeek (which takes
no JSON schema) still failed after the previous fix: the model sometimes
answers with the payload alone, without {"kind":"final"}, which the host's
schema check refused outright; or puts an echoed object before the
decision, or raw newlines inside the answer.
- The worker now asks the host for JSON mode, with the decision schema in
the prompt, so the host no longer refuses a reply this worker accepts.
- decision() takes the first valid decision among the reply's JSON objects
(raw newlines allowed in strings), and a bare payload that carries every
key the payload schema requires counts as the final answer. The server
still validates every payload, and lookups still go through its read
boundary.
Docs: CHECKSUMS.txt describes releases only. The install steps now say to
pin a release's commit, and that a commit between releases fails the
check; the release notes and the safety page say tools/checksums.mjs lists
the native files, so each release's CHECKSUMS.txt fingerprints them. The
upgrade step names the --force a reinstall needs.
…needs it Checked against the Claude subscription provider (which projects a JSON schema onto Anthropic's structured output), the decision schema was refused before any answer: "For 'object' type, 'additionalProperties' must be explicitly set to false". `args` and `payload` were open objects. - The worker asks the host for the schema again, not bare JSON mode: the same provider refuses JSON-object-only mode, while it, and OpenAI, take a schema. A route that can't take one (DeepSeek through Hermes' fallback) still gets the request without it, and decision() digs the decision out of the reply text, as before. - `args` lists the boundary's own argument names, and each request puts the payload schema the server sent in place of the open `payload`. Every object in the schema sent now says additionalProperties: false. The server still checks bounds and the payload, as before.
- tests/release.test.mjs requires the version heading's date again
(`## X.Y.Z (YYYY-MM-DD)`), as upstream does; this branch had loosened
it while refactoring the version pattern.
- A bare payload counts as the final answer only when the reply has no
"kind" key at all; {"kind": null, ...} is refused as not a decision.
- A test pins the args list the worker sends to the provider to the
boundary's own (hermes-boundary.mjs), so the two can't drift apart.
- README.md and docs/hermes.md: in a terminal, Hermes' install scan asks
"Install anyway? Only continue if you trust the source. [y/N]"; only
without a terminal does it stop until --force.
Upstream moved from 0.6.3 to 0.7.3 while this branch waited. Seven files conflicted; each keeps upstream's change and adds the Hermes part: - agent.mjs: the "none" agent and unattended mode, plus "hermes". - build.mjs: serve.mjs and page-safety.mjs are written fresh (read-only installs); hermes-boundary.mjs joins that loop instead of being copied, so a read-only install can build a Hermes map twice. The AGENT report line covers Codex, Hermes and none. - refresh.mjs: upstream's runBuild (--json) everywhere, fed the flags this refresh was given, values included, so `--agent hermes` survives a blueprint refresh (upstream's blueprint path passed flags without their values). - serve.mjs: scriptJson and the page's Content-Security-Policy, plus the Hermes fields and the schema check at start. A Hermes Change now also publishes page-safety.mjs, which serve.mjs imports. - viewer.html: upstream's agent ternary gains a Hermes branch; the "none" label names Hermes among the agents. - CHANGELOG.md: Unreleased stays on top of 0.7.3..0.7.0. - docs/development.md: both sets of test rows. Also: plugin.yaml says 0.7.3 like the other manifests; tests follow the extra placed/published file (read-only-install, hermes-blueprint-change), the Hermes label is checked next to Claude/Codex/none in unattended.test, and hermes-generation.test reads the multi-line AGENT statement.
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
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
Floorplan installs into Hermes Agent as a native plugin, alongside Claude Code and Codex. It uses the same skill, scripts and map. Hermes builds and refreshes the map with
--agent hermes, and the map's Ask bar, guided flows and blueprint Change answer through the selected Hermes profile. Claude Code and Codex behave as before.How an answer stays read-only:
sequenceDiagram participant Page as Map page participant Server as serve.mjs participant Worker as hermes floorplan ask (no tools) participant Model as the profile's model Page->>Server: question (token, same origin) Server->>Worker: question, map overview, answer schema loop up to 8 decisions, 7 lookups Worker->>Model: answer, or ask for one lookup Worker->>Server: one lookup Server-->>Worker: map data, or text from a scanned file only (deny list, 200 lines / 32 KiB, hash-bound single-use ticket) end Worker-->>Server: answer Server-->>Page: answer, checked against the same answer schema as todayEvidence
There's no CI here for this branch, so I ran everything on Linux (x86_64, Node and Python 3.14), on the branch head
84b8b5d, from a fresh clone:node --testgives 373 tests, 371 pass, 0 fail, 2 skipped.python3 -m unittest discover -s tests -p 'hermes*_test.py': 31 run, OK. On my fork, the Tests workflow passed on the same head.claude plugin validate .passes.hermes plugins install <fork>/floorplan --ref 84b8b5d --no-enable --forceon Hermes Agent v0.22.5, into a profile that didn't have it (my main profile runs the same head). All 200 tracked files are byte-identical to the commit,hermes plugins doctor --cipasses, andhermes floorplan probereports"ask": "ready". Enabling it changed only the plugin list and Floorplan's own entry in the profile config.build.mjs --agent hermes: descriptions 51/51 files and 16/16 modules. The project's git tree stays clean.plugin_llm.complete_structured plugin=floorplanon the profile's Claude model, with no fallback call. Example: asked "where is a card stored, and who can read that file?", it named the SQLite file and its default location, and quoted the0o600file mode and0o700folder mode from the store's source. It then offered three follow-ups. I checked the files the answers cite, and they exist and say what the answer says.Merge Danger
Door: two-way. It adds files and one engine; reverting the commits removes Hermes support and nothing else.
Blast Radius: contained. The shared touches are
serve.mjs(the engine table and request lifecycle) andviewer.html(labels). Existing tests keep passing; the ones that list agents, manifests, placed files or allowed programs gain Hermes cases. CI gains a Linux Node 24 job and a POSIX Python job.Known limitations
--force. Hermes scans every plugin from outside its catalog and rates Floorplan CAUTION (mostly the vendored layout engine reading as obfuscated, and the skill's!status line reading as a command). In a terminal it asks whether to install anyway; without one it stops until you add--force. README.md and docs/hermes.md say so.importlibimport, anos.openline that mentionsflags, or a stray.pycoutside__pycache__would get past them.tests/public-by-design.test.mjs(unchanged here) failed once on Windows Node 18 withbuild.mjsexiting non-zero and no stderr, and once at an earlier head withscan.mjs; both re-runs passed. I couldn't attribute it.npm testa home.No issue covers Hermes yet, so there's nothing to link; I can open one first if you'd rather discuss it there. The branch is up to date with main (0.7.3): the merge commit lists how each conflict was resolved. There's no version bump; the changelog entry is under "Unreleased".