Maestro Orchestration Runtime

Maestro is Aweb's canonical orchestration runtime. Call /api/v2/orchestrate/run to plan and execute a creative or commercialization DAG with durable job_id, run_id, and plan_id correlation across sync and streaming modes.

Canonical ingress

Public Maestro orchestration goes through POST /api/v2/orchestrate/run. The older /api/maestro/produce route is deprecated and restricted to localhost development or internal service-auth callers.

{
  "query": "Research ADHD planner demand, generate a product concept, and draft launch assets",
  "stream": false
}

Architecture

The orchestration engine is built on 8 interconnected systems:

System 1Adapters37 capability adapters with Zod-validated input/output schemas
System 2KernelCentral coordinator — failover, semantic cache (LRU 500), cost preflight
System 3Graph ExecutorDAG builder with cycle detection and wave-based parallel execution
System 4Dynamic QueryElo-rated scoring (K=32) with real-time health and badge data
System 5ObservabilityVCR recorder for cassette replay, ring buffer logger (1000 entries)
System 6Test Harness5 gates: compile, contract, sandbox, replay, chaos
System 7Badge RoutingGold/Silver/Bronze certification gates provider access
System 8DNA IntegrationPlatform philosophy drives routing policies automatically

Query-driven orchestration

Submit a natural-language brief and Maestro plans the DAG internally. Independent steps are then executed in parallel waves, with failover and review gates applied at runtime.

import Aweb from '@aweb/sdk';

const aweb = new Aweb({ apiKey: process.env.AWEB_API_KEY });

const result = await aweb.orchestrate.run({
  query: 'Write a tagline for an AI product, generate a hero image, and compose a short voiceover',
  stream: false,
});

console.log(result.data.job_id);
console.log(result.data.run_id);
console.log(result.data.plan_id);
console.log(result.data.job?.status);
console.log(result.data.run?.status);
console.log(result.data.audit_receipt?.request_id);

Lifecycle envelope

The first normalized orchestration contract now distinguishes between the durable workflow job and the concrete execution attempt. That gives callers one stable way to reason about status, retries, audits, and later artifact fetches across SDK, CLI, and API surfaces.

{
  "object": "orchestration",
  "data": {
    "job_id": "job_req_orch_123",
    "run_id": "maestro_run_123",
    "plan_id": "plan_123",
    "status": "completed",
    "job": {
      "object": "job",
      "id": "job_req_orch_123",
      "kind": "orchestration",
      "status": "completed",
      "mode": "sync",
      "durability": "persisted",
      "run_id": "maestro_run_123"
    },
    "run": {
      "object": "run",
      "id": "maestro_run_123",
      "job_id": "job_req_orch_123",
      "status": "completed",
      "mode": "sync",
      "plan_id": "plan_123"
    },
    "audit_receipt": {
      "object": "audit_receipt",
      "request_id": "req_orch_123",
      "auth_mode": "api_key",
      "source": {
        "method": "POST",
        "route": "/api/v2/orchestrate/run"
      }
    }
  }
}

Checkpoint resume

When a streaming orchestration pauses in waiting_checkpoint, read the durable run state with GET /api/v2/orchestrate/run/:id and then resolve the open checkpoint through the same resource tree.

const status = await aweb.orchestrate.get('job_req_waiting_123');

const checkpointId = status.data.pending_checkpoint?.id;
if (!checkpointId) throw new Error('No pending checkpoint');

const activeStep = status.data.steps.find(step => step.step_id === 'hero');
console.log(activeStep?.status);

await aweb.orchestrate.resolveCheckpoint('job_req_waiting_123', checkpointId, {
  selected_asset_id: 'asset_1',
});

// Equivalent raw API call:
// POST /api/v2/orchestrate/run/job_req_waiting_123/checkpoints/${checkpointId}
// { "selected_asset_id": "asset_1" }

Routing policies

Three built-in policies control provider selection. Each step can override the default.

fastLowest latency. Picks the fastest healthy provider. Ideal for real-time UIs.
balancedDefault. Weighs quality, cost, and latency equally. Best for most use cases.
bestHighest quality. Picks premium providers regardless of cost. For critical outputs.

Quality gates

Every provider passes through a 5-gate test harness before receiving production traffic:

Gate 1CompileTypeScript compilation and schema validation
Gate 2ContractInput/output contract conformance testing
Gate 3SandboxLive API call with result verification
Gate 4ReplayVCR cassette replay for regression testing
Gate 5ChaosFault injection (timeout, 429, 500, network error)

Providers earn Gold, Silver, or Bronze badges based on gate results. Badge level gates access to production routing.

Feature flags

Roll out orchestrated routes progressively with 5-state feature flags: off → shadow → dark → live → only. Shadow mode runs both legacy and orchestrated paths, compares results, without affecting users.