@meyicloud/meyi-cost-server 1.4.1 → 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,20 +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 Markdown/PDF downloads
 - `GET /budgets` and `POST /budgets`
 - `DELETE /budgets/:id`
 - `GET /budget-alert-dismissals` and `POST /budget-alert-dismissals`

package/README.md

@@ -30,6 +30,9 @@ and AWS onboarding. The plugin owns cost routes and its budget-related tables.
 - Explicit CUR setup, pending-data, and unavailable states
 - Tenant-scoped budget rules
 - User-, tenant-, month-, and status-scoped budget-alert dismissals
+- Tenant-configurable daily, weekly, and monthly AI report schedules
+- PostgreSQL-backed background report jobs with failure history
+- Server-generated PDF reports available through tenant-scoped downloads
 
 Budgets are application rules stored in PostgreSQL; they are not AWS Budgets
 resources. The consuming application evaluates them against current cost and
@@ -94,7 +97,7 @@ For a local package installation test:
 
 ```bash
 npm pack
-npm install /path/to/meyicloud-meyi-cost-server-1.4.1.tgz
+npm install /path/to/meyicloud-meyi-cost-server-1.5.0.tgz
 ```
 
 ## Publish to npm
@@ -255,58 +258,54 @@ 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 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.
 
-| 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` | `1600` | No | Maximum response tokens, clamped from 600 to 3000. |
-| `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. |
-
-### Choosing a provider
+The authenticated report API is:
 
-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.
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `GET` | `/analysis/schedule` | Read this tenant's schedule. |
+| `PUT` | `/analysis/schedule` | Update the schedule; requires `req.user.role=admin`. |
+| `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. |
 
-`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.**
+Schedule and report rows live in `cost_ai_report_schedules` and
+`cost_ai_reports`. The worker atomically claims due schedules with a lease, so
+a restarted task can resume future work without relying on in-memory timers.
 
-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. Model or permission failures affect only the analysis
-request and do not change CUR, reports, or budgets.
+| Variable | Default | Required | Purpose |
+| --- | --- | --- | --- |
+| `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` | `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. |
+
+`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.4.1",
+  "version": "1.6.0",
   "description": "Tenant-aware AWS CUR and Athena cost plugin server for MeyiConnect",
   "type": "module",
   "main": "./index.js",
@@ -19,13 +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"
+    "express": "^4.21.1",
+    "luxon": "^3.7.2"
   },
   "peerDependencies": {
     "pg": ">=8"

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

@@ -1,8 +1,7 @@
-import { dateRange } from "../lib/cost-utils.js";
-
 export class CostAnalysisController {
-  constructor({ service }) {
+  constructor({ service, reportService }) {
     this.service = service;
+    this.reportService = reportService;
   }
 
   async status(req, res, next) {
@@ -13,16 +12,47 @@ 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); }
+  }
+
+  async schedule(req, res, next) {
+    try { return res.json(await this.reportService.getSchedule(req)); }
+    catch (error) { return next(error); }
+  }
+
+  async updateSchedule(req, res, next) {
+    try { return res.json(await this.reportService.saveSchedule(req, req.body || {})); }
+    catch (error) { return next(error); }
+  }
+
+  async reports(req, res, next) {
+    try { return res.json({ reports: await this.reportService.list(req, req.query.limit) }); }
+    catch (error) { return next(error); }
+  }
+
+  async report(req, res, next) {
+    try { return res.json(await this.reportService.get(req, req.params.id)); }
+    catch (error) { return next(error); }
+  }
+
+  async downloadPdf(req, res, next) {
+    try {
+      const report = await this.reportService.pdf(req, req.params.id);
+      res.setHeader("Content-Type", "application/pdf");
+      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); }
   }
 
-  async generate(req, res, next) {
+  async downloadMarkdown(req, res, next) {
     try {
-      const range = dateRange(req.body || {});
-      const durationDays = (new Date(`${range.End}T00:00:00Z`) - new Date(`${range.Start}T00:00:00Z`)) / 86_400_000;
-      if (durationDays > 366) return res.status(400).json({ error: "AI analysis supports a maximum range of 366 days" });
-      return res.json(await this.service.analyze(req, range));
+      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/lib/cost-analysis-schedule.js

@@ -0,0 +1,45 @@
+import { DateTime, IANAZone } from "luxon";
+
+const FREQUENCIES = new Set(["daily", "weekly", "monthly"]);
+
+export function validateSchedule(input = {}) {
+  const frequency = String(input.frequency || "weekly").toLowerCase();
+  const timezone = String(input.timezone || "UTC").trim();
+  const time = String(input.time || "09:00").trim();
+  if (!FREQUENCIES.has(frequency)) throw Object.assign(new Error("Frequency must be daily, weekly, or monthly"), { statusCode: 400 });
+  if (!IANAZone.isValidZone(timezone)) throw Object.assign(new Error("A valid IANA timezone is required"), { statusCode: 400 });
+  if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(time)) throw Object.assign(new Error("Time must use 24-hour HH:mm format"), { statusCode: 400 });
+  const dayOfWeek = frequency === "weekly" ? Number(input.dayOfWeek ?? 1) : null;
+  const dayOfMonth = frequency === "monthly" ? Number(input.dayOfMonth ?? 1) : null;
+  if (dayOfWeek !== null && (!Number.isInteger(dayOfWeek) || dayOfWeek < 0 || dayOfWeek > 6)) throw Object.assign(new Error("Weekly day must be between 0 and 6"), { statusCode: 400 });
+  if (dayOfMonth !== null && (!Number.isInteger(dayOfMonth) || dayOfMonth < 1 || dayOfMonth > 28)) throw Object.assign(new Error("Monthly day must be between 1 and 28"), { statusCode: 400 });
+  return { enabled: Boolean(input.enabled), frequency, timezone, time, dayOfWeek, dayOfMonth };
+}
+
+function atTime(date, time) {
+  const [hour, minute] = time.split(":").map(Number);
+  return date.set({ hour, minute, second: 0, millisecond: 0 });
+}
+
+export function nextScheduleRun(schedule, after = new Date()) {
+  const local = DateTime.fromJSDate(after, { zone: schedule.timezone });
+  let candidate = atTime(local.startOf("day"), schedule.time);
+  if (schedule.frequency === "daily") {
+    if (candidate <= local) candidate = candidate.plus({ days: 1 });
+  } else if (schedule.frequency === "weekly") {
+    const targetWeekday = schedule.dayOfWeek === 0 ? 7 : schedule.dayOfWeek;
+    candidate = atTime(local.startOf("week").plus({ days: targetWeekday - 1 }), schedule.time);
+    if (candidate <= local) candidate = candidate.plus({ weeks: 1 });
+  } else {
+    candidate = atTime(local.startOf("month").set({ day: schedule.dayOfMonth }), schedule.time);
+    if (candidate <= local) candidate = atTime(candidate.plus({ months: 1 }).startOf("month").set({ day: schedule.dayOfMonth }), schedule.time);
+  }
+  return candidate.toUTC().toJSDate();
+}
+
+export function reportRange(schedule, scheduledFor) {
+  const scheduledDay = DateTime.fromJSDate(new Date(scheduledFor), { zone: schedule.timezone }).startOf("day");
+  const end = schedule.frequency === "monthly" ? scheduledDay.startOf("month") : scheduledDay;
+  const start = schedule.frequency === "monthly" ? end.minus({ months: 1 }) : end.minus({ days: schedule.frequency === "weekly" ? 7 : 1 });
+  return { Start: start.toISODate(), End: end.toISODate() };
+}

package/src/plugin.js

@@ -11,10 +11,12 @@ 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 { CostAnalysisRepository } from "./repositories/cost-analysis.repository.js";
-import { CostAnalysisDataService } from "./services/cost-analysis-data.service.js";
-import { CostAnalysisService } from "./services/cost-analysis.service.js";
+import { installCostAnalysisReportSchema } from "./schema/cost-analysis-report.schema.js";
+import { CostAnalysisReportRepository } from "./repositories/cost-analysis-report.repository.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";
 import { CurDiscoveryAws } from "./cur-discovery/cur-discovery.aws.js";
@@ -22,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}"`;
@@ -31,7 +33,7 @@ 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 });
   const athenaContextService = new SaasAthenaContextService();
@@ -49,18 +51,18 @@ 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 costAnalysisController = new CostAnalysisController({ service: costAnalysisService });
+  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");
     },
@@ -70,10 +72,12 @@ export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = co
         mounted = true;
       }
       discoveryWorker.start();
+      costAnalysisReportWorker.start();
       logger.log?.(`[Cost] Routes active at ${apiBaseUri}/cost/*`);
     },
     async stop() {
       discoveryWorker.stop();
+      costAnalysisReportWorker.stop();
     },
     router,
   };

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

@@ -0,0 +1,127 @@
+import { randomUUID } from "node:crypto";
+import { sql } from "drizzle-orm";
+import { rows } from "../lib/cost-utils.js";
+
+export class CostAnalysisReportRepository {
+  constructor({ db, qSchema }) {
+    this.db = db;
+    this.schedules = `${qSchema}.cost_ai_report_schedules`;
+    this.reports = `${qSchema}.cost_ai_reports`;
+  }
+
+  async getSchedule(tenantId) {
+    return rows(await this.db.execute(sql`SELECT * FROM ${sql.raw(this.schedules)} WHERE tenant_id = ${tenantId}`))[0] || null;
+  }
+
+  async saveSchedule(tenantId, schedule, nextRunAt) {
+    return rows(await this.db.execute(sql`
+      INSERT INTO ${sql.raw(this.schedules)}
+        (tenant_id, enabled, frequency, time_of_day, timezone, day_of_week, day_of_month, next_run_at)
+      VALUES (${tenantId}, ${schedule.enabled}, ${schedule.frequency}, ${schedule.time}, ${schedule.timezone}, ${schedule.dayOfWeek}, ${schedule.dayOfMonth}, ${nextRunAt})
+      ON CONFLICT (tenant_id) DO UPDATE SET
+        enabled = EXCLUDED.enabled, frequency = EXCLUDED.frequency,
+        time_of_day = EXCLUDED.time_of_day, timezone = EXCLUDED.timezone,
+        day_of_week = EXCLUDED.day_of_week, day_of_month = EXCLUDED.day_of_month,
+        next_run_at = EXCLUDED.next_run_at, updated_at = now()
+      RETURNING *
+    `))[0];
+  }
+
+  async claimDue(limit, leaseMs) {
+    const leaseUntil = new Date(Date.now() + leaseMs);
+    const batchSize = Math.min(Math.max(Number(limit) || 10, 1), 50);
+    return rows(await this.db.execute(sql`
+      WITH due AS (
+        SELECT tenant_id, next_run_at AS scheduled_for
+        FROM ${sql.raw(this.schedules)}
+        WHERE enabled = true AND next_run_at IS NOT NULL AND next_run_at <= now()
+        ORDER BY next_run_at
+        FOR UPDATE SKIP LOCKED
+        LIMIT ${batchSize}
+      )
+      UPDATE ${sql.raw(this.schedules)} s
+      SET next_run_at = ${leaseUntil}, updated_at = now()
+      FROM due
+      WHERE s.tenant_id = due.tenant_id
+      RETURNING s.*, due.scheduled_for
+    `));
+  }
+
+  async setNextRun(tenantId, nextRunAt, completed = false, leaseUntil = null) {
+    await this.db.execute(sql`
+      UPDATE ${sql.raw(this.schedules)}
+      SET next_run_at = ${nextRunAt}, last_run_at = CASE WHEN ${completed} THEN now() ELSE last_run_at END, updated_at = now()
+      WHERE tenant_id = ${tenantId}
+        AND (${leaseUntil}::timestamptz IS NULL OR next_run_at = ${leaseUntil})
+    `);
+  }
+
+  async createReport(schedule, range) {
+    const inserted = rows(await this.db.execute(sql`
+      INSERT INTO ${sql.raw(this.reports)}
+        (id, tenant_id, schedule_frequency, scheduled_for, period_start, period_end)
+      VALUES (${randomUUID()}, ${schedule.tenant_id}, ${schedule.frequency}, ${schedule.scheduled_for}, ${range.Start}, ${range.End})
+      ON CONFLICT (tenant_id, scheduled_for) DO NOTHING
+      RETURNING *
+    `));
+    return inserted[0] || null;
+  }
+
+  async markRunning(id) {
+    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},
+        facts = ${JSON.stringify(analysis.facts)}::jsonb,
+        result = ${JSON.stringify({ summary: analysis.summary, findings: analysis.findings, recommendations: analysis.recommendations, limitations: analysis.limitations })}::jsonb,
+        pdf_data = ${pdf}, pdf_size = ${pdf.length}, completed_at = now(), updated_at = now()
+      WHERE id = ${id}
+    `);
+  }
+
+  async fail(id, error) {
+    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, 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)}
+    `));
+  }
+
+  async find(tenantId, id, includePdf = false) {
+    if (includePdf) {
+      return rows(await this.db.execute(sql`SELECT * FROM ${sql.raw(this.reports)} WHERE tenant_id = ${tenantId} AND id = ${id} LIMIT 1`))[0] || null;
+    }
+    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, 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

@@ -11,7 +11,12 @@ export function createCostRouter({ costController, budgetController, costAnalysi
   router.get("/cur-discovery", costController.curDiscovery.bind(costController));
   router.get("/analysis/status", costAnalysisController.status.bind(costAnalysisController));
   router.get("/analysis/latest", costAnalysisController.latest.bind(costAnalysisController));
-  router.post("/analysis", costAnalysisController.generate.bind(costAnalysisController));
+  router.get("/analysis/schedule", costAnalysisController.schedule.bind(costAnalysisController));
+  router.put("/analysis/schedule", costAnalysisController.updateSchedule.bind(costAnalysisController));
+  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

@@ -0,0 +1,53 @@
+import { sql } from "drizzle-orm";
+
+export async function installCostAnalysisReportSchema(db, qSchema) {
+  await db.execute(sql.raw(`CREATE TABLE IF NOT EXISTS ${qSchema}.cost_ai_report_schedules (
+    tenant_id text PRIMARY KEY,
+    enabled boolean NOT NULL DEFAULT false,
+    frequency text NOT NULL DEFAULT 'weekly' CHECK (frequency IN ('daily', 'weekly', 'monthly')),
+    time_of_day time NOT NULL DEFAULT '09:00:00',
+    timezone text NOT NULL DEFAULT 'UTC',
+    day_of_week smallint CHECK (day_of_week BETWEEN 0 AND 6),
+    day_of_month smallint CHECK (day_of_month BETWEEN 1 AND 28),
+    next_run_at timestamptz,
+    last_run_at timestamptz,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    updated_at timestamptz NOT NULL DEFAULT now()
+  )`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_ai_report_schedules_due_idx ON ${qSchema}.cost_ai_report_schedules (enabled, next_run_at)`));
+
+  await db.execute(sql.raw(`CREATE TABLE IF NOT EXISTS ${qSchema}.cost_ai_reports (
+    id text PRIMARY KEY,
+    tenant_id text NOT NULL,
+    schedule_frequency text NOT NULL CHECK (schedule_frequency IN ('daily', 'weekly', 'monthly')),
+    scheduled_for timestamptz NOT NULL,
+    period_start date NOT NULL,
+    period_end date NOT NULL,
+    status text NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING', 'RUNNING', 'COMPLETED', 'FAILED')),
+    attempt_count integer NOT NULL DEFAULT 0,
+    model_id text,
+    data_source text,
+    facts jsonb,
+    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,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    updated_at timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (tenant_id, scheduled_for)
+  )`));
+  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`));
+}