The product

Beach.

An application scaffold with an opaque, protocol-agnostic interior and pluggable protocol edges.

The shape

What Beach is.

An application scaffold. Not a runtime, not a gateway, not a framework, not a protocol. Beach gives your application a shape in which protocols arrive and depart at the edges, and the middle does not see them.

Your domain logic, your participants, your routing rules, and your data operate in the interior vocabulary. Inbound adapters translate external protocol into internal event. Outbound plugins translate internal event into external protocol. The event router and the manifest registry are the only components that see both sides of a call — and they see events and manifests, never protocols.

Getting started

The way in is beach-starter.

@cool-ai/beach-starter is a pre-scaffolded working application. It bundles the packages you will typically want — core, session, protocol, LLM, transport — and wires them together as the smallest complete example the architecture permits: an event router, a manifest-backed turn, a participant that responds, an inbound adapter that mounts externally, and an outbound plugin that reaches out.

Clone it, run it, read it, modify it. The shortest path from reading about Beach to having Beach running.

npm install @cool-ai/beach-starter
Packages

Independently versioned. Take what you need.

The core package alone is useful. The full stack is for applications that need the full architecture. Neither choice is penalised.

@cool-ai/beach-starter

Pre-scaffolded Hello World. Bundles the other packages and wires them as a minimal working application.

Beach Upstream

Protocol surfaces and edge contracts. What the outside world speaks to.

@cool-ai/beach-protocol@0.5.6

Envelope types, canonical part types, Agent Card schema.

@cool-ai/beach-transport@0.3.12

Inbound adapter and outbound plugin interfaces, with reference implementations.

@cool-ai/beach-transport-email@0.3.0

IMAP and SMTP wire layer: connection management, polling, sending. No envelope translation; use beach-channel-email for the full channel.

@cool-ai/beach-transport-whatsapp@0.2.2

WhatsApp Cloud API wire layer: webhook parsing and outbound message posting. No envelope translation; use beach-channel-whatsapp for the full channel.

@cool-ai/beach-channel-email@0.2.10

Full email channel: IMAP inbound + SMTP outbound with envelope translation, Missive part-bag, and Delivery Manifest integration.

@cool-ai/beach-channel-whatsapp@0.2.10

Full WhatsApp channel: webhook inbound + Cloud API outbound with envelope translation, Missive part-bag, and Delivery Manifest integration.

@cool-ai/beach-a2ui@0.4.2

A2UI catalog types and renderer.

@cool-ai/beach-a2ui-basics@0.0.2

Core A2UI catalog primitives and base types.

@cool-ai/beach-missives@0.0.8

Universal message record, storage adapters.

@cool-ai/beach-format@1.1.7

Composer base types and deterministic content renderers.

@cool-ai/beach-format-email@0.1.7

Email-shaped HTML and plain-text composer.

Beach Middle

The opaque interior. Event router, turn lifecycle, actors.

@cool-ai/beach-core@0.7.3

Event router, open registries, retry queue, turn lifecycle, manifests, telemetry hooks.

@cool-ai/beach-llm@0.6.7

LLM-shaped actor invocation, respond() tool, approval intercept.

@cool-ai/beach-llm-mastra@0.1.8

Mastra-provider adapter for LLM actors.

@cool-ai/beach-config@0.2.2

Configuration primitives for Beach applications.

Beach Downstream

Developer tooling and consumers of the event log.

@cool-ai/beach-inspect@1.1.12

Dev UI over the event log.

@cool-ai/beach-evals@0.0.25

Replay-based test primitives.

@cool-ai/beach-session-store@0.2.1

Per-key session data; concurrent-safe Redis primitive for domain-specific state.

@cool-ai/beach-missives-mastra-adapter@0.1.5

Mastra adapter for the missives store.

@cool-ai/eslint-plugin-beach@0.1.1

ESLint plugin enforcing Beach's architectural rules.

The edge contract

Three shapes at the edge.

An adapter, a plugin, or a participant. Each has a narrow contract with the interior and no contract with any other edge.

Inbound adapter

Accepts external protocol traffic on a transport it owns. Translates that traffic into Beach's internal event shape. Calls router.routeEvent(event), and its job ends.

Outbound plugin

Declares a capability. Implements invoke(event) and returns a manifest wait handle. Settles the manifest when the downstream service completes.

Participant

Receives events from the router. Produces results that land in manifests. LLM actor, deterministic handler, long-running process, or a type not yet named — the interior treats them identically.

Works alongside

Beach does not replace
what it doesn't have to.

LLM providers

Delegate to Mastra, Vercel AI SDK, LiteLLM, or plug your own. Beach ships an LLMProvider interface with a reference Anthropic implementation.

Durable execution

Delegate to Temporal, Inngest, or Cloudflare Durable Objects via the DurableExecutor interface. Beach does not ship durability; it cooperates with systems that do.

Observability

OpenTelemetry spans from the router, LLM provider, tool executor, and transport adapter. Configure an OTLP endpoint and distributed tracing works out of the box.

Gateways

A Beach application runs happily behind agentgateway, Gravitee, Salesforce Agent Fabric, or any proxy the enterprise requires. Different concerns, same application.

Adoption

Incremental, package by package.

Adopt only what you need. Add the rest when you need it.

  1. 01

    Adopt beach-core and move application routing to the event router.

    The minimum useful adoption. Routing becomes declarative; turn lifecycle and manifests are available from the first step.

  2. 02

    Adopt beach-protocol for the envelope types.

    Shared event shape across actors. Data types become first-class.

  3. 03

    Adopt beach-llm when an LLM actor is required.

    The respond() tool, approval intercept, turn-state markers.

  4. 04

    Adopt beach-transport when external protocol support is needed.

    Mount adapters and plugins for MCP, A2A, A2UI, REST, webhook, email, and the rest.

  5. 05

    Adopt beach-missives for cross-channel message persistence.

    A universal message record across whichever channels your application speaks.

Question, contribution, or bug? Get in touch.