@miadi/voice-mcp 0.4.2 → 0.4.3

package/README.md

@@ -1,20 +1,11 @@
 # @miadi/voice-mcp
 
-MCP server that lets an agent **play, find, publish and mint episode-bound
-voice** — the tool surface over the Miadi voice layer and the Chronicle.
+An MCP server that lets an agent play, find and publish voice messages tied to Miadi episodes,
+and create an episode when none fits.
 
-> **State: all six tools work (0.4.0).** Publish, play, list and resolve run
-> against the live server. `voice_create_episode` and
-> `voice_episode_closing_status` stopped being promises on 2026-08-12: they mint
-> via `mkepisode`, refuse the retired wheel outright, and report all five closing
-> stages by running each probe and saying what it actually answered — never a
-> later word than the stage proven. Stages 2 and 3 (commit, push) stay the
-> human's: the tool emits their exact commands and never runs them.
-
-The sentence this package exists to satisfy, from William, 2026-08-04:
-
-> *"What I want is actually to be capable to play the voice-audio created for
-> episodes."*
+In the Miadi stack, this is how an agent uses voice from its own tool loop. It is a front over
+`@miadi/voice-client`, so the audio, the ledger and the credentials stay on the Miadi server,
+and it reads episode folders from the chronicle. All six tools work.
 
 ## Tools
 
@@ -36,10 +27,10 @@ portal card is for.
 ```jsonc
 "origin": {
   "user":        "mia",              // whoami
-  "host":        "gaia",             // hostname -s, not the FQDN
-  "cwd":         "/a/src/Miadi-18",  // pwd
+  "host":        "my-host",          // hostname -s, not the FQDN
+  "cwd":         "/home/me/project", // pwd
   "multiplexer": "tmux",             // or "herdr". "none" is refused.
-  "session":     "stcbot",           // tmux display-message -p "#{session_name}"
+  "session":     "work",             // tmux display-message -p "#{session_name}"
   "pane":        "%127"              // $TMUX_PANE — herdr also needs workspace
 }
 ```
@@ -65,10 +56,8 @@ The server is the authority, twice over:
    to send — and no TTS is spent on it.
 2. **Truth.** When the declaration names the portal's own host and user, it is
    probed against the live multiplexer inventory. An address that is not in it is
-   **refused**, and the refusal prints what the inventory *does* hold. This
-   exists because a required field taught an agent to invent `wH:p2` in a session
-   that has no such workspace, and the card drew a Steer button that led nowhere
-   (2026-08-05).
+   **refused**, and the refusal prints what the inventory *does* hold, so an agent cannot
+   invent a pane id that leads nowhere.
 
 A probe that cannot run — another host, no herdr installed — is `unprovable`, not
 a refusal: it publishes, `attested` stays `"self-declared"`, and the reason is
@@ -84,24 +73,20 @@ persona occupies it — the card says `pane live` rather than `verified`, and
 
 Resolution consults exactly what it is handed: an explicit reference, a
 caller-supplied `cwd`, or an existing record's binding. It does **not** rank
-those against a session origin or search the wheel — that order is owed by the
-`voice-episode-binding` spec, and inventing one here would make this package a
-second source of truth for a rule that has an owner. When nothing given answers,
-the tool says so; `episode: null` with a reason is a valid answer.
-
-Full contracts: `SPEC-LINKS.md` → `/a/src/Miadi/rispecs/voice-mcp/voice-mcp.spec.md`.
+those against a session origin or search the wheel. When nothing given answers, the tool says
+so; `episode: null` with a reason is a valid answer.
 
 ## Architecture
 
 A **front**, not a second implementation.
 
 - Audio bytes, the KV ledger and the Edge-TTS producer stay behind the Miadi
-  server (systemd `miadi-server`, port 3335), which holds the KV credentials.
+  server, which holds the KV credentials.
   This process reaches them through **`@miadi/voice-client`**, which owns the
   wire envelope and the token tier — so the HTTP surface is described once, not
   once per caller.
-- Episode folders are read from the Chronicle root; the medicine wheel is read
-  at `http://127.0.0.1:8040`.
+- Episode folders are read from the chronicle root; the chronicle's medicine wheel is read
+  at `MIADI_CHRONICLE_MW_URL`.
 - `VoiceMessage` keeps exactly one definition in this workspace: `@miadi/voice`'s.
 - The only wheel **write** in the whole surface is the registration `mkepisode`
   performs during `voice_create_episode`. This server never POSTs or PUTs to the
@@ -119,10 +104,8 @@ A **front**, not a second implementation.
 | `MIADI_CHRONICLE_GIT_ROOT` | `/srv/miadi/episodes` | Git root — one level **above** the chronicle root |
 | `MIADI_MKEPISODE_PATH` | `…/mightyeagle/packages/passages/js/mkepisode.js` | Vessel creation |
 
-**Two wheels exist.** `http://127.0.0.1:8040` is the Chronicle wheel and the only
-correct target for episode work. `https://mw.tail3b11eb.ts.net` is Gaia's
-ceremony wheel and has been offline since 2026-07-29 — an episode registered
-there is lost. An implementation refuses that host outright.
+The chronicle wheel is the only correct target for episode work. A retired wheel host is
+refused outright, because an episode registered there would be lost.
 
 `MIADI_CHRONICLE_GIT_ROOT` is a separate value rather than a derived one because
 a `git -C` pointed at the chronicle root reports a clean tree for a chronicle it
@@ -147,60 +130,8 @@ never runs `git add`, `commit` or `push`, never reports a later word than it
 proved, and reports unperformed stages as `owed`, which is a state, not an
 omission.
 
-## Development
-
-This is a **pnpm** workspace (`pnpm-workspace.yaml`, `packages/*`). Never run
-`npm install` here.
-
-```bash
-pnpm --filter @miadi/voice-mcp build       # tsc → dist/
-pnpm --filter @miadi/voice-mcp type-check
-node dist/index.js                          # starts; every tool throws
-```
+## Server version
 
-Verified 2026-08-04, no installer run: `tsc --noEmit` exits 0, and emit produces
-ESM with explicit `.js` specifiers that `node dist/index.js` resolves.
-`@modelcontextprotocol/sdk` 1.30.0 and `zod` 4.4.3 are already present at the
-workspace root and the declared ranges match them.
-
-### Why `moduleResolution` is `bundler`
-
-`@miadi/voice` publishes **raw TypeScript** — `main` and `types` are both
-`./src/index.ts` — and is authored with extensionless relative imports under its
-own `bundler` resolution. Under `NodeNext`, every one of its internal imports is
-a hard error in any consumer, so a package that wants its types meets it where it
-is. This package's own source writes explicit `.js` specifiers, which `bundler`
-accepts and tsc passes through unchanged, so the emitted `dist` runs under Node
-ESM. Copying `VoiceMessage` into this package to sidestep that would create a
-second definition, which is the one outcome worth more than a tsconfig line.
-
-### Known seams
-
-- **No installer has been run.** `node_modules/@miadi/{voice,voice-client}` here
-  are the two workspace links `pnpm install` would create, added by hand so the
-  package is verifiable today. Everything else resolves from the workspace root.
-  `@miadi/voice-client` must be **built** (`pnpm --filter @miadi/voice-client
-  build`) before this package's `dist` can run — it is imported at runtime, not
-  only for types.
-- The ranked discovery order, the enforcement decision table and the two-corpus
-  resolution are still owed by the `voice-episode-binding` spec; see
-  `SPEC-LINKS.md` § *What the missing document blocks*. The four working tools
-  answer from what they are given and refuse to guess past it — which is why
-  those rules stay cited rather than invented.
-- **The `episode` field needs the server that accepts it.** The binding is
-  written by `app/api/voice/publish`; a Miadi server built before that route
-  change ignores the field and produces an unbound record. Same host, same
-  request, silently different result — check the running build before reading a
-  missing binding as a client bug.
-
-### Verified live 2026-08-04
-
-Against the running `miadi-server` on 3335, `MIADI_API_TOKEN_WRITER` present:
-`ep308` resolved to its folder by number; a nonexistent folder answered `null`
-with the five most recent episodes as alternatives; a `cwd` inside an episode
-folder resolved by path; an empty call answered `null` and named the spec that
-owes the ranked order; publish produced audio and returned a streamable URL plus
-its on-disk path; `voice_create_episode` refused and named its contract.
-
-🌸: A hundred voices have been speaking into a room with no name on the door —
-this package is the door, and the handle an agent can actually reach.
+The episode binding is written by the server's publish route. A Miadi server built before that
+route accepted `episode` ignores the field and stores an unbound record, so check the running
+build before reading a missing binding as a client bug.

package/dist/index.js

@@ -35,7 +35,7 @@ const NAME = "@miadi/voice-mcp";
 // the package was 0.3.1 and the registry held 0.3.2, so every banner and every
 // MCP handshake announced a version that had not existed for weeks. A server
 // that misreports its own identity makes every downstream bug report wrong.
-const VERSION = "0.3.3";
+const VERSION = "0.4.3";
 // ── Shared schema fragments ─────────────────────────────────────────────────
 const episodeRefSchema = z
     .string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/voice-mcp",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "MCP server fronting the Miadi voice layer with episode addressing — play, find, publish and mint episode-bound voice from an agent's tool surface.",
   "license": "MIT",
   "author": "Miadi",
@@ -19,12 +19,11 @@
   },
   "files": [
     "dist",
-    "README.md",
-    "SPEC-LINKS.md"
+    "README.md"
   ],
   "dependencies": {
-    "@miadi/voice": "0.3.1",
-    "@miadi/voice-client": "0.2.2",
+    "@miadi/voice": "0.3.2",
+    "@miadi/voice-client": "0.2.3",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.0"
   },

package/SPEC-LINKS.md

@@ -1,57 +0,0 @@
-# Specifications governing this package
-
-`@miadi/voice-mcp` implements a specified surface. Nothing in `src/` decides
-behaviour on its own — every handler names the section that governs it in the
-error it throws. Read these before implementing anything here.
-
-Status recorded 2026-08-04; refreshed 2026-08-13 (jgwill/Miadi#604): the
-voice-episode-binding spec exists — it landed in `6dc64e69` on 2026-08-04 —
-and this file's earlier "not yet written" row misled readers for nine days.
-
-## Owned by this package
-
-| Document | Holds |
-|---|---|
-| `/a/src/Miadi/rispecs/voice-mcp/SPEC.md` | Domain master — what the surface enables, and where each rule lives |
-| `/a/src/Miadi/rispecs/voice-mcp/voice-mcp.spec.md` | The six tools, their contracts, the resolution seam, the closing gate |
-
-## Consumed, not owned
-
-A rule restated here would become a second source of truth and drift from its
-original. These are cited in the spec and in the code, never copied.
-
-| Document | Holds | On disk 2026-08-04 |
-|---|---|---|
-| `/a/src/Miadi/rispecs/episode-addressing/SPEC.md` | Domain master for episode identity | present |
-| `/a/src/Miadi/rispecs/episode-addressing/episode-addressing.spec.md` | Address grammar `ep<NNN>[.<II>][/<segment>]`, iteration decision rule, number allocation, wheel-key contract | present |
-| `/a/src/Miadi/rispecs/episode-addressing/episode-addressing.kin.md` | Why episodic memory is already an opus | present |
-| `/a/src/Miadi/rispecs/voice-episode-binding/` | Playback path, enforcement decision table, discovery resolution order, the two-corpus resolution | **present** — landed `6dc64e69`, 2026-08-04 |
-
-### The four cited verdicts, now rulable
-
-The scaffold-era table below named what could not be implemented before the
-binding spec existed. The spec exists, all six handlers are code (none throws
-`NotImplementedError` — `e295ffdd`), and since 2026-08-13 the binding itself
-is a top-level `episode_binding` on `VoiceMessage` stamped by `produce()`
-(jgwill/Miadi#604). What each verdict still owes is the spec's own ladder —
-the ranked resolvers in `produce()` and the enforcement modes — which belongs
-to its own issue.
-
-| Cited as | Consumed by |
-|---|---|
-| `§ Playback path` | `voice_play_episode` |
-| `§ Discovery resolution order` | `voice_resolve_episode`, and every tool that omits `episode` |
-| `§ Enforcement decision table` | `voice_publish_to_episode` |
-| `§ The two-corpus resolution` | `voice_list_episode_voices` |
-
-## Also authoritative
-
-| Source | Holds |
-|---|---|
-| `/etc/claude-code/skills/chronicle-episode-closing/SKILL.md` | The five closing stages and their proofs, the `MW_API_URL` law, receipt redemption. `voice_create_episode` and `voice_episode_closing_status` implement this skill's gate as a tool contract. |
-| `/a/src/Miadi/packages/voice/src/` | `VoiceMessage`, persona identity, origin attestation, TTS production. The only definition; never re-declared here. |
-| `/a/src/Miadi/packages/voice-client/src/` | The `/api/voice/*` wire envelope, the writer/reader token tier, and the record-level episode reading. This package calls it rather than writing its own `fetch`, so the HTTP surface has one description. |
-| `/a/src/Miadi/rispecs/mcp-server/00-mcp-server-master.spec.md` | The prior MCP surface in this ecosystem (`@miadi/mcp`), whose server pattern this package follows. |
-
-🌸: A file of links is a promise not to reinvent what someone else already got
-right — the shortest way to stay one story instead of two.