# @crvouga/mockingbird-service-hermes

> Local emulators. Real API contracts. Part of [Mockingbird](https://github.com/crvouga/mockingbird).

Work-in-progress emulator for the Hermes Agent public peer-run API pinned to
`v2026.8.31`. Submission, polling and stop work with explicit synthetic lifecycle observations.
Events, approval and steer remain unsupported. No agent or inference runs.
[API_EVIDENCE.md](API_EVIDENCE.md) records source-backed semantics and gaps;
[SUPPORT.md](SUPPORT.md) records current operation support.

## Install

```sh
bun add @crvouga/mockingbird-service-hermes
```

## Usage

```ts
import { createServer } from "@crvouga/mockingbird-service-hermes/server"

// Test setup: the emulator on an ephemeral loopback port.
const server = await createServer({ seed: 42 })

// 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. Without a listener,
`createRuntime().fetch(request)` serves the same routes in-process.

The admin controls share the origin:

```ts
import { createServer } from "@crvouga/mockingbird-service-hermes/server"

const server = await createServer() // ephemeral loopback port
try {
  console.log(await (await fetch(`${server.url}/__admin/health`)).json())
} finally {
  await server.close()
}
```

The CLI is `mockingbird-hermes serve --port 8827`. Point a peer HTTP client's base
URL at `http://127.0.0.1:8827`; submission returns immediately while execution remains queued until scripted.
The Node entry is separate from the portable Fetch entry.

## Routes and controls

`POST /v1/runs` admits a run and `GET /v1/runs/{run_id}` polls it.
`POST /v1/runs/{run_id}/stop` requests interruption. Events, approval and steer
return an emulator-only 501 envelope with `error.type` of
`mockingbird_unsupported` and `error.code` of `operation_not_implemented`.
Missing runs use the pinned `run_not_found` 404 envelope. Unknown paths return
404. Emulator-only errors do not claim real Hermes rejection behavior.

- `GET /__admin/health` identifies the `hermes` runtime.
- Select isolated namespaces with `x-mockingbird-namespace` or `/__admin/ns/<name>/…`.
- `POST /__admin/reset` clears selected provider state and Timeline. Shared clock,
  faults and diagnostic journal retain their standard independent lifetimes.
- `POST /__admin/clock` controls the shared clock.
- `POST /__admin/faults` configures scoped operation/path/method fault rules;
  `DELETE /__admin/faults` clears them. Named Hermes presets are documented below.
- `GET /__admin/requests` exposes request metadata without bodies, query values
  or credentials. `DELETE /__admin/requests` clears selected diagnostic history.
- `POST /__admin/checkpoints` captures shared Timeline state. Checkout through
  `POST /__admin/branches/<name>/checkout` with `{ "checkpoint": "cp_…" }`.

The existing shared `adminKey` option controls admin access. No credential-based
namespace mapping or Hermes provider authentication logic is introduced.

## API

The portable entry exports:

- `HermesAPI`: provider `fetch` and `reset`, with namespace and shared SQLite storage.
- `HERMES_NAMESPACE`: the default storage namespace, `hermes`.
- `createRuntime`: the standard service runtime and shared controls.
- `document`: annotated OpenAPI contract.
- `operationIds`: all inventoried operations.
- `supportedOperationIds`: `RunCreate`, `RunGet`, and `RunStop`.

The Node-only `/server` entry exports:

- `createServer`: returns `runtime`, `server`, `url`, `host`, `port`, and `close`.
- `DEFAULT_PORT`: CLI default 8827; programmatic calls default to an ephemeral port.
- `serveTarget`: shared CLI server target.

Types include `HermesAPIOptions`, `HermesRuntime`, `HermesRuntimeOptions`,
`OperationId`, `SupportedOperationId`, `HermesServer`, and `HermesServerOptions`.
The executable `mockingbird-hermes` provides `serve`.

## Script a run

```ts
import { createServer } from "@crvouga/mockingbird-service-hermes/server"

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: json,
  body: JSON.stringify({ input: "synthetic prompt" }),
})
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: json,
  body: JSON.stringify({ status: "completed", output: "synthetic result" }),
})

// 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
status starts as `queued`. Repeated polling does not advance execution or time.
Use the same namespace on submission, observations and polling. Optional
`session_id` defaults to the run ID when absent or falsy. `model` defaults to
`hermes-agent` only when absent; an explicit null or empty value is retained, as
in the pinned handler. A valid `X-Hermes-Session-Key` is echoed without deriving a
conversation ID or authenticating credentials. Model routing and transcript loading
are not simulated. IDs are deterministic opaque hex strings, separate from sessions.

The observation control accepts `status`: `queued`, `running`,
`waiting_for_approval`, `stopping`, `completed`, `failed`, `cancelled`, or
`interrupted`. It accepts optional `last_event`; `approval` only while waiting;
`error` only for failed/interrupted; and `output`, `usage`, `pending_steer` only
for completed. Usage has three nonnegative integer counts: `input_tokens`,
`output_tokens`, `total_tokens`. Completion defaults to empty output and zero counts.
Terminal observations cannot be changed (409); invalid control payloads return 400
without changing state. These are emulator controls, not additional Hermes routes.

Timestamps are Unix seconds from the shared clock. Run records and their identity
sequence use shared storage and Timeline; reset clears them. No timers, agent
handles or prompts are stored. Polling result content stays out of journals.
Malformed roots/final input elements, hosted rooms and invalid memory-scope headers
currently return explicit emulator-only 501 responses. See evidence for these limits.

## Idempotent submission and synthetic scope

Send `Idempotency-Key` to reserve a delivery. Identical retries return 202 with
the original run ID, its current status, `replayed: true`, and
`Idempotency-Replayed: true`. A changed payload with the same scoped key returns
409 `idempotency_key_conflict`. Concurrent identical requests reserve one run.
Empty/whitespace keys disable deduplication; other keys must contain 1–255 visible
ASCII characters after Python-style trimming. Validation errors reserve nothing.

The fingerprint covers the entire parsed JSON body, including unknown fields,
and the trimmed `X-Hermes-Session-Key`. Object key order does not matter; array
order and session/body changes do. Raw integer/float forms follow Python:
`1` and `1.0` conflict, `1.0` and `1e0` replay, and negative floating zero differs
from positive zero. Lone Unicode surrogates return an explicit emulator-only 501;
Python cannot UTF-8 encode that fingerprint either.

`POST /__admin/hermes/scope` with `{ "profile": "synthetic-profile",
"identity": "synthetic-listener" }` selects an explicit synthetic scope within
the current Mockingbird namespace. Defaults are `default` and
`unauthenticated-test-listener`. Use only synthetic labels, never credentials.
Changing scope isolates reservations and public polling; returning to it restores
access to its runs. Session IDs and memory keys are not scope selectors, and
bearer text is ignored. This control does not implement authentication.

Reservations and owners survive reconstructing a `HermesAPI` with the same
SQLite client and namespace. Terminal replay is verified after that modeled
adapter reconstruction. Actual process/disk durability and unfinished-run restart
outcomes are modeled by the explicit restart control below. Shared
Timeline restores scope, reservations and run records together; reset clears them.
No public key-lookup endpoint is added. Request bodies are hashed in memory and
not persisted; stored reservations contain the key, hash, run identity and durable observation.

## Stop and logical restart

`POST /v1/runs/{run_id}/stop` returns 200 `{ run_id, status: "stopping" }` for
locally active work. Repeated stop requests retain that intermediate state. Use
`observe` to script the eventual outcome: `cancelled` for acknowledged interruption,
`completed` when normal completion wins the race, or `failed` for execution failure.
Stopping a terminal run returns its full unchanged status, not a new cancellation.
Missing or inaccessible runs return 404 `run_not_found`.

`POST /__admin/hermes/restart` with `{ "owner": "stale" }` models loss of the
current namespace's gateway. It discards cached observations and retains surviving keyed durable
reservations across all synthetic profiles in that namespace. An unfinished keyed
run becomes `interrupted` when next polled, replayed or stopped, with
`The gateway restarted before this run settled.` and `run.interrupted`.
Its creation timestamp remains intact; its update timestamp reflects that first
observation. Terminal runs retain their status and result. Retrying an old delivery
key replays the interrupted run; a new key creates a different run.

Use `{ "owner": "alive" }` to model another live owner after gateway replacement.
Keyed observations stay unchanged, but stopping unfinished foreign work returns
409 `run_not_active`. An explicit `observe` can represent that owner's eventual
completion. Neither control reads PIDs, interrupts a real process, or runs an agent.
It is a logical scenario, not a process/disk durability guarantee. Shared Timeline
restores the owner flags and run/reservation state together.

## Retention and history

The controlled clock governs two independent retention layers. Cached `completed`,
`failed` and `cancelled` results expire when their update age is strictly greater
than one hour; equality survives and `interrupted` is excluded. The emulator evaluates
elapsed 60-second sweep ticks on admission or observation, without a background
process. `POST /__admin/hermes/sweep` with `{}` explicitly executes one sweep at the
current clock, returning `cacheRemoved` and `simulated: true`.

Keyed terminal reservations expire only when their durable update age is strictly
greater than 24 hours. Valid keyed admission triggers that pruning, including a
request that subsequently conflicts. Polling and keyless admission do not prune
durable rows. Active reservations never expire by age. Polling can recover a
retained durable result after cache eviction, even beyond 24 hours before pruning;
a cached result can also temporarily outlive its pruned reservation. Missing results
return the ordinary 404 `run_not_found`, without an invented expired state.

Same-status progress observations update cached timestamps but do not persist the
new progress payload unless a selected durable field changes. Logical restart
clears cached observations and hydrates only surviving durable rows. Timeline
restores both layers, ownership, the sweep schedule and controlled clock together.
These are shared-storage and logical-restart guarantees, not process-crash or disk
durability evidence. SSE buffer and hosted-room retention remain outside the subset.

## Fault and consumer scenarios

Use `POST /__admin/faults` with `{ "preset": "hermes_submit_accepted_drop" }` to
admit one new run and lose its response. The shared journal records acceptance and
its checkpoint even though delivery fails. Retry the same body and idempotency key
to recover the original run. Validation failures still return their normal errors.

Other one-shot presets are `hermes_poll_timeout` (delay one poll by 1000ms),
`hermes_throttled` (429 with the pinned default-capacity envelope), and
`hermes_draining` (503 with the pinned draining envelope). Both rejection presets
include `Retry-After: 1` and run before admission. These are explicit scenarios;
they do not automatically count capacity or simulate a real draining gateway.
To script an executor failure, use `observe` with `status: "failed"` and synthetic
`error` text, then poll or replay the same run.

The Node HTTP consumer fixture owns its disposable server and uses an independent
HTTP client to test lost responses, replay, polling, stopping, client deadlines and
expiry. It does not import Initiative or impose a consumer retry policy. Property
tests compare eligible peer operations and assert coverage; a seeded poll check
injects a schema-valid lifecycle divergence to test the comparator. Self-parity is
consistency evidence, not an independent Hermes runtime compatibility claim.

## Deliberately not modelled

Prompts, instructions and history are validated then discarded.
Synthetic result text can be stored by observation controls and is cleared by reset.
Kanban attempts, client intake/recovery policy, inference, Python dispatchers,
host tool execution and credential enforcement are excluded. There are no outgoing
webhooks, provider calls or agent processes. Public peer-run IDs will remain
separate from consumer intake and Kanban identities.

Source evidence is not runtime parity. Package/shared-control tests do not establish
compatibility with a real Hermes process. The opt-in
[pinned oracle](oracle/README.md) separately passed 33 documented public HTTP
comparisons, including a fresh-process SQLite restart; its substitutions and
limitations remain explicit. Keep this package WIP until independent Ready requirements are met.


## HTTP replay example

Start `mockingbird-hermes serve --port 8827`, then submit a synthetic delivery:

```sh
curl -sS http://127.0.0.1:8827/v1/runs \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-delivery' \
  -d '{"input":"synthetic prompt"}'
```

Repeating the identical request returns the same `run_id` and a replay header.
Poll `GET /v1/runs/<run_id>`; request interruption with
`POST /v1/runs/<run_id>/stop`. A stop response is intermediate. Complete the
scenario with `POST /__admin/hermes/runs/<run_id>/observe`, using a JSON body
such as `{ "status": "cancelled" }`, then poll again. Use only synthetic input
and result data. No Python dispatcher or Kanban integration is required.

## Verification and evidence

The package remains **WIP**. Three of six inventoried operations are supported;
SSE events, approval execution and steering remain excluded. The shipped
[oracle guide](oracle/README.md), [source manifest](oracle/source-lock.json), and
[recorded comparisons](evidence/pinned-oracle.json) make the exact upstream pin
and substitutions inspectable. Run the oracle only after separately authorizing
its dependency, disposable database and process operations. Normal package tests
need none of those operations or provider credentials.

From this repository, run `bun test packages/service/hermes` and the package's
`typecheck`, `lint`, `generate:check`, `openapi:check`, `build`, `portability` and
`pack:check` scripts. Root `bun run check` also verifies catalog and generated
documentation freshness. The docs catalog playground uses the same portable
runtime; its state is local to the browser.