Family event routing engine — same event, every member, the right context.
Status: Alpha — Workflow parser, DAG executor, context interpolation, gateway client, and resume support are implemented with 114 tests passing.
coral is the family event routing engine for OpenOctopus. It powers the core differentiator: one event triggers intelligent, role-aware responses across realms and family members. coral provides DAG-based (Directed Acyclic Graph) orchestration for cross-realm coordination with family-aware routing.
Named after the coral structures that connect and support diverse life in a reef, coral connects your Realms into coordinated workflows — and routes outputs to the right family member with the right context.
When grandpa mentions "My knee hurts again" in the family group chat, coral routes intelligently:
┌──────────────────────────────────────────────────────┐
│ Trigger: "Grandpa says his knee hurts" │
└──────────────────────┬───────────────────────────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌────────────┐ ┌─────────┐ ┌──────────┐
│ Health │ │ Finance │ │ Parents │
│ Realm │ │ Realm │ │ Realm │
│ │ │ │ │ │
│ Medical │ │ Insurance│ │ Family │
│ history + │ │ balance +│ │ schedule │
│ available │ │ coverage │ │ check │
│ doctors │ │ status │ │ │
└─────┬──────┘ └────┬────┘ └────┬─────┘
│ │ │
└──────────────┼───────────┘
▼
┌──────────────────┐
│ Role-Aware │
│ Routing │
└────────┬─────────┘
┌────────────┼────────────┐
▼ ▼ ▼
┌────────────┐ ┌─────────┐ ┌──────────┐
│ → Dad │ │ → Mom │ │ → Daughter│
│ │ │ │ │ │
│ "Schedule │ │ "Buy │ │ (not │
│ checkup?" │ │ pain │ │ disturbed)│
│ + history │ │ relief?"│ │ │
│ + slots │ │ + supply│ │ │
└────────────┘ └─────────┘ └──────────┘
3 seconds. Same event, 3 different family members, 3 different versions — each with the context they need.
When you say "I'm traveling to Tokyo next week for 5 days", coral orchestrates across multiple Realms:
┌─────────────────────────────────────────────────────┐
│ Trigger: "Travel to Tokyo, 5 days" │
└──────────────────────┬──────────────────────────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌────────────┐ ┌─────────┐ ┌──────────┐
│ Pet Realm │ │ Finance │ │ Work │
│ │ │ Realm │ │ Realm │
│ Momo: │ │ │ │ │
│ "Who feeds │ │ Budget │ │ Set OOO │
│ me for │ │ estimate│ │ Delegate │
│ 5 days?" │ │ ¥X,XXX │ │ tasks │
└─────┬──────┘ └────┬────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
┌────────────┐ ┌─────────┐ ┌──────────┐
│ Parents │ │ Vehicle │ │ Health │
│ Realm │ │ Realm │ │ Realm │
│ │ │ │ │ │
│ Mom: "I can│ │ Airport │ │ Travel │
│ come take │ │ parking │ │ insurance│
│ care of │ │ or taxi?│ │ check │
│ Momo!" │ │ │ │ │
└────────────┘ └─────────┘ └──────────┘
│ │ │
└──────────────┼───────────┘
▼
┌──────────────────┐
│ Travel Checklist │
│ (unified action │
│ plan for user │
│ confirmation) │
└──────────────────┘
Each Realm's agents contribute their perspective, and coral merges the results into a unified, actionable plan.
Workflows are defined as directed acyclic graphs where each node is a Realm query or action:
workflow: travel-preparation
trigger: "travel to {destination} for {duration}"
steps:
- id: pet-care
realm: pet
action: arrange-care
params: { duration: "{{duration}}" }
- id: budget
realm: finance
action: estimate-budget
params: { destination: "{{destination}}", duration: "{{duration}}" }
- id: work-handoff
realm: work
action: set-out-of-office
params: { duration: "{{duration}}" }
- id: transport
realm: vehicle
action: plan-transport
depends_on: [budget]
- id: health-check
realm: health
action: travel-health-check
params: { destination: "{{destination}}" }
- id: summarize
action: merge-results
depends_on: [pet-care, budget, work-handoff, transport, health-check]- DAG execution — Parallel and sequential step orchestration with dependency resolution
- Cross-realm context — Each step can read (but not write) data from other Realms
- Summoned agent participation — Summoned entities contribute to workflows from their perspective
- Human-in-the-loop — Critical actions require user confirmation before execution
- Failure handling — Retry, skip, or fallback strategies per step
- Resumable — Pause at approval gates, resume later without re-running completed steps
# Run a workflow by name
coral run travel-preparation --args '{"destination":"Tokyo","duration":"5 days"}'
# Run from a YAML file
coral run --file workflows/travel-preparation.yml --args '{"destination":"Tokyo","duration":"5 days"}'
# Dry run — show what would execute without side effects
coral run travel-preparation --dry-run --args '{"destination":"Tokyo","duration":"5 days"}'
# List available workflows
coral list
# Validate a workflow file
coral validate workflows/my-workflow.yml
# Resume a paused workflow (at approval gate)
coral resume --token wf_abc123$ coral run travel-preparation --args '{"destination":"Tokyo","duration":"5 days"}'
[coral] Starting workflow: travel-preparation
[coral] Step pet-care ... running (Pet Realm)
[coral] Step budget ... running (Finance Realm)
[coral] Step work-handoff ... running (Work Realm)
[coral] Step health-check ... running (Health Realm)
[coral] Step pet-care ... done — Mom will care for Momo
[coral] Step budget ... done — Estimated budget: ¥180,000
[coral] Step work-handoff ... done — OOO set, tasks delegated
[coral] Step health-check ... done — Travel insurance valid
[coral] Step transport ... running (Vehicle Realm, depends on: budget)
[coral] Step transport ... done — Airport taxi booked, ¥6,500
[coral] Step summarize ... merging results
Travel Checklist:
- Pet care: Mom will visit daily (confirmed)
- Budget: ¥180,000 estimated (flights ¥85,000 + hotel ¥65,000 + daily ¥30,000)
- Work: OOO Mar 15-20, 3 tasks delegated to team
- Transport: Taxi to NRT, ¥6,500 (pickup 6:00 AM)
- Health: Travel insurance active, no vaccinations needed
Approve this plan? [y/n]
workflow: morning-routine
trigger: "good morning"
steps:
- id: health-check
realm: health
action: daily-summary
- id: calendar
realm: work
action: today-preview
- id: pet-status
realm: pet
action: care-status
- id: weather
action: fetch-weather
- id: summarize
action: merge-results
depends_on: [health-check, calendar, pet-status, weather]workflow: moving-house
trigger: "moving to {address} on {date}"
steps:
- id: utilities
realm: home
action: transfer-utilities
params: { new_address: "{{address}}", date: "{{date}}" }
- id: pet-logistics
realm: pet
action: moving-plan
params: { date: "{{date}}" }
- id: address-update
realm: legal
action: update-address
params: { new_address: "{{address}}" }
- id: insurance
realm: finance
action: update-policies
depends_on: [address-update]
- id: vet-transfer
realm: pet
action: find-new-vet
depends_on: [pet-logistics]
params: { near: "{{address}}" }
approval: required
- id: checklist
action: merge-results
depends_on: [utilities, pet-logistics, address-update, insurance, vet-transfer]| Component | Choice |
|---|---|
| Runtime | Node.js >= 22 + TypeScript |
| DAG Engine | Custom (inspired by LangGraph, Temporal) |
| Workflow Format | YAML definitions |
| Integration | WebSocket RPC to ink gateway |
- Workflow YAML format specification
- DAG parser and validator
- Step executor with dependency resolution
- Cross-realm context injection
- Summoned agent participation protocol
- Built-in workflow templates (travel, moving, event planning)
- Visual workflow editor (dashboard integration)
| Project | Description |
|---|---|
| openoctopus | Core monorepo — Realm manager, agent runner, ink gateway |
| realms | Official realm packages |
| realmhub | Realm package marketplace |
coral is in the planning phase. Join The Reef (Discord) to discuss workflow design, or open an issue with use case ideas.
See CONTRIBUTING.md for general guidelines.
MIT — see the .github repo for the full license text.