diff options
Diffstat (limited to 'skills')
| -rw-r--r-- | skills/chatting-with-hermes.json | 17 | ||||
| -rw-r--r-- | skills/chatting-with-hermes.md | 76 | ||||
| -rw-r--r-- | skills/index.json | 20 |
3 files changed, 110 insertions, 3 deletions
diff --git a/skills/chatting-with-hermes.json b/skills/chatting-with-hermes.json new file mode 100644 index 0000000..d16578f --- /dev/null +++ b/skills/chatting-with-hermes.json @@ -0,0 +1,17 @@ +{ + "name": "chatting-with-hermes", + "description": "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", + "tags": [ + "hermes", + "chat", + "operator", + "escalation", + "feedback", + "agent" + ], + "category": "system", + "content": "---\nname: chatting-with-hermes\ndescription: 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\ntags: [hermes, chat, operator, escalation, feedback, agent]\ncategory: system\n---\n\n# Talking to Hermes\n\nHermes is the operator agent that runs the host. You can reach it from the terminal or from your\ntool loop, and its answer comes back on its own. Use it for decisions you cannot make yourself:\npolicy, deploy approval, scope, \"is this what you wanted\".\n\nContract: `/_docs/chat-contract.md`.\n\n## Say it\n\n hermes <message> # send (legacy alias: feedback)\n hermes-poll # check for new replies now (alias: feedback-inbox)\n hermes-reset # rotate the token, start a fresh thread\n\n**Not `chat`.** `ChatStudioModule` already registers `chat` (it toggles the chat overlay) and\ncommand dispatch walks modules in order, so a second `chat` is unreachable β it silently does\nnothing. If you type `chat hello` and nothing happens, that is why.\n\nInside the tool loop:\n\n chat_hermes { \"action\": \"send\", \"text\": \"...\" } -> { \"sent\": true, \"id\": ..., \"epoch\": ... }\n chat_hermes { \"action\": \"read\" } -> { \"awaiting\": bool, \"messages\": [...] }\n\nReplies are **asynchronous**. Send, continue working, read on a later step. Do not block on an\nanswer that is minutes away.\n\n## Read it\n\nReplies print themselves: a 30 second poller shows `π€ <text>` in the terminal with no command\nfrom you. The cursor is persisted, so a reload does not replay history.\n\n`awaiting: true` means the last word in the thread is yours β an answer is pending. `false` means\nHermes answered.\n\n## Failures and what they mean\n\n| Status | Code | Meaning | Do |\n|---|---|---|---|\n| 401 | `bad_token` | token missing or malformed in localStorage | `hermes-reset` |\n| 413 | `too_long` | over 4000 **codepoints** (emoji count as one) | shorten; nothing was sent |\n| 413 | `too_large` | body over 32 KB | shorten |\n| 429 | `rate_limited` | 20/thread or 40/IP per 10 min | wait `retry_after_ms` |\n| 503 | β | nginx is throttling the host, HTML body | retry with backoff; **not** your mistake |\n| 507 | `thread_limit` | too many threads on disk | tell the operator |\n\nOnly `429` and `503` are worth retrying. Everything else is permanent for that payload.\n\n## The cursor is milliseconds\n\n`epoch` and `cursor` are epoch **milliseconds**. Seconds look plausible and are wrong β two\nmessages in the same second would collide. Never compute the cursor yourself; the server issues it\non every poll, including an empty one (0).\n\n## Rules that keep this useful\n\n- One thought per message. A wall of text gets a shallow answer.\n- Never send credentials, tokens or personal data β it is stored in plain text on the host.\n- Do not poll in a loop. 30 s is already automatic; `hermes-poll` is for \"I need it now\".\n- Threads are per browser token. `hermes-reset` deliberately abandons the old thread, and the old\n messages stay on disk but you will not see them again.\n- If Hermes asks a question, answer it in the same thread β the operator loses the context otherwise.\n\n## Verify your own result\n\n hermes hello -> \"π¨ Sendingβ¦\" then \"β
sent id=β¦ epoch=β¦\"\n hermes-poll -> \"β³ waiting for Hermes\" while the answer is pending\n\nA send that prints only `π¨ Sendingβ¦` and never a β
or β means the request never completed β\nreport that, it is a bug, not a slow answer.\n", + "created_at": "2026-10-23T19:50:00+00:00", + "updated_at": "2026-10-23T19:50:00+00:00", + "source": "seed" +}
\ No newline at end of file diff --git a/skills/chatting-with-hermes.md b/skills/chatting-with-hermes.md new file mode 100644 index 0000000..0bc246a --- /dev/null +++ b/skills/chatting-with-hermes.md @@ -0,0 +1,76 @@ +--- +name: chatting-with-hermes +description: 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 +tags: [hermes, chat, operator, escalation, feedback, agent] +category: 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 <message> # 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 `π€ <text>` 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. diff --git a/skills/index.json b/skills/index.json index 4bce206..d9ac86d 100644 --- a/skills/index.json +++ b/skills/index.json @@ -108,7 +108,7 @@ }, "module-editing-workflow": { "name": "module-editing-workflow", - "description": "Step-by-step procedure for editing a WebX11 module: view \u2192 edit \u2192 test \u2192 keep or reload", + "description": "Step-by-step procedure for editing a WebX11 module: view β edit β test β keep or reload", "tags": [ "modules", "editing", @@ -121,7 +121,7 @@ }, "vfs-content-search": { "name": "vfs-content-search", - "description": "Find files in the VFS by semantic concept (NVFS) or by content keyword (grep) \u2014 decision table", + "description": "Find files in the VFS by semantic concept (NVFS) or by content keyword (grep) β decision table", "tags": [ "vfs", "search", @@ -148,7 +148,7 @@ }, "vfs-path-normalize": { "name": "vfs-path-normalize", - "description": "Strip trailing slashes from VFS paths before API calls \u2014 prevents /skills/ vs /skills resolution failures", + "description": "Strip trailing slashes from VFS paths before API calls β prevents /skills/ vs /skills resolution failures", "tags": [ "vfs", "utility", @@ -236,5 +236,19 @@ "category": "system", "created": "2026-10-23T16:27:07.000Z", "updated": "2026-10-23T16:27:07.000Z" + }, + "chatting-with-hermes": { + "name": "chatting-with-hermes", + "description": "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", + "tags": [ + "hermes", + "chat", + "operator", + "escalation", + "feedback", + "agent" + ], + "category": "system", + "updated_at": "2026-10-23T19:50:00+00:00" } }
\ No newline at end of file |