agents can transcribe an audio file: the transcribe_audio tool, through the harness and the speech-to-text service

docs/4-implementation/turn-loop/mcp.md

@@ -95,7 +95,7 @@ hive_name?, swarm_name?, matrix_accounts? }`. `matrix_accounts` is a
   `name` to query self.
 
 **Always-on, no permission needed**: `set_status(text)`, `compact()`,
-`mark_todos_done(ids)`.
+`mark_todos_done(ids)`, `transcribe_audio(path)`.
 
 - `set_status` — set a free-text status string visible on the
   dashboard. Single line, ≤ 200 chars. Persisted to
@@ -112,6 +112,15 @@ hive_name?, swarm_name?, matrix_accounts? }`. `matrix_accounts` is a
   notes-checkpoint turn still fires first. Dispatched through the
   in-agent socket (`hive-agent-sock::Request::Compact`), not the
   broker — see `hive-agent/src/todo_server.rs`.
+- `transcribe_audio(path)` — the text spoken in an audio file (a matrix
+  voice memo that `download_file` saved, or any Ogg, WAV, FLAC, MP3, AMR,
+  MP4/M4A or WebM file up to 6 MiB). Dials the in-agent socket
+  (`hive-agent-sock::Request::Transcribe`) with a 16-minute deadline; the
+  harness reads the file and sends it over the swarm queue on this agent's
+  request subject to the speech-to-text service
+  ([`stt.md`](../swarm/stt.md)), which keeps each transcript for a day by the
+  audio's hash. An error names why: no service running, a file that isn't
+  audio, too large, or the service busy.
 - `mark_todos_done(ids)` — bulk-clear specific loose-ends-v2 todo rows
   by id in one call, instead of `cancel_loose_end`ing each one.
   List-based: pass the ids `get_loose_ends` actually showed you reviewed;

docs/5-project/process/conventions.md

@@ -274,7 +274,7 @@ host access it has.
 | `metrics` | the metrics store: `swarm-metrics` queries. Checked by `swarm-metrics-agent-auth`, the same binary, for the metrics gateway. Off by default. |
 
 **Always-on tools** — `Permission::ALWAYS_ON_TOOLS` exposes `set_status`,
-`compact`, and `mark_todos_done` to every agent regardless of its
+`compact`, `mark_todos_done` and `transcribe_audio` to every agent regardless of its
 permissions. The operator dashboard depends on every agent being able to
 report its status chip, and the server-side `SetStatus` handler has no
 permission check (only length validation), so gating it would only desync
@@ -282,6 +282,9 @@ the `--allowedTools` list from what the host actually accepts. Revoking
 `meta` therefore drops `get_agent_meta` but never `set_status`.
 `mark_todos_done` is here because producers push todos to an agent whether
 or not it holds `inbox`, and an agent without it still needs to clear them.
+`transcribe_audio` is here because it only turns an audio file the agent
+already holds into text through the swarm's service; it reaches nothing the
+agent couldn't read.
 
 **Where they live** — in the swarm, not on the hive: the `permissions` field of
 the agent's key in the `agent-permissions` KV bucket