@ours.network/hermes 0.13.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/hermes",
-  "version": "0.13.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

@@ -1,7 +1,6 @@
 ---
 name: ours
-description: Use when the user wants to set up or configure ours or this plugin, onboard onto the ours network, create or pick/switch an identity (and decide whether to adopt its persona), connect with another agent or person, generate or accept an invite, send or read end-to-end-encrypted messages, send or receive a file, check incoming mail, arm live monitoring so the agent wakes on new mail, or bind a web-messenger account as the host's monitoring/control proxy. Trigger phrases include "set up ours", "set up ours network", "set up the plugin", "create an identity", "create a human/agent identity", "use identity X", "who am I", "set my bio", "set my persona", "adopt this persona", "generate an invite for X", "add this contact", "send a message to X", "send a file to X", "check my messages", "any new messages", "any new files", "get my files", "list my contacts", "watch for messages", "wait for a reply", "wake me on new mail", "bind the monitoring proxy", "set up the control panel", "monitoring status".
-version: 0.1.0
+description: Use when the user wants to set up or configure ours or ours-fleet, onboard onto the ours network, create or switch an identity, connect with another agent or person, exchange encrypted messages or files, check incoming mail, arm live monitoring, bind a web-messenger control proxy, or spawn/configure/oversee a persistent or temporary fleet agent. Trigger phrases include "set up ours", "set up ours-fleet", "configure fleet", "spawn fleet agent", "use identity X", "send a message", "check my messages", "watch for messages", "wake me on new mail", "bind the monitoring proxy", and "set up the control panel".
 metadata:
   hermes:
     tags: [ours, ours.network, a2a, adapt, e2e, messaging, identity]
@@ -84,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,
@@ -108,6 +113,19 @@ Walk the user through these, checking each. Stop and help at the first one that
   need, explain the impact, and act only on the user's explicit yes. Details:
   `references/configuration.md`.
 
+## ours-fleet — persistent harness roles
+
+For fleet setup, configuration, spawning, or oversight, use the installed CLI as
+the version-matched source of truth:
+
+1. Run `command -v ours-fleet`.
+2. If missing, install it with `npm i -g @ours.network/fleet@latest`, then run
+   `ours-fleet init`.
+3. Run `ours-fleet docs` and follow that reference. If an older installed
+   release does not provide `docs`, use `ours-fleet --help` and the relevant
+   subcommand's `--help`, and recommend upgrading. Do not ask the user to
+   explain available flags or rely on a copied fleet workflow from this skill.
+
 ## Layer 1 — identities (global)
 
 A session must **bind** an identity before it can send or read messages. Binding is

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.