Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

16.4 KB
Raw Blame
/**
 * UsageService - reports usage created by Akeru's connected provider runtimes.
 *
 * The usage ledger is environment-local. Provider CLI transcript directories
 * are intentionally not consulted: a machine-wide CLI login is not an Akeru
 * Settings -> Providers connection and must never appear on this page.
 *
 * @module UsageService
 */
import * as NodeOS from "node:os";

import {
  USAGE_CONTRACT_VERSION,
  type AkeruUsageEntry,
  type SubscriptionProviderId,
  type UsageProviderKind,
  type UsageSource,
  type UsageSummary,
  type UsageProviderPlanLimits,
  type UsageSummaryInput,
  type UsageTokenTotals,
  UsageReadError,
} from "@akeru/contracts";
import * as Clock from "effect/Clock";
import * as Context from "effect/Context";
import * as DateTime from "effect/DateTime";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Schema from "effect/Schema";
import * as Scope from "effect/Scope";
import { HttpClient, HttpClientResponse } from "effect/unstable/http";

import { ServerConfig } from "../config.ts";
import { SubscriptionAuthService } from "../subscription-auth/service.ts";
import { ProviderUsageHistory } from "./ProviderUsageHistory.ts";
import { UsageAggregator } from "./usageAggregation.ts";
import { parseRateTable, priceUsage, type PricedUsage, type RateTable } from "./usagePricing.ts";
import { planLimitsReader } from "./usagePlanLimits.ts";
import type { UsageRecord } from "./usageTranscripts.ts";

const LITELLM_RATES_URL =
  "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";

const RATES_TTL_MS = 24 * 60 * 60 * 1000;

const RATES_FAILURE_BACKOFF_MS = 60_000;

const RATES_MAX_FAILURE_BACKOFF_MS = 60 * 60 * 1000;

const MAX_HOURLY_WINDOW_MS = 24 * 60 * 60 * 1000;

const DAILY_QUERY_SLACK_HOURS = 36;

const decodeRateDocument = Schema.decodeUnknownEffect(Schema.Json);

const RatesCacheFile = Schema.Struct({
  fetchedAtMs: Schema.Number,
  document: Schema.Json,
});

const decodeRatesCache = Schema.decodeUnknownEffect(Schema.fromJsonString(RatesCacheFile));

const encodeRatesCache = Schema.encodeEffect(Schema.fromJsonString(RatesCacheFile));

const DRIVER_CONNECTIONS = {
  claudeAgent: { provider: "claude", connection: "anthropic" },
  codex: { provider: "codex", connection: "openai-codex" },
  grok: { provider: "grok", connection: "xai" },
  kimi: { provider: "kimi", connection: "kimi-for-coding" },
  opencode: { provider: "opencode", connection: "opencode-go" },
  opencodeGo: { provider: "opencode", connection: "opencode-go" },
} as const satisfies Record<
  string,
  { readonly provider: UsageProviderKind; readonly connection: SubscriptionProviderId }
>;

export interface PriceStepUsageInput {
  readonly model: string;
  readonly totals: UsageTokenTotals;
  readonly reportedCostUsd: number | null;
}

export class UsageService extends Context.Service<
  UsageService,
  {
    readonly readSummary: (input: UsageSummaryInput) => Effect.Effect<UsageSummary, UsageReadError>;
    readonly priceStepUsage: (input: PriceStepUsageInput) => Effect.Effect<PricedUsage>;
    readonly readPlanLimits: (
      provider?: SubscriptionProviderId,
    ) => Effect.Effect<readonly UsageProviderPlanLimits[]>;
  }
>()("akeru-bot/usage/UsageService") {}

/** Maps one ledger row only when its Akeru provider connection is active. */
export function usageRecordFromEntry(
  entry: AkeruUsageEntry,
  connectedProviders: ReadonlySet<SubscriptionProviderId>,
): UsageRecord | null {
  if (entry.provider === null || entry.model === null) return null;

  const mapping = Object.entries(DRIVER_CONNECTIONS).find(
    ([driver]) => driver === entry.provider,
  )?.[1];

  if (mapping === undefined || !connectedProviders.has(mapping.connection)) return null;

  const timestamp = DateTime.make(entry.createdAt);

  if (Option.isNone(timestamp)) return null;

  const outputTokens = entry.outputTokens ?? 0;

  return {
    provider: mapping.provider,
    timestampMs: DateTime.toEpochMillis(timestamp.value),
    model: entry.model,
    sessionId: entry.threadId ?? entry.botId,
    totals: {
      uncachedInputTokens: Math.max(
        0,
        (entry.inputTokens ?? 0) -
          (entry.cachedInputTokens ?? 0) -
          (entry.cacheCreationTokens ?? 0),
      ),
      cachedInputTokens: entry.cachedInputTokens ?? 0,
      cacheCreationTokens: entry.cacheCreationTokens ?? 0,
      outputTokens,
      reasoningTokens: Math.min(entry.reasoningTokens ?? 0, outputTokens),
    },
    reportedCostUsd: null,
    dedupeKey: entry.reservationId,
  };
}

/** Filesystem identity of an environment's usage ledger, as `device:inode`. */
export const readUsageStoreVolumeId = Effect.fn("UsageService.readUsageStoreVolumeId")(function* (
  fileSystem: FileSystem.FileSystem,
  databasePath: string,
) {
  const stats = yield* fileSystem
    .stat(databasePath)
    .pipe(Effect.catchCause(() => Effect.succeed(null)));

  if (stats === null || Option.isNone(stats.ino)) return "";

  return `${stats.dev}:${stats.ino.value}`;
});

/** Empty summary, for suites that only need the RPC surface to resolve. */
export const layerTestWithRates = (rateTable: RateTable) =>
  Layer.succeed(
    UsageService,
    UsageService.of({
      readSummary: (input) =>
        Effect.succeed({
          contractVersion: USAGE_CONTRACT_VERSION,
          readAt: "1970-01-01T00:00:00.000Z",
          timeZone: input.timeZone,
          sinceDay: input.sinceDay,
          untilDay: input.untilDay,
          buckets: [],
          sources: [],
          pricing: {
            status: "unavailable",
            source: LITELLM_RATES_URL,
            fetchedAt: null,
            knownModels: rateTable.size,
          },
          scanDurationMs: 0,
          planLimits: [],
          connectedProviders: [],
        }),
      readPlanLimits: () => Effect.succeed([]),
      priceStepUsage: (input) =>
        Effect.succeed(priceUsage(rateTable, input.model, input.totals, input.reportedCostUsd)),
    }),
  );

export const layerTest = layerTestWithRates(new Map());

// The service scope owns shared work; disconnecting one caller only cancels its wait.
const singleFlight = <A, E>(scope: Scope.Scope) => {
  const pending = new Map<string, Deferred.Deferred<A, E>>();

  const acquire = Effect.fnUntraced(function* (key: string, work: Effect.Effect<A, E>) {
    const existing = pending.get(key);

    if (existing) return existing;
    const shared = Deferred.makeUnsafe<A, E>();
    pending.set(key, shared);
    yield* Deferred.into(
      work.pipe(
        Effect.ensuring(
          Effect.sync(() => {
            pending.delete(key);
          }),
        ),
      ),
      shared,
    ).pipe(Effect.forkIn(scope));

    return shared;
  }, Effect.uninterruptible);

  return (key: string, work: Effect.Effect<A, E>) =>
    acquire(key, work).pipe(Effect.flatMap(Deferred.await));
};

export const make = Effect.gen(function* () {
  const fileSystem = yield* FileSystem.FileSystem;
  const path = yield* Path.Path;
  const config = yield* ServerConfig;
  const httpClient = yield* HttpClient.HttpClient;
  const providerUsageHistory = yield* ProviderUsageHistory;
  const subscriptionAuth = yield* SubscriptionAuthService.forSecretsDir(config.secretsDir);

  const readPlanLimits = yield* planLimitsReader((provider) =>
    subscriptionAuth.getPlanAccess(provider),
  );

  const scope = yield* Scope.Scope;
  const shareSummary = singleFlight<UsageSummary, UsageReadError>(scope);
  const shareRates = singleFlight<void, never>(scope);

  const ratesCachePath = path.join(config.stateDir, "usage-model-rates.json");
  const usageDatabasePath = path.join(config.stateDir, "state.sqlite");
  let rates: RateTable = new Map();
  let ratesFetchedAtMs: number | null = null;
  let ratesStatus: UsageSummary["pricing"]["status"] = "unavailable";
  let ratesNextAttemptAtMs = 0;
  let ratesFailures = 0;
  let ratesRefreshRunning = false;

  const loadRates = yield* Effect.cached(
    Effect.gen(function* () {
      const fromDisk = yield* fileSystem.readFileString(ratesCachePath).pipe(
        Effect.flatMap(decodeRatesCache),
        Effect.catchCause(() => Effect.succeed(null)),
      );

      if (fromDisk === null) return;
      const parsed = parseRateTable(fromDisk.document);

      if (parsed.size > 0) {
        rates = parsed;
        ratesFetchedAtMs = fromDisk.fetchedAtMs;
        ratesStatus = "cached";
      }
    }),
  );

  const refreshRates = yield* Effect.cachedWithTTL(
    Effect.gen(function* () {
      const now = yield* Clock.currentTimeMillis;

      if (now < ratesNextAttemptAtMs) return;

      if (ratesFetchedAtMs !== null && now - ratesFetchedAtMs < RATES_TTL_MS) return;

      const fetched = yield* httpClient.get(LITELLM_RATES_URL).pipe(
        Effect.flatMap(HttpClientResponse.filterStatusOk),
        Effect.flatMap((response) => response.json),
        Effect.flatMap(decodeRateDocument),
        Effect.timeout(10_000),
        Effect.catchCause(() => Effect.succeed(null)),
      );

      const parsed = parseRateTable(fetched);
      const completedAt = yield* Clock.currentTimeMillis;

      if (parsed.size === 0) {
        ratesStatus = rates.size > 0 ? "cached" : "unavailable";
        ratesNextAttemptAtMs =
          completedAt +
          Math.min(
            RATES_MAX_FAILURE_BACKOFF_MS,
            RATES_FAILURE_BACKOFF_MS * 2 ** Math.min(ratesFailures, 6),
          );
        ratesFailures += 1;

        return;
      }

      rates = parsed;
      ratesFetchedAtMs = completedAt;
      ratesStatus = "fresh";
      ratesFailures = 0;
      ratesNextAttemptAtMs = 0;
      yield* encodeRatesCache({ fetchedAtMs: completedAt, document: fetched }).pipe(
        Effect.flatMap((serialized) => fileSystem.writeFileString(ratesCachePath, serialized)),
        Effect.catchCause(() => Effect.void),
      );
    }),
    0,
  );

  // Cold readers share the fetch; stale readers keep working while one scoped refresh runs.
  const ensureRates = Effect.fn("UsageService.ensureRates")(
    function* () {
      yield* loadRates;
      const now = yield* Clock.currentTimeMillis;

      if (ratesFetchedAtMs !== null && now - ratesFetchedAtMs < RATES_TTL_MS) return;
      ratesStatus = rates.size > 0 ? "cached" : "unavailable";

      if (now < ratesNextAttemptAtMs) return;

      if (rates.size === 0) {
        yield* refreshRates;
      } else if (!ratesRefreshRunning) {
        ratesRefreshRunning = true;
        yield* refreshRates.pipe(
          Effect.ensuring(
            Effect.sync(() => {
              ratesRefreshRunning = false;
            }),
          ),
          Effect.forkIn(scope),
        );
      }
    },
    (effect) => shareRates("rates", effect),
  );

  const priceStepUsage = Effect.fn("UsageService.priceStepUsage")(function* (
    input: PriceStepUsageInput,
  ) {
    yield* ensureRates();

    return priceUsage(rates, input.model, input.totals, input.reportedCostUsd);
  });

  const readSummary = Effect.fn("UsageService.readSummary")(function* (input: UsageSummaryInput) {
    if (input.sinceDay > input.untilDay) {
      return yield* new UsageReadError({
        reason: "invalidWindow",
        detail: `sinceDay '${input.sinceDay}' is after untilDay '${input.untilDay}'`,
      });
    }

    let hourlyWindow: { readonly sinceTimeMs: number; readonly untilTimeMs: number } | null = null;

    if (input.resolution === "hour") {
      const sinceTime =
        input.sinceTime === undefined ? Option.none() : DateTime.make(input.sinceTime);

      const untilTime =
        input.untilTime === undefined ? Option.none() : DateTime.make(input.untilTime);

      if (Option.isNone(sinceTime) || Option.isNone(untilTime)) {
        return yield* new UsageReadError({
          reason: "invalidWindow",
          detail: "Hourly usage requires valid sinceTime and untilTime instants",
        });
      }

      const sinceTimeMs = DateTime.toEpochMillis(sinceTime.value);
      const untilTimeMs = DateTime.toEpochMillis(untilTime.value);
      const durationMs = untilTimeMs - sinceTimeMs;

      if (durationMs <= 0 || durationMs > MAX_HOURLY_WINDOW_MS) {
        return yield* new UsageReadError({
          reason: "invalidWindow",
          detail: "Hourly usage window must be greater than zero and at most 24 hours",
        });
      }

      hourlyWindow = { sinceTimeMs, untilTimeMs };
    }

    const sinceBoundary = DateTime.make(`${input.sinceDay}T00:00:00Z`);
    const untilBoundary = DateTime.make(`${input.untilDay}T00:00:00Z`);

    if (Option.isNone(sinceBoundary) || Option.isNone(untilBoundary)) {
      return yield* new UsageReadError({
        reason: "invalidWindow",
        detail: "Usage day window contains an invalid date",
      });
    }

    const startedAtMs = yield* Clock.currentTimeMillis;
    yield* ensureRates();
    yield* subscriptionAuth.reload();

    const connectedProviders = subscriptionAuth
      .statuses()
      .filter((status) => status.connected)
      .map((status) => status.provider);

    const connectedSet = new Set<SubscriptionProviderId>(connectedProviders);

    const querySince = hourlyWindow
      ? DateTime.makeUnsafe(hourlyWindow.sinceTimeMs)
      : DateTime.subtract(sinceBoundary.value, { hours: DAILY_QUERY_SLACK_HOURS });

    const queryUntil = hourlyWindow
      ? DateTime.makeUnsafe(hourlyWindow.untilTimeMs)
      : DateTime.add(untilBoundary.value, { hours: 24 + DAILY_QUERY_SLACK_HOURS });

    const entries = yield* providerUsageHistory
      .readReported({
        sinceAt: DateTime.formatIso(querySince),
        untilAt: DateTime.formatIso(queryUntil),
      })
      .pipe(
        Effect.mapError(
          (cause) =>
            new UsageReadError({
              reason: "scanFailed",
              detail: "Akeru provider usage could not be read.",
              cause,
            }),
        ),
      );

    const aggregator = new UsageAggregator({
      timeZone: input.timeZone,
      sinceDay: input.sinceDay,
      untilDay: input.untilDay,
      resolution: input.resolution ?? "day",
      ...hourlyWindow,
      rates,
    });

    const sessionsByProvider = new Map<UsageProviderKind, Set<string>>();

    for (const entry of entries) {
      const record = usageRecordFromEntry(entry, connectedSet);

      if (record === null || !aggregator.add(record)) continue;
      const sessions = sessionsByProvider.get(record.provider) ?? new Set<string>();

      if (record.sessionId.length > 0) sessions.add(record.sessionId);
      sessionsByProvider.set(record.provider, sessions);
    }

    const hostId = NodeOS.hostname();
    const volumeId = yield* readUsageStoreVolumeId(fileSystem, usageDatabasePath);

    const sources: UsageSource[] = [
      ...new Set(
        Object.values(DRIVER_CONNECTIONS)
          .filter((mapping) => connectedSet.has(mapping.connection))
          .map((mapping) => mapping.provider),
      ),
    ].map((provider) => ({
      fingerprint: { hostId, provider, resolvedHomePath: usageDatabasePath, volumeId },
      status: "ok",
      scannedFiles: 0,
      skippedFiles: 0,
      malformedRecords: 0,
      distinctSessions: sessionsByProvider.get(provider)?.size ?? 0,
      message: null,
    }));

    const aggregated = aggregator.finish();
    const readAt = yield* DateTime.now;
    const finishedAtMs = yield* Clock.currentTimeMillis;
    const planLimits = yield* readPlanLimits().pipe(Effect.catchCause(() => Effect.succeed([])));

    return {
      contractVersion: USAGE_CONTRACT_VERSION,
      readAt: DateTime.formatIso(readAt),
      timeZone: input.timeZone,
      sinceDay: input.sinceDay,
      untilDay: input.untilDay,
      buckets: aggregated.buckets,
      sources,
      planLimits,
      connectedProviders,
      pricing: {
        status: ratesStatus,
        source: LITELLM_RATES_URL,
        fetchedAt:
          ratesFetchedAtMs === null
            ? null
            : DateTime.formatIso(DateTime.makeUnsafe(ratesFetchedAtMs)),
        knownModels: rates.size,
      },
      scanDurationMs: Math.max(0, finishedAtMs - startedAtMs),
    } satisfies UsageSummary;
  });

  return {
    readSummary: (input: UsageSummaryInput) =>
      shareSummary(
        JSON.stringify([
          input.sinceDay,
          input.untilDay,
          input.timeZone,
          input.resolution ?? "day",
          input.sinceTime,
          input.untilTime,
        ]),
        readSummary(input),
      ),
    priceStepUsage,
    readPlanLimits,
  } as const;
});

export const layer = Layer.effect(UsageService, make);