stack/docs/tess/hermes-runtime-adapter-design.md

TESS-HRM-001 — Hermes runtime adapter boundary

Normalized provider surface

HermesRuntimeProvider implements the existing Mosaic-owned AgentRuntimeProvider unchanged. Its public surface is therefore capabilities, health, session list/tree, stream, send, attach/detach, and terminate, accepting only RuntimeScope, RuntimeMessage, RuntimeSession, RuntimeStreamEvent, and other types from @mosaicstack/types. Provider id is runtime.hermes.

The provider receives a narrow injected HermesRuntimeTransport, whose method names and inputs may represent Hermes API operations but whose return values are explicitly private HermesLegacy* types defined only in packages/agent/src/hermes-runtime-provider.ts. Mapping functions convert those private values to Mosaic sessions, state, hierarchy, and stream events. Capability negotiation maps a supplied Hermes feature inventory onto the fixed Mosaic runtime capability vocabulary; no unknown/ambiguous legacy feature is advertised. Unsupported Mosaic operations throw the typed fail-closed capability_unsupported provider error before a transport call.

Boundary line

Hermes legacy schema ends at HermesRuntimeTransport and its private adapter-local HermesLegacy* definitions in packages/agent. packages/types is never changed to contain a Hermes field, enum, identifier, session shape, status, or capability. apps/gateway registers/resolves the provider only through AgentRuntimeProvider and receives normalized values only. Identity remains server-derived RuntimeScope data and is passed to the injected transport as context, never reconstructed from a legacy response.

Initial mapping and safety posture

• Hermes conversation/thread identifiers map to opaque Mosaic RuntimeSession.id; parent linkage maps only when a known parent exists.
• Hermes status strings map through a closed lookup to RuntimeSessionState; unknown statuses become failed, never a permissive active state.
• Legacy stream chunks map to message.delta / message.complete; malformed or unsupported events become a normalized runtime.error event.
• Send, attach, and terminate require the normalized capability first. terminate continues to be approval-bound by the gateway service; the adapter does not weaken gateway authority.
• Kanban, skills, memory, tools, and cron are capability-inventory entries for this transitional adapter, not additions to the core runtime contract. They are reported as explicitly unsupported until a Mosaic-owned capability contract exists.