@kal-elsam/kairo-runtime 0.16.0 → 0.17.0

package/src/global/runtime/usage-store.js

@@ -0,0 +1,69 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { EXECUTION_ADAPTER_IDS } from "./execution-adapters/index.js";
+import { writeAtomicJson } from "./write-atomic-json.js";
+
+const writeLocks = new Map();
+
+export function getUsageDir(homeDir) {
+  return harnessHomePaths(homeDir).usageDir;
+}
+
+/**
+ * The one real boundary a provider id gets validated at before it's ever
+ * used to build a path — the same defense-in-depth role
+ * assertWorktreeId/assertTaskId already play elsewhere. Provider ids are a
+ * real, closed list (the same one execution-adapters/index.js resolves
+ * against), never a free-form string, so an unknown one is always a bug
+ * to surface loudly rather than a path to silently sanitize.
+ */
+function usagePath(homeDir, provider) {
+  if (!EXECUTION_ADAPTER_IDS.includes(provider)) {
+    throw new Error(`Unknown provider "${provider}" for usage tracking. Use ${EXECUTION_ADAPTER_IDS.join(", ")}.`);
+  }
+  return join(getUsageDir(homeDir), `${provider}.json`);
+}
+
+export async function readProviderUsage(homeDir, provider) {
+  const statePath = usagePath(homeDir, provider);
+  if (!existsSync(statePath)) return null;
+
+  try {
+    return JSON.parse(await readFile(statePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Invalid provider usage state at ${statePath}: ${error.message}`);
+  }
+}
+
+/** Read-modify-write is serialized per provider — same real race protection run-store.js's writeRunState already relies on. */
+export async function writeProviderUsage(homeDir, provider, record) {
+  const key = provider;
+  const previous = writeLocks.get(key) ?? Promise.resolve();
+  const next = previous.then(async () => {
+    const usageDir = getUsageDir(homeDir);
+    await mkdir(usageDir, { recursive: true });
+    await writeAtomicJson(usagePath(homeDir, provider), record);
+    return record;
+  });
+  writeLocks.set(key, next.catch(() => {}));
+  return next;
+}
+
+export async function listProviderUsage(homeDir) {
+  const usageDir = getUsageDir(homeDir);
+  if (!existsSync(usageDir)) return [];
+
+  const entries = await readdir(usageDir, { withFileTypes: true });
+  const records = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    const provider = entry.name.slice(0, -".json".length);
+    if (!EXECUTION_ADAPTER_IDS.includes(provider)) continue;
+    const record = await readProviderUsage(homeDir, provider);
+    if (record) records.push(record);
+  }
+  records.sort((left, right) => left.provider.localeCompare(right.provider));
+  return records;
+}

package/src/global/runtime/usage-types.js

@@ -0,0 +1,62 @@
+export const USAGE_SCHEMA = "kairo.provider-usage/v1";
+
+// HEALTHY: well under budget. MODERATE/CONSERVE: real, rising signal — no
+// enforcement yet. CRITICAL: the last tier before the gate. EXHAUSTED: the
+// real, enforced stop — assertProviderNotExhausted (usage-manager.js)
+// refuses to start a new run for a provider in this tier.
+export const USAGE_TIERS = Object.freeze({
+  HEALTHY: "healthy",
+  MODERATE: "moderate",
+  CONSERVE: "conserve",
+  CRITICAL: "critical",
+  EXHAUSTED: "exhausted"
+});
+
+// Fractions of the configured budget. Ratios strictly below MODERATE stay
+// HEALTHY; at/above 1.0 (100% of budget) is always EXHAUSTED, regardless
+// of where CRITICAL is set.
+export const USAGE_TIER_THRESHOLDS = Object.freeze({
+  MODERATE: 0.5,
+  CONSERVE: 0.75,
+  CRITICAL: 0.9
+});
+
+/**
+ * Classifies real, cumulative consumption against a real, configured
+ * budget — never against a single run's own usage. No budget configured
+ * (null) means no gate exists for this provider yet: always HEALTHY,
+ * exactly mirroring how a null profile.tokenBudget already means "no
+ * per-request gate" elsewhere in this codebase (see router.js).
+ */
+export function classifyUsageTier(consumedTokens, budgetTokens) {
+  if (budgetTokens == null || !Number.isFinite(budgetTokens) || budgetTokens <= 0) {
+    return USAGE_TIERS.HEALTHY;
+  }
+  const consumed = Number.isFinite(consumedTokens) ? Math.max(0, consumedTokens) : 0;
+  const ratio = consumed / budgetTokens;
+
+  if (ratio >= 1) return USAGE_TIERS.EXHAUSTED;
+  if (ratio >= USAGE_TIER_THRESHOLDS.CRITICAL) return USAGE_TIERS.CRITICAL;
+  if (ratio >= USAGE_TIER_THRESHOLDS.CONSERVE) return USAGE_TIERS.CONSERVE;
+  if (ratio >= USAGE_TIER_THRESHOLDS.MODERATE) return USAGE_TIERS.MODERATE;
+  return USAGE_TIERS.HEALTHY;
+}
+
+export function isProviderExhausted(tier) {
+  return tier === USAGE_TIERS.EXHAUSTED;
+}
+
+export function createProviderUsageRecord(provider) {
+  const now = new Date().toISOString();
+  return {
+    schema: USAGE_SCHEMA,
+    provider,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalTokens: 0,
+    totalCost: 0,
+    runCount: 0,
+    createdAt: now,
+    updatedAt: now
+  };
+}