Orchestrator Vision: Toward an Orchestration Platform

Status: partially shipped — this page separates what exists in 0.6.0 from what is still open Owner: maintainer

Why This Exists

TramAI is already strong at single typed AI-backed operations via @AiService, and the tramai-orchestration module provides a workflow DSL for composing those operations. Beyond that, the question has always been how far a JVM library should reach into platform territory: scheduling workflows, exposing them over HTTP, calling external agents, and running across multiple machines.

This page records the direction: type-safe, testable, observable, and framework-agnostic at every level — without turning the core runtime into an agent framework.

Design Tenets

Every new module is optional. The tramai-orchestration workflow DSL must remain usable standalone. New modules add capabilities on top.
Workflows remain typed and testable. No step should require raw prompt strings or untyped state maps.
External integrations are explicit step types, not magic. HTTP, shell, Hermes, Codex, and MCP are named steps in the DSL, not hidden side effects.
MCP is a first-class protocol surface. TramAI workflows should be exposable as MCP servers so external agents can call them.
Observability is mandatory at the hook level, optional at the OTel dependency level. Every module emits stable TramAI observer events; tramai-observability maps them to OpenTelemetry when it is on the classpath.

What Has Shipped

Capability	Module	Status in 0.6.0
Workflow DSL and checkpoint/resume	`tramai-orchestration`	Shipped (preview)
Cron and delay scheduling	`tramai-scheduler`	Shipped (preview, published)
REST API, webhooks, SSE	`tramai-server`	Shipped (internal, not published)
MCP adapter	`tramai-mcp`	Shipped (internal, not published)
Multi-tenancy, API keys, rate limiting, audit	`tramai-platform`	Shipped (preview, published)
Admin UI	`tramai-dashboard`	Shipped (internal, not published)
External step types (HTTP, shell, Hermes, Codex, MCP, plugins)	`tramai-orchestration`	Shipped

Internal classification is not a maturity judgment — it means those modules are not published artifacts, so there is no coordinate for an application to depend on today.

What Is Still Open

Gap	Why it matters	Where it would land
No per-step timeout	A hanging step stalls the entire workflow	`tramai-orchestration`
No per-step retry with backoff	Steps fail without a retry option	`tramai-orchestration`
No agent spawning as a platform service	Workflows call external agents through step types, not as a managed service	— (no module exists)
No distributed worker pool as a separate module	Multi-node execution is lease-coordinated, not a distributed runtime	— (no module exists)
No visual workflow builder	Operators build definitions in code today	`tramai-dashboard`

None of these are promised for a specific release. Treat this table as the honest boundary of the current design, and see Limitations for the same boundary expressed as consumer-facing constraints.

Module Architecture (Direction)

tramai-platform   (preview, published: tenancy, plugin/runtime policy, audit)
    |
tramai-dashboard  (internal: admin UI)
    |
tramai-server     (internal: REST API, MCP server, webhooks, SSE)
    |
tramai-orchestration  (preview: the workflow DSL)
    aiStep, localStep, gateStep, branchStep, parallelStep, external steps
    |
tramai-engine | tramai-structured | tramai-core

Each layer composes the one below it. Nothing here redefines the core execution model: tramai-engine keeps ownership of provider execution, retries, fallbacks, tool loops, and operation-level observability. The Module Architecture page explains how those directions are enforced rather than merely intended.

Product Positioning

	Temporal	n8n	Airflow	TramAI
Runtime	Any (gRPC)	Node.js	Python	JVM (Kotlin/Java)
AI-native typed services	No	No	No	`@AiService`
Structured output	No	No	No	Built in
MCP surface	No	No	No	Adapter module (internal)
Checkpoint / resume	Best-in-class	No	Yes	Built in (top-level step boundaries)
Visual builder	No	Yes	Yes	Not shipped
OpenTelemetry	No	No	No	Built in when OTel is on the classpath

Target context: JVM teams — Spring Boot or plain Kotlin — that want typed AI workflows without leaving the JVM ecosystem or adopting a Python-era orchestration model.

Limitations — the consumer-facing boundary of the current release
Orchestration — the workflow DSL as it exists today
Orchestration Persistence — checkpoints, leases, and resume
Module Architecture — layers, ownership, and enforcement