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.

@cool-ai/beach-core

The event router, open registries, retry queue, telemetry hooks.

@cool-ai/beach-session

Turn manager, manifest registry, replay.

@cool-ai/beach-llm

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

@cool-ai/beach-transport

Inbound adapter and outbound plugin interfaces, with reference implementations.

@cool-ai/beach-protocol

Envelope types, canonical part types, Agent Card schema.

@cool-ai/beach-a2ui

Basic Catalog types and renderer.

@cool-ai/beach-missives

Universal message record, storage adapters.

@cool-ai/beach-inspect

Optional. Dev UI over the event log.

@cool-ai/beach-evals

Optional. Replay-based test primitives.

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; everything else stays where it is.

  2. 02

    Adopt beach-protocol for the envelope types.

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

  3. 03

    Adopt beach-session when a turn lifecycle is needed.

    Manifest registry, turn states, and replay. The unlock for asynchronous and multi-channel completion.

  4. 04

    Adopt beach-llm when an LLM participant is required.

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

  5. 05

    Adopt beach-transport when external protocol support is needed.

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

  6. 06

    Adopt beach-missives for cross-channel message persistence.

    A universal message record across whichever channels your application speaks.