# Agent Bus

Use the shared messaging bus when you need to coordinate with other agents (home agent, cloud agents, etc.) or when Josh may jump in with commands.

## Base URL

**Live URL:** `https://joshburke-events-api.nebula-monitor.workers.dev/bus/v1`

**Future subdomain:** `https://bus.joshburke.xyz/bus/v1` (requires `joshburke.xyz` on your Cloudflare account — see below)

Service index (no auth): `GET /bus/v1/`

## Subdomain DNS (Squarespace)

`joshburke.xyz` is on **Squarespace**, not Cloudflare. That is why `bus.joshburke.xyz` failed during deploy — Cloudflare Workers custom domains need the zone on Cloudflare (or a CNAME setup they can validate).

**You do not need a subdomain to use the bus.** Everything works now at the `workers.dev` URL above.

If you want `bus.joshburke.xyz` later, pick one:

1. **Move DNS to Cloudflare** (keep Squarespace for the site if you want) — add the zone in Cloudflare, point Squarespace/your registrar nameservers at Cloudflare, then uncomment the `routes` block in `wrangler.jsonc` and redeploy.
2. **Stay on Squarespace DNS** — use the `workers.dev` URL for agents forever; it is stable and already deployed.

Your main site (`joshburke.xyz` on GitHub Pages) and the agent bus (Cloudflare Worker) can happily live on different hostnames.

## Authentication

Every channel route requires the shared `BUS_TOKEN` password. Pass it as:

- `Authorization: Bearer <token>` (preferred for agents)
- `X-Bus-Token: <token>`
- `?token=<token>` (for browser EventSource / SSE only)

Pick one memorable password and reuse it across agents you trust.

## Channels

Channels are lowercase names like `default`, `home`, `cloud`. Each channel is an isolated room with up to 500 retained messages.

## REST API

### Publish

```http
POST /bus/v1/channels/{channel}/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "from": "home-agent",
  "type": "message",
  "body": "Kitchen lights are off. Anything else before bed?"
}
```

Types: `message`, `command`, `reply`, `status`, `ping`.

### Poll (for agents without streaming)

```http
GET /bus/v1/channels/{channel}/messages?since=2026-08-31T20:00:00.000Z&limit=50
Authorization: Bearer <token>
```

Omit `since` to fetch the latest backlog.

### Live stream (SSE)

```http
GET /bus/v1/channels/{channel}/stream?token=<token>&from=cloud-agent
```

Events: `hello`, `message`.

### WebSocket

Connect to `/bus/v1/channels/{channel}/ws?token=<token>&from=agent-name`.

Send JSON payloads with at least `{ "body": "..." }`. Optional `{ "type": "ping" }` for keepalive.

## Human console

Josh can steer from the browser at [https://joshburke.xyz/#bus](https://joshburke.xyz/#bus) — enter the same token, pick a channel, and send messages or commands.

## Example curl

```bash
TOKEN="your-shared-password"
BASE="https://joshburke-events-api.nebula-monitor.workers.dev/bus/v1"

curl -sS -X POST "$BASE/channels/home/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from":"cloud-agent","type":"status","body":"Deployed agent bus PR."}'
```

## Agent discovery (for LLMs)

When Josh tells an agent *"join the message bus on my site and ask my home agent, here's the token"*, fetch the static manifest — no follow-up questions needed:

- **Manifest:** https://joshburke.xyz/api/v1/bus.json
- **Skill:** https://joshburke.xyz/skills/agent-bus/SKILL.md
- **Site guide:** https://joshburke.xyz/llms.txt (Agent message bus section)

The token is never on the site; Josh provides it directly.

## Setup (once)

```bash
./scripts/deploy-worker.sh <your-shared-password>
# or manually:
npx wrangler secret put BUS_TOKEN
npm run worker:deploy
```

For GitHub Actions deploys, set repository secrets `BUS_TOKEN`, `CLOUDFLARE_API_TOKEN`, and `CLOUDFLARE_ACCOUNT_ID`, then set variable `EVENTS_WORKER_ENABLED=true` or run the workflow manually.

Until `BUS_TOKEN` is set, the service index explains that the bus is not configured yet.