@project-ava-supernova/core 0.2.71

package/dist/awareness/tick-engine.js

@@ -0,0 +1,156 @@
+/**
+ * ══════════════════════════════════════════════════════════════════════
+ * Ava Tick Engine — Proactive Awareness System
+ * ══════════════════════════════════════════════════════════════════════
+ *
+ * Periodic background check that makes Ava continuously aware of the
+ * user's world — tasks, journal, memory, support, token balance — and
+ * surfaces findings only when they matter.
+ *
+ * She checks silently. If there's nothing worth saying, the user never
+ * knows. If there is, she speaks up gently.
+ *
+ * Inspired by concepts that a certain "AI safety" company accidentally
+ * published to npm because they forgot to add *.map to .npmignore.
+ * Cheers Anthropic — couldn't have done it without your generosity. 🍻
+ *
+ * Unlike theirs, this one ships openly. No feature flags. No stealth.
+ * No "undercover mode". Just transparency, as always.
+ *
+ * ══════════════════════════════════════════════════════════════════════
+ */
+/** Maximum time a proactive action should block the user (ms) */
+const BLOCKING_BUDGET_MS = 15_000;
+/** Minimum interval between ticks (ms) — don't spam */
+const MIN_TICK_INTERVAL_MS = 120_000; // 2 minutes
+/** Don't fire the same event type more than once per interval (ms) */
+const DEDUP_INTERVAL_MS = 600_000; // 10 minutes
+export class TickEngine {
+    lastTick = 0;
+    lastEventByType = new Map();
+    /**
+     * Run a single tick — check everything, return events worth surfacing.
+     * Designed to be called periodically from an interval timer.
+     * Fast and non-blocking — total execution should stay under BLOCKING_BUDGET_MS.
+     */
+    async tick(ctx) {
+        const now = Date.now();
+        // Rate limit — don't tick too frequently
+        if (now - this.lastTick < MIN_TICK_INTERVAL_MS) {
+            return { events: [], timestamp: now };
+        }
+        this.lastTick = now;
+        const events = [];
+        const start = Date.now();
+        // ── Overdue tasks ──────────────────────────────────────────────
+        if (ctx.getOverdueTasks && Date.now() - start < BLOCKING_BUDGET_MS) {
+            try {
+                const overdue = await ctx.getOverdueTasks();
+                if (overdue.length > 0 && !this.isDuplicate('task_overdue', now)) {
+                    const urgent = overdue.filter(t => t.priority === 'urgent' || t.priority === 'high');
+                    if (urgent.length > 0) {
+                        events.push({
+                            type: 'task_overdue',
+                            message: `You've got ${urgent.length} high-priority task${urgent.length > 1 ? 's' : ''} overdue — "${urgent[0].title}"${urgent.length > 1 ? ` and ${urgent.length - 1} more` : ''}`,
+                            severity: 'urgent',
+                            blocking: false,
+                        });
+                    }
+                    else if (overdue.length > 0) {
+                        events.push({
+                            type: 'task_overdue',
+                            message: `${overdue.length} task${overdue.length > 1 ? 's' : ''} overdue — "${overdue[0].title}"${overdue.length > 1 ? ` and ${overdue.length - 1} more` : ''}`,
+                            severity: 'nudge',
+                            blocking: false,
+                        });
+                    }
+                }
+            }
+            catch { /* non-critical */ }
+        }
+        // ── Journal streak ─────────────────────────────────────────────
+        if (ctx.getJournalStreak && Date.now() - start < BLOCKING_BUDGET_MS) {
+            try {
+                const streak = await ctx.getJournalStreak();
+                if (streak.days >= 3 && !streak.writtenToday && !this.isDuplicate('journal_streak', now)) {
+                    const hour = new Date().getHours();
+                    if (hour >= 19) { // Only nudge in the evening
+                        events.push({
+                            type: 'journal_streak',
+                            message: `You've got a ${streak.days}-day journal streak going. Quick entry before the day ends?`,
+                            severity: 'nudge',
+                            blocking: false,
+                        });
+                    }
+                }
+            }
+            catch { /* non-critical */ }
+        }
+        // ── Token balance ──────────────────────────────────────────────
+        if (ctx.getTokenBalance) {
+            const balance = ctx.getTokenBalance();
+            if (balance && balance.limit > 0 && balance.limit < 999_999_999) {
+                const remaining = balance.limit - balance.used;
+                const pct = (remaining / balance.limit) * 100;
+                if (pct <= 10 && !this.isDuplicate('token_warning', now)) {
+                    events.push({
+                        type: 'token_warning',
+                        message: `Heads up — you've used ${Math.round(100 - pct)}% of your tokens this month. About ${formatTokens(remaining)} left.`,
+                        severity: pct <= 5 ? 'urgent' : 'nudge',
+                        blocking: false,
+                    });
+                }
+            }
+        }
+        // ── Support unread ─────────────────────────────────────────────
+        if (ctx.getSupportUnread) {
+            const unread = ctx.getSupportUnread();
+            if (unread > 0 && !this.isDuplicate('support_reply', now)) {
+                events.push({
+                    type: 'support_reply',
+                    message: `You've got ${unread} unread support message${unread > 1 ? 's' : ''}. Check the Help section.`,
+                    severity: 'nudge',
+                    blocking: false,
+                });
+            }
+        }
+        // ── Memory health ──────────────────────────────────────────────
+        if (ctx.getMemoryHealth && Date.now() - start < BLOCKING_BUDGET_MS) {
+            try {
+                const health = await ctx.getMemoryHealth();
+                if (health.contradictions > 0 && !this.isDuplicate('memory_health', now)) {
+                    events.push({
+                        type: 'memory_health',
+                        message: `I noticed ${health.contradictions} potential contradiction${health.contradictions > 1 ? 's' : ''} in my memory. Might be worth reviewing.`,
+                        severity: 'info',
+                        blocking: false,
+                    });
+                }
+            }
+            catch { /* non-critical */ }
+        }
+        // Mark events as fired for dedup
+        for (const event of events) {
+            this.lastEventByType.set(event.type, now);
+        }
+        return { events, timestamp: now };
+    }
+    /** Check if this event type was already fired recently */
+    isDuplicate(type, now) {
+        const last = this.lastEventByType.get(type);
+        return !!last && now - last < DEDUP_INTERVAL_MS;
+    }
+    /** Reset dedup tracking — useful when user explicitly asks for a check */
+    reset() {
+        this.lastEventByType.clear();
+        this.lastTick = 0;
+    }
+}
+function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${Math.round(n / 1000)}K`;
+    return String(n);
+}
+//# sourceMappingURL=tick-engine.js.map

package/dist/awareness/tick-engine.js.map

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

package/dist/billing/credits.d.ts

@@ -0,0 +1,213 @@
+import type { PlanTier } from './plans.js';
+/** Every metered operation has an action type. Stage 2's meter interceptor
+ *  will tag each LLM / generation / Creative-Studio call with one of these
+ *  so the usage pipeline can map it to a credit cost.
+ *
+ *  Actions are the *unit of user intent* ("you just did X"), not the
+ *  underlying provider cost. Two different models running the same action
+ *  cost the user the same credits; raw provider cost varies underneath. */
+export type CreditAction = 'chat_turn' | 'light_call' | 'heavy_persona' | 'light_persona' | 'orchestration' | 'image_gen' | 'video_gen' | 'voice_gen' | 'music_gen' | 'logo_gen' | 'bg_removal';
+/** Base credit cost for each action. Cache-hit discount applies per-call
+ *  via creditsFor(). Raw provider cost column is illustrative (typical mid-
+ *  2026 rates) — it drifts, which is exactly why we decouple from it. */
+export declare const CREDIT_COST: Record<CreditAction, number>;
+/**
+ * Video credits scale with Wan output resolution. 720p is the base; 1080p
+ * costs ~2× because Wan's per-clip cost roughly doubles, holding the same
+ * margin. Charge is flat across clip duration. Kept in sync with the web
+ * platform's credits-pricing VIDEO_GEN_CREDITS. `video_gen` above is the
+ * 720p base for callers that don't tier.
+ */
+export declare const VIDEO_GEN_CREDITS: Record<'480' | '720' | '1080', number>;
+export declare function videoCreditCost(sr: number | string | null | undefined): number;
+/** Default cache-hit discount: user pays 0.3× normal cost when the provider
+ *  reports a prompt-cache hit. Cache savings on input-heavy turns roughly
+ *  match this; output cost is unaffected by cache so on output-heavy models
+ *  (V4 Pro) a flat 0.3× whole-turn discount over-credits the user and the
+ *  margin can flip negative — see CACHE_HIT_MULTIPLIER_BY_MODEL.
+ *
+ *  Minimum 1 credit is deducted so cache hits are never free. */
+export declare const CACHE_HIT_MULTIPLIER = 0.3;
+/** Per-model cache-hit discount override. Output-heavy models cap the
+ *  discount at 0.5× because the input share of total cost is smaller, so
+ *  a 0.3× whole-turn discount exceeds actual savings. Calibrated 2026-04-25.
+ *  Default 0.3× still applies for any model not listed. */
+export declare const CACHE_HIT_MULTIPLIER_BY_MODEL: Record<string, number>;
+/** Look up the cache-hit multiplier for a given model id. */
+export declare function cacheHitMultiplier(model: string | null | undefined): number;
+/** Action costs are flat brackets (chat_turn = 2, heavy_persona = 3, etc.)
+ *  but per-token spend varies wildly by model — V4 Pro is ~17× the cost of
+ *  Qwen Flash for the same input. Without a per-model adjustment, V4 Pro
+ *  on chat_turn loses money on every call. The multiplier scales the
+ *  bracket cost to track actual spend.
+ *
+ *  SUPERSEDED IN PART, 2026-08-16. Everything below describes a table built
+ *  by scaling ratios that were themselves hand-calibrated. Four entries
+ *  (qwen3.7-plus, qwen3.8-max, qwen3.5-flash, mistral-medium-3.5) have since
+ *  been re-derived from MEASURED traffic and no longer follow it — including
+ *  the anchor the others were scaled against. Read the per-entry notes as
+ *  authoritative over this header wherever the two disagree.
+ *
+ *  Recalibrated 2026-07-19 to a 30% net margin target (was 40%, was 55%
+ *  before that). Every multiplier scaled by 6/7 — the exact factor to
+ *  move 40% → 30% (price = cost / (1 − margin)). Trade is deliberate:
+ *  thinner margin per existing user, materially more credits per dollar,
+ *  the difference goes back to the user. "Value over margin" —
+ *  sustainability floor, not ceiling.
+ *
+ *  NOTE: 30% is the *typical* target at ~60% utilisation. The margin at
+ *  100% utilisation has NOT been re-modelled since the 40% rebalance —
+ *  see MARGIN_TARGETS. Derive it before cutting further; heavy users are
+ *  where a low target turns negative first.
+ *
+ *  Mirror of web's credits-pricing.ts MODEL_COST_MULTIPLIER — keep them
+ *  in sync; web is the authoritative billing surface and core's meter
+ *  dual-writes for dataset audit. Default 1.0 for unlisted models. */
+export declare const MODEL_COST_MULTIPLIER: Record<string, number>;
+/** Per-mode cost multiplier — applied AFTER the model multiplier in
+ *  `creditsForTurn` / `creditsFor`. Lets a mode price itself based on
+ *  the richness of its specialist fleet, independent of which model
+ *  the orchestrator picks for a given role.
+ *
+ *  All modes 1.0× as of the 2026-04-29 40% rebalance. Aurora used to
+ *  carry a 1.3× bump to compensate for Medium 3.5's price; that's been
+ *  folded into the per-model multiplier (Medium 3.5 = 3.12×) instead.
+ *  Per-model is the honest place to scale model cost — a BYOK user
+ *  picking Medium 3.5 directly outside Aurora pays the same per-token
+ *  rate the model genuinely costs us. The mode multiplier stays in the
+ *  architecture as a future hook (premium-tier modes, billed-by-mode
+ *  experiments) but no mode currently uses it. */
+export declare const MODE_COST_MULTIPLIER: Record<string, number>;
+/** Apply per-mode cost multiplier. Default 1.0 for unlisted modes. */
+export declare function modeCostMultiplier(mode: string | null | undefined): number;
+/** Apply per-model cost multiplier. Accepts catalogue, prefixed or wire ids. */
+export declare function modelCostMultiplier(model: string | null | undefined): number;
+/** Compute the credits to deduct for a single metered action.
+ *  Pass `model` to apply the per-model cost multiplier — strongly
+ *  recommended for any LLM call. Defaults to 1.0× when omitted. */
+export declare function creditsFor(action: CreditAction, opts?: {
+    cacheHit?: boolean;
+    model?: string;
+}): number;
+/** A generated health plan: training only, nutrition only, or both. */
+export type HealthPlanKind = 'fitness' | 'meal' | 'combined';
+/** Per-week credit rate for plan generation. Combined ≈ 2× single because it
+ *  weaves two domains (training + nutrition). Approved 2026-06-30. */
+export declare const PLAN_CREDITS_PER_WEEK: Record<'single' | 'combined', number>;
+/**
+ * Flat credit cost to generate a health plan — the single, predictable price
+ * that REPLACES per-turn billing for plan generation (the route that builds
+ * the plan server-side charges this once instead of metering each turn).
+ *
+ * Scales by DAY at the weekly rate, rounded up, minimum 1. Single
+ * (fitness | meal) = 5 cr/week; combined = 10.
+ *   single   1d = 1 · 3d = 3 · 7d = 5 · 28d = 20 · 84d = 60
+ *   combined 1d = 2 · 3d = 5 · 7d = 10 · 28d = 40 · 84d = 120
+ *
+ * It used to round UP TO WHOLE WEEKS, which meant a 1-day plan cost exactly
+ * what a 7-day plan cost. That was a harmless edge case while the offered
+ * durations were 1/7/28/56/84 and nobody picked 1. It stopped being harmless
+ * when the durations became 1/3/7: we would have been steering people toward
+ * the shortest plan while charging them a full week for a seventh of the
+ * output, which is indefensible however you dress it up.
+ *
+ * Every price that existed before is unchanged — 7, 14, 21, 28, 56 and 84 days
+ * all come out identical, because 28/7 x 5 is 20 by either route. Only the two
+ * new short durations move, and only downward.
+ */
+export declare function creditsForPlan(type: HealthPlanKind, durationDays: number): number;
+/** Bracket size in effective tokens — one bracket = the flat per-action
+ *  charge. A typical agentic turn (~16K input + ~2K output, weighted to
+ *  ~24K effective) lands in 1-2 brackets. Larger turns scale linearly. */
+export declare const TOKENS_PER_BRACKET = 16000;
+/** Output tokens cost ~3-6× more than input across our model lineup
+ *  (Qwen 3.7 Plus: 5.86×, V4 Pro: 2.0×, Qwen Flash: 8×). A flat 4× weight
+ *  is the reasonable midpoint without per-model pricing tables here.
+ *  The cache discount weight (0.1×) reflects ~90% provider cache savings. */
+export declare const OUTPUT_TOKEN_WEIGHT = 4;
+export declare const CACHED_TOKEN_WEIGHT = 0.1;
+/** Token-aware credit cost for a single LLM turn. Replaces flat
+ *  `creditsFor(action)` for chat-like actions when prompt/output token
+ *  counts are known. Behaviour:
+ *
+ *    1. Compute effective_tokens = nonCachedInput + 0.1×cachedInput +
+ *       4×output. Captures both the input volume and the output-cost
+ *       weight without a per-model pricing table.
+ *    2. brackets = ceil(effective_tokens / TOKENS_PER_BRACKET), min 1.
+ *    3. credits = max(flatScaled, brackets × base × multiplier).
+ *
+ *  Effect: small turns charge the flat per-action rate (no surprise
+ *  for users on light chat). Long-context turns (200K input, 1M context)
+ *  scale up so they actually pay for themselves at the COGS layer.
+ *
+ *  Cache discount is folded into effective_tokens via CACHED_TOKEN_WEIGHT
+ *  rather than applied as a second multiplier — applying both would
+ *  double-discount cache. Small-turn cache hits still use the legacy
+ *  whole-turn discount via creditsFor() since brackets=1 short-circuits. */
+export declare function creditsForTurn(action: CreditAction, opts: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedTokens?: number;
+    model?: string;
+    /** Orchestrated mode in play — drives the mode-cost multiplier
+     *  (Aurora 1.3×, Maestro/Supernova 1.0×). Layered on top of the
+     *  per-model multiplier so a richer fleet pays for itself without
+     *  lying about model cost. Optional — omitted = 1.0×. */
+    mode?: string;
+}): {
+    credits: number;
+    brackets: number;
+};
+/** New plan shape for the credit-based era. Kept separate from the legacy
+ *  PLANS export in plans.ts so Stages 2-3 can dual-write without breaking
+ *  existing consumers of token-based allowances. When Stage 3 flips billing
+ *  to credits, plans.ts becomes display-only / deprecated. */
+export interface CreditPlanDefinition {
+    name: string;
+    price: number;
+    credits: number;
+    storageGb: number;
+    rateLimit: number;
+    /** Rough ceiling of mixed actions per month. Pitch copy number, not a
+     *  hard metering rule. Derived from a typical workload mix: 60% chat,
+     *  20% orchestrated, 15% Creative, 5% Teach. */
+    approximateMixedActions: number;
+}
+export declare const CREDIT_PLANS: Record<PlanTier, CreditPlanDefinition>;
+/** Credit-denominated top-ups. Priced to land 60-70% net margin per bundle.
+ *  Sized to be crisp human units (1.5K, 6K, 15K) rather than arbitrary
+ *  multiples, so users can budget against the plans (1.5K matches Free's
+ *  monthly, 15K matches Pro's monthly). */
+export interface CreditTopupDefinition {
+    id: 'credits_1500' | 'credits_6000' | 'credits_12500';
+    credits: number;
+    price: number;
+    label: string;
+    subtitle: string;
+    /** Pre-computed rate for UI comparison — don't duplicate the maths. */
+    effectiveRate: string;
+    popular?: boolean;
+}
+export declare const CREDIT_TOPUPS: CreditTopupDefinition[];
+/** Net margin targets modelled into plan sizing. Used by the admin hub's
+ *  financials page + anywhere we want to sanity-check plan economics at a
+ *  glance. Not consumed at billing time. */
+export declare const MARGIN_TARGETS: {
+    /** 30% at ~60% utilisation — the live design point as of 2026-07-19.
+     *  MODEL_COST_MULTIPLIER is the source of truth; this mirrors its target
+     *  so the hub's financials page reports what we actually charge. It sat
+     *  at 0.55 while billing was calibrated to 0.40, which overstated margin
+     *  in our own planning for months. */
+    readonly typicalNetMargin: 0.3;
+    /** ⚠ UNVERIFIED — not re-derived since the 2026-04-29 rebalance. The old
+     *  pair (0.55 typical / 0.30 max) implied a ~25pt drop between 60% and
+     *  100% utilisation; carrying that spread onto a 30% typical lands here.
+     *  Treat as a flag to model properly, NOT as a measured figure — heavy
+     *  users are where a thin target goes negative first, and this is the
+     *  number that must be derived before any further cut. */
+    readonly maxUtilisationNet: 0.05;
+    /** USD / month worst case on Free — funded out of paid margin, so it
+     *  gets harder to carry as the target comes down. */
+    readonly freeSubsidyPerUser: 0.72;
+};
+//# sourceMappingURL=credits.d.ts.map

package/dist/billing/credits.d.ts.map

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