@ai-sdlc/orchestrator 0.1.0

package/dist/cost-governance.js

@@ -0,0 +1,106 @@
+/**
+ * CostGovernancePlugin — orchestrator plugin that wires budget checks,
+ * circuit breaker, and cost alert evaluation into the pipeline lifecycle.
+ *
+ * Registered automatically when a Pipeline has a costPolicy.
+ */
+/**
+ * Compute the start of the current budget period.
+ */
+function periodStart(period) {
+    const now = new Date();
+    switch (period) {
+        case 'day':
+            return new Date(now.getFullYear(), now.getMonth(), now.getDate()).toISOString();
+        case 'week': {
+            const day = now.getDay();
+            const diff = now.getDate() - day;
+            return new Date(now.getFullYear(), now.getMonth(), diff).toISOString();
+        }
+        case 'month':
+            return new Date(now.getFullYear(), now.getMonth(), 1).toISOString();
+        case 'quarter': {
+            const quarterMonth = Math.floor(now.getMonth() / 3) * 3;
+            return new Date(now.getFullYear(), quarterMonth, 1).toISOString();
+        }
+    }
+}
+export class CostGovernancePlugin {
+    costPolicy;
+    name = 'cost-governance';
+    costTracker;
+    notificationRouter;
+    log;
+    budgetAmount;
+    budgetPeriod;
+    constructor(costPolicy) {
+        this.costPolicy = costPolicy;
+    }
+    initialize(ctx) {
+        this.costTracker = ctx.costTracker;
+        this.notificationRouter = ctx.notificationRouter;
+        this.log = ctx.log;
+        this.budgetAmount = this.costPolicy.budget?.amount;
+        this.budgetPeriod = this.costPolicy.budget?.period;
+    }
+    async beforeRun(_event) {
+        const since = this.budgetPeriod ? periodStart(this.budgetPeriod) : undefined;
+        // Circuit breaker: check hard limit against current budget status
+        if (this.costTracker && this.costPolicy.perExecution?.hardLimit) {
+            const budget = this.costTracker.getBudgetStatus(this.budgetAmount, since);
+            if (budget.overBudget && this.costPolicy.perExecution.hardLimit.action === 'abort') {
+                throw new Error(`Cost governance: budget exceeded ($${budget.spentUsd.toFixed(2)} / $${budget.budgetUsd.toFixed(2)}). Execution aborted.`);
+            }
+            if (budget.overBudget &&
+                this.costPolicy.perExecution.hardLimit.action === 'require-approval') {
+                this.log.info(`Cost governance: budget exceeded ($${budget.spentUsd.toFixed(2)} / $${budget.budgetUsd.toFixed(2)}). Approval required.`);
+            }
+        }
+        // Soft limit check
+        if (this.costTracker && this.costPolicy.perExecution?.softLimit) {
+            const budget = this.costTracker.getBudgetStatus(this.budgetAmount, since);
+            if (budget.spentUsd >= this.costPolicy.perExecution.softLimit.amount) {
+                this.log.info(`Cost governance: soft limit reached ($${budget.spentUsd.toFixed(2)} >= $${this.costPolicy.perExecution.softLimit.amount.toFixed(2)})`);
+                if (this.notificationRouter) {
+                    await this.notificationRouter.dispatch({
+                        type: 'cost-alert',
+                        data: {
+                            utilization: budget.utilizationPercent.toFixed(0),
+                            spent: budget.spentUsd.toFixed(2),
+                            budget: budget.budgetUsd.toFixed(2),
+                            threshold: 'soft-limit',
+                            action: this.costPolicy.perExecution.softLimit.action,
+                        },
+                        severity: 'warning',
+                    });
+                }
+            }
+        }
+    }
+    async afterRun(_event) {
+        // Evaluate budget alerts after each run
+        if (this.costTracker && this.costPolicy.budget?.alerts) {
+            const since = this.budgetPeriod ? periodStart(this.budgetPeriod) : undefined;
+            const budget = this.costTracker.getBudgetStatus(this.budgetAmount, since);
+            for (const alert of this.costPolicy.budget.alerts) {
+                if (budget.utilizationPercent / 100 >= alert.threshold) {
+                    this.log.info(`Cost alert: ${(alert.threshold * 100).toFixed(0)}% budget consumed (action: ${alert.action})`);
+                    if (this.notificationRouter) {
+                        await this.notificationRouter.dispatch({
+                            type: 'cost-alert',
+                            data: {
+                                utilization: budget.utilizationPercent.toFixed(0),
+                                spent: budget.spentUsd.toFixed(2),
+                                budget: budget.budgetUsd.toFixed(2),
+                                threshold: (alert.threshold * 100).toFixed(0),
+                                action: alert.action,
+                            },
+                            severity: 'warning',
+                        });
+                    }
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=cost-governance.js.map

package/dist/cost-tracker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * CostTracker — records LLM usage costs, computes summaries,
+ * and tracks budget status.
+ *
+ * RFC reference: Lines 618-720 (cost tracking).
+ */
+import type { StateStore } from './state/store.js';
+import type { CostLedgerEntry } from './state/types.js';
+export interface CostSummary {
+    totalCostUsd: number;
+    totalTokens: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    entryCount: number;
+    avgCostPerRun: number;
+    avgTokensPerRun: number;
+    costByAgent: Record<string, number>;
+    costByModel: Record<string, number>;
+    period?: string;
+}
+export interface BudgetStatus {
+    budgetUsd: number;
+    spentUsd: number;
+    remainingUsd: number;
+    utilizationPercent: number;
+    overBudget: boolean;
+    projectedMonthlyUsd: number;
+}
+export interface CostTimeSeriesPoint {
+    date: string;
+    costUsd: number;
+    tokens: number;
+    runCount: number;
+}
+export declare class CostTracker {
+    private store;
+    constructor(store: StateStore);
+    /**
+     * Compute cost in USD from token counts and model name.
+     */
+    static computeCost(inputTokens: number, outputTokens: number, model: string, cacheReadTokens?: number): number;
+    /**
+     * Record a cost entry.
+     */
+    recordCost(entry: Omit<CostLedgerEntry, 'id' | 'createdAt'>): number;
+    /**
+     * Get a cost summary for a time range.
+     */
+    getCostSummary(since?: string): CostSummary;
+    /**
+     * Get budget status for a given budget and period.
+     */
+    getBudgetStatus(budgetUsd?: number, since?: string): BudgetStatus;
+    /**
+     * Get cost breakdown by agent.
+     */
+    getCostByAgent(since?: string): Record<string, {
+        costUsd: number;
+        tokens: number;
+        runs: number;
+    }>;
+    /**
+     * Get cost breakdown by pipeline stage.
+     */
+    getCostByStage(since?: string): Record<string, {
+        costUsd: number;
+        tokens: number;
+        runs: number;
+    }>;
+    /**
+     * Get cost time series at a given granularity.
+     */
+    getCostTimeSeries(granularity?: 'day' | 'week' | 'month', since?: string): CostTimeSeriesPoint[];
+}
+//# sourceMappingURL=cost-tracker.d.ts.map

package/dist/cost-tracker.js

@@ -0,0 +1,177 @@
+/**
+ * CostTracker — records LLM usage costs, computes summaries,
+ * and tracks budget status.
+ *
+ * RFC reference: Lines 618-720 (cost tracking).
+ */
+import { DEFAULT_MODEL_COSTS, DEFAULT_COST_BUDGET_USD } from './defaults.js';
+export class CostTracker {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Compute cost in USD from token counts and model name.
+     */
+    static computeCost(inputTokens, outputTokens, model, cacheReadTokens = 0) {
+        const costs = DEFAULT_MODEL_COSTS[model];
+        if (!costs) {
+            // Fallback: use sonnet pricing
+            const fallback = DEFAULT_MODEL_COSTS['claude-sonnet-4-5-20250929'] ?? {
+                inputPer1M: 3,
+                outputPer1M: 15,
+                cacheReadPer1M: 0.3,
+            };
+            return ((inputTokens * fallback.inputPer1M +
+                outputTokens * fallback.outputPer1M +
+                cacheReadTokens * (fallback.cacheReadPer1M ?? 0)) /
+                1_000_000);
+        }
+        return ((inputTokens * costs.inputPer1M +
+            outputTokens * costs.outputPer1M +
+            cacheReadTokens * (costs.cacheReadPer1M ?? 0)) /
+            1_000_000);
+    }
+    /**
+     * Record a cost entry.
+     */
+    recordCost(entry) {
+        // Auto-compute cost if not provided
+        let costUsd = entry.costUsd ?? 0;
+        if (costUsd === 0 && entry.model && (entry.inputTokens || entry.outputTokens)) {
+            costUsd = CostTracker.computeCost(entry.inputTokens ?? 0, entry.outputTokens ?? 0, entry.model, entry.cacheReadTokens ?? 0);
+        }
+        return this.store.saveCostEntry({
+            ...entry,
+            costUsd,
+            totalTokens: entry.totalTokens ?? (entry.inputTokens ?? 0) + (entry.outputTokens ?? 0),
+        });
+    }
+    /**
+     * Get a cost summary for a time range.
+     */
+    getCostSummary(since) {
+        const entries = this.store.getCostEntries({ since });
+        const dbSummary = this.store.getCostSummary(since);
+        const costByAgent = {};
+        const costByModel = {};
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        for (const entry of entries) {
+            costByAgent[entry.agentName] = (costByAgent[entry.agentName] ?? 0) + (entry.costUsd ?? 0);
+            if (entry.model) {
+                costByModel[entry.model] = (costByModel[entry.model] ?? 0) + (entry.costUsd ?? 0);
+            }
+            totalInputTokens += entry.inputTokens ?? 0;
+            totalOutputTokens += entry.outputTokens ?? 0;
+        }
+        const entryCount = dbSummary.entryCount;
+        return {
+            totalCostUsd: dbSummary.totalCostUsd,
+            totalTokens: dbSummary.totalTokens,
+            totalInputTokens,
+            totalOutputTokens,
+            entryCount,
+            avgCostPerRun: entryCount > 0 ? dbSummary.totalCostUsd / entryCount : 0,
+            avgTokensPerRun: entryCount > 0 ? dbSummary.totalTokens / entryCount : 0,
+            costByAgent,
+            costByModel,
+            period: since,
+        };
+    }
+    /**
+     * Get budget status for a given budget and period.
+     */
+    getBudgetStatus(budgetUsd, since) {
+        const budget = budgetUsd ?? DEFAULT_COST_BUDGET_USD;
+        const summary = this.getCostSummary(since);
+        // Project monthly cost based on daily average
+        const entries = this.store.getCostEntries({ since });
+        let projectedMonthlyUsd = 0;
+        if (entries.length > 0) {
+            const oldest = entries[entries.length - 1];
+            const newest = entries[0];
+            if (oldest.createdAt && newest.createdAt) {
+                const daySpan = Math.max(1, (new Date(newest.createdAt).getTime() - new Date(oldest.createdAt).getTime()) /
+                    (24 * 60 * 60 * 1000));
+                const dailyRate = summary.totalCostUsd / daySpan;
+                projectedMonthlyUsd = dailyRate * 30;
+            }
+        }
+        return {
+            budgetUsd: budget,
+            spentUsd: summary.totalCostUsd,
+            remainingUsd: Math.max(0, budget - summary.totalCostUsd),
+            utilizationPercent: budget > 0 ? (summary.totalCostUsd / budget) * 100 : 0,
+            overBudget: summary.totalCostUsd > budget,
+            projectedMonthlyUsd,
+        };
+    }
+    /**
+     * Get cost breakdown by agent.
+     */
+    getCostByAgent(since) {
+        const entries = this.store.getCostEntries({ since });
+        const result = {};
+        for (const entry of entries) {
+            if (!result[entry.agentName]) {
+                result[entry.agentName] = { costUsd: 0, tokens: 0, runs: 0 };
+            }
+            result[entry.agentName].costUsd += entry.costUsd ?? 0;
+            result[entry.agentName].tokens += entry.totalTokens ?? 0;
+            result[entry.agentName].runs += 1;
+        }
+        return result;
+    }
+    /**
+     * Get cost breakdown by pipeline stage.
+     */
+    getCostByStage(since) {
+        const entries = this.store.getCostEntries({ since });
+        const result = {};
+        for (const entry of entries) {
+            const stage = entry.stageName ?? 'unknown';
+            if (!result[stage]) {
+                result[stage] = { costUsd: 0, tokens: 0, runs: 0 };
+            }
+            result[stage].costUsd += entry.costUsd ?? 0;
+            result[stage].tokens += entry.totalTokens ?? 0;
+            result[stage].runs += 1;
+        }
+        return result;
+    }
+    /**
+     * Get cost time series at a given granularity.
+     */
+    getCostTimeSeries(granularity = 'day', since) {
+        const entries = this.store.getCostEntries({ since, limit: 10000 });
+        const buckets = new Map();
+        for (const entry of entries) {
+            if (!entry.createdAt)
+                continue;
+            const date = new Date(entry.createdAt);
+            let key;
+            switch (granularity) {
+                case 'day':
+                    key = date.toISOString().split('T')[0];
+                    break;
+                case 'week': {
+                    const weekStart = new Date(date);
+                    weekStart.setDate(weekStart.getDate() - weekStart.getDay());
+                    key = weekStart.toISOString().split('T')[0];
+                    break;
+                }
+                case 'month':
+                    key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
+                    break;
+            }
+            const existing = buckets.get(key) ?? { date: key, costUsd: 0, tokens: 0, runCount: 0 };
+            existing.costUsd += entry.costUsd ?? 0;
+            existing.tokens += entry.totalTokens ?? 0;
+            existing.runCount += 1;
+            buckets.set(key, existing);
+        }
+        return [...buckets.values()].sort((a, b) => a.date.localeCompare(b.date));
+    }
+}
+//# sourceMappingURL=cost-tracker.js.map

package/dist/defaults.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Centralized default values for the AI-SDLC orchestrator.
+ *
+ * All magic numbers, fallback strings, and environment-driven defaults live
+ * here so they can be tuned from a single location.  Every value can be
+ * overridden by an environment variable, a Pipeline/AgentRole YAML field,
+ * or an explicit function parameter — these are only the last-resort
+ * fallbacks.
+ */
+import type { NetworkPolicy, SandboxConstraints } from '@ai-sdlc/reference';
+/**
+ * Default model name (literal fallback).
+ * Consumers should read `AI_SDLC_MODEL` env var at call time and fall back
+ * to this constant, so tests that set env vars at runtime see the override.
+ */
+export declare const DEFAULT_MODEL = "claude-sonnet-4-5-20250929";
+/**
+ * Fallback values for GitHub org/repo — empty strings require explicit config.
+ * Consumers should read `GITHUB_REPOSITORY_OWNER` / `GITHUB_REPOSITORY`
+ * at call time and fall back to these constants.
+ */
+export declare const DEFAULT_GITHUB_ORG = "";
+export declare const DEFAULT_GITHUB_REPO = "";
+export declare const DEFAULT_GITHUB_REPOSITORY = "";
+export declare const DEFAULT_CONFIG_DIR_NAME: string;
+export declare const DEFAULT_SANDBOX_MEMORY_MB = 512;
+export declare const DEFAULT_SANDBOX_CPU_PERCENT = 80;
+export declare const DEFAULT_SANDBOX_NETWORK_POLICY: NetworkPolicy;
+export declare const DEFAULT_SANDBOX_TIMEOUT_MS: number;
+/** Build a SandboxConstraints object from defaults, optionally overriding timeout and workDir. */
+export declare function defaultSandboxConstraints(workDir: string, timeoutMs?: number): SandboxConstraints;
+export declare const DEFAULT_RUNNER_TIMEOUT_MS: number;
+export declare const DEFAULT_ALLOWED_TOOLS = "Edit,Write,Read,Glob,Grep,Bash";
+export declare const DEFAULT_MAX_FILES_PER_CHANGE = 15;
+export declare const DEFAULT_REQUIRE_TESTS = true;
+export declare const DEFAULT_BLOCKED_PATHS: string[];
+/**
+ * Lint command injected into agent prompts.
+ * Undefined by default — users opt in via AI_SDLC_LINT_COMMAND env var
+ * or by passing `lintCommand` in AgentContext.
+ */
+export declare const DEFAULT_LINT_COMMAND: string | undefined;
+/**
+ * Format command injected into agent prompts.
+ * Undefined by default — users opt in via AI_SDLC_FORMAT_COMMAND env var
+ * or by passing `formatCommand` in AgentContext.
+ */
+export declare const DEFAULT_FORMAT_COMMAND: string | undefined;
+export declare const DEFAULT_COMMIT_MESSAGE_TEMPLATE: string;
+export declare const DEFAULT_COMMIT_CO_AUTHOR: string;
+export declare const DEFAULT_OPENAI_API_URL = "https://api.openai.com/v1/chat/completions";
+export declare const DEFAULT_OPENAI_MODEL = "gpt-4";
+export declare const DEFAULT_ANTHROPIC_API_URL = "https://api.anthropic.com/v1/messages";
+export declare const DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5-20250929";
+export declare const DEFAULT_GENERIC_LLM_MODEL = "default";
+export declare const DEFAULT_COPILOT_MODEL: string | undefined;
+export declare const DEFAULT_CURSOR_MODEL: string | undefined;
+export declare const DEFAULT_CODEX_MODEL: string | undefined;
+export declare const DEFAULT_LLM_TIMEOUT_MS = 120000;
+export declare const DEFAULT_LLM_MAX_TOKENS = 4096;
+export declare const DEFAULT_LLM_SYSTEM_PROMPT = "You are a software engineering agent. Implement code changes as instructed.";
+export declare const DEFAULT_DOCKER_IMAGE = "node:20-slim";
+export declare const DEFAULT_WORKFLOW_FILE = "ci.yml";
+export declare const DEFAULT_LABEL_TO_SKILL_MAP: Record<string, string>;
+export declare const DEFAULT_ANALYSIS_CACHE_TTL_MS: number;
+export declare const DEFAULT_MAX_FIX_ATTEMPTS = 2;
+export declare const DEFAULT_MAX_LOG_LINES = 150;
+export declare const DEFAULT_GH_CLI_TIMEOUT_MS: number;
+export declare const DEFAULT_JIT_TTL_MS: number;
+export declare const DEFAULT_JIT_SCOPE: string[];
+export declare const DEFAULT_BRANCH_TEMPLATE = "ai-sdlc/issue-{issueNumber}";
+export declare const DEFAULT_BRANCH_PATTERN: RegExp;
+export declare const DEFAULT_PR_TITLE_TEMPLATE = "fix: {issueTitle} (#{issueNumber})";
+export declare const DEFAULT_PR_FOOTER = "*This PR was generated by [AI-SDLC](https://github.com/ai-sdlc-framework/ai-sdlc).*";
+export declare const DEFAULT_COMPLEXITY_THRESHOLDS: {
+    'fully-autonomous': {
+        min: number;
+        max: number;
+        strategy: "fully-autonomous";
+    };
+    'ai-with-review': {
+        min: number;
+        max: number;
+        strategy: "ai-with-review";
+    };
+    'ai-assisted': {
+        min: number;
+        max: number;
+        strategy: "ai-assisted";
+    };
+    'human-led': {
+        min: number;
+        max: number;
+        strategy: "human-led";
+    };
+};
+export declare const DEFAULT_MAX_LINES_PER_PR: {
+    readonly level0: 100;
+    readonly level1: 300;
+    readonly level2: 500;
+};
+export declare const DEFAULT_ANALYSIS_INCLUDE: string[];
+export declare const DEFAULT_ANALYSIS_EXCLUDE: string[];
+export declare const DEFAULT_GIT_HISTORY_DAYS = 90;
+export declare const DEFAULT_HOTSPOT_THRESHOLD = 0.3;
+/** Cost per million tokens for known models (input/output/cache-read). */
+export declare const DEFAULT_MODEL_COSTS: Record<string, {
+    inputPer1M: number;
+    outputPer1M: number;
+    cacheReadPer1M: number;
+}>;
+/** Default monthly cost budget in USD. */
+export declare const DEFAULT_COST_BUDGET_USD = 500;
+/** Dashboard refresh interval in milliseconds. */
+export declare const DEFAULT_DASHBOARD_REFRESH_MS = 2000;
+export type ComplexityBand = 'trivial' | 'standard' | 'complex' | 'critical';
+export interface GateProfile {
+    band: ComplexityBand;
+    minScore: number;
+    maxScore: number;
+    defaultEnforcement: string;
+    testCoverageThreshold: number;
+    reviewRequired: boolean;
+    securityScanRequired: boolean;
+    documentationRequired: boolean;
+}
+/** Static gate profiles per complexity band (RFC 217-228). */
+export declare const PROGRESSIVE_GATE_PROFILES: readonly GateProfile[];
+export declare const NOTIFICATION_TITLES: {
+    readonly issueValidationFailed: "AI-SDLC: Issue Validation Failed";
+    readonly complexityTooHigh: "AI-SDLC: Complexity Too High";
+    readonly agentFailed: "AI-SDLC: Agent Failed";
+    readonly guardrailViolations: "AI-SDLC: Guardrail Violations";
+    readonly prCreated: "AI-SDLC: PR Created";
+    readonly fixCIRetryLimit: "AI-SDLC: Fix-CI Retry Limit Reached";
+    readonly fixCIAgentFailed: "AI-SDLC: Fix-CI Agent Failed";
+    readonly fixCIGuardrailViolations: "AI-SDLC: Fix-CI Guardrail Violations";
+    readonly fixCIApplied: "AI-SDLC: Fix-CI Applied";
+};
+//# sourceMappingURL=defaults.d.ts.map