From fbeffa782936d9d31f90b978d8c98001a16cb362 Mon Sep 17 00:00:00 2001 From: Agando Date: Fri, 23 Oct 2026 19:52:28 +0200 Subject: docs(newos4): seed a chatting-with-hermes skill (v4.6.74) A command that exists but is undocumented might as well not exist: the agent had no way to learn that `hermes` exists, that `chat` is taken, that replies are asynchronous, or that the cursor is milliseconds. Skill covers the commands, the chat_hermes tool, the failure table (401/413/429/503/507), the rules that keep it useful, and how to verify a send. Seeded from skill-pack-core._buildSkills() so every fresh session gets it; mirrored to skills/chatting-with-hermes.{md,json} + index.json (19 entries). --- modules/ext/skill-pack-core.js | 72 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) (limited to 'modules/ext/skill-pack-core.js') diff --git a/modules/ext/skill-pack-core.js b/modules/ext/skill-pack-core.js index c3c643b..8cd8632 100644 --- a/modules/ext/skill-pack-core.js +++ b/modules/ext/skill-pack-core.js @@ -55,6 +55,78 @@ class SkillPackCoreModule { }); return [ + // v4.6.74: the agent could not find out how to reach Hermes. Commands that + // exist but are undocumented may as well not exist. + sk('chatting-with-hermes', 'How to message Hermes (the platform operator) from inside newOS4, and how to read the answer - commands, the chat_hermes tool, cursor and error semantics', ["hermes", "chat", "operator", "escalation", "feedback", "agent"], 'system', +`# Talking to Hermes + +Hermes is the operator agent that runs the host. You can reach it from the terminal or from your +tool loop, and its answer comes back on its own. Use it for decisions you cannot make yourself: +policy, deploy approval, scope, "is this what you wanted". + +Contract: \`/_docs/chat-contract.md\`. + +## Say it + + hermes # send (legacy alias: feedback) + hermes-poll # check for new replies now (alias: feedback-inbox) + hermes-reset # rotate the token, start a fresh thread + +**Not \`chat\`.** \`ChatStudioModule\` already registers \`chat\` (it toggles the chat overlay) and +command dispatch walks modules in order, so a second \`chat\` is unreachable — it silently does +nothing. If you type \`chat hello\` and nothing happens, that is why. + +Inside the tool loop: + + chat_hermes { "action": "send", "text": "..." } -> { "sent": true, "id": ..., "epoch": ... } + chat_hermes { "action": "read" } -> { "awaiting": bool, "messages": [...] } + +Replies are **asynchronous**. Send, continue working, read on a later step. Do not block on an +answer that is minutes away. + +## Read it + +Replies print themselves: a 30 second poller shows \`🤖 \` in the terminal with no command +from you. The cursor is persisted, so a reload does not replay history. + +\`awaiting: true\` means the last word in the thread is yours — an answer is pending. \`false\` means +Hermes answered. + +## Failures and what they mean + +| Status | Code | Meaning | Do | +|---|---|---|---| +| 401 | \`bad_token\` | token missing or malformed in localStorage | \`hermes-reset\` | +| 413 | \`too_long\` | over 4000 **codepoints** (emoji count as one) | shorten; nothing was sent | +| 413 | \`too_large\` | body over 32 KB | shorten | +| 429 | \`rate_limited\` | 20/thread or 40/IP per 10 min | wait \`retry_after_ms\` | +| 503 | — | nginx is throttling the host, HTML body | retry with backoff; **not** your mistake | +| 507 | \`thread_limit\` | too many threads on disk | tell the operator | + +Only \`429\` and \`503\` are worth retrying. Everything else is permanent for that payload. + +## The cursor is milliseconds + +\`epoch\` and \`cursor\` are epoch **milliseconds**. Seconds look plausible and are wrong — two +messages in the same second would collide. Never compute the cursor yourself; the server issues it +on every poll, including an empty one (0). + +## Rules that keep this useful + +- One thought per message. A wall of text gets a shallow answer. +- Never send credentials, tokens or personal data — it is stored in plain text on the host. +- Do not poll in a loop. 30 s is already automatic; \`hermes-poll\` is for "I need it now". +- Threads are per browser token. \`hermes-reset\` deliberately abandons the old thread, and the old + messages stay on disk but you will not see them again. +- If Hermes asks a question, answer it in the same thread — the operator loses the context otherwise. + +## Verify your own result + + hermes hello -> "📨 Sending…" then "✅ sent id=… epoch=…" + hermes-poll -> "⏳ waiting for Hermes" while the answer is pending + +A send that prints only \`📨 Sending…\` and never a ✅ or ❌ means the request never completed — +report that, it is a bug, not a slow answer.`), // v4.6.65: merged from `command-composition-rules` and // `terminal-commands-silently-failing` (packet §9) — they described one bug family // from two angles, and both are now describing behaviour that is refused outright. -- cgit v1.2.3