@hearthforge/protocol

The message contract between the HearthForge panel and its agents. The panel owns state and decisions; an agent on each node owns Docker and executes what the panel sends it over one WebSocket. This package defines every frame that crosses that socket — the ProtocolMessage envelope, each panel → agent and agent → panel message type, the protocol version — and the runtime guards both sides run on every inbound frame, so a malformed or unknown frame is dropped at ingress instead of being dispatched on trust. It is game-agnostic: game data crosses only as opaque payloads the plugin owns.

Install

pnpm add @hearthforge/protocol @hearthforge/shared

Node >= 22.

Usage

import { PROTOCOL_VERSION, isAgentMessage, isPanelMessage, protocolAtLeast } from "@hearthforge/protocol";

// On the panel: every frame from an agent is untrusted until proven.
export function onAgentFrame(raw: string): void {
  const frame: unknown = JSON.parse(raw);
  if (!isAgentMessage(frame)) return; // not a well-formed agent → panel message
  if (frame.type === "agent:heartbeat") {
    console.log(frame.payload.nodeId, frame.payload.cpu);
  }
}

// On the agent: the same, the other way round.
export function onPanelFrame(raw: string): boolean {
  return isPanelMessage(JSON.parse(raw));
}

// Capability negotiation is by version.
export const speaksCurrent = (agentVersion: string) => protocolAtLeast(agentVersion, PROTOCOL_VERSION);

isAgentMessage / isPanelMessage narrow to the AgentMessage / PanelMessage unions, so a switch on type is typed from there. Payload-level guards (parseGracefulStopPayload, parseLiveSamplesPayload, …) validate the payloads that carry numbers or nested shapes.

Peer dependencies

| peer | range | |---|---| | @hearthforge/shared | the matching 0.x line |

Versioning

The package follows semver, pre-1.0: a minor release may break the contract; a patch never does. PROTOCOL_VERSION is separate from the package version — it is the wire version a panel and an agent exchange, and runtime compatibility is major-only apart from the capabilities a panel checks with protocolAtLeast. Maintenance lines publish from release/X.Y branches under the release-X.Y npm dist-tag and never move latest — see Maintenance releases.

License

Apache-2.0.

Links

• Repository: hearthforge/hearthforge-sdk
• Contributing: CLA.md (required for every contribution)
• HearthForge core: hearthforge/hearthforge