@crvouga/mockingbird-service-hermes 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog — @crvouga/mockingbird-service-hermes
 
-## 1.2.0 (2026-10-11)
+## 1.3.0 (2026-10-15)
+
+### Features
+
+- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
+
+## 1.2.0 (2026-10-08)
 
 ### Features
 

package/DISCOVERY.md

@@ -34,6 +34,7 @@ repository; live parity is an additional oracle check, not a substitute for the
 
 - `GET /__admin/health`
 - `GET /__admin`
+- `GET /__admin/controls`
 - `GET /__admin/state`
 - `GET /__admin/requests`
 - `GET /__admin/metrics`
@@ -44,6 +45,28 @@ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/p
 parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
 designed for assertions and diagnosis by consuming test suites.
 
+## Admin controls
+
+Every HTTP emulator takes the same controls, and each means the same thing at boot
+(`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
+
+| Control | Admin API | Request header | Interface |
+| --- | --- | --- | --- |
+| Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
+| Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
+| Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
+| Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
+| Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
+| Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
+| Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
+| Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
+| See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
+
+`GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
+is the namespace's current control document. The same seed and the same requests give the same
+bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
+the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
+
 ## Report a mismatch or missing capability
 
 Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,

package/README.md

@@ -17,19 +17,29 @@ bun add @crvouga/mockingbird-service-hermes
 ## Usage
 
 ```ts
-import { createRuntime } from "@crvouga/mockingbird-service-hermes"
+import { createServer } from "@crvouga/mockingbird-service-hermes/server"
+
+// Test setup: the emulator on an ephemeral loopback port.
+const server = await createServer({ seed: 42 })
 
-const hermes = createRuntime({ seed: 42 })
-const response = await hermes.fetch(new Request("http://hermes.mock/__admin/health"))
-console.log(await response.json())
+// Application code: the peer HTTP client's base URL is server.url.
+const baseUrl = server.url
+const accepted = await fetch(`${baseUrl}/v1/runs`, {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ input: "synthetic prompt" }),
+})
+console.log(await accepted.json()) // { run_id, status: "started", replayed: false }
+await server.close()
 ```
 
 Use the portable `HermesAPI` class for provider routes alone. `createRuntime`
 adds health, namespaces, admin controls, faults, clock, metrics, metadata-only
 request journal, and shared Timeline checkpoints. It needs no Hermes installation,
-provider account, prompt data, API key, or local service.
+provider account, prompt data, API key, or local service. Without a listener,
+`createRuntime().fetch(request)` serves the same routes in-process.
 
-For an HTTP endpoint:
+The admin controls share the origin:
 
 ```ts
 import { createServer } from "@crvouga/mockingbird-service-hermes/server"
@@ -94,22 +104,31 @@ The executable `mockingbird-hermes` provides `serve`.
 ## Script a run
 
 ```ts
-import { createRuntime } from "@crvouga/mockingbird-service-hermes"
+import { createServer } from "@crvouga/mockingbird-service-hermes/server"
 
-const hermes = createRuntime({ seed: 42 })
-const accepted = await hermes.fetch(new Request("http://hermes.mock/v1/runs", {
+const server = await createServer({ seed: 42 })
+const baseUrl = server.url
+const json = { "content-type": "application/json" }
+
+// Application code: submit a run.
+const accepted = await fetch(`${baseUrl}/v1/runs`, {
   method: "POST",
-  headers: { "content-type": "application/json" },
+  headers: json,
   body: JSON.stringify({ input: "synthetic prompt" }),
-}))
-const { run_id } = await accepted.json()
-await hermes.fetch(new Request(`http://hermes.mock/__admin/hermes/runs/${run_id}/observe`, {
+})
+const { run_id } = (await accepted.json()) as { run_id: string }
+
+// Test control: script the outcome. No agent runs, so nothing moves until you do.
+await fetch(`${baseUrl}/__admin/hermes/runs/${run_id}/observe`, {
   method: "POST",
-  headers: { "content-type": "application/json" },
+  headers: json,
   body: JSON.stringify({ status: "completed", output: "synthetic result" }),
-}))
-const status = await hermes.fetch(new Request(`http://hermes.mock/v1/runs/${run_id}`))
+})
+
+// Application code: poll the run.
+const status = await fetch(`${baseUrl}/v1/runs/${run_id}`)
 console.log(await status.json())
+await server.close()
 ```
 
 Admission returns 202 `{ run_id, status: "started", replayed: false }`. The stored