Skip to content

Hermes: run Floorplan as a native Hermes plugin - #114

Open
leonardsellem wants to merge 6 commits into
haydenschmitty:mainfrom
leonardsellem:feat/hermes
Open

leonardsellem wants to merge 6 commits into
haydenschmitty:mainfrom
leonardsellem:feat/hermes

Conversation

@leonardsellem

Copy link
Copy Markdown

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.

 floorplan/
+├── plugin.yaml                       # Hermes manifest: no hooks, tools, MCP servers or dependencies
+├── __init__.py                       # registers /floorplan:floorplan and `hermes floorplan`
+├── hermes/runner.py                  # model-free probe, and the Ask worker (it has no tools)
 ├── skills/floorplan/
 │   ├── SKILL.md                      # + a Hermes paragraph (--agent hermes, no CLAUDE.local.md)
 │   ├── scripts/lib/agent.mjs         # + hermes, only when named, never guessed
 │   └── assets/
+│       ├── hermes-boundary.mjs       # what the worker may read, schema checks, single-use read tickets
 │       ├── serve.mjs                 # + the hermes engine, Stop, Change publication
 │       └── viewer.html               # + Hermes labels and attribution
+├── docs/hermes.md                    # install, use, read limits, Change, upgrade, rollback, support matrix
 └── tests/                            # + 7 hermes-*.test.mjs and hermes_runner_test.py (fake Hermes CLI, no model calls)

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 today
Loading

Evidence

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:

  • Tests: node --test gives 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 Code: claude plugin validate . passes.
  • Install: hermes plugins install <fork>/floorplan --ref 84b8b5d --no-enable --force on 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 --ci passes, and hermes floorplan probe reports "ask": "ready". Enabling it changed only the plugin list and Floorplan's own entry in the profile config.
  • Map: a ~50-file Python service, built with build.mjs --agent hermes: descriptions 51/51 files and 16/16 modules. The project's git tree stays clean.
  • Ask, on a real question set: 6 questions (one through the Ask bar in a real browser, five through the same HTTP endpoint), plus one follow-up in the same session. All 6 were answered and so was the follow-up, each in 23–60 s with 3–7 lookups. Every answer cites real map ids. The Hermes audit log shows each model call (44) as plugin_llm.complete_structured plugin=floorplan on 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 the 0o600 file mode and 0o700 folder 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) and viewer.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

  • Install needs a yes, or --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.
  • Ask needs a model that follows a JSON format. On Claude through Hermes it answered 6 of 6. On DeepSeek V4 Flash, through Hermes' fallback, it gave no valid answer in 17 tries: its tool-call markup leaks into the reply, it invents map ids, and it never stops looking things up. The Ask bar then shows an error; the map itself is unaffected.
  • Platforms. Not tried on macOS. Windows-native Hermes Ask is unsupported (the map still opens offline), and the Ask bar then says Hermes isn't installed rather than that the platform isn't supported.
  • The supply-chain tripwires are textual. A dynamic importlib import, an os.open line that mentions flags, or a stray .pyc outside __pycache__ would get past them.
  • Windows CI. On my fork, tests/public-by-design.test.mjs (unchanged here) failed once on Windows Node 18 with build.mjs exiting non-zero and no stderr, and once at an earlier head with scan.mjs; both re-runs passed. I couldn't attribute it.
  • Reinstalling prints "declares Node dependencies (package.json)… Skipped Node deps". There are none: package.json only gives npm test a home.
  • Size. 47 files. Happy to split it (plugin and probe, Ask, Change, docs) if that's easier to review.

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".

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant