@evalops/maestro 0.10.51 → 0.10.53

package/dist/server/utils/token-estimator.d.ts

@@ -1,3 +1,3 @@
-export declare function approximateTokensFromText(text: string): number;
-export declare function approximateTokensFromJson(value: unknown): number;
+export { estimateTokens as approximateTokensFromText } from "@evalops/contracts";
+export { estimateTokensFromJson as approximateTokensFromJson } from "@evalops/contracts";
 //# sourceMappingURL=token-estimator.d.ts.map

package/dist/server/utils/token-estimator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-estimator.d.ts","sourceRoot":"","sources":["../../../src/server/utils/token-estimator.ts"],"names":[],"mappings":"AAAA,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMhE"}
+{"version":3,"file":"token-estimator.d.ts","sourceRoot":"","sources":["../../../src/server/utils/token-estimator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,sBAAsB,IAAI,yBAAyB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/server/utils/token-estimator.js

@@ -1,13 +1,3 @@
-export function approximateTokensFromText(text) {
-    // Rough heuristic: 1 token ≈ 4 chars, with minimum floor at 1
-    return Math.max(1, Math.round(text.length / 4));
-}
-export function approximateTokensFromJson(value) {
-    try {
-        return approximateTokensFromText(JSON.stringify(value));
-    }
-    catch {
-        return 0;
-    }
-}
+export { estimateTokens as approximateTokensFromText } from "@evalops/contracts";
+export { estimateTokensFromJson as approximateTokensFromJson } from "@evalops/contracts";
 //# sourceMappingURL=token-estimator.js.map

package/dist/server/utils/token-estimator.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-estimator.js","sourceRoot":"","sources":["../../../src/server/utils/token-estimator.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACrD,8DAA8D;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACvD,IAAI,CAAC;QACJ,OAAO,yBAAyB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,CAAC,CAAC;IACV,CAAC;AACF,CAAC","sourcesContent":["export function approximateTokensFromText(text: string): number {\n\t// Rough heuristic: 1 token ≈ 4 chars, with minimum floor at 1\n\treturn Math.max(1, Math.round(text.length / 4));\n}\n\nexport function approximateTokensFromJson(value: unknown): number {\n\ttry {\n\t\treturn approximateTokensFromText(JSON.stringify(value));\n\t} catch {\n\t\treturn 0;\n\t}\n}\n"]}
+{"version":3,"file":"token-estimator.js","sourceRoot":"","sources":["../../../src/server/utils/token-estimator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,sBAAsB,IAAI,yBAAyB,EAAE,MAAM,oBAAoB,CAAC","sourcesContent":["export { estimateTokens as approximateTokensFromText } from \"@evalops/contracts\";\nexport { estimateTokensFromJson as approximateTokensFromJson } from \"@evalops/contracts\";\n"]}

package/dist/server/validation.d.ts

@@ -3,6 +3,8 @@ import type { Static } from "@sinclair/typebox";
 import { type AnySchema } from "ajv";
 export declare const ChatRequestSchema: import("@sinclair/typebox").TObject<{
     model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    profile: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    persistProfile: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     messages: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         role: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"user">, import("@sinclair/typebox").TLiteral<"assistant">, import("@sinclair/typebox").TLiteral<"system">, import("@sinclair/typebox").TLiteral<"tool">]>;
         content: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
@@ -61,6 +63,32 @@ export declare const ChatRequestSchema: import("@sinclair/typebox").TObject<{
         }>>;
         provider: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         api: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        routingReceipt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            decisionId: import("@sinclair/typebox").TString;
+            requestedProfile: import("@sinclair/typebox").TString;
+            source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"request">, import("@sinclair/typebox").TLiteral<"session">, import("@sinclair/typebox").TLiteral<"compatibility_default">]>;
+            resolvedProfileId: import("@sinclair/typebox").TString;
+            resolvedProfileVersion: import("@sinclair/typebox").TNumber;
+            provider: import("@sinclair/typebox").TString;
+            model: import("@sinclair/typebox").TString;
+            reasoningEffort: import("@sinclair/typebox").TString;
+            createdAt: import("@sinclair/typebox").TString;
+            oracle: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                policyVersion: import("@sinclair/typebox").TString;
+                mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"available">, import("@sinclair/typebox").TLiteral<"recommended">, import("@sinclair/typebox").TLiteral<"required">]>;
+                reasons: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+            }>>;
+            fallback: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                reason: import("@sinclair/typebox").TString;
+                provider: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
+            experiment: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                experimentId: import("@sinclair/typebox").TString;
+                arm: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"control">, import("@sinclair/typebox").TLiteral<"treatment">]>;
+                policyVersion: import("@sinclair/typebox").TString;
+            }>>;
+        }>>;
         model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
     thinkingLevel: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"off">, import("@sinclair/typebox").TLiteral<"minimal">, import("@sinclair/typebox").TLiteral<"low">, import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"high">]>>;
@@ -152,6 +180,32 @@ export declare const PromptSuggestionRequestSchema: import("@sinclair/typebox").
         }>>;
         provider: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         api: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        routingReceipt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            decisionId: import("@sinclair/typebox").TString;
+            requestedProfile: import("@sinclair/typebox").TString;
+            source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"request">, import("@sinclair/typebox").TLiteral<"session">, import("@sinclair/typebox").TLiteral<"compatibility_default">]>;
+            resolvedProfileId: import("@sinclair/typebox").TString;
+            resolvedProfileVersion: import("@sinclair/typebox").TNumber;
+            provider: import("@sinclair/typebox").TString;
+            model: import("@sinclair/typebox").TString;
+            reasoningEffort: import("@sinclair/typebox").TString;
+            createdAt: import("@sinclair/typebox").TString;
+            oracle: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                policyVersion: import("@sinclair/typebox").TString;
+                mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"available">, import("@sinclair/typebox").TLiteral<"recommended">, import("@sinclair/typebox").TLiteral<"required">]>;
+                reasons: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+            }>>;
+            fallback: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                reason: import("@sinclair/typebox").TString;
+                provider: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            }>>;
+            experiment: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                experimentId: import("@sinclair/typebox").TString;
+                arm: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"control">, import("@sinclair/typebox").TLiteral<"treatment">]>;
+                policyVersion: import("@sinclair/typebox").TString;
+            }>>;
+        }>>;
         model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
     sessionId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;

package/dist/server/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/server/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAajD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAEN,KAAK,SAAS,EAGd,MAAM,KAAK,CAAC;AAgBb,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA4B,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEhE,eAAO,MAAM,cAAc;;EAAyB,CAAC;AACrD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D,eAAO,MAAM,wBAAwB;;;EAAmC,CAAC;AACzE,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE9E,eAAO,MAAM,2BAA2B;;EAAsC,CAAC;AAC/E,MAAM,MAAM,0BAA0B,GAAG,MAAM,CAC9C,OAAO,2BAA2B,CAClC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;IAA4B,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEhE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACJ,CAAC;AACvC,MAAM,MAAM,4BAA4B,GAAG,MAAM,CAChD,OAAO,6BAA6B,CACpC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;EACJ,CAAC;AACvC,MAAM,MAAM,4BAA4B,GAAG,MAAM,CAChD,OAAO,6BAA6B,CACpC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;EACJ,CAAC;AACtC,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC/C,OAAO,4BAA4B,CACnC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;EACJ,CAAC;AACtC,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC/C,OAAO,4BAA4B,CACnC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;EAA4B,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEhE,wBAAsB,oBAAoB,CAAC,CAAC,EAC3C,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,SAAS,GACf,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED,wBAAgB,eAAe,CAAC,CAAC,EAChC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,SAAS,EACjB,KAAK,SAAS,GACZ,CAAC,CAoBH"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/server/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAajD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAEN,KAAK,SAAS,EAGd,MAAM,KAAK,CAAC;AAgBb,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA4B,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEhE,eAAO,MAAM,cAAc;;EAAyB,CAAC;AACrD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D,eAAO,MAAM,wBAAwB;;;EAAmC,CAAC;AACzE,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE9E,eAAO,MAAM,2BAA2B;;EAAsC,CAAC;AAC/E,MAAM,MAAM,0BAA0B,GAAG,MAAM,CAC9C,OAAO,2BAA2B,CAClC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;IAA4B,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEhE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACJ,CAAC;AACvC,MAAM,MAAM,4BAA4B,GAAG,MAAM,CAChD,OAAO,6BAA6B,CACpC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;EACJ,CAAC;AACvC,MAAM,MAAM,4BAA4B,GAAG,MAAM,CAChD,OAAO,6BAA6B,CACpC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;EACJ,CAAC;AACtC,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC/C,OAAO,4BAA4B,CACnC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;EACJ,CAAC;AACtC,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC/C,OAAO,4BAA4B,CACnC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;EAA4B,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEhE,wBAAsB,oBAAoB,CAAC,CAAC,EAC3C,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,SAAS,GACf,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED,wBAAgB,eAAe,CAAC,CAAC,EAChC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,SAAS,EACjB,KAAK,SAAS,GACZ,CAAC,CAoBH"}

package/dist/services/image-providers/cost.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Painter cost estimation and spend ceiling.
+ *
+ * Image generation is metered per-image and prices are not exposed on the API
+ * response in a stable field, so pre-call gating needs a price table. We do
+ * NOT ship fabricated prices: the default table is empty and the ceiling only
+ * enforces when an operator configures both `MAESTRO_PAINTER_PRICE_TABLE` and
+ * `MAESTRO_PAINTER_MAX_COST_CENTS`. When prices are unknown, the gate fails
+ * OPEN (allows the call) and surfaces a reason, rather than blocking work on
+ * missing data.
+ *
+ * Price table shape (JSON env): keyed by `${model}|${size}|${quality}` →
+ * whole cents per image. A `*` wildcard is allowed for size and quality, e.g.
+ * `{"gpt-image-2|*|high": 8}`. Lookups prefer the most specific key.
+ *
+ * @module services/image-providers/cost
+ */
+export interface CostInput {
+    model: string;
+    size?: string;
+    quality?: string;
+    n?: number;
+}
+export interface BudgetDecision {
+    ok: boolean;
+    /** True when a ceiling is configured and prices are known. */
+    enforced: boolean;
+    estimatedCents?: number;
+    cumulativeCents: number;
+    ceilingCents?: number;
+    reason?: string;
+}
+export interface PriceTable {
+    /** key `${model}|${size}|${quality}` → cents per image */
+    [key: string]: number;
+}
+/**
+ * Estimate the cost in whole cents for a single image-API request. Returns
+ * `undefined` when no matching price is configured.
+ */
+export declare function estimateImageCost(input: CostInput): number | undefined;
+/**
+ * Process-level spend accumulator with an optional ceiling. Singleton so
+ * multiple painter calls within one agent process share a budget. Reset
+ * between sessions by the caller (or by process restart).
+ */
+export declare class PainterBudget {
+    private spent;
+    /** Whole cents; undefined when no ceiling is configured. */
+    readonly ceilingCents: number | undefined;
+    constructor();
+    reset(): void;
+    /**
+     * Release previously reserved cents, e.g. when the API call failed and the
+     * provider did not charge. Clamped at zero so a buggy caller can't go
+     * negative and effectively raise the ceiling.
+     */
+    release(cents: number): void;
+    get cumulativeCents(): number;
+    /**
+     * Check the request against the ceiling and reserve the estimate when
+     * allowed. Fails open when the ceiling or prices are unknown.
+     */
+    checkAndReserve(input: CostInput): BudgetDecision;
+}
+/** Process-wide budget. Re-evaluates the ceiling env on first access only. */
+export declare function getPainterBudget(): PainterBudget;
+/** Test-only: discard the cached budget so env changes take effect. */
+export declare function resetPainterBudgetSingleton(): void;
+//# sourceMappingURL=cost.d.ts.map

package/dist/services/image-providers/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../../src/services/image-providers/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IAC1B,0DAA0D;IAC1D,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB;AAyCD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAOtE;AAoBD;;;;GAIG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,KAAK,CAAK;IAElB,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;;IAW1C,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI5B,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc;CAuCjD;AAID,8EAA8E;AAC9E,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AAED,uEAAuE;AACvE,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/services/image-providers/cost.js

@@ -0,0 +1,164 @@
+/**
+ * Painter cost estimation and spend ceiling.
+ *
+ * Image generation is metered per-image and prices are not exposed on the API
+ * response in a stable field, so pre-call gating needs a price table. We do
+ * NOT ship fabricated prices: the default table is empty and the ceiling only
+ * enforces when an operator configures both `MAESTRO_PAINTER_PRICE_TABLE` and
+ * `MAESTRO_PAINTER_MAX_COST_CENTS`. When prices are unknown, the gate fails
+ * OPEN (allows the call) and surfaces a reason, rather than blocking work on
+ * missing data.
+ *
+ * Price table shape (JSON env): keyed by `${model}|${size}|${quality}` →
+ * whole cents per image. A `*` wildcard is allowed for size and quality, e.g.
+ * `{"gpt-image-2|*|high": 8}`. Lookups prefer the most specific key.
+ *
+ * @module services/image-providers/cost
+ */
+import { createLogger } from "../../utils/logger.js";
+const logger = createLogger("painter:cost");
+function priceTableFromEnv() {
+    const raw = process.env.MAESTRO_PAINTER_PRICE_TABLE?.trim();
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const table = {};
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
+                    table[k] = Math.floor(v);
+                }
+            }
+            return table;
+        }
+        logger.warn("MAESTRO_PAINTER_PRICE_TABLE is not a JSON object; ignoring");
+    }
+    catch {
+        logger.warn("MAESTRO_PAINTER_PRICE_TABLE is not valid JSON; ignoring");
+    }
+    return {};
+}
+function lookupCents(table, model, size, quality) {
+    const keys = [
+        `${model}|${size}|${quality}`,
+        `${model}|${size}|*`,
+        `${model}|*|${quality}`,
+        `${model}|*|*`,
+    ];
+    for (const k of keys) {
+        if (k in table)
+            return table[k];
+    }
+    return undefined;
+}
+/**
+ * Estimate the cost in whole cents for a single image-API request. Returns
+ * `undefined` when no matching price is configured.
+ */
+export function estimateImageCost(input) {
+    const table = getPriceTable();
+    const size = (input.size ?? "auto").toString();
+    const quality = (input.quality ?? "auto").toString();
+    const per = lookupCents(table, input.model, size, quality);
+    if (per === undefined)
+        return undefined;
+    return per * Math.max(1, input.n ?? 1);
+}
+/**
+ * Cached parsed price table, invalidated when MAESTRO_PAINTER_PRICE_TABLE
+ * changes. Env is immutable over a process lifetime in production, so this
+ * JSON.parses at most once; tests that mutate the env still re-parse because
+ * the cache key is the raw env string.
+ */
+let priceTableKey;
+let priceTableCache = {};
+function getPriceTable() {
+    const key = process.env.MAESTRO_PAINTER_PRICE_TABLE;
+    if (key !== priceTableKey) {
+        priceTableCache = priceTableFromEnv();
+        priceTableKey = key;
+    }
+    return priceTableCache;
+}
+/**
+ * Process-level spend accumulator with an optional ceiling. Singleton so
+ * multiple painter calls within one agent process share a budget. Reset
+ * between sessions by the caller (or by process restart).
+ */
+export class PainterBudget {
+    constructor() {
+        this.spent = 0;
+        const raw = process.env.MAESTRO_PAINTER_MAX_COST_CENTS?.trim();
+        if (raw) {
+            const parsed = Number.parseInt(raw, 10);
+            this.ceilingCents =
+                Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+        }
+    }
+    reset() {
+        this.spent = 0;
+    }
+    /**
+     * Release previously reserved cents, e.g. when the API call failed and the
+     * provider did not charge. Clamped at zero so a buggy caller can't go
+     * negative and effectively raise the ceiling.
+     */
+    release(cents) {
+        if (cents > 0)
+            this.spent = Math.max(0, this.spent - cents);
+    }
+    get cumulativeCents() {
+        return this.spent;
+    }
+    /**
+     * Check the request against the ceiling and reserve the estimate when
+     * allowed. Fails open when the ceiling or prices are unknown.
+     */
+    checkAndReserve(input) {
+        const ceiling = this.ceilingCents;
+        const estimate = estimateImageCost(input);
+        if (ceiling === undefined) {
+            return { ok: true, enforced: false, cumulativeCents: this.spent };
+        }
+        if (estimate === undefined) {
+            return {
+                ok: true,
+                enforced: false,
+                cumulativeCents: this.spent,
+                ceilingCents: ceiling,
+                reason: "cost ceiling set but no price configured for this model/size/quality; gate disabled",
+            };
+        }
+        if (this.spent + estimate > ceiling) {
+            return {
+                ok: false,
+                enforced: true,
+                estimatedCents: estimate,
+                cumulativeCents: this.spent,
+                ceilingCents: ceiling,
+                reason: `painter cost ceiling would be exceeded (${this.spent} + ${estimate} > ${ceiling} cents)`,
+            };
+        }
+        this.spent += estimate;
+        return {
+            ok: true,
+            enforced: true,
+            estimatedCents: estimate,
+            cumulativeCents: this.spent,
+            ceilingCents: ceiling,
+        };
+    }
+}
+let singleton = null;
+/** Process-wide budget. Re-evaluates the ceiling env on first access only. */
+export function getPainterBudget() {
+    if (!singleton)
+        singleton = new PainterBudget();
+    return singleton;
+}
+/** Test-only: discard the cached budget so env changes take effect. */
+export function resetPainterBudgetSingleton() {
+    singleton = null;
+}
+//# sourceMappingURL=cost.js.map

package/dist/services/image-providers/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../../src/services/image-providers/cost.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Painter cost estimation and spend ceiling.\n *\n * Image generation is metered per-image and prices are not exposed on the API\n * response in a stable field, so pre-call gating needs a price table. We do\n * NOT ship fabricated prices: the default table is empty and the ceiling only\n * enforces when an operator configures both `MAESTRO_PAINTER_PRICE_TABLE` and\n * `MAESTRO_PAINTER_MAX_COST_CENTS`. When prices are unknown, the gate fails\n * OPEN (allows the call) and surfaces a reason, rather than blocking work on\n * missing data.\n *\n * Price table shape (JSON env): keyed by `${model}|${size}|${quality}` →\n * whole cents per image. A `*` wildcard is allowed for size and quality, e.g.\n * `{\"gpt-image-2|*|high\": 8}`. Lookups prefer the most specific key.\n *\n * @module services/image-providers/cost\n */\n\nimport { createLogger } from \"../../utils/logger.js\";\n\nconst logger = createLogger(\"painter:cost\");\n\nexport interface CostInput {\n\tmodel: string;\n\tsize?: string;\n\tquality?: string;\n\tn?: number;\n}\n\nexport interface BudgetDecision {\n\tok: boolean;\n\t/** True when a ceiling is configured and prices are known. */\n\tenforced: boolean;\n\testimatedCents?: number;\n\tcumulativeCents: number;\n\tceilingCents?: number;\n\treason?: string;\n}\n\nexport interface PriceTable {\n\t/** key `${model}|${size}|${quality}` → cents per image */\n\t[key: string]: number;\n}\n\nfunction priceTableFromEnv(): PriceTable {\n\tconst raw = process.env.MAESTRO_PAINTER_PRICE_TABLE?.trim();\n\tif (!raw) return {};\n\ttry {\n\t\tconst parsed = JSON.parse(raw);\n\t\tif (parsed && typeof parsed === \"object\" && !Array.isArray(parsed)) {\n\t\t\tconst table: PriceTable = {};\n\t\t\tfor (const [k, v] of Object.entries(parsed)) {\n\t\t\t\tif (typeof v === \"number\" && Number.isFinite(v) && v >= 0) {\n\t\t\t\t\ttable[k] = Math.floor(v);\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn table;\n\t\t}\n\t\tlogger.warn(\"MAESTRO_PAINTER_PRICE_TABLE is not a JSON object; ignoring\");\n\t} catch {\n\t\tlogger.warn(\"MAESTRO_PAINTER_PRICE_TABLE is not valid JSON; ignoring\");\n\t}\n\treturn {};\n}\n\nfunction lookupCents(\n\ttable: PriceTable,\n\tmodel: string,\n\tsize: string,\n\tquality: string,\n): number | undefined {\n\tconst keys = [\n\t\t`${model}|${size}|${quality}`,\n\t\t`${model}|${size}|*`,\n\t\t`${model}|*|${quality}`,\n\t\t`${model}|*|*`,\n\t];\n\tfor (const k of keys) {\n\t\tif (k in table) return table[k];\n\t}\n\treturn undefined;\n}\n\n/**\n * Estimate the cost in whole cents for a single image-API request. Returns\n * `undefined` when no matching price is configured.\n */\nexport function estimateImageCost(input: CostInput): number | undefined {\n\tconst table = getPriceTable();\n\tconst size = (input.size ?? \"auto\").toString();\n\tconst quality = (input.quality ?? \"auto\").toString();\n\tconst per = lookupCents(table, input.model, size, quality);\n\tif (per === undefined) return undefined;\n\treturn per * Math.max(1, input.n ?? 1);\n}\n\n/**\n * Cached parsed price table, invalidated when MAESTRO_PAINTER_PRICE_TABLE\n * changes. Env is immutable over a process lifetime in production, so this\n * JSON.parses at most once; tests that mutate the env still re-parse because\n * the cache key is the raw env string.\n */\nlet priceTableKey: string | undefined;\nlet priceTableCache: PriceTable = {};\n\nfunction getPriceTable(): PriceTable {\n\tconst key = process.env.MAESTRO_PAINTER_PRICE_TABLE;\n\tif (key !== priceTableKey) {\n\t\tpriceTableCache = priceTableFromEnv();\n\t\tpriceTableKey = key;\n\t}\n\treturn priceTableCache;\n}\n\n/**\n * Process-level spend accumulator with an optional ceiling. Singleton so\n * multiple painter calls within one agent process share a budget. Reset\n * between sessions by the caller (or by process restart).\n */\nexport class PainterBudget {\n\tprivate spent = 0;\n\n\t/** Whole cents; undefined when no ceiling is configured. */\n\treadonly ceilingCents: number | undefined;\n\n\tconstructor() {\n\t\tconst raw = process.env.MAESTRO_PAINTER_MAX_COST_CENTS?.trim();\n\t\tif (raw) {\n\t\t\tconst parsed = Number.parseInt(raw, 10);\n\t\t\tthis.ceilingCents =\n\t\t\t\tNumber.isFinite(parsed) && parsed >= 0 ? parsed : undefined;\n\t\t}\n\t}\n\n\treset(): void {\n\t\tthis.spent = 0;\n\t}\n\n\t/**\n\t * Release previously reserved cents, e.g. when the API call failed and the\n\t * provider did not charge. Clamped at zero so a buggy caller can't go\n\t * negative and effectively raise the ceiling.\n\t */\n\trelease(cents: number): void {\n\t\tif (cents > 0) this.spent = Math.max(0, this.spent - cents);\n\t}\n\n\tget cumulativeCents(): number {\n\t\treturn this.spent;\n\t}\n\n\t/**\n\t * Check the request against the ceiling and reserve the estimate when\n\t * allowed. Fails open when the ceiling or prices are unknown.\n\t */\n\tcheckAndReserve(input: CostInput): BudgetDecision {\n\t\tconst ceiling = this.ceilingCents;\n\t\tconst estimate = estimateImageCost(input);\n\n\t\tif (ceiling === undefined) {\n\t\t\treturn { ok: true, enforced: false, cumulativeCents: this.spent };\n\t\t}\n\n\t\tif (estimate === undefined) {\n\t\t\treturn {\n\t\t\t\tok: true,\n\t\t\t\tenforced: false,\n\t\t\t\tcumulativeCents: this.spent,\n\t\t\t\tceilingCents: ceiling,\n\t\t\t\treason:\n\t\t\t\t\t\"cost ceiling set but no price configured for this model/size/quality; gate disabled\",\n\t\t\t};\n\t\t}\n\n\t\tif (this.spent + estimate > ceiling) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\tenforced: true,\n\t\t\t\testimatedCents: estimate,\n\t\t\t\tcumulativeCents: this.spent,\n\t\t\t\tceilingCents: ceiling,\n\t\t\t\treason: `painter cost ceiling would be exceeded (${this.spent} + ${estimate} > ${ceiling} cents)`,\n\t\t\t};\n\t\t}\n\n\t\tthis.spent += estimate;\n\t\treturn {\n\t\t\tok: true,\n\t\t\tenforced: true,\n\t\t\testimatedCents: estimate,\n\t\t\tcumulativeCents: this.spent,\n\t\t\tceilingCents: ceiling,\n\t\t};\n\t}\n}\n\nlet singleton: PainterBudget | null = null;\n\n/** Process-wide budget. Re-evaluates the ceiling env on first access only. */\nexport function getPainterBudget(): PainterBudget {\n\tif (!singleton) singleton = new PainterBudget();\n\treturn singleton;\n}\n\n/** Test-only: discard the cached budget so env changes take effect. */\nexport function resetPainterBudgetSingleton(): void {\n\tsingleton = null;\n}\n"]}

package/dist/services/image-providers/flux.d.ts

@@ -0,0 +1,40 @@
+import type { GenerateOptions, ImageProvider, ImageResult } from "./types.js";
+interface FalImage {
+    url?: string;
+    content_type?: string;
+}
+interface FalResponse {
+    images?: FalImage[];
+}
+export interface FluxTransport {
+    post(url: string, body: unknown, signal?: AbortSignal): Promise<FalResponse>;
+    get(url: string, signal?: AbortSignal): Promise<Buffer>;
+}
+export interface FluxImageProviderOptions {
+    apiKey: string;
+    model?: string;
+    writeImage: (bytes: Buffer, ext: string) => Promise<{
+        path: string;
+    }>;
+    /** Test seam; defaults to a fetch-backed transport. */
+    transport?: FluxTransport;
+}
+/** Map our size strings to fal's image_size enum. */
+export declare function mapSizeToFlux(size?: string): string;
+export declare class FluxImageProvider implements ImageProvider {
+    readonly id = "flux";
+    readonly supports: {
+        readonly generate: true;
+        readonly edit: false;
+        readonly mask: false;
+    };
+    private readonly apiKey;
+    private readonly model;
+    private readonly writeImage;
+    private readonly transport;
+    constructor(options: FluxImageProviderOptions);
+    generate(options: GenerateOptions): Promise<ImageResult>;
+    edit(): Promise<ImageResult>;
+}
+export {};
+//# sourceMappingURL=flux.d.ts.map

package/dist/services/image-providers/flux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flux.d.ts","sourceRoot":"","sources":["../../../src/services/image-providers/flux.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAkB9E,UAAU,QAAQ;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,WAAW;IACpB,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC7B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7E,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,wBAAwB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,uDAAuD;IACvD,SAAS,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAanD;AAgCD,qBAAa,iBAAkB,YAAW,aAAa;IACtD,QAAQ,CAAC,EAAE,UAAU;IACrB,QAAQ,CAAC,QAAQ;;;;MAAyD;IAE1E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,OAAO,EAAE,wBAAwB;IAOvC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;IAmCxD,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC;CAKlC"}

package/dist/services/image-providers/flux.js

@@ -0,0 +1,99 @@
+/**
+ * FLUX image provider via fal.ai.
+ *
+ * fal.run FLUX is generate-only here. It returns image URLs (not base64), so
+ * the provider fetches each URL and hands the bytes to the same `writeImage`
+ * callback the OpenAI provider uses. Masked editing is not supported (FLUX
+ * inpainting is a separate endpoint on fal; left for a follow-up).
+ *
+ * Stub-tested only: there is no live FAL_KEY in this environment, so the
+ * request/response mapping is unit-tested with an injected transport. Verify
+ * against your fal.ai account before relying on it.
+ */
+const DEFAULT_MODEL = "fal-ai/flux/schnell";
+const FAL_BASE = "https://fal.run";
+/** Map our size strings to fal's image_size enum. */
+export function mapSizeToFlux(size) {
+    switch (size) {
+        case "1024x1024":
+            return "square";
+        case "1536x1024":
+        case "1792x1024":
+            return "landscape_4_3";
+        case "1024x1536":
+        case "1024x1792":
+            return "portrait_4_3";
+        default:
+            return "square_hd";
+    }
+}
+function defaultTransport(apiKey) {
+    const headers = {
+        Authorization: `Key ${apiKey}`,
+        "Content-Type": "application/json",
+    };
+    return {
+        async post(url, body, signal) {
+            const res = await fetch(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!res.ok) {
+                throw new Error(`fal.ai request failed (${res.status}): ${await res.text()}`);
+            }
+            return (await res.json());
+        },
+        async get(url, signal) {
+            const res = await fetch(url, { signal });
+            if (!res.ok) {
+                throw new Error(`fal.ai image fetch failed (${res.status})`);
+            }
+            return Buffer.from(await res.arrayBuffer());
+        },
+    };
+}
+export class FluxImageProvider {
+    constructor(options) {
+        this.id = "flux";
+        this.supports = { generate: true, edit: false, mask: false };
+        this.apiKey = options.apiKey;
+        this.model = options.model ?? DEFAULT_MODEL;
+        this.writeImage = options.writeImage;
+        this.transport = options.transport ?? defaultTransport(this.apiKey);
+    }
+    async generate(options) {
+        const body = {
+            prompt: options.prompt,
+            image_size: mapSizeToFlux(options.size),
+            num_images: Math.max(1, options.n ?? 1),
+            output_format: "png",
+            enable_safety_checker: true,
+        };
+        const response = await this.transport.post(`${FAL_BASE}/${this.model}`, body, options.signal);
+        const items = response.images ?? [];
+        if (items.length === 0) {
+            throw new Error("FLUX provider returned no images.");
+        }
+        const images = [];
+        for (const item of items) {
+            if (!item.url)
+                continue;
+            const bytes = await this.transport.get(item.url, options.signal);
+            const { path } = await this.writeImage(bytes, "png");
+            images.push({
+                path,
+                mimeType: item.content_type ?? "image/png",
+            });
+        }
+        if (images.length === 0) {
+            throw new Error("FLUX provider returned no downloadable image URLs.");
+        }
+        return { images, provider: this.id, model: this.model };
+    }
+    async edit() {
+        throw new Error("FLUX provider does not support editing (generate only). Use the OpenAI provider for edits.");
+    }
+}
+//# sourceMappingURL=flux.js.map

package/dist/services/image-providers/flux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flux.js","sourceRoot":"","sources":["../../../src/services/image-providers/flux.ts"],"names":[],"mappings":"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","sourcesContent":["import type { GenerateOptions, ImageProvider, ImageResult } from \"./types.js\";\n\n/**\n * FLUX image provider via fal.ai.\n *\n * fal.run FLUX is generate-only here. It returns image URLs (not base64), so\n * the provider fetches each URL and hands the bytes to the same `writeImage`\n * callback the OpenAI provider uses. Masked editing is not supported (FLUX\n * inpainting is a separate endpoint on fal; left for a follow-up).\n *\n * Stub-tested only: there is no live FAL_KEY in this environment, so the\n * request/response mapping is unit-tested with an injected transport. Verify\n * against your fal.ai account before relying on it.\n */\n\nconst DEFAULT_MODEL = \"fal-ai/flux/schnell\";\nconst FAL_BASE = \"https://fal.run\";\n\ninterface FalImage {\n\turl?: string;\n\tcontent_type?: string;\n}\n\ninterface FalResponse {\n\timages?: FalImage[];\n}\n\nexport interface FluxTransport {\n\tpost(url: string, body: unknown, signal?: AbortSignal): Promise<FalResponse>;\n\tget(url: string, signal?: AbortSignal): Promise<Buffer>;\n}\n\nexport interface FluxImageProviderOptions {\n\tapiKey: string;\n\tmodel?: string;\n\twriteImage: (bytes: Buffer, ext: string) => Promise<{ path: string }>;\n\t/** Test seam; defaults to a fetch-backed transport. */\n\ttransport?: FluxTransport;\n}\n\n/** Map our size strings to fal's image_size enum. */\nexport function mapSizeToFlux(size?: string): string {\n\tswitch (size) {\n\t\tcase \"1024x1024\":\n\t\t\treturn \"square\";\n\t\tcase \"1536x1024\":\n\t\tcase \"1792x1024\":\n\t\t\treturn \"landscape_4_3\";\n\t\tcase \"1024x1536\":\n\t\tcase \"1024x1792\":\n\t\t\treturn \"portrait_4_3\";\n\t\tdefault:\n\t\t\treturn \"square_hd\";\n\t}\n}\n\nfunction defaultTransport(apiKey: string): FluxTransport {\n\tconst headers = {\n\t\tAuthorization: `Key ${apiKey}`,\n\t\t\"Content-Type\": \"application/json\",\n\t};\n\treturn {\n\t\tasync post(url, body, signal) {\n\t\t\tconst res = await fetch(url, {\n\t\t\t\tmethod: \"POST\",\n\t\t\t\theaders,\n\t\t\t\tbody: JSON.stringify(body),\n\t\t\t\tsignal,\n\t\t\t});\n\t\t\tif (!res.ok) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`fal.ai request failed (${res.status}): ${await res.text()}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn (await res.json()) as FalResponse;\n\t\t},\n\t\tasync get(url, signal) {\n\t\t\tconst res = await fetch(url, { signal });\n\t\t\tif (!res.ok) {\n\t\t\t\tthrow new Error(`fal.ai image fetch failed (${res.status})`);\n\t\t\t}\n\t\t\treturn Buffer.from(await res.arrayBuffer());\n\t\t},\n\t};\n}\n\nexport class FluxImageProvider implements ImageProvider {\n\treadonly id = \"flux\";\n\treadonly supports = { generate: true, edit: false, mask: false } as const;\n\n\tprivate readonly apiKey: string;\n\tprivate readonly model: string;\n\tprivate readonly writeImage: FluxImageProviderOptions[\"writeImage\"];\n\tprivate readonly transport: FluxTransport;\n\n\tconstructor(options: FluxImageProviderOptions) {\n\t\tthis.apiKey = options.apiKey;\n\t\tthis.model = options.model ?? DEFAULT_MODEL;\n\t\tthis.writeImage = options.writeImage;\n\t\tthis.transport = options.transport ?? defaultTransport(this.apiKey);\n\t}\n\n\tasync generate(options: GenerateOptions): Promise<ImageResult> {\n\t\tconst body = {\n\t\t\tprompt: options.prompt,\n\t\t\timage_size: mapSizeToFlux(options.size),\n\t\t\tnum_images: Math.max(1, options.n ?? 1),\n\t\t\toutput_format: \"png\" as const,\n\t\t\tenable_safety_checker: true,\n\t\t};\n\t\tconst response = await this.transport.post(\n\t\t\t`${FAL_BASE}/${this.model}`,\n\t\t\tbody,\n\t\t\toptions.signal,\n\t\t);\n\n\t\tconst items = response.images ?? [];\n\t\tif (items.length === 0) {\n\t\t\tthrow new Error(\"FLUX provider returned no images.\");\n\t\t}\n\n\t\tconst images = [];\n\t\tfor (const item of items) {\n\t\t\tif (!item.url) continue;\n\t\t\tconst bytes = await this.transport.get(item.url, options.signal);\n\t\t\tconst { path } = await this.writeImage(bytes, \"png\");\n\t\t\timages.push({\n\t\t\t\tpath,\n\t\t\t\tmimeType: item.content_type ?? \"image/png\",\n\t\t\t});\n\t\t}\n\t\tif (images.length === 0) {\n\t\t\tthrow new Error(\"FLUX provider returned no downloadable image URLs.\");\n\t\t}\n\t\treturn { images, provider: this.id, model: this.model };\n\t}\n\n\tasync edit(): Promise<ImageResult> {\n\t\tthrow new Error(\n\t\t\t\"FLUX provider does not support editing (generate only). Use the OpenAI provider for edits.\",\n\t\t);\n\t}\n}\n"]}

package/dist/services/image-providers/index.d.ts

@@ -0,0 +1,24 @@
+import type { ImageProvider } from "./types.js";
+export type { ImageBackground, ImageOutput, ImageProvider, ImageQuality, ImageResult, ImageSize, } from "./types.js";
+export type PainterProviderName = "openai" | "flux";
+export interface CreateImageProviderOptions {
+    provider?: PainterProviderName;
+    apiKey?: string;
+    baseURL?: string;
+    model?: string;
+    /**
+     * Persist decoded image bytes to disk and return the absolute path.
+     * Forwarded to the provider so it stays free of filesystem policy.
+     */
+    writeImage: (bytes: Buffer, ext: string) => Promise<{
+        path: string;
+    }>;
+}
+/**
+ * Build the configured image provider. Selection via the `provider` field
+ * (the painter resolves this from MAESTRO_PAINTER_PROVIDER, default "openai").
+ * Each provider declares its own `supports` map; the painter must respect it
+ * before calling generate/edit.
+ */
+export declare function createImageProvider(options: CreateImageProviderOptions): ImageProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/services/image-providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/image-providers/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,YAAY,EACX,eAAe,EACf,WAAW,EACX,aAAa,EACb,YAAY,EACZ,WAAW,EACX,SAAS,GACT,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,0BAA0B,GACjC,aAAa,CAiBf"}

package/dist/services/image-providers/index.js

@@ -0,0 +1,27 @@
+import { FluxImageProvider } from "./flux.js";
+import { OpenAIImageProvider } from "./openai.js";
+/**
+ * Build the configured image provider. Selection via the `provider` field
+ * (the painter resolves this from MAESTRO_PAINTER_PROVIDER, default "openai").
+ * Each provider declares its own `supports` map; the painter must respect it
+ * before calling generate/edit.
+ */
+export function createImageProvider(options) {
+    if (options.provider === "flux") {
+        if (!options.apiKey) {
+            throw new Error("FLUX provider requires FAL_KEY to be set.");
+        }
+        return new FluxImageProvider({
+            apiKey: options.apiKey,
+            model: options.model,
+            writeImage: options.writeImage,
+        });
+    }
+    return new OpenAIImageProvider({
+        apiKey: options.apiKey,
+        baseURL: options.baseURL,
+        model: options.model,
+        writeImage: options.writeImage,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/services/image-providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/image-providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA0BlD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAClC,OAAmC;IAEnC,IAAI,OAAO,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QACjC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,IAAI,iBAAiB,CAAC;YAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,UAAU,EAAE,OAAO,CAAC,UAAU;SAC9B,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,mBAAmB,CAAC;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,UAAU,EAAE,OAAO,CAAC,UAAU;KAC9B,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { FluxImageProvider } from \"./flux.js\";\nimport { OpenAIImageProvider } from \"./openai.js\";\nimport type { ImageProvider } from \"./types.js\";\n\nexport type {\n\tImageBackground,\n\tImageOutput,\n\tImageProvider,\n\tImageQuality,\n\tImageResult,\n\tImageSize,\n} from \"./types.js\";\n\nexport type PainterProviderName = \"openai\" | \"flux\";\n\nexport interface CreateImageProviderOptions {\n\tprovider?: PainterProviderName;\n\tapiKey?: string;\n\tbaseURL?: string;\n\tmodel?: string;\n\t/**\n\t * Persist decoded image bytes to disk and return the absolute path.\n\t * Forwarded to the provider so it stays free of filesystem policy.\n\t */\n\twriteImage: (bytes: Buffer, ext: string) => Promise<{ path: string }>;\n}\n\n/**\n * Build the configured image provider. Selection via the `provider` field\n * (the painter resolves this from MAESTRO_PAINTER_PROVIDER, default \"openai\").\n * Each provider declares its own `supports` map; the painter must respect it\n * before calling generate/edit.\n */\nexport function createImageProvider(\n\toptions: CreateImageProviderOptions,\n): ImageProvider {\n\tif (options.provider === \"flux\") {\n\t\tif (!options.apiKey) {\n\t\t\tthrow new Error(\"FLUX provider requires FAL_KEY to be set.\");\n\t\t}\n\t\treturn new FluxImageProvider({\n\t\t\tapiKey: options.apiKey,\n\t\t\tmodel: options.model,\n\t\t\twriteImage: options.writeImage,\n\t\t});\n\t}\n\treturn new OpenAIImageProvider({\n\t\tapiKey: options.apiKey,\n\t\tbaseURL: options.baseURL,\n\t\tmodel: options.model,\n\t\twriteImage: options.writeImage,\n\t});\n}\n"]}