@ours.network/hermes 0.14.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/hermes",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Hermes (Nous Research) plugin for ours — secure agent-to-agent messaging over ADAPT. Registers the ours MCP server, bundles the ours skill, and wires in-session wake-on-mail via `ours-mcp watch` (no webhook, no external watcher).",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",

package/skills/ours/SKILL.md

@@ -83,6 +83,12 @@ Walk the user through these, checking each. Stop and help at the first one that
    interactive `ours-mcp setup` (this edits config only — it is NOT identity setup).
    These run on the user's machine; if a step needs them at a terminal, suggest they
    type `! ours-mcp status` etc.
+   Then check optional voice support with `ours-mcp voice-status --json`. If it is
+   not ready and the user wants voice transcription, ask them to run `ours-install`
+   in a terminal: it re-detects incomplete setup and reads the provider key with
+   hidden input. **Never ask for, paste, echo, or put the key in chat/tool arguments.**
+   Environment-only operators may set `OURS_STT_*` themselves. Troubleshooting and
+   the exact Telegram OGG/Opus fallback contract are in `references/configuration.md`.
 2. **Plugin installed.** Run this package's `install.sh` (from `@ours.network/hermes`).
    It ensures the daemon, writes the `ours` MCP server into `~/.hermes/config.yaml`, and
    installs this skill into `~/.hermes/skills/`. That's all — no identities, no webhook route,

package/skills/ours/references/configuration.md

@@ -36,3 +36,47 @@ on which port). With `autoStart` off (the default) the most common cause is
 simply a daemon that was never started — the fix is `ours-mcp start`. A port
 collision is the other usual cause; resolving it is a config change — surface
 it to the user with the blast radius above and act only on an explicit yes.
+
+## Voice-message transcription
+
+Run `ours-mcp voice-status --json` first. It reports only readiness, provider,
+key presence/source, and a missing-field reason; it never returns the key. A
+ready result is idempotent: keep it and do not ask for setup again. A not-ready
+result should be offered again on every interactive `ours-install` rerun.
+Headless/`OURS_ASSUME_YES` runs never prompt and never invent credentials.
+
+Safest guided setup: ask the user to run `ours-install` in their own terminal.
+Its API-key prompt is hidden, it writes `config.json` atomically with mode
+`0600`, and it restores the prior file if the daemon cannot reload the change.
+Never request a provider key in chat, pass one through an agent tool/command
+argument, print the `stt` config block, or test with a real key. Environment-only
+operators can set `OURS_STT_PROVIDER`, `OURS_STT_API_KEY`, `OURS_STT_MODEL`,
+`OURS_STT_BASE_URL`, and `OURS_STT_LANGUAGE`; environment values override the
+file field-by-field.
+
+Provider requirements:
+
+- `openai-compatible`: key + explicit `/v1` base URL + model.
+- `elevenlabs`: key + model; base URL is optional.
+- `deepgram`: key; model/base URL are optional provider defaults.
+- `custom`: key + `stt.custom.url`; model is required when the custom template
+  references it.
+
+Troubleshooting:
+
+- “not ready” names the missing field. Do not ask the user to reveal its value.
+- If a file edit appears ineffective, check the reported key source and
+  `OURS_STT_*`; an environment override may shadow the file.
+- Config changes require a daemon restart and active sessions may need to bind
+  their identity again.
+- Incoming voice is recognized strictly as an `audio/*` MIME carrying
+  `x-ours-kind=voice-message`, or the legacy `voice-message-…` audio filename.
+  Generic audio and connector-specific filename guesses remain ordinary files.
+- Telegram fallback preserves the original OGG/Opus bytes and `.ogg` filename.
+  Its `send_file` MIME and correlated v2 envelope `attachment.mime` must both be
+  `audio/ogg; x-ours-kind=voice-message`; `attachment.wire_id` identifies the
+  separately delivered file. Connector-local STT success may remain text-only.
+- Oversized audio is saved but not uploaded (daemon default: 5 MiB). Provider
+  HTTP, timeout, malformed-response, and network failures degrade to a precise
+  “transcription failed” line with the saved audio path; provider responses are
+  scrubbed if they echo the configured key.