@meyicloud/meyi-cost-server 1.5.0 → 1.6.0

package/AGENTS.md

@@ -35,23 +35,13 @@ Keep HTTP concerns in routes/controllers, AWS and database behavior in services,
 schema creation in `schema`, and pure calculations in `lib`. `index.js` and
 `cur.js` must remain thin compatibility entry points.
 
-## AI provider abstraction
+## External cost analyser
 
-`src/lib/llm-provider.js` is the only place that knows which vendor answers.
-`createLlmProvider({ provider, modelId, apiKey, region, ... })` returns an
-object with a single `converse({ system, messages, maxTokens, temperature,
-topP })` method resolving to `{ text }`. Bedrock, Anthropic and OpenAI are
-supported; `normalizeProviderName` matches loosely so UI labels like
-"AWS Bedrock" resolve correctly.
-
-`CostAnalysisService.resolveProvider(tenantId)` picks between a host-supplied
-`providerResolver` and the `COST_AI_*` environment defaults. Two rules matter:
-the analysis fingerprint is computed from the **effective** model so switching
-provider cannot serve a cached answer from the previous one, and a resolver
-failure degrades to the environment rather than failing the request.
-
-When adding a provider, add it here and to `test/llm-provider.test.js`; no
-other file should need to change.
+The backend package never calls an LLM directly. `CostAnalysisReportWorker`
+claims due tenant schedules and delegates execution to `CostAnalyserService`,
+which starts one tenant-scoped `meyi-cost-ai-analyser` Fargate task. The task
+writes canonical Markdown and derived PDF artifacts to private S3. Keep ECS
+task overrides tenant-scoped and never log the customer role external ID.
 
 ## Request and data flow
 
@@ -62,21 +52,17 @@ flowchart LR
   Enabled --> Router[/api/v1/cost router]
   Router --> Controller[Cost controller]
   Controller --> Customer[Customer AWS context service]
-  Customer -->|Customer role| CE[AWS Cost Explorer]
-  Controller --> Source{Configured source}
-  Source -->|CUR| SaaS[SaaS Athena context service]
+  Controller --> SaaS[SaaS Athena context service]
   SaaS --> Athena[Central tenant CUR partition]
-  Source -->|auto fallback| CE
-  Controller --> Budget[Budget and dismissal services]
-  Budget --> DB[(Tenant-scoped PostgreSQL)]
-  Athena --> Controller
-  CE --> Controller
+  Athena --> Scheduler[Scheduled report worker]
+  Scheduler --> ECS[Cost analyser Fargate task]
+  ECS --> Artifacts[Private Markdown and PDF S3 objects]
 ```
 
 The plugin currently owns these route groups under `${apiBaseUri}/cost`:
 
 - `GET /accounts`, `/data-status`, `/overview`, `/filter-options`, `/reports`, `/tags`
-- `GET`/`PUT /analysis/schedule`, `GET /analysis/reports`, and tenant-scoped PDF downloads
+- `GET`/`PUT /analysis/schedule`, `GET /analysis/reports`, and tenant-scoped Markdown/PDF downloads
 - `GET /budgets` and `POST /budgets`
 - `DELETE /budgets/:id`
 - `GET /budget-alert-dismissals` and `POST /budget-alert-dismissals`

package/README.md

@@ -258,12 +258,12 @@ SaaS Athena resources.
 
 ### AI analysis variables
 
-AI analysis is optional and invokes Amazon Bedrock from the backend runtime.
-Only aggregated cost facts are sent to the model; tenant IDs, AWS credentials,
-resource IDs, and raw CUR rows are excluded. AI reports are generated by a
-background worker, not by a browser request. Daily reports cover the previous
-complete day, weekly reports cover the previous seven complete days, and
-monthly reports cover the previous calendar month in the configured timezone.
+AI reports are generated by a separate `meyi-cost-ai-analyser` Fargate task.
+The backend only schedules jobs, launches and monitors the task, and serves
+tenant-scoped artifacts. It does not invoke Bedrock or generate PDFs itself.
+Daily reports cover the previous complete day, weekly reports cover the
+previous seven complete days, and monthly reports cover the previous calendar
+month in the configured timezone.
 
 The authenticated report API is:
 
@@ -274,6 +274,7 @@ The authenticated report API is:
 | `GET` | `/analysis/reports` | List tenant report history without PDF bytes. |
 | `GET` | `/analysis/reports/:id` | Read one tenant report. |
 | `GET` | `/analysis/reports/:id/pdf` | Download a completed report PDF. |
+| `GET` | `/analysis/reports/:id/markdown` | Download the canonical Markdown report. |
 
 Schedule and report rows live in `cost_ai_report_schedules` and
 `cost_ai_reports`. The worker atomically claims due schedules with a lease, so
@@ -281,56 +282,30 @@ a restarted task can resume future work without relying on in-memory timers.
 
 | Variable | Default | Required | Purpose |
 | --- | --- | --- | --- |
-| `COST_AI_ENABLED` | `false` | No | Enables the AI analysis endpoints and Bedrock client. |
-| `COST_AI_REGION` | `AWS_REGION` or `us-east-1` | When enabled | Region used by the Bedrock Runtime client. |
-| `COST_AI_MODEL_ID` | Global Claude Sonnet inference profile | When enabled | Bedrock model or inference-profile ID. |
-| `COST_AI_MAX_TOKENS` | `4000` | No | Maximum response tokens, clamped from 600 to 8000. |
-| `COST_AI_CACHE_TTL_MS` | `21600000` | No | Tenant analysis cache duration; defaults to six hours. |
-| `COST_AI_HOURLY_LIMIT` | `6` | No | Maximum non-cached generations per tenant per hour. |
-| `COST_AI_TIMEOUT_MS` | `120000` | No | Per-request timeout for key-based providers; Bedrock uses the SDK default. |
+| `COST_AI_ENABLED` | `false` | No | Enables the schedule worker and external analyser integration. |
+| `COST_AI_ANALYSER_REGION` | `AWS_REGION` | When enabled | ECS and report-bucket region. |
+| `COST_AI_ANALYSER_CLUSTER` | Empty | When enabled | ECS cluster ARN or name. |
+| `COST_AI_ANALYSER_TASK_DEFINITION` | Empty | When enabled | Fargate task definition ARN. |
+| `COST_AI_ANALYSER_CONTAINER_NAME` | `cost-ai-analyser` | No | Container override target. |
+| `COST_AI_ANALYSER_SUBNETS` | Empty | When enabled | Comma-separated private subnet IDs. |
+| `COST_AI_ANALYSER_SECURITY_GROUPS` | Empty | When enabled | Comma-separated task security groups. |
+| `COST_AI_ANALYSER_REPORT_BUCKET` | Empty | When enabled | Private S3 Markdown/PDF artifact bucket. |
+| `COST_AI_ANALYSER_BEDROCK_REGION` | Empty | When enabled | Bedrock region passed to the analyser task. |
+| `COST_AI_ANALYSER_BEDROCK_MODEL_ID` | Empty | When enabled | Model passed only to the analyser task. |
+| `COST_AI_ANALYSER_TARGET_REGIONS` | `AWS_REGION` | No | Customer regions inspected for resource detail. |
+| `COST_AI_ANALYSER_TOP_N_SERVICES` | `10` | No | Maximum high-cost service agents run per report. |
+| `COST_AI_ANALYSER_POLL_INTERVAL_MS` | `15000` | No | ECS task status polling interval. |
+| `COST_AI_ANALYSER_TIMEOUT_MS` | `2700000` | No | Maximum external task duration. |
 | `COST_AI_REPORT_POLL_INTERVAL_MS` | `60000` | No | How often the background worker claims due schedules; minimum 10 seconds. |
-| `COST_AI_REPORT_LEASE_MS` | `1800000` | No | Claim lease used to recover from an interrupted worker. |
+| `COST_AI_REPORT_LEASE_MS` | `3600000` | No | Claim lease used to recover from an interrupted worker. |
 | `COST_AI_REPORT_BATCH_SIZE` | `5` | No | Maximum schedules claimed by one worker tick; clamped from 1 to 25. |
 
-### Choosing a provider
-
-The `COST_AI_*` variables above configure the deployment default, which is
-Bedrock. A host application can additionally supply `providerResolver` to
-`createInsightCost` to select a provider per tenant:
-
-```js
-createInsightCost({
-  app, db,
-  providerResolver: async (tenantId) => ({
-    provider: "anthropic",        // bedrock | anthropic | openai
-    modelId: "claude-sonnet-4-5",
-    apiKey: "...",                // required for anthropic and openai
-    region: "ap-south-2",         // bedrock only
-    accessKeyId: "...",           // bedrock only; omit to use ambient credentials
-    secretAccessKey: "...",
-  }),
-})
-```
-
-Returning `null` falls back to the environment configuration, so a host that
-does not pass a resolver behaves exactly as before. A resolver that throws is
-logged and also falls back, so a credential-store outage degrades the feature
-rather than failing the request.
-
-Why this exists: Bedrock authenticates with SigV4 and is subject to
-account-level Anthropic model access. The key-based providers are not, so a
-deployment blocked on Bedrock model access can still run analysis. It also
-lets a customer bring their own model account.
-
-`GET /analysis/status` reports the provider that would serve the caller's
-tenant, including a `source` of `tenant-configuration` or `environment`.
-**Host applications are responsible for encrypting stored credentials.**
-
-The runtime role needs `bedrock:InvokeModel` for the selected model or
-inference profile. Analysis results are stored in the tenant-scoped
-`cost_ai_analyses` table and scheduled PDF jobs are stored in
-`cost_ai_reports`. Model or permission failures mark only that scheduled report
-as failed and do not change CUR, standard reports, onboarding, or budgets.
+`GET /analysis/status` reports `meyi-cost-ai-analyser` with an `ecs-task`
+source. The analyser uses the shared ECS task role for Athena, S3, Bedrock, and
+cross-account role assumption. New reports store task and private artifact
+references in `cost_ai_reports`; existing database-backed PDF rows remain
+downloadable for compatibility. Model or task failures mark only that report as
+failed and do not change CUR, standard reports, or onboarding.
 
 ### CUR/Athena variables
 

package/index.js

@@ -1,2 +1 @@
 export { createInsightCost, createInsightCost as default } from "./src/plugin.js";
-export { createLlmProvider, normalizeProviderName, PROVIDER_BEDROCK, PROVIDER_ANTHROPIC, PROVIDER_OPENAI } from "./src/lib/llm-provider.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meyicloud/meyi-cost-server",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Tenant-aware AWS CUR and Athena cost plugin server for MeyiConnect",
   "type": "module",
   "main": "./index.js",
@@ -19,15 +19,14 @@
   ],
   "dependencies": {
     "@aws-sdk/client-athena": "^3.850.0",
-    "@aws-sdk/client-bedrock-runtime": "^3.850.0",
+    "@aws-sdk/client-ecs": "^3.850.0",
     "@aws-sdk/client-glue": "^3.850.0",
     "@aws-sdk/client-s3": "^3.850.0",
     "@aws-sdk/client-sts": "^3.850.0",
     "@aws-sdk/credential-providers": "^3.850.0",
     "drizzle-orm": "^0.44.7",
     "express": "^4.21.1",
-    "luxon": "^3.7.2",
-    "pdfkit": "^0.17.2"
+    "luxon": "^3.7.2"
   },
   "peerDependencies": {
     "pg": ">=8"

package/src/controllers/cost-analysis.controller.js

@@ -12,7 +12,7 @@ export class CostAnalysisController {
 
   async latest(req, res, next) {
     try {
-      return res.json({ analysis: await this.service.latest(req) });
+      return res.json({ analysis: await this.reportService.latest(req) });
     } catch (error) { return next(error); }
   }
 
@@ -45,4 +45,14 @@ export class CostAnalysisController {
       return res.send(report.data);
     } catch (error) { return next(error); }
   }
+
+  async downloadMarkdown(req, res, next) {
+    try {
+      const report = await this.reportService.markdown(req, req.params.id);
+      res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+      res.setHeader("Content-Disposition", `attachment; filename="${report.filename}"`);
+      res.setHeader("Content-Length", report.data.length);
+      return res.send(report.data);
+    } catch (error) { return next(error); }
+  }
 }

package/src/plugin.js

@@ -11,13 +11,11 @@ import { BudgetController } from "./controllers/budget.controller.js";
 import { CostAnalysisController } from "./controllers/cost-analysis.controller.js";
 import { createCostRouter } from "./routes/index.js";
 import { installCostBudgetSchema } from "./schema/cost-budget.schema.js";
-import { installCostAnalysisSchema } from "./schema/cost-analysis.schema.js";
 import { installCostAnalysisReportSchema } from "./schema/cost-analysis-report.schema.js";
-import { CostAnalysisRepository } from "./repositories/cost-analysis.repository.js";
 import { CostAnalysisReportRepository } from "./repositories/cost-analysis-report.repository.js";
-import { CostAnalysisDataService } from "./services/cost-analysis-data.service.js";
-import { CostAnalysisService } from "./services/cost-analysis.service.js";
+import { CostAnalyserService } from "./services/cost-analyser.service.js";
 import { CostAnalysisReportService } from "./services/cost-analysis-report.service.js";
+import { CostReportArtifactService } from "./services/cost-report-artifact.service.js";
 import { CostAnalysisReportWorker } from "./workers/cost-analysis-report.worker.js";
 import { installCurDiscoverySchema } from "./cur-discovery/schema.js";
 import { CurDiscoveryRepository } from "./cur-discovery/cur-discovery.repository.js";
@@ -26,7 +24,7 @@ import { CurDiscoveryService } from "./cur-discovery/cur-discovery.service.js";
 import { CurDiscoveryWorker } from "./cur-discovery/cur-discovery.worker.js";
 import { safeSchema } from "./lib/cost-utils.js";
 
-export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = console, providerResolver = null } = {}) {
+export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = console } = {}) {
   if (!db) throw new Error("db is required");
   const schema = safeSchema(process.env.DB_SCHEMA || "meyiconnect");
   const qSchema = `"${schema}"`;
@@ -35,7 +33,6 @@ export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = co
   const contextService = new CustomerAwsContextService({ repository: onboardingRepository, defaultTenant });
   const budgetRepository = new BudgetRepository({ db, qSchema });
   const budgetAlertRepository = new BudgetAlertRepository({ db, qSchema });
-  const costAnalysisRepository = new CostAnalysisRepository({ db, qSchema });
   const costAnalysisReportRepository = new CostAnalysisReportRepository({ db, qSchema });
   const budgetService = new BudgetService({ repository: budgetRepository });
   const budgetAlertService = new BudgetAlertService({ repository: budgetAlertRepository });
@@ -54,20 +51,17 @@ export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = co
   const discoveryWorker = new CurDiscoveryWorker({ repository: discoveryRepository, service: discoveryService, logger });
   const costController = new CostController({ contextService, curProvider, discoveryRepository, logger });
   const budgetController = new BudgetController({ contextService, budgetService, budgetAlertService });
-  const costAnalysisDataService = new CostAnalysisDataService({ curProvider });
-  // providerResolver lets the host supply per-tenant LLM credentials (the AI
-  // Providers screen). Null keeps the environment-only behaviour.
-  const costAnalysisService = new CostAnalysisService({ contextService, dataService: costAnalysisDataService, repository: costAnalysisRepository, logger, providerResolver });
-  const costAnalysisReportService = new CostAnalysisReportService({ contextService, repository: costAnalysisReportRepository, analysisService: costAnalysisService });
-  const costAnalysisReportWorker = new CostAnalysisReportWorker({ repository: costAnalysisReportRepository, analysisService: costAnalysisService, logger });
-  const costAnalysisController = new CostAnalysisController({ service: costAnalysisService, reportService: costAnalysisReportService });
+  const costAnalyserService = new CostAnalyserService({ contextService, athenaContextService, logger });
+  const artifactService = new CostReportArtifactService();
+  const costAnalysisReportService = new CostAnalysisReportService({ contextService, repository: costAnalysisReportRepository, artifactService });
+  const costAnalysisReportWorker = new CostAnalysisReportWorker({ repository: costAnalysisReportRepository, analyserService: costAnalyserService, logger });
+  const costAnalysisController = new CostAnalysisController({ service: costAnalyserService, reportService: costAnalysisReportService });
   const router = createCostRouter({ costController, budgetController, costAnalysisController }, logger);
   let mounted = false;
 
   return {
     async install() {
       await installCostBudgetSchema(db, qSchema);
-      await installCostAnalysisSchema(db, qSchema);
       await installCostAnalysisReportSchema(db, qSchema);
       await installCurDiscoverySchema(db, qSchema);
       logger.log?.("[Cost] Database migration verified");

package/src/repositories/aws-onboarding.repository.js

@@ -24,9 +24,10 @@ export class AwsOnboardingRepository {
 
     const connection = rows(await this.db.execute(sql`
       SELECT
-        connection_id,
-        role_arn,
-        external_id
+        connection_id,
+        role_arn,
+        external_id,
+        management_account_id
       FROM ${sql.raw(this.connectionsTable)}
       WHERE tenant_id::text = ${tenant}
         AND status = 'CONNECTED'
@@ -72,7 +73,8 @@ export class AwsOnboardingRepository {
         status: item.status,
       })),
       meta: {
-        payerRoleArn: connection.role_arn,
+        payerRoleArn: connection.role_arn,
+        managementAccountId: connection.management_account_id,
         externalId: connection.external_id,
         connectionId: connection.connection_id,
         curExportArn: curConfig.export_arn,

package/src/repositories/cost-analysis-report.repository.js

@@ -71,6 +71,22 @@ export class CostAnalysisReportRepository {
     return rows(await this.db.execute(sql`UPDATE ${sql.raw(this.reports)} SET status = 'RUNNING', attempt_count = attempt_count + 1, started_at = now(), error = NULL, updated_at = now() WHERE id = ${id} AND status = 'PENDING' RETURNING *`))[0] || null;
   }
 
+  async setTaskArn(id, taskArn) {
+    await this.db.execute(sql`UPDATE ${sql.raw(this.reports)} SET ecs_task_arn = ${taskArn}, updated_at = now() WHERE id = ${id}`);
+  }
+
+  async completeExternal(id, result) {
+    await this.db.execute(sql`
+      UPDATE ${sql.raw(this.reports)} SET status = 'COMPLETED', ecs_task_arn = ${result.taskArn},
+        model_id = ${result.modelId}, data_source = ${result.dataSource}, facts = ${JSON.stringify(result.facts || {})}::jsonb,
+        result = ${JSON.stringify(result.summary || {})}::jsonb, artifact_bucket = ${result.artifactBucket},
+        markdown_key = ${result.markdownKey}, markdown_size = ${Number(result.markdownSize || 0)},
+        pdf_key = ${result.pdfKey}, pdf_size = ${Number(result.pdfSize || 0)}, pdf_data = NULL,
+        completed_at = now(), updated_at = now()
+      WHERE id = ${id}
+    `);
+  }
+
   async complete(id, analysis, pdf) {
     await this.db.execute(sql`
       UPDATE ${sql.raw(this.reports)} SET status = 'COMPLETED', model_id = ${analysis.modelId}, data_source = ${analysis.dataSource || null},
@@ -82,13 +98,14 @@ export class CostAnalysisReportRepository {
   }
 
   async fail(id, error) {
-    await this.db.execute(sql`UPDATE ${sql.raw(this.reports)} SET status = 'FAILED', error = ${String(error?.message || error).slice(0, 2000)}, completed_at = now(), updated_at = now() WHERE id = ${id}`);
+    await this.db.execute(sql`UPDATE ${sql.raw(this.reports)} SET status = 'FAILED', ecs_task_arn = COALESCE(${error?.taskArn || null}, ecs_task_arn), error = ${String(error?.message || error).slice(0, 2000)}, completed_at = now(), updated_at = now() WHERE id = ${id}`);
   }
 
   async list(tenantId, limit = 100) {
     return rows(await this.db.execute(sql`
       SELECT id, schedule_frequency, scheduled_for, period_start, period_end, status,
-             attempt_count, model_id, data_source, facts, result, pdf_size, error,
+             attempt_count, model_id, data_source, facts, result, artifact_bucket,
+             markdown_key, markdown_size, pdf_key, pdf_size, error,
              started_at, completed_at, created_at
       FROM ${sql.raw(this.reports)} WHERE tenant_id = ${tenantId}
       ORDER BY scheduled_for DESC LIMIT ${Math.min(Math.max(Number(limit) || 100, 1), 250)}
@@ -101,7 +118,8 @@ export class CostAnalysisReportRepository {
     }
     return rows(await this.db.execute(sql`
       SELECT id, schedule_frequency, scheduled_for, period_start, period_end, status,
-             attempt_count, model_id, data_source, facts, result, pdf_size, error,
+             attempt_count, model_id, data_source, facts, result, artifact_bucket,
+             markdown_key, markdown_size, pdf_key, pdf_size, error,
              started_at, completed_at, created_at
       FROM ${sql.raw(this.reports)} WHERE tenant_id = ${tenantId} AND id = ${id} LIMIT 1
     `))[0] || null;

package/src/routes/index.js

@@ -16,6 +16,7 @@ export function createCostRouter({ costController, budgetController, costAnalysi
   router.get("/analysis/reports", costAnalysisController.reports.bind(costAnalysisController));
   router.get("/analysis/reports/:id", costAnalysisController.report.bind(costAnalysisController));
   router.get("/analysis/reports/:id/pdf", costAnalysisController.downloadPdf.bind(costAnalysisController));
+  router.get("/analysis/reports/:id/markdown", costAnalysisController.downloadMarkdown.bind(costAnalysisController));
   router.get("/budgets", budgetController.list.bind(budgetController));
   router.post("/budgets", budgetController.create.bind(budgetController));
   router.delete("/budgets/:id", budgetController.delete.bind(budgetController));

package/src/schema/cost-analysis-report.schema.js

@@ -31,6 +31,11 @@ export async function installCostAnalysisReportSchema(db, qSchema) {
     result jsonb,
     pdf_data bytea,
     pdf_size integer,
+    ecs_task_arn text,
+    artifact_bucket text,
+    markdown_key text,
+    markdown_size integer,
+    pdf_key text,
     error text,
     started_at timestamptz,
     completed_at timestamptz,
@@ -40,4 +45,9 @@ export async function installCostAnalysisReportSchema(db, qSchema) {
   )`));
   await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_ai_reports_tenant_created_idx ON ${qSchema}.cost_ai_reports (tenant_id, created_at DESC)`));
   await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_ai_reports_status_idx ON ${qSchema}.cost_ai_reports (status, created_at)`));
+  await db.execute(sql.raw(`ALTER TABLE ${qSchema}.cost_ai_reports ADD COLUMN IF NOT EXISTS ecs_task_arn text`));
+  await db.execute(sql.raw(`ALTER TABLE ${qSchema}.cost_ai_reports ADD COLUMN IF NOT EXISTS artifact_bucket text`));
+  await db.execute(sql.raw(`ALTER TABLE ${qSchema}.cost_ai_reports ADD COLUMN IF NOT EXISTS markdown_key text`));
+  await db.execute(sql.raw(`ALTER TABLE ${qSchema}.cost_ai_reports ADD COLUMN IF NOT EXISTS markdown_size integer`));
+  await db.execute(sql.raw(`ALTER TABLE ${qSchema}.cost_ai_reports ADD COLUMN IF NOT EXISTS pdf_key text`));
 }

package/src/services/cost-analyser.service.js

@@ -0,0 +1,158 @@
+import {
+  DescribeTasksCommand,
+  ECSClient,
+  RunTaskCommand,
+  StopTaskCommand,
+} from "@aws-sdk/client-ecs";
+import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { truthy } from "../lib/cost-utils.js";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const list = (value) => String(value || "").split(",").map((item) => item.trim()).filter(Boolean);
+
+function required(value, name) {
+  const text = String(value || "").trim();
+  if (!text) throw Object.assign(new Error(`${name} is required for external cost analysis`), { name: "CostAnalyserConfigError", statusCode: 503 });
+  return text;
+}
+
+function environment(values) {
+  return Object.entries(values).filter(([, value]) => value !== undefined && value !== null && value !== "").map(([name, value]) => ({ name, value: String(value) }));
+}
+
+async function bodyText(body) {
+  if (!body) return "";
+  if (typeof body.transformToString === "function") return body.transformToString();
+  const chunks = [];
+  for await (const chunk of body) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export class CostAnalyserService {
+  constructor({ contextService, athenaContextService, logger = console, env = process.env, ecsClient = null, s3Client = null } = {}) {
+    this.contextService = contextService;
+    this.athenaContextService = athenaContextService;
+    this.logger = logger;
+    this.enabled = truthy(env.COST_AI_ENABLED);
+    this.region = String(env.COST_AI_ANALYSER_REGION || env.AWS_REGION || env.AWS_DEFAULT_REGION || "us-east-1");
+    this.cluster = String(env.COST_AI_ANALYSER_CLUSTER || "").trim();
+    this.taskDefinition = String(env.COST_AI_ANALYSER_TASK_DEFINITION || "").trim();
+    this.containerName = String(env.COST_AI_ANALYSER_CONTAINER_NAME || "cost-ai-analyser").trim();
+    this.subnets = list(env.COST_AI_ANALYSER_SUBNETS);
+    this.securityGroups = list(env.COST_AI_ANALYSER_SECURITY_GROUPS);
+    this.assignPublicIp = truthy(env.COST_AI_ANALYSER_ASSIGN_PUBLIC_IP) ? "ENABLED" : "DISABLED";
+    this.reportBucket = String(env.COST_AI_ANALYSER_REPORT_BUCKET || "").trim();
+    this.targetRegions = String(env.COST_AI_ANALYSER_TARGET_REGIONS || env.AWS_REGION || "us-east-1").trim();
+    this.bedrockRegion = String(env.COST_AI_ANALYSER_BEDROCK_REGION || "").trim();
+    this.bedrockModelId = String(env.COST_AI_ANALYSER_BEDROCK_MODEL_ID || "").trim();
+    this.topServices = String(env.COST_AI_ANALYSER_TOP_N_SERVICES || "10").trim();
+    this.pollMs = Math.max(Number(env.COST_AI_ANALYSER_POLL_INTERVAL_MS || 15_000), 2_000);
+    this.timeoutMs = Math.max(Number(env.COST_AI_ANALYSER_TIMEOUT_MS || 45 * 60_000), 60_000);
+    this.ecs = ecsClient || new ECSClient({ region: this.region });
+    this.s3 = s3Client || new S3Client({ region: this.region });
+  }
+
+  status() {
+    const configured = Boolean(this.cluster && this.taskDefinition && this.subnets.length && this.securityGroups.length && this.reportBucket && this.bedrockModelId);
+    return {
+      enabled: this.enabled && configured,
+      provider: "meyi-cost-ai-analyser",
+      modelId: configured ? this.bedrockModelId : null,
+      region: configured ? this.bedrockRegion : null,
+      source: "ecs-task",
+    };
+  }
+
+  validate() {
+    if (!this.enabled) throw Object.assign(new Error("AI cost analysis is not enabled for this deployment"), { name: "CostAiDisabledError", statusCode: 503 });
+    required(this.cluster, "COST_AI_ANALYSER_CLUSTER");
+    required(this.taskDefinition, "COST_AI_ANALYSER_TASK_DEFINITION");
+    if (!this.subnets.length) required("", "COST_AI_ANALYSER_SUBNETS");
+    if (!this.securityGroups.length) required("", "COST_AI_ANALYSER_SECURITY_GROUPS");
+    required(this.reportBucket, "COST_AI_ANALYSER_REPORT_BUCKET");
+    required(this.bedrockModelId, "COST_AI_ANALYSER_BEDROCK_MODEL_ID");
+  }
+
+  async readJson(key) {
+    const response = await this.s3.send(new GetObjectCommand({ Bucket: this.reportBucket, Key: key }));
+    return JSON.parse(await bodyText(response.Body));
+  }
+
+  async execute({ tenantId, reportId, range, frequency, onStarted = null }) {
+    this.validate();
+    const customer = await this.contextService.resolve({ headers: {}, user: { tenant_id: tenantId, tenantId } });
+    const athena = this.athenaContextService.resolve(customer).config;
+    if (!athena.enabled) throw Object.assign(new Error("CUR discovery has not produced a queryable Athena table for this tenant"), { name: "CurDataNotReadyError", statusCode: 503 });
+    const targetRoleArn = required(customer.meta?.payerRoleArn, "customer TARGET_ROLE_ARN");
+    const targetAccountId = required(customer.meta?.managementAccountId || customer.accounts?.[0]?.id, "customer management account ID");
+    const prefix = `tenants/${tenantId}/reports/${reportId}`;
+    const values = {
+      REPORT_JOB_ID: reportId,
+      REPORT_TENANT_ID: tenantId,
+      REPORT_KEY_PREFIX: prefix,
+      REPORT_START_DATE: range.Start,
+      REPORT_END_DATE: range.End,
+      REPORT_FREQUENCY: frequency,
+      REPORT_BUCKET: this.reportBucket,
+      REPORT_BUCKET_REGION: this.region,
+      TARGET_ACCOUNT_ID: targetAccountId,
+      TARGET_ROLE_ARN: targetRoleArn,
+      TARGET_ROLE_EXTERNAL_ID: customer.meta?.externalId,
+      TARGET_REGIONS: this.targetRegions,
+      COST_CUR_DATABASE: athena.database,
+      COST_CUR_TABLE: athena.table,
+      COST_CUR_WORKGROUP: athena.workgroup,
+      COST_CUR_OUTPUT_LOCATION: athena.outputLocation,
+      COST_CUR_REGION: athena.region,
+      COST_CUR_TENANT_COLUMN: athena.tenantColumn,
+      COST_CUR_TENANT_PARTITION: athena.tenantPartition || tenantId,
+      BEDROCK_REGION: this.bedrockRegion,
+      BEDROCK_MODEL_ID: this.bedrockModelId,
+      TOP_N_SERVICES: this.topServices,
+    };
+    const launched = await this.ecs.send(new RunTaskCommand({
+      cluster: this.cluster,
+      taskDefinition: this.taskDefinition,
+      launchType: "FARGATE",
+      count: 1,
+      enableExecuteCommand: false,
+      networkConfiguration: { awsvpcConfiguration: { subnets: this.subnets, securityGroups: this.securityGroups, assignPublicIp: this.assignPublicIp } },
+      overrides: { containerOverrides: [{ name: this.containerName, environment: environment(values) }] },
+      startedBy: `meyi-cost-${reportId}`.slice(0, 36),
+    }));
+    if (launched.failures?.length || !launched.tasks?.[0]?.taskArn) {
+      const reason = launched.failures?.map((item) => item.reason || item.detail).filter(Boolean).join("; ") || "ECS did not return a task ARN";
+      throw Object.assign(new Error(`Unable to start cost analyser: ${reason}`), { name: "CostAnalyserLaunchError", statusCode: 502 });
+    }
+    const taskArn = launched.tasks[0].taskArn;
+    await onStarted?.(taskArn);
+    const deadline = Date.now() + this.timeoutMs;
+    while (Date.now() < deadline) {
+      const response = await this.ecs.send(new DescribeTasksCommand({ cluster: this.cluster, tasks: [taskArn] }));
+      const task = response.tasks?.[0];
+      if (task?.lastStatus === "STOPPED") {
+        const container = task.containers?.find((item) => item.name === this.containerName) || task.containers?.[0];
+        let status;
+        try { status = await this.readJson(`${prefix}/status.json`); } catch { status = null; }
+        if (Number(container?.exitCode ?? 1) !== 0 || status?.status !== "COMPLETED") {
+          throw Object.assign(new Error(status?.error || container?.reason || task.stoppedReason || "Cost analyser task failed"), { name: "CostAnalyserTaskError", statusCode: 502, taskArn });
+        }
+        return {
+          taskArn,
+          artifactBucket: this.reportBucket,
+          markdownKey: status.markdownKey || `${prefix}/report.md`,
+          pdfKey: status.pdfKey || `${prefix}/report.pdf`,
+          markdownSize: Number(status.markdownSize || 0),
+          pdfSize: Number(status.pdfSize || 0),
+          modelId: this.bedrockModelId,
+          dataSource: "AWS CUR",
+          facts: { currentTotal: Number(status.summary?.totalMonthlyCost || 0), currency: "USD" },
+          summary: status.summary || {},
+        };
+      }
+      await sleep(this.pollMs);
+    }
+    await this.ecs.send(new StopTaskCommand({ cluster: this.cluster, task: taskArn, reason: "Meyi cost analysis timeout" }));
+    throw Object.assign(new Error("Cost analyser task timed out"), { name: "CostAnalyserTimeoutError", statusCode: 504, taskArn });
+  }
+}

package/src/services/cost-analysis-report.service.js

@@ -11,17 +11,17 @@ function reportDto(row) {
     period: { Start: String(row.period_start).slice(0, 10), End: String(row.period_end).slice(0, 10) },
     status: row.status, attempts: Number(row.attempt_count || 0), modelId: row.model_id,
     dataSource: row.data_source, facts: row.facts || null, ...(row.result || {}),
-    pdfReady: row.status === "COMPLETED" && Number(row.pdf_size || 0) > 0,
+    pdfReady: row.status === "COMPLETED" && Boolean(row.pdf_key || row.pdf_data || Number(row.pdf_size || 0) > 0),
     pdfSize: Number(row.pdf_size || 0), error: row.error, startedAt: row.started_at,
     completedAt: row.completed_at, createdAt: row.created_at,
   };
 }
 
 export class CostAnalysisReportService {
-  constructor({ contextService, repository, analysisService }) {
+  constructor({ contextService, repository, artifactService }) {
     this.contextService = contextService;
     this.repository = repository;
-    this.analysisService = analysisService;
+    this.artifactService = artifactService;
   }
 
   tenant(req) { return this.contextService.tenantId(req); }
@@ -37,6 +37,11 @@ export class CostAnalysisReportService {
 
   async list(req, limit) { return (await this.repository.list(this.tenant(req), limit)).map(reportDto); }
 
+  async latest(req) {
+    const reports = await this.list(req, 1);
+    return reports[0] || null;
+  }
+
   async get(req, id) {
     const row = await this.repository.find(this.tenant(req), id);
     if (!row) throw Object.assign(new Error("AI cost report was not found"), { statusCode: 404 });
@@ -46,7 +51,18 @@ export class CostAnalysisReportService {
   async pdf(req, id) {
     const row = await this.repository.find(this.tenant(req), id, true);
     if (!row) throw Object.assign(new Error("AI cost report was not found"), { statusCode: 404 });
-    if (row.status !== "COMPLETED" || !row.pdf_data) throw Object.assign(new Error("The PDF is not ready"), { statusCode: 409 });
-    return { data: Buffer.from(row.pdf_data), filename: `meyi-cost-analysis-${String(row.period_start).slice(0, 10)}-${id.slice(0, 8)}.pdf` };
+    if (row.status !== "COMPLETED") throw Object.assign(new Error("The PDF is not ready"), { statusCode: 409 });
+    const data = row.pdf_key ? await this.artifactService.get(row.artifact_bucket, row.pdf_key) : row.pdf_data ? Buffer.from(row.pdf_data) : null;
+    if (!data?.length) throw Object.assign(new Error("The PDF artifact is unavailable"), { statusCode: 409 });
+    return { data, filename: `meyi-cost-analysis-${String(row.period_start).slice(0, 10)}-${id.slice(0, 8)}.pdf` };
+  }
+
+  async markdown(req, id) {
+    const row = await this.repository.find(this.tenant(req), id, true);
+    if (!row) throw Object.assign(new Error("AI cost report was not found"), { statusCode: 404 });
+    if (row.status !== "COMPLETED" || !row.markdown_key) throw Object.assign(new Error("The Markdown report is not ready"), { statusCode: 409 });
+    const data = await this.artifactService.get(row.artifact_bucket, row.markdown_key);
+    if (!data?.length) throw Object.assign(new Error("The Markdown artifact is unavailable"), { statusCode: 409 });
+    return { data, filename: `meyi-cost-analysis-${String(row.period_start).slice(0, 10)}-${id.slice(0, 8)}.md` };
   }
 }

package/src/services/cost-report-artifact.service.js

@@ -0,0 +1,22 @@
+import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";
+
+async function bytes(body) {
+  if (!body) return Buffer.alloc(0);
+  if (typeof body.transformToByteArray === "function") return Buffer.from(await body.transformToByteArray());
+  const chunks = [];
+  for await (const chunk of body) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks);
+}
+
+export class CostReportArtifactService {
+  constructor({ client = null, region = process.env.COST_AI_ANALYSER_REGION || process.env.AWS_REGION } = {}) {
+    this.client = client || new S3Client({ region });
+  }
+
+  async get(bucket, key) {
+    if (!bucket || !key) return null;
+    const response = await this.client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+    return bytes(response.Body);
+  }
+}
+