@intelligo-dev/executions 1.0.0-beta.1

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAiB/C,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC;;;;GAIG;AACH,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,aAAa,EACb,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,WAAW,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Execution lifecycle — the SaaS boundary around a native AI run.
+ *
+ *   const run = await executions.begin({ workspaceId, userId, capability });
+ *   if (!run.allowed) return refuse(run.reason);
+ *   try {
+ *     const result = await careerAgent.generate(messages); // native
+ *     await run.complete({ usage: result.usage, model: result.model });
+ *     return result;
+ *   } catch (error) {
+ *     await run.fail({ error });
+ *     throw error;
+ *   }
+ *
+ * The handle knows nothing about agents, tools, messages, or streams —
+ * only actor, workspace, capability, entitlement, status, usage, cost,
+ * credits, and audit (ADR-0003).
+ *
+ * Every terminal transition is idempotent: calling complete() twice, or
+ * fail() after complete(), leaves the first outcome in place. Streaming
+ * routes have several plausible finish paths (usage resolved, client
+ * abort, error) and must be able to fire whichever arrives first
+ * without racing.
+ */
+import type { ExecutionPorts } from "./ports";
+/**
+ * Row lifecycle. `settling` is non-terminal and deliberate: it marks
+ * the window where usage is being charged, so a second complete() or a
+ * racing fail() cannot re-enter it, and a settlement that dies mid-way
+ * leaves a state the stale sweep reports rather than a row that claims
+ * success for usage nobody recorded.
+ */
+export type ExecutionStatus = "running" | "settling" | "succeeded" | "failed" | "refused";
+export type BeginExecutionInput = {
+    workspaceId: string;
+    userId?: string | null;
+    /** Product-defined verb, e.g. "career.recommendation". */
+    capability: string;
+    /** Supply to reuse an existing correlation id; generated otherwise. */
+    requestId?: string;
+    /** Model the caller intends to use — informs the entitlement hold. */
+    model?: string;
+    metadata?: Record<string, unknown>;
+};
+export type CompleteExecutionInput = {
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    model?: string;
+    metadata?: Record<string, unknown>;
+};
+export type ExecutionRun = {
+    id: string;
+    requestId: string;
+    /** False when entitlement refused; complete()/fail() are then no-ops. */
+    allowed: boolean;
+    /** Set when allowed is false. */
+    reason?: string;
+    estimatedMnt?: number;
+    usingTrialCredits: boolean;
+    complete(input?: CompleteExecutionInput): Promise<void>;
+    fail(input: {
+        error: unknown;
+    }): Promise<void>;
+};
+export declare function createExecutions(ports?: ExecutionPorts): {
+    begin: (input: BeginExecutionInput) => Promise<ExecutionRun>;
+};
+export type Executions = ReturnType<typeof createExecutions>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAI9C;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,UAAU,GACV,WAAW,GACX,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;IACjB,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,IAAI,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD,CAAC;AAMF,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,cAAmB;mBAC7B,mBAAmB,KAAG,OAAO,CAAC,YAAY,CAAC;EAkOxE;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/lifecycle.js

@@ -0,0 +1,236 @@
+/**
+ * Execution lifecycle — the SaaS boundary around a native AI run.
+ *
+ *   const run = await executions.begin({ workspaceId, userId, capability });
+ *   if (!run.allowed) return refuse(run.reason);
+ *   try {
+ *     const result = await careerAgent.generate(messages); // native
+ *     await run.complete({ usage: result.usage, model: result.model });
+ *     return result;
+ *   } catch (error) {
+ *     await run.fail({ error });
+ *     throw error;
+ *   }
+ *
+ * The handle knows nothing about agents, tools, messages, or streams —
+ * only actor, workspace, capability, entitlement, status, usage, cost,
+ * credits, and audit (ADR-0003).
+ *
+ * Every terminal transition is idempotent: calling complete() twice, or
+ * fail() after complete(), leaves the first outcome in place. Streaming
+ * routes have several plausible finish paths (usage resolved, client
+ * abort, error) and must be able to fire whichever arrives first
+ * without racing.
+ */
+import { db } from "@intelligo-dev/core/db";
+import { createLogger } from "@intelligo-dev/core/logger";
+import { recordAuditEvent } from "@intelligo-dev/audit";
+import { and, eq } from "drizzle-orm";
+import { executions } from "./db/schema";
+const log = createLogger("Executions");
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createExecutions(ports = {}) {
+    async function begin(input) {
+        const requestId = input.requestId ?? crypto.randomUUID();
+        const id = crypto.randomUUID();
+        const startedAt = new Date();
+        const decision = ports.checkEntitlement
+            ? await ports.checkEntitlement({
+                workspaceId: input.workspaceId,
+                userId: input.userId,
+                capability: input.capability,
+                requestId,
+                model: input.model,
+            })
+            : { allowed: true };
+        await db.insert(executions).values({
+            id,
+            workspaceId: input.workspaceId,
+            userId: input.userId ?? null,
+            capability: input.capability,
+            requestId,
+            status: decision.allowed ? "running" : "refused",
+            model: input.model ?? null,
+            reservedMnt: decision.estimatedMnt ?? null,
+            refusalReason: decision.allowed ? null : (decision.reason ?? "refused"),
+            startedAt,
+            finishedAt: decision.allowed ? null : startedAt,
+            durationMs: decision.allowed ? null : 0,
+            metadata: input.metadata ?? null,
+        });
+        const usingTrialCredits = decision.usingTrialCredits ?? false;
+        if (!decision.allowed) {
+            await recordAuditEvent({
+                workspaceId: input.workspaceId,
+                actorId: input.userId ?? null,
+                action: "execution.refused",
+                resourceKind: "execution",
+                resourceId: id,
+                outcome: "failed",
+                metadata: {
+                    capability: input.capability,
+                    requestId,
+                    reason: decision.reason,
+                },
+            });
+            return {
+                id,
+                requestId,
+                allowed: false,
+                reason: decision.reason,
+                estimatedMnt: decision.estimatedMnt,
+                usingTrialCredits,
+                async complete() { },
+                async fail() { },
+            };
+        }
+        /**
+         * Compare-and-swap the row's status. Returns false when another
+         * path already moved it, so the caller can skip the side effects
+         * that belong to the transition it lost.
+         */
+        async function transition(from, to, fields = {}) {
+            const updated = await db
+                .update(executions)
+                .set({ status: to, ...fields })
+                .where(and(eq(executions.id, id), eq(executions.status, from)))
+                .returning();
+            return updated.length > 0;
+        }
+        /** Terminal transition: stamps the finish time and duration. */
+        function finishFields(fields) {
+            const finishedAt = new Date();
+            return {
+                finishedAt,
+                durationMs: finishedAt.getTime() - startedAt.getTime(),
+                ...fields,
+            };
+        }
+        return {
+            id,
+            requestId,
+            allowed: true,
+            estimatedMnt: decision.estimatedMnt,
+            usingTrialCredits,
+            async complete(result = {}) {
+                const inputTokens = result.usage?.inputTokens ?? 0;
+                const outputTokens = result.usage?.outputTokens ?? 0;
+                const totalTokens = result.usage?.totalTokens ?? inputTokens + outputTokens;
+                const model = result.model ?? input.model;
+                // Claim the right to settle BEFORE spending money. The CAS used
+                // to happen after settleUsage, so a second complete() — or a
+                // complete() racing a fail() — charged the workspace again and
+                // then quietly discovered it had lost the race. Status and
+                // audit were idempotent; the deduction was not.
+                if (!(await transition("running", "settling")))
+                    return;
+                let chargedMnt;
+                if (ports.settleUsage) {
+                    try {
+                        const settled = await ports.settleUsage({
+                            workspaceId: input.workspaceId,
+                            userId: input.userId,
+                            requestId,
+                            capability: input.capability,
+                            model,
+                            inputTokens,
+                            outputTokens,
+                            totalTokens,
+                            usingTrialCredits,
+                            metadata: result.metadata ?? input.metadata,
+                        });
+                        chargedMnt = settled?.chargedMnt;
+                    }
+                    catch (error) {
+                        // Usage is money: never silently drop it. The row stays
+                        // `settling` — a non-terminal state the stale sweep reports
+                        // — so the execution is visibly unsettled rather than
+                        // recorded as a successful free turn.
+                        log.error("Usage settlement failed", {
+                            executionId: id,
+                            requestId,
+                            workspaceId: input.workspaceId,
+                            error: errorMessage(error),
+                        });
+                        await recordAuditEvent({
+                            workspaceId: input.workspaceId,
+                            actorId: input.userId ?? null,
+                            action: "execution.settlement_failed",
+                            resourceKind: "execution",
+                            resourceId: id,
+                            outcome: "failed",
+                            metadata: {
+                                requestId,
+                                capability: input.capability,
+                                error: errorMessage(error),
+                            },
+                        });
+                        throw error;
+                    }
+                }
+                await transition("settling", "succeeded", finishFields({
+                    model: model ?? null,
+                    inputTokens,
+                    outputTokens,
+                    totalTokens,
+                    chargedMnt: chargedMnt ?? null,
+                }));
+                await recordAuditEvent({
+                    workspaceId: input.workspaceId,
+                    actorId: input.userId ?? null,
+                    action: "execution.completed",
+                    resourceKind: "execution",
+                    resourceId: id,
+                    metadata: {
+                        requestId,
+                        capability: input.capability,
+                        model,
+                        totalTokens,
+                        chargedMnt,
+                    },
+                });
+            },
+            async fail({ error }) {
+                // Only from `running`. Once complete() has claimed the row for
+                // settlement, a late abort must not release a hold that is
+                // about to be charged.
+                const transitioned = await transition("running", "failed", finishFields({ errorMessage: errorMessage(error).slice(0, 1000) }));
+                if (!transitioned)
+                    return;
+                if (ports.releaseHold) {
+                    try {
+                        await ports.releaseHold({
+                            workspaceId: input.workspaceId,
+                            requestId,
+                        });
+                    }
+                    catch (releaseError) {
+                        // Non-fatal: an unreleased hold expires on its own.
+                        log.warn("Hold release failed", {
+                            executionId: id,
+                            requestId,
+                            error: errorMessage(releaseError),
+                        });
+                    }
+                }
+                await recordAuditEvent({
+                    workspaceId: input.workspaceId,
+                    actorId: input.userId ?? null,
+                    action: "execution.failed",
+                    resourceKind: "execution",
+                    resourceId: id,
+                    outcome: "failed",
+                    metadata: {
+                        requestId,
+                        capability: input.capability,
+                        error: errorMessage(error),
+                    },
+                });
+            },
+        };
+    }
+    return { begin };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/ports.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Ports the execution lifecycle depends on.
+ *
+ * `executions` must not import `billing` — in the target structure
+ * entitlement decisions live in `entitlements` and the hold/settle
+ * mechanics in `credits`, neither of which exists yet. Rather than
+ * bake in a dependency that has to be unwound later, the lifecycle
+ * declares what it needs and the composition root binds today's
+ * billing implementations to it (ADR-0005).
+ *
+ * Both ports are optional: with neither bound, executions still record
+ * the lifecycle, they just don't gate or charge. That is what the
+ * reference app and any non-metered capability want.
+ */
+export type EntitlementDecision = {
+    allowed: boolean;
+    /** Human-readable refusal, surfaced to the caller and recorded. */
+    reason?: string;
+    /** Worst-case charge held for this execution, in MNT. */
+    estimatedMnt?: number;
+    /** True when the hold came out of the trial grant. */
+    usingTrialCredits?: boolean;
+};
+export type EntitlementRequest = {
+    workspaceId: string;
+    userId?: string | null;
+    capability: string;
+    /** Correlates the hold with settlement. */
+    requestId: string;
+    model?: string;
+};
+export type UsageSettlement = {
+    workspaceId: string;
+    userId?: string | null;
+    requestId: string;
+    capability: string;
+    model?: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    usingTrialCredits: boolean;
+    metadata?: Record<string, unknown>;
+};
+export type SettlementResult = {
+    /** Actual amount charged, in MNT, if the port computed one. */
+    chargedMnt?: number;
+};
+export type ExecutionPorts = {
+    /**
+     * Decide whether this execution may run and hold the worst-case
+     * cost. Called before the run; a refusal short-circuits it.
+     */
+    checkEntitlement?: (request: EntitlementRequest) => Promise<EntitlementDecision>;
+    /**
+     * Record real usage and release the hold. Called after a successful
+     * run. Must be idempotent per requestId — the lifecycle may retry.
+     */
+    settleUsage?: (settlement: UsageSettlement) => Promise<SettlementResult | void>;
+    /**
+     * Release a hold without charging (run failed before producing
+     * usage). Optional: when absent, the hold is left to expire.
+     */
+    releaseHold?: (input: {
+        workspaceId: string;
+        requestId: string;
+    }) => Promise<void>;
+};
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CACjB,OAAO,EAAE,kBAAkB,KACxB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAElC;;;OAGG;IACH,WAAW,CAAC,EAAE,CACZ,UAAU,EAAE,eAAe,KACxB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAEtC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;KACnB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB,CAAC"}

package/dist/ports.js

@@ -0,0 +1,16 @@
+/**
+ * Ports the execution lifecycle depends on.
+ *
+ * `executions` must not import `billing` — in the target structure
+ * entitlement decisions live in `entitlements` and the hold/settle
+ * mechanics in `credits`, neither of which exists yet. Rather than
+ * bake in a dependency that has to be unwound later, the lifecycle
+ * declares what it needs and the composition root binds today's
+ * billing implementations to it (ADR-0005).
+ *
+ * Both ports are optional: with neither bound, executions still record
+ * the lifecycle, they just don't gate or charge. That is what the
+ * reference app and any non-metered capability want.
+ */
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/pricing.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Model registry and execution cost accounting.
+ *
+ * This lives in `executions` rather than beside the provider clients
+ * because it is not AI code: it is what an execution costs. The
+ * boundary records actor, workspace, capability, usage and cost
+ * (ADR-0003), and the price of a token is the last of those.
+ *
+ * Deliberately a leaf module — no database, no provider SDK, no
+ * imports at all — and reachable as `@intelligo-dev/executions/pricing`
+ * so a client bundle can read a display name or a price without
+ * pulling in Drizzle. `@intelligo-dev/ai` re-exports it, so the ids that
+ * pick a provider and the ids that carry a price stay one list; two
+ * lists is how a model runs on Gemini and bills at Claude rates.
+ */
+/**
+ * Model configuration with display information and cost tracking
+ *
+ * 6 models, 3 providers: Google (2), OpenAI (3), Anthropic (1)
+ */
+export declare const MODEL_CONFIGS: {
+    readonly "google/gemini-2.5-flash": {
+        readonly provider: "google";
+        readonly model: "gemini-2.5-flash";
+        readonly displayName: "Gemini 2.5 Flash";
+        readonly costPerMInputTokens: 0.3;
+        readonly costPerMOutputTokens: 2.5;
+        readonly capabilities: {
+            readonly thinking: true;
+            readonly toolCall: true;
+            readonly vision: true;
+            readonly webSearch: true;
+            readonly codeExec: true;
+        };
+    };
+    readonly "google/gemini-2.5-pro": {
+        readonly provider: "google";
+        readonly model: "gemini-2.5-pro";
+        readonly displayName: "Gemini 2.5 Pro";
+        readonly costPerMInputTokens: 1.25;
+        readonly costPerMOutputTokens: 10;
+        readonly capabilities: {
+            readonly thinking: true;
+            readonly toolCall: true;
+            readonly vision: true;
+            readonly webSearch: true;
+            readonly codeExec: true;
+        };
+    };
+    readonly "openai/gpt-5-mini": {
+        readonly provider: "openai";
+        readonly model: "gpt-5-mini";
+        readonly displayName: "GPT-5 Mini";
+        readonly costPerMInputTokens: 0.25;
+        readonly costPerMOutputTokens: 2;
+        readonly capabilities: {
+            readonly thinking: true;
+            readonly toolCall: true;
+            readonly vision: true;
+            readonly webSearch: false;
+            readonly codeExec: false;
+        };
+    };
+    readonly "openai/gpt-5.4-mini": {
+        readonly provider: "openai";
+        readonly model: "gpt-5.4-mini";
+        readonly displayName: "GPT-5.4 Mini";
+        readonly costPerMInputTokens: 0.75;
+        readonly costPerMOutputTokens: 4.5;
+        readonly capabilities: {
+            readonly thinking: true;
+            readonly toolCall: true;
+            readonly vision: true;
+            readonly webSearch: true;
+            readonly codeExec: true;
+        };
+    };
+    readonly "openai/o4-mini": {
+        readonly provider: "openai";
+        readonly model: "o4-mini";
+        readonly displayName: "o4-mini";
+        readonly costPerMInputTokens: 1.1;
+        readonly costPerMOutputTokens: 4.4;
+        readonly capabilities: {
+            readonly thinking: true;
+            readonly toolCall: true;
+            readonly vision: true;
+            readonly webSearch: true;
+            readonly codeExec: true;
+        };
+    };
+    readonly "anthropic/claude-sonnet-4-6": {
+        readonly provider: "anthropic";
+        readonly model: "claude-sonnet-4-6-20260214";
+        readonly displayName: "Claude Sonnet 4.6";
+        readonly costPerMInputTokens: 3;
+        readonly costPerMOutputTokens: 15;
+        readonly capabilities: {
+            readonly thinking: true;
+            readonly toolCall: true;
+            readonly vision: true;
+            readonly webSearch: true;
+            readonly codeExec: true;
+        };
+    };
+};
+export type ModelId = keyof typeof MODEL_CONFIGS;
+/**
+ * Calculate the dollar cost for a given model and token counts.
+ */
+export declare function calculateCost(modelId: string, inputTokens: number, outputTokens: number): number;
+/**
+ * Default billing margin multiplier applied on top of raw model cost.
+ * Covers infra, tool overhead, FX volatility, and profit. Tunable per
+ * deploy via billing_settings.margin_multiplier; this constant is the
+ * fallback when the DB value is absent.
+ *
+ * INVARIANT — 65% gross margin floor (founder contract):
+ *   gross_margin = 1 − 1/multiplier
+ *   We must keep gross_margin ≥ 0.65 across every model in MODEL_CONFIGS,
+ *   which means multiplier ≥ 1/0.35 ≈ 2.857. The current value of 4
+ *   yields 75%, leaving comfortable buffer above the floor for FX moves
+ *   and unexpected provider price hikes. The Vitest assertion in
+ *   models.test.ts pins this — drop below 2.857 at your own risk.
+ */
+export declare const DEFAULT_BILLING_MARGIN = 4;
+/**
+ * Default USD→MNT exchange rate fallback. Real value lives in
+ * billing_settings.usd_to_mnt_rate and is read per request.
+ */
+export declare const DEFAULT_USD_TO_MNT_RATE = 3450;
+/**
+ * Per-model maximum output budget used for worst-case pre-request cost
+ * estimation in checkQuota. Numbers are conservative — cap on streamed
+ * output tokens we'd actually let a single chat turn produce.
+ */
+export declare const MODEL_OUTPUT_BUDGET: Record<ModelId, number>;
+export type ChargedAmount = {
+    rawCostUsd: number;
+    chargedMnt: number;
+};
+/**
+ * Convert raw model cost to MNT user-facing charged amount.
+ *
+ * chargedMnt = ceil( rawCostUsd × margin × fxRate )
+ *
+ * The rounding is upward so micro-fractions never let a free request
+ * slip through; over-billing per request is at most 1 MNT.
+ */
+export declare function calculateChargedMnt(modelId: string, inputTokens: number, outputTokens: number, fxRate?: number, margin?: number): ChargedAmount;
+/**
+ * Worst-case MNT cost estimate for a single chat turn against a given
+ * model. Used by checkQuota to refuse requests whose ceiling cost would
+ * exceed remaining balance, before we burn provider tokens. Uses the
+ * full MODEL_OUTPUT_BUDGET as the output side and a generous 16K input
+ * budget to cover system prompt + conversation history.
+ */
+export declare function estimateWorstCaseChargedMnt(modelId: string, fxRate?: number, margin?: number): number;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwFhB,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,aAAa,CAAC;AAEjD;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,MAAM,CAkBR;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAOvD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,MAAgC,EACxC,MAAM,GAAE,MAA+B,GACtC,aAAa,CAIf;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAgC,EACxC,MAAM,GAAE,MAA+B,GACtC,MAAM,CAKR"}