@jobmatchme/bee-dance-schema

bee-dance-schema is the schema layer for the Bee Dance communication protocol.

The package exists for systems that want agents or user interfaces to exchange structured messages without hard-coding one concrete transport or one concrete runtime. Instead of coupling every participant to one implementation, Bee Dance describes the protocol as JSON Schemas for envelopes, commands, responses, events, items, and capability negotiation.

What this package contains

• the version manifest for the protocol schema set
• JSON Schemas for the top-level envelope
• JSON Schemas for protocol handshake messages
• JSON Schemas for turn lifecycle messages
• JSON Schemas for item, action, and approval events
• shared schema fragments such as actors, capabilities, and item parts

Why a schema package exists at all

Distributed agent systems tend to evolve quickly. New transports appear, new clients want to render richer outputs, and runtimes often need to be replaced without rewriting every connected component. A dedicated schema package helps by making the wire contract explicit and versioned.

That has a few practical benefits:

• producers and consumers can validate messages independently
• gateways and sidecars can adapt between protocol versions more safely
• tooling can generate validators, fixtures, documentation, or test harnesses
• protocol review can happen at the contract level before implementation details are fixed

Design intent

Bee Dance is meant for conversational and tool-using agents that do more than return one final string. The protocol therefore separates:

• envelope metadata such as message identity, sender, session, thread, and turn
• capability negotiation for compatible protocol use
• commands such as starting or cancelling a turn
• streamed events such as run lifecycle updates, appended items, and approval requests
• structured content parts, so that text, status information, approvals, diffs, artifacts, and forms can travel in the same message model

The schemas are transport-agnostic. They do not prescribe NATS, HTTP, Slack, or any other integration surface. They only define the message shapes.

Typical usage

This package is usually paired with a small protocol runtime that:

• loads these schemas
• validates incoming and outgoing envelopes
• provides helpers for building valid protocol messages

Applications can then use the runtime while keeping the schema source of truth separate and easy to review.

License

MIT

Publishing

The package is set up to publish publicly to npm from GitHub Actions using npm Trusted Publishing via GitHub OIDC.

A release tag such as v0.2.1 is expected to point to a commit whose package.json version matches the tag. The workflow then installs dependencies with npm ci, builds the package, and publishes it to npm without a long-lived publish token.

For this to work, the package must be configured on npm with a trusted publisher that points to the matching GitHub repository and workflow filename.