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.
feat(server): enforce per-bot token usage caps (#35)
Leof7f576ff1def
diff --git a/apps/server/integration/OrchestrationEngineHarness.integration.ts b/apps/server/integration/OrchestrationEngineHarness.integration.tsindex 726a02cc9..6bff12bef 100644--- a/apps/server/integration/OrchestrationEngineHarness.integration.ts+++ b/apps/server/integration/OrchestrationEngineHarness.integration.ts@@ -85,6 +85,7 @@ import { VcsStatusBroadcaster } from "../src/vcs/VcsStatusBroadcaster.ts";import { GitWorkflowService } from "../src/git/GitWorkflowService.ts";import * as VcsProcess from "../src/vcs/VcsProcess.ts";import * as AgentAwarenessRelay from "../src/relay/AgentAwarenessRelay.ts";+import { BotUsageLedgerLive } from "../src/usage/BotUsageLedger.ts";const decodeCodexSettings = Schema.decodeEffect(CodexSettings);@@ -313,6 +314,7 @@ export const makeOrchestrationIntegrationHarness = (ProjectionBotRepositoryLive,ProjectionCheckpointRepositoryLive,ProjectionPendingApprovalRepositoryLive,+ BotUsageLedgerLive,checkpointStoreLayer,agentControllerLayer,RuntimeReceiptBusTest,diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.tsindex 97acdf5d5..be63254b6 100644--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts@@ -69,6 +69,7 @@ import * as Clock from "effect/Clock";import { ServerSettingsService } from "../../serverSettings.ts";import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";import * as GitWorkflowService from "../../git/GitWorkflowService.ts";+import { BotUsageLedger, BotUsageLedgerLive } from "../../usage/BotUsageLedger.ts";const asProjectId = (value: string): ProjectId => ProjectId.make(value);const asApprovalRequestId = (value: string): ApprovalRequestId => ApprovalRequestId.make(value);@@ -110,7 +111,7 @@ describe("ProviderCommandReactor", () => {);});let runtime: ManagedRuntime.ManagedRuntime<- OrchestrationEngineService | ProviderCommandReactor | ProjectionSnapshotQuery,+ OrchestrationEngineService | ProviderCommandReactor | ProjectionSnapshotQuery | BotUsageLedger,unknown> | null = null;let scope: Scope.Closeable | null = null;@@ -173,6 +174,8 @@ describe("ProviderCommandReactor", () => {session: ProviderSession,) => Effect.Effect<ProviderSession, ProviderAdapterRequestError>;readonly botEngine?: { readonly provider: string; readonly model: string } | null;+ readonly botUsageCap?: { readonly unit: "tokens"; readonly limit: number } | null;+ readonly bindTurnFailure?: boolean;readonly unavailableEngine?: boolean;}) {const now = "2026-01-01T00:00:00.000Z";@@ -442,10 +445,20 @@ describe("ProviderCommandReactor", () => {} satisfies OrchestrationEngineService["Service"];}),).pipe(Layer.provide(orchestrationLayer));+ const botUsageLedgerLayer = Layer.effect(+ BotUsageLedger,+ BotUsageLedger.pipe(+ Effect.map((ledger) => ({+ ...ledger,+ bindTurn: input?.bindTurnFailure ? () => Effect.die("bind failed") : ledger.bindTurn,+ })),+ ),+ ).pipe(Layer.provide(BotUsageLedgerLive.pipe(Layer.provide(SqlitePersistenceMemory))));const layer = ProviderCommandReactorLive.pipe(Layer.provideMerge(reactorOrchestrationLayer),Layer.provideMerge(projectionSnapshotLayer),Layer.provideMerge(ProjectionBotRepositoryLive.pipe(Layer.provide(SqlitePersistenceMemory))),+ Layer.provideMerge(botUsageLedgerLayer),Layer.provideMerge(Layer.succeed(AgentController, service)),Layer.provideMerge(makeProviderRegistryLayer(providerSnapshots as never)),Layer.provideMerge(@@ -504,7 +517,7 @@ describe("ProviderCommandReactor", () => {engine: input.botEngine,sandbox: "local",runtimeMode: "approval-required",- usageCap: null,+ usageCap: input.botUsageCap ?? null,groupId: null,createdAt: now,}),@@ -586,6 +599,10 @@ describe("ProviderCommandReactor", () => {stateDir,drain,runEffect,+ summarizeBotUsage: () =>+ runtime!.runPromise(+ BotUsageLedger.pipe(Effect.flatMap((ledger) => ledger.summarize(BotId.make("bot-1")))),+ ),get titleRegenerationCompletionDispatchAttempts() {return titleRegenerationCompletionDispatchAttempts;},@@ -687,6 +704,162 @@ describe("ProviderCommandReactor", () => {});});+ effectIt.effect("reserves a configured bot's usage cap and binds the provider turn", () =>+ Effect.gen(function* () {+ const harness = yield* Effect.promise(() =>+ createHarness({+ botEngine: { provider: "codex", model: "gpt-5-codex" },+ botUsageCap: { unit: "tokens", limit: 1_000 },+ }),+ );++ yield* harness.engine.dispatch({+ type: "thread.turn.start",+ commandId: CommandId.make("cmd-turn-start-metered-bot"),+ threadId: ThreadId.make("thread-1"),+ message: {+ messageId: asMessageId("user-message-metered-bot"),+ role: "user",+ text: "meter this turn",+ attachments: [],+ },+ interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,+ runtimeMode: "approval-required",+ createdAt: "2026-01-01T00:00:00.000Z",+ });++ yield* Effect.promise(() => waitFor(() => harness.sendTurn.mock.calls.length === 1));+ yield* Effect.promise(() =>+ waitFor(async () => (await harness.summarizeBotUsage()).entries[0]?.turnId === "turn-1"),+ );+ const usage = yield* Effect.promise(() => harness.summarizeBotUsage());+ expect(usage.reservedTokens).toBe(1_000);+ expect(usage.entries).toContainEqual(+ expect.objectContaining({+ botId: "bot-1",+ threadId: "thread-1",+ turnId: "turn-1",+ state: "reserved",+ reservedTokens: 1_000,+ }),+ );+ }),+ );++ effectIt.effect("rejects a new turn after a configured bot reserves its full usage cap", () =>+ Effect.gen(function* () {+ const harness = yield* Effect.promise(() =>+ createHarness({+ botEngine: { provider: "codex", model: "gpt-5-codex" },+ botUsageCap: { unit: "tokens", limit: 1_000 },+ }),+ );+ const dispatchTurn = (suffix: string) =>+ harness.engine.dispatch({+ type: "thread.turn.start",+ commandId: CommandId.make(`cmd-turn-start-cap-${suffix}`),+ threadId: ThreadId.make("thread-1"),+ message: {+ messageId: asMessageId(`user-message-cap-${suffix}`),+ role: "user" as const,+ text: suffix,+ attachments: [],+ },+ interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,+ runtimeMode: "approval-required" as const,+ createdAt: `2026-01-01T00:00:0${suffix === "first" ? "0" : "1"}.000Z`,+ });++ yield* dispatchTurn("first");+ yield* Effect.promise(() => waitFor(() => harness.sendTurn.mock.calls.length === 1));+ yield* dispatchTurn("second");+ yield* Effect.promise(() => harness.drain());++ expect(harness.sendTurn).toHaveBeenCalledTimes(1);+ const readModel = yield* Effect.promise(() => harness.readModel());+ const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));+ expect(thread?.activities).toContainEqual(+ expect.objectContaining({+ kind: "provider.turn.start.failed",+ payload: expect.objectContaining({+ detail: "Bot bot-1 reached its 1000-token usage cap.",+ requestId: "user-message-cap-second",+ }),+ }),+ );+ }),+ );++ effectIt.effect("releases a configured bot's usage reservation when dispatch fails", () =>+ Effect.gen(function* () {+ const harness = yield* Effect.promise(() =>+ createHarness({+ botEngine: { provider: "codex", model: "gpt-5-codex" },+ botUsageCap: { unit: "tokens", limit: 1_000 },+ }),+ );+ harness.sendTurn.mockImplementation(() => Effect.die("dispatch failed"));++ yield* harness.engine.dispatch({+ type: "thread.turn.start",+ commandId: CommandId.make("cmd-turn-start-dispatch-failure"),+ threadId: ThreadId.make("thread-1"),+ message: {+ messageId: asMessageId("user-message-dispatch-failure"),+ role: "user",+ text: "fail dispatch",+ attachments: [],+ },+ interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,+ runtimeMode: "approval-required",+ createdAt: "2026-01-01T00:00:00.000Z",+ });+ yield* Effect.promise(() => harness.drain());++ const usage = yield* Effect.promise(() => harness.summarizeBotUsage());+ expect(usage.consumedTokens).toBe(0);+ expect(usage.reservedTokens).toBe(0);+ expect(usage.entries[0]?.state).toBe("released");+ }),+ );++ effectIt.effect("charges a configured bot's usage reservation when turn binding fails", () =>+ Effect.gen(function* () {+ const harness = yield* Effect.promise(() =>+ createHarness({+ botEngine: { provider: "codex", model: "gpt-5-codex" },+ botUsageCap: { unit: "tokens", limit: 1_000 },+ bindTurnFailure: true,+ }),+ );++ yield* harness.engine.dispatch({+ type: "thread.turn.start",+ commandId: CommandId.make("cmd-turn-start-bind-failure"),+ threadId: ThreadId.make("thread-1"),+ message: {+ messageId: asMessageId("user-message-bind-failure"),+ role: "user",+ text: "fail binding",+ attachments: [],+ },+ interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,+ runtimeMode: "approval-required",+ createdAt: "2026-01-01T00:00:00.000Z",+ });+ yield* Effect.promise(() => harness.drain());++ const usage = yield* Effect.promise(() => harness.summarizeBotUsage());+ expect(harness.sendTurn).toHaveBeenCalledTimes(1);+ expect(usage.consumedTokens).toBe(1_000);+ expect(usage.reservedTokens).toBe(0);+ expect(usage.entries[0]).toMatchObject({+ state: "unavailable",+ unavailableReason: "Usage reservation could not bind to the provider turn.",+ });+ }),+ );+it("projects a typed failure when the configured bot engine is unavailable", async () => {const harness = await createHarness({botEngine: { provider: "missing", model: "missing-model" },diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.tsindex f362272f3..4b5f047aa 100644--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts@@ -1,4 +1,5 @@import {+ AkeruUsageReservationId,type ChatAttachment,CommandId,EventId,@@ -40,6 +41,11 @@ import {botRuntimeResourceScope,botWorkspaceResourceKey,} from "../../provider/botWorkspacePool.ts";+import {+ AKERU_TURN_USAGE_RESERVATION_TOKENS,+ BotUsageCapExceeded,+ BotUsageLedger,+} from "../../usage/BotUsageLedger.ts";import { AgentController } from "../../provider/Services/AgentController.ts";import { ProviderRegistry } from "../../provider/Services/ProviderRegistry.ts";import { ProjectionBotRepository } from "../../persistence/Services/ProjectionBots.ts";@@ -60,6 +66,7 @@ import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";import { GitWorkflowService } from "../../git/GitWorkflowService.ts";const isProviderAdapterRequestError = Schema.is(ProviderAdapterRequestError);const isAgentControllerUnsupportedEngineError = Schema.is(AgentControllerUnsupportedEngineError);+const isBotUsageCapExceeded = Schema.is(BotUsageCapExceeded);const isProviderDriverKind = Schema.is(ProviderDriverKind);export function resolveControllerBotId(@@ -330,6 +337,7 @@ const make = Effect.gen(function* () {const vcsStatusBroadcaster = yield* VcsStatusBroadcaster;const textGeneration = yield* TextGeneration;const serverSettingsService = yield* ServerSettingsService;+ const botUsageLedger = yield* BotUsageLedger;const serverCommandId = (tag: string) =>crypto.randomUUIDv4.pipe(Effect.map((uuid) => CommandId.make(`server:${tag}:${uuid}`)));const serverEventId = () => crypto.randomUUIDv4.pipe(Effect.map(EventId.make));@@ -391,6 +399,8 @@ const make = Effect.gen(function* () {const formatFailureDetail = (cause: Cause.Cause<unknown>): string => {const failReason = cause.reasons.find(Cause.isFailReason);+ const capError = isBotUsageCapExceeded(failReason?.error) ? failReason.error : undefined;+ if (capError) return capError.message;const providerError = isProviderAdapterRequestError(failReason?.error)? failReason.error: undefined;@@ -1287,6 +1297,47 @@ const make = Effect.gen(function* () {),);+ const respondingBotId = resolveControllerBotId(thread);+ const respondingBot =+ respondingBotId === null+ ? undefined+ : yield* projectionBotRepository+ .getById({ botId: respondingBotId })+ .pipe(Effect.map(Option.getOrUndefined));+ const reservationId = AkeruUsageReservationId.make(`turn:${event.eventId}`);+ const reserved =+ respondingBotId === null+ ? true+ : yield* botUsageLedger+ .reserve({+ reservationId,+ sourceKey: `turn-start:${event.eventId}`,+ botId: respondingBotId,+ threadId: thread.id,+ turnId: null,+ category: "turn",+ maximumTokens: AKERU_TURN_USAGE_RESERVATION_TOKENS,+ capLimit: respondingBot?.usageCap?.limit ?? Number.MAX_SAFE_INTEGER,+ provider:+ [+ thread.session?.providerName,+ event.payload.modelSelection?.instanceId,+ respondingBot?.engine?.provider,+ thread.modelSelection.instanceId,+ ].find(isProviderDriverKind) ?? null,+ model:+ event.payload.modelSelection?.model ??+ respondingBot?.engine?.model ??+ thread.modelSelection.model ??+ null,+ createdAt: event.payload.createdAt,+ })+ .pipe(+ Effect.as(true),+ Effect.catchCause((cause) => handleTurnStartFailure(cause).pipe(Effect.as(false))),+ );+ if (!reserved) return;+const sendTurnRequest = yield* buildSendTurnRequestForThread({threadId: event.payload.threadId,messageText: message.text,@@ -1298,16 +1349,58 @@ const make = Effect.gen(function* () {createdAt: event.payload.createdAt,}).pipe(Effect.map(Option.some),- Effect.catchCause((cause) => handleTurnStartFailure(cause).pipe(Effect.as(Option.none()))),+ Effect.catchCause((cause) =>+ (respondingBotId === null+ ? Effect.void+ : botUsageLedger.settle({+ reservationId,+ state: "released",+ settledAt: event.payload.createdAt,+ })+ ).pipe(Effect.andThen(handleTurnStartFailure(cause)), Effect.as(Option.none())),+ ),);if (Option.isNone(sendTurnRequest)) {return;}- yield* agentController- .sendTurn(sendTurnRequest.value)- .pipe(Effect.catchCause(recoverTurnStartFailure), Effect.forkScoped);+ yield* agentController.sendTurn(sendTurnRequest.value).pipe(+ Effect.tap((result) =>+ respondingBotId === null+ ? Effect.void+ : botUsageLedger.bindTurn({ reservationId, turnId: result.turnId }).pipe(+ Effect.catchCause(() =>+ botUsageLedger+ .settle({+ reservationId,+ state: "unavailable",+ reason: "Usage reservation could not bind to the provider turn.",+ settledAt: event.payload.createdAt,+ })+ .pipe(+ Effect.catchCause((settleCause) =>+ Effect.logWarning("failed to charge an unbound bot usage reservation", {+ reservationId,+ cause: Cause.pretty(settleCause),+ }),+ ),+ ),+ ),+ ),+ ),+ Effect.catchCause((cause) =>+ (respondingBotId === null+ ? Effect.void+ : botUsageLedger.settle({+ reservationId,+ state: "released",+ settledAt: event.payload.createdAt,+ })+ ).pipe(Effect.andThen(recoverTurnStartFailure(cause))),+ ),+ Effect.forkScoped,+ );});const processTurnInterruptRequested = Effect.fn("processTurnInterruptRequested")(function* (diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.tsindex 5b84aa107..246277a5a 100644--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts@@ -12,6 +12,7 @@ import {} from "@t3tools/contracts";import {ApprovalRequestId,+ AkeruUsageReservationId,BotId,CommandId,DEFAULT_PROVIDER_INTERACTION_MODE,@@ -58,6 +59,7 @@ import { ServerConfig } from "../../config.ts";import { ServerSettingsService } from "../../serverSettings.ts";import * as NodeServices from "@effect/platform-node/NodeServices";import { BotInboxService } from "../../bot-inbox/service.ts";+import { BotUsageLedger, BotUsageLedgerLive } from "../../usage/BotUsageLedger.ts";function makeTestServerSettingsLayer(overrides: Partial<ServerSettings> = {}) {return ServerSettingsService.layerTest(overrides);@@ -188,7 +190,10 @@ async function waitForThread(describe("ProviderRuntimeIngestion", () => {let runtime: ManagedRuntime.ManagedRuntime<- OrchestrationEngineService | ProviderRuntimeIngestionService | ProjectionSnapshotQuery,+ | OrchestrationEngineService+ | ProviderRuntimeIngestionService+ | ProjectionSnapshotQuery+ | BotUsageLedger,unknown> | null = null;let scope: Scope.Closeable | null = null;@@ -218,6 +223,7 @@ describe("ProviderRuntimeIngestion", () => {serverSettings?: Partial<ServerSettings>;threadTitle?: string;botOwned?: boolean;+ botUsageCap?: { readonly unit: "tokens"; readonly limit: number } | null;}) {const workspaceRoot = makeTempDir("t3-provider-project-");NodeFS.mkdirSync(NodePath.join(workspaceRoot, ".git"));@@ -242,6 +248,7 @@ describe("ProviderRuntimeIngestion", () => {Layer.provideMerge(ThreadBackgroundLiveness.layer),Layer.provideMerge(ThreadPlanProgress.layer),Layer.provideMerge(SqlitePersistenceMemory),+ Layer.provideMerge(BotUsageLedgerLive.pipe(Layer.provide(SqlitePersistenceMemory))),Layer.provideMerge(Layer.succeed(AgentController, provider.service)),Layer.provideMerge(makeTestServerSettingsLayer(options?.serverSettings)),Layer.provideMerge(ServerConfig.layerTest(process.cwd(), workspaceRoot)),@@ -283,7 +290,7 @@ describe("ProviderRuntimeIngestion", () => {},sandbox: null,runtimeMode: "approval-required",- usageCap: null,+ usageCap: options.botUsageCap ?? null,groupId: null,createdAt,});@@ -339,6 +346,32 @@ describe("ProviderRuntimeIngestion", () => {botInbox: new BotInboxService(NodePath.join(workspaceRoot, "userdata", "secrets", "bot-inbox.json"),),+ reserveBotUsage: (turnId: TurnId | null) =>+ runtime!.runPromise(+ BotUsageLedger.pipe(+ Effect.flatMap((ledger) =>+ ledger.reserve({+ reservationId: AkeruUsageReservationId.make(`test:${turnId}`),+ sourceKey: `test:${turnId}`,+ botId: BotId.make("bot-akeru"),+ threadId: ThreadId.make("thread-1"),+ turnId,+ category: "turn",+ maximumTokens: 1_000,+ capLimit: 1_000,+ provider: ProviderDriverKind.make("codex"),+ model: "gpt-5-codex",+ createdAt,+ }),+ ),+ ),+ ),+ summarizeBotUsage: () =>+ runtime!.runPromise(+ BotUsageLedger.pipe(+ Effect.flatMap((ledger) => ledger.summarize(BotId.make("bot-akeru"))),+ ),+ ),};}@@ -428,6 +461,177 @@ describe("ProviderRuntimeIngestion", () => {expect(thread.session?.lastError).toBe("turn failed");});+ it("records provider token usage and releases the remaining turn reservation", async () => {+ const harness = await createHarness({ botOwned: true });+ const turnId = asTurnId("turn-metered");+ await harness.reserveBotUsage(turnId);++ harness.emit({+ type: "thread.token-usage.updated",+ eventId: asEventId("evt-turn-usage"),+ provider: ProviderDriverKind.make("codex"),+ threadId: asThreadId("thread-1"),+ turnId,+ createdAt: "2026-01-01T00:00:01.000Z",+ payload: {+ usage: {+ usedTokens: 150,+ inputTokens: 100,+ outputTokens: 50,+ reasoningOutputTokens: 20,+ },+ },+ });+ harness.emit({+ type: "turn.completed",+ eventId: asEventId("evt-turn-usage-completed"),+ provider: ProviderDriverKind.make("codex"),+ threadId: asThreadId("thread-1"),+ turnId,+ createdAt: "2026-01-01T00:00:02.000Z",+ payload: { state: "completed" },+ });+ await harness.drain();++ const usage = await harness.summarizeBotUsage();+ expect(usage.consumedTokens).toBe(150);+ expect(usage.reservedTokens).toBe(0);+ expect(usage.entries[0]).toMatchObject({+ state: "reported",+ inputTokens: 100,+ outputTokens: 50,+ reasoningTokens: 20,+ settledAt: "2026-01-01T00:00:02.000Z",+ });+ });++ it("charges the reservation when a provider completes without token usage", async () => {+ const harness = await createHarness({ botOwned: true });+ const turnId = asTurnId("turn-unavailable-usage");+ await harness.reserveBotUsage(turnId);++ harness.emit({+ type: "turn.completed",+ eventId: asEventId("evt-turn-unavailable-usage-completed"),+ provider: ProviderDriverKind.make("codex"),+ threadId: asThreadId("thread-1"),+ turnId,+ createdAt: "2026-01-01T00:00:01.000Z",+ payload: { state: "completed" },+ });+ await harness.drain();++ const usage = await harness.summarizeBotUsage();+ expect(usage.consumedTokens).toBe(1_000);+ expect(usage.reservedTokens).toBe(0);+ expect(usage.entries[0]).toMatchObject({+ state: "unavailable",+ unavailableReason: "Provider completed without token usage.",+ });+ });++ it("does not charge a replacement reservation from stale turn events", async () => {+ const harness = await createHarness({ botOwned: true });+ const replacementTurnId = asTurnId("turn-replacement");+ await harness.dispatch({+ type: "thread.turn.start",+ commandId: CommandId.make("cmd-turn-start-replacement"),+ threadId: asThreadId("thread-1"),+ message: {+ messageId: asMessageId("message-replacement"),+ role: "user",+ text: "replace the old turn",+ attachments: [],+ },+ interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,+ runtimeMode: "approval-required",+ createdAt: "2026-01-01T00:00:01.000Z",+ });+ await harness.dispatch({+ type: "thread.session.set",+ commandId: CommandId.make("cmd-session-replacement-active"),+ threadId: asThreadId("thread-1"),+ session: {+ threadId: asThreadId("thread-1"),+ status: "starting",+ providerName: "codex",+ runtimeMode: "approval-required",+ activeTurnId: null,+ updatedAt: "2026-01-01T00:00:01.000Z",+ lastError: null,+ },+ createdAt: "2026-01-01T00:00:01.000Z",+ });+ harness.setProviderSession({+ provider: ProviderDriverKind.make("codex"),+ status: "running",+ runtimeMode: "approval-required",+ threadId: asThreadId("thread-1"),+ activeTurnId: replacementTurnId,+ createdAt: "2026-01-01T00:00:01.000Z",+ updatedAt: "2026-01-01T00:00:01.000Z",+ });+ await harness.reserveBotUsage(null);++ const staleTurnId = asTurnId("turn-stale");+ harness.emit({+ type: "thread.token-usage.updated",+ eventId: asEventId("evt-stale-turn-usage"),+ provider: ProviderDriverKind.make("codex"),+ threadId: asThreadId("thread-1"),+ turnId: staleTurnId,+ createdAt: "2026-01-01T00:00:02.000Z",+ payload: {+ usage: { usedTokens: 150, inputTokens: 100, outputTokens: 50 },+ },+ });+ harness.emit({+ type: "turn.completed",+ eventId: asEventId("evt-stale-turn-completed"),+ provider: ProviderDriverKind.make("codex"),+ threadId: asThreadId("thread-1"),+ turnId: staleTurnId,+ createdAt: "2026-01-01T00:00:03.000Z",+ payload: { state: "completed" },+ });+ await harness.drain();++ const usage = await harness.summarizeBotUsage();+ expect(usage.consumedTokens).toBe(0);+ expect(usage.reservedTokens).toBe(1_000);+ expect(usage.entries[0]).toMatchObject({ state: "reserved", turnId: null });++ harness.emit({+ type: "thread.token-usage.updated",+ eventId: asEventId("evt-replacement-turn-usage"),+ provider: ProviderDriverKind.make("codex"),+ threadId: asThreadId("thread-1"),+ turnId: replacementTurnId,+ createdAt: "2026-01-01T00:00:04.000Z",+ payload: {+ usage: { usedTokens: 150, inputTokens: 100, outputTokens: 50 },+ },+ });+ harness.emit({+ type: "turn.completed",+ eventId: asEventId("evt-replacement-turn-completed"),+ provider: ProviderDriverKind.make("codex"),+ threadId: asThreadId("thread-1"),+ turnId: replacementTurnId,+ createdAt: "2026-01-01T00:00:05.000Z",+ payload: { state: "completed" },+ });+ await harness.drain();++ const settledUsage = await harness.summarizeBotUsage();+ expect(settledUsage.consumedTokens).toBe(150);+ expect(settledUsage.reservedTokens).toBe(0);+ expect(settledUsage.entries[0]).toMatchObject({+ state: "reported",+ turnId: replacementTurnId,+ });+ });+it("applies provider session.state.changed transitions directly", async () => {const harness = await createHarness();const waitingAt = "2026-01-01T00:00:00.000Z";diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.tsindex fd5a3ab74..7b2878a4c 100644--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts@@ -52,6 +52,8 @@ import { ServerSettingsService } from "../../serverSettings.ts";import { canReplaceThreadTitle } from "../threadTitles.ts";import { ServerConfig } from "../../config.ts";import { BotInboxService } from "../../bot-inbox/service.ts";+import { BotUsageLedger } from "../../usage/BotUsageLedger.ts";+import { resolveControllerBotId } from "./ProviderCommandReactor.ts";const providerTurnKey = (threadId: ThreadId, turnId: TurnId) => `${threadId}:${turnId}`;const providerTaskKey = (threadId: ThreadId, taskId: string) => `${threadId}:${taskId}`;@@ -914,6 +916,7 @@ const make = Effect.gen(function* () {const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;const agentController = yield* AgentController;const projectionTurnRepository = yield* ProjectionTurnRepository;+ const botUsageLedger = yield* BotUsageLedger;const serverSettingsService = yield* ServerSettingsService;const serverConfig = yield* ServerConfig;const botInbox = BotInboxService.forSecretsDir(serverConfig.secretsDir);@@ -1562,15 +1565,81 @@ const make = Effect.gen(function* () {const now = event.createdAt;const eventTurnId = toTurnId(event.turnId);+ const respondingBotId = resolveControllerBotId(thread);const activeTurnId = thread.session?.activeTurnId ?? null;+ const conflictsWithActiveTurn =+ activeTurnId !== null && eventTurnId !== undefined && !sameId(activeTurnId, eventTurnId);const pendingTurnStart = yield* projectionTurnRepository.getPendingTurnStartByThreadId({threadId: thread.id,});+ const expectedPendingTurnId = Option.isSome(pendingTurnStart)+ ? yield* getExpectedProviderTurnIdForThread(thread.id)+ : undefined;+ const eventMatchesPendingTurn =+ Option.isSome(pendingTurnStart) && sameId(expectedPendingTurnId, eventTurnId);+ const canReconcileUsage =+ !conflictsWithActiveTurn &&+ (activeTurnId !== null || Option.isNone(pendingTurnStart) || eventMatchesPendingTurn);+ if (+ respondingBotId !== null &&+ eventTurnId !== undefined &&+ canReconcileUsage &&+ event.type === "thread.token-usage.updated"+ ) {+ const usage = event.payload.usage;+ const outputTokens = usage.lastOutputTokens ?? usage.outputTokens ?? 0;+ yield* botUsageLedger+ .settleForTurn({+ botId: respondingBotId,+ threadId: thread.id,+ turnId: eventTurnId,+ state: "reported",+ inputTokens:+ usage.lastInputTokens ??+ usage.inputTokens ??+ Math.max(0, (usage.lastUsedTokens ?? usage.usedTokens) - outputTokens),+ outputTokens,+ reasoningTokens: usage.lastReasoningOutputTokens ?? usage.reasoningOutputTokens ?? null,+ settledAt: now,+ })+ .pipe(+ Effect.catchCause((cause) =>+ Effect.logWarning("provider runtime ingestion failed to record bot usage", {+ eventId: event.eventId,+ threadId: thread.id,+ turnId: eventTurnId,+ cause: Cause.pretty(cause),+ }),+ ),+ );+ }+ if (+ respondingBotId !== null &&+ eventTurnId !== undefined &&+ canReconcileUsage &&+ (event.type === "turn.completed" || event.type === "turn.aborted")+ ) {+ yield* botUsageLedger+ .finalizeForTurn({+ botId: respondingBotId,+ threadId: thread.id,+ turnId: eventTurnId,+ settledAt: now,+ })+ .pipe(+ Effect.catchCause((cause) =>+ Effect.logWarning("provider runtime ingestion failed to finalize bot usage", {+ eventId: event.eventId,+ threadId: thread.id,+ turnId: eventTurnId,+ cause: Cause.pretty(cause),+ }),+ ),+ );+ }const hasPendingTurnStart =Option.isSome(pendingTurnStart) && thread.session?.status === "starting";- const conflictsWithActiveTurn =- activeTurnId !== null && eventTurnId !== undefined && !sameId(activeTurnId, eventTurnId);const missingTurnForActiveTurn = activeTurnId !== null && eventTurnId === undefined;// A turn.started that conflicts with the active turn is legitimate when@@ -1580,10 +1649,7 @@ const make = Effect.gen(function* () {// new turn without ever completing the superseded one. A stale// turn.started for some other turn id still gets rejected.const conflictingTurnStartIsPendingTurnStart =- event.type === "turn.started" && conflictsWithActiveTurn- ? sameId(yield* getExpectedProviderTurnIdForThread(thread.id), eventTurnId) &&- Option.isSome(pendingTurnStart)- : false;+ event.type === "turn.started" && conflictsWithActiveTurn ? eventMatchesPendingTurn : false;const shouldApplyThreadLifecycle = (() => {if (!STRICT_PROVIDER_LIFECYCLE_GUARD) {@@ -1605,6 +1671,9 @@ const make = Effect.gen(function* () {if (activeTurnId !== null && eventTurnId !== undefined) {return sameId(activeTurnId, eventTurnId);}+ if (Option.isSome(pendingTurnStart)) {+ return eventMatchesPendingTurn;+ }// No active turn tracked: accept only completions that name their// turn (covers a real completion whose turn.started was lost). An// untargeted completion cannot prove it belongs to any turn thisdiff --git a/apps/server/src/orchestration/runtimeLayer.ts b/apps/server/src/orchestration/runtimeLayer.tsindex 0792863cc..f92a04ac9 100644--- a/apps/server/src/orchestration/runtimeLayer.ts+++ b/apps/server/src/orchestration/runtimeLayer.ts@@ -4,6 +4,7 @@ import { OrchestrationCommandReceiptRepositoryLive } from "../persistence/Layersimport { OrchestrationEventStoreLive } from "../persistence/Layers/OrchestrationEventStore.ts";import { ProjectionBotRepositoryLive } from "../persistence/Layers/ProjectionBots.ts";import { ProjectionGroupRepositoryLive } from "../persistence/Layers/ProjectionGroups.ts";+import { BotUsageLedgerLive } from "../usage/BotUsageLedger.ts";import { OrchestrationEngineLive } from "./Layers/OrchestrationEngine.ts";import { OrchestrationProjectionPipelineLive } from "./Layers/ProjectionPipeline.ts";import { OrchestrationProjectionSnapshotQueryLive } from "./Layers/ProjectionSnapshotQuery.ts";@@ -25,6 +26,7 @@ export const OrchestrationInfrastructureLayerLive = Layer.mergeAll(OrchestrationProjectionPipelineLayerLive,ProjectionBotRepositoryLive,ProjectionGroupRepositoryLive,+ BotUsageLedgerLive,// Shared background-liveness and plan-progress registries: written by// runtime ingestion, read by the snapshot query. provideMerge feeds the// same instance to the snapshot query here and re-exports it for runtimediff --git a/apps/server/src/persistence/Migrations.ts b/apps/server/src/persistence/Migrations.tsindex d75323516..f41012999 100644--- a/apps/server/src/persistence/Migrations.ts+++ b/apps/server/src/persistence/Migrations.ts@@ -68,6 +68,7 @@ import Migration0052 from "./Migrations/052_ExecutorPluginCommand.ts";import Migration0053 from "./Migrations/053_BotVoiceEnabled.ts";import Migration0054 from "./Migrations/054_AkeruEntityMemory.ts";import Migration0055 from "./Migrations/055_AkeruMemoryCandidates.ts";+import Migration0056 from "./Migrations/056_AkeruBotUsageLedger.ts";/*** Migration loader with all migrations defined inline.@@ -135,6 +136,7 @@ export const migrationEntries = [[53, "BotVoiceEnabled", Migration0053],[54, "AkeruEntityMemory", Migration0054],[55, "AkeruMemoryCandidates", Migration0055],+ [56, "AkeruBotUsageLedger", Migration0056],] as const;export const migrationManifest = migrationEntries.map(([id, name]) => [id, name] as const);diff --git a/apps/server/src/persistence/Migrations/056_AkeruBotUsageLedger.test.ts b/apps/server/src/persistence/Migrations/056_AkeruBotUsageLedger.test.tsnew file mode 100644index 000000000..8d94a2971--- /dev/null+++ b/apps/server/src/persistence/Migrations/056_AkeruBotUsageLedger.test.ts@@ -0,0 +1,39 @@+import { assert, it } from "@effect/vitest";+import * as Effect from "effect/Effect";+import * as Layer from "effect/Layer";+import * as SqlClient from "effect/unstable/sql/SqlClient";++import { runMigrations } from "../Migrations.ts";+import * as NodeSqliteClient from "../NodeSqliteClient.ts";++it.layer(Layer.mergeAll(NodeSqliteClient.layerMemory()))("056_AkeruBotUsageLedger", (it) => {+ it.effect("creates constrained balances and bot-scoped source keys", () =>+ Effect.gen(function* () {+ const sql = yield* SqlClient.SqlClient;+ yield* runMigrations({ toMigrationInclusive: 56 });+ yield* sql`+ INSERT INTO akeru_bot_usage_balances (bot_id, consumed_tokens, reserved_tokens, updated_at)+ VALUES ('bot-1', 0, 10, '2026-08-30T20:00:00.000Z')+ `;+ yield* sql`+ INSERT INTO akeru_bot_usage_entries (+ reservation_id, source_key, bot_id, thread_id, turn_id, category, state,+ reserved_tokens, held_tokens, created_at+ ) VALUES+ ('reservation-1', 'shared-key', 'bot-1', 'thread-1', NULL, 'turn', 'reserved', 10, 10, '2026-08-30T20:00:00.000Z'),+ ('reservation-2', 'shared-key', 'bot-2', 'thread-2', NULL, 'turn', 'reserved', 10, 10, '2026-08-30T20:00:00.000Z')+ `;+ const rows = yield* sql<{ readonly count: number }>`+ SELECT COUNT(*) AS count FROM akeru_bot_usage_entries+ `;+ assert.equal(rows[0]?.count, 2);++ const invalid = yield* sql`+ INSERT INTO akeru_bot_usage_entries (+ reservation_id, source_key, bot_id, category, state, reserved_tokens, created_at+ ) VALUES ('invalid', 'invalid', 'bot-1', 'unknown', 'reserved', 0, '2026-08-30T20:00:00.000Z')+ `.pipe(Effect.exit);+ assert.equal(invalid._tag, "Failure");+ }),+ );+});diff --git a/apps/server/src/persistence/Migrations/056_AkeruBotUsageLedger.ts b/apps/server/src/persistence/Migrations/056_AkeruBotUsageLedger.tsnew file mode 100644index 000000000..2e9e04173--- /dev/null+++ b/apps/server/src/persistence/Migrations/056_AkeruBotUsageLedger.ts@@ -0,0 +1,52 @@+import * as Effect from "effect/Effect";+import * as SqlClient from "effect/unstable/sql/SqlClient";++export default Effect.gen(function* () {+ const sql = yield* SqlClient.SqlClient;++ yield* sql`+ CREATE TABLE akeru_bot_usage_balances (+ bot_id TEXT PRIMARY KEY,+ consumed_tokens INTEGER NOT NULL DEFAULT 0 CHECK (consumed_tokens >= 0),+ reserved_tokens INTEGER NOT NULL DEFAULT 0 CHECK (reserved_tokens >= 0),+ updated_at TEXT NOT NULL+ )+ `;+ yield* sql`+ CREATE TABLE akeru_bot_usage_entries (+ reservation_id TEXT PRIMARY KEY,+ source_key TEXT NOT NULL,+ bot_id TEXT NOT NULL,+ thread_id TEXT,+ turn_id TEXT,+ category TEXT NOT NULL,+ state TEXT NOT NULL,+ reserved_tokens INTEGER NOT NULL CHECK (reserved_tokens >= 0),+ held_tokens INTEGER NOT NULL DEFAULT 0 CHECK (held_tokens >= 0),+ input_tokens INTEGER,+ output_tokens INTEGER,+ reasoning_tokens INTEGER,+ provider TEXT,+ model TEXT,+ unavailable_reason TEXT,+ created_at TEXT NOT NULL,+ settled_at TEXT,+ CHECK (category IN ('turn', 'tool', 'observer', 'reflector', 'extraction', 'recall', 'routine', 'delegated')),+ CHECK (state IN ('reserved', 'reported', 'unavailable', 'released')),+ UNIQUE (bot_id, source_key)+ )+ `;+ yield* sql`+ CREATE INDEX idx_akeru_bot_usage_entries_bot_created+ ON akeru_bot_usage_entries (bot_id, created_at DESC)+ `;+ yield* sql`+ CREATE INDEX idx_akeru_bot_usage_entries_thread_turn+ ON akeru_bot_usage_entries (thread_id, turn_id)+ `;+ yield* sql`+ CREATE UNIQUE INDEX idx_akeru_bot_usage_entries_bound_turn+ ON akeru_bot_usage_entries (bot_id, thread_id, turn_id)+ WHERE category = 'turn' AND turn_id IS NOT NULL+ `;+});diff --git a/apps/server/src/usage/BotUsageLedger.test.ts b/apps/server/src/usage/BotUsageLedger.test.tsnew file mode 100644index 000000000..9c2b81af1--- /dev/null+++ b/apps/server/src/usage/BotUsageLedger.test.ts@@ -0,0 +1,493 @@+import { assert, it } from "@effect/vitest";+import {+ AkeruUsageReservationId,+ BotId,+ ProviderDriverKind,+ ThreadId,+ TurnId,+} from "@t3tools/contracts";+import * as Effect from "effect/Effect";+import * as Layer from "effect/Layer";++import {+ makeSqlitePersistenceLive,+ SqlitePersistenceMemory,+} from "../persistence/Layers/Sqlite.ts";+import { BotUsageLedger, BotUsageLedgerLive, type ReserveBotUsageInput } from "./BotUsageLedger.ts";++const layer = BotUsageLedgerLive.pipe(Layer.provideMerge(SqlitePersistenceMemory));++const reserveInput = (+ reservationId: string,+ overrides: Partial<ReserveBotUsageInput> = {},+): ReserveBotUsageInput => ({+ reservationId: AkeruUsageReservationId.make(reservationId),+ sourceKey: `turn-start:${reservationId}`,+ botId: BotId.make("bot-1"),+ threadId: ThreadId.make("thread-1"),+ turnId: null,+ category: "turn",+ maximumTokens: 1_000,+ capLimit: 1_000,+ provider: ProviderDriverKind.make("codex"),+ model: "gpt-5.6-sol",+ createdAt: "2026-08-30T20:00:00.000Z",+ ...overrides,+});++it.layer(layer)("BotUsageLedger", (it) => {+ it.effect("reconciles progressive reports without counting reasoning twice", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const botId = BotId.make("bot-progressive");+ yield* ledger.reserve(reserveInput("progressive", { botId }));+ const turnId = TurnId.make("turn-progressive");++ yield* ledger.settleForTurn({+ botId,+ threadId: ThreadId.make("thread-1"),+ turnId,+ state: "reported",+ inputTokens: 100,+ outputTokens: 20,+ reasoningTokens: 10,+ settledAt: "2026-08-30T20:01:00.000Z",+ });+ yield* ledger.settleForTurn({+ botId,+ threadId: ThreadId.make("thread-1"),+ turnId,+ state: "reported",+ inputTokens: 150,+ outputTokens: 30,+ reasoningTokens: 15,+ settledAt: "2026-08-30T20:02:00.000Z",+ });+ yield* ledger.settleForTurn({+ botId,+ threadId: ThreadId.make("thread-1"),+ turnId,+ state: "reported",+ inputTokens: 150,+ outputTokens: 30,+ reasoningTokens: 15,+ settledAt: "2026-08-30T20:03:00.000Z",+ });++ const inFlight = yield* ledger.summarize(botId);+ assert.equal(inFlight.consumedTokens, 180);+ assert.equal(inFlight.reservedTokens, 820);+ yield* ledger.finalizeForTurn({+ botId,+ threadId: ThreadId.make("thread-1"),+ turnId,+ settledAt: "2026-08-30T20:04:00.000Z",+ });+ const summary = yield* ledger.summarize(botId);+ assert.equal(summary.consumedTokens, 180);+ assert.equal(summary.reservedTokens, 0);+ assert.equal(summary.entries[0]?.reasoningTokens, 15);+ }),+ );++ it.effect("claims a runtime turn before a late command binding", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const reservation = yield* ledger.reserve(+ reserveInput("runtime-first", { botId: BotId.make("bot-runtime-first") }),+ );+ const turnId = TurnId.make("turn-runtime-first");+ const claimed = yield* ledger.settleForTurn({+ botId: BotId.make("bot-runtime-first"),+ threadId: ThreadId.make("thread-1"),+ turnId,+ state: "reported",+ inputTokens: 40,+ outputTokens: 2,+ reasoningTokens: null,+ settledAt: "2026-08-30T20:01:00.000Z",+ });+ assert.equal(claimed[0]?.turnId, turnId);++ const late = yield* ledger.bindTurn({ reservationId: reservation.reservationId, turnId });+ assert.equal(late.turnId, turnId);+ const conflict = yield* ledger+ .bindTurn({+ reservationId: reservation.reservationId,+ turnId: TurnId.make("another-turn"),+ })+ .pipe(Effect.exit);+ assert.equal(conflict._tag, "Failure");+ }),+ );++ it.effect("isolates source keys and balances by bot", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const sourceKey = "turn-start:shared-event-id";+ const firstBotId = BotId.make("bot-isolation-a");+ const secondBotId = BotId.make("bot-isolation-b");+ yield* ledger.reserve(+ reserveInput("bot-a", {+ sourceKey,+ botId: firstBotId,+ maximumTokens: 60,+ capLimit: 100,+ }),+ );+ yield* ledger.reserve(+ reserveInput("bot-b", {+ sourceKey,+ botId: secondBotId,+ maximumTokens: 60,+ capLimit: 100,+ }),+ );++ const first = yield* ledger.summarize(firstBotId);+ const second = yield* ledger.summarize(secondBotId);+ assert.equal(first.entries.length, 1);+ assert.equal(second.entries.length, 1);+ assert.equal(first.reservedTokens, 60);+ assert.equal(second.reservedTokens, 60);+ }),+ );++ it.effect("rejects a second reservation when a cap is fully reserved", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const botId = BotId.make("bot-cap");+ yield* ledger.reserve(+ reserveInput("cap-first", { botId, maximumTokens: 100, capLimit: 100 }),+ );+ const exit = yield* ledger+ .reserve(reserveInput("cap-second", { botId, maximumTokens: 100, capLimit: 100 }))+ .pipe(Effect.exit);+ assert.isTrue(exit._tag === "Failure");+ const summary = yield* ledger.summarize(botId);+ assert.equal(summary.reservedTokens, 100);+ assert.equal(summary.entries.length, 1);+ }),+ );++ it.effect("reserves the remaining cap when a request exceeds it", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const botId = BotId.make("bot-partial-cap");+ yield* ledger.reserve(+ reserveInput("partial-first", { botId, maximumTokens: 60, capLimit: 100 }),+ );+ const reservation = yield* ledger.reserve(+ reserveInput("partial-second", { botId, maximumTokens: 50, capLimit: 100 }),+ );+ assert.equal(reservation.reservedTokens, 40);+ const failure = yield* ledger+ .reserve(reserveInput("partial-third", { botId, maximumTokens: 1, capLimit: 100 }))+ .pipe(Effect.flip);+ assert.equal(failure._tag, "BotUsageCapExceeded");+ const summary = yield* ledger.summarize(botId);+ assert.equal(summary.reservedTokens, 100);+ assert.equal(summary.entries.length, 2);+ }),+ );++ it.effect("charges the reservation when provider usage is unavailable", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const botId = BotId.make("bot-unavailable");+ const reservation = yield* ledger.reserve(+ reserveInput("unavailable", { botId, maximumTokens: 500, capLimit: 500 }),+ );+ yield* ledger.settle({+ reservationId: reservation.reservationId,+ state: "unavailable",+ reason: "Provider completed without token usage.",+ settledAt: "2026-08-30T20:01:00.000Z",+ });+ yield* ledger.settle({+ reservationId: reservation.reservationId,+ state: "unavailable",+ reason: "Provider completed without token usage.",+ settledAt: "2026-08-30T20:02:00.000Z",+ });++ const summary = yield* ledger.summarize(botId);+ assert.equal(summary.consumedTokens, 500);+ assert.equal(summary.reservedTokens, 0);+ assert.equal(+ summary.entries[0]?.unavailableReason,+ "Provider completed without token usage.",+ );+ }),+ );++ it.effect("records reported overage as enforcement truth", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const botId = BotId.make("bot-reported-overage");+ const reservation = yield* ledger.reserve(+ reserveInput("reported-overage", { botId, maximumTokens: 100, capLimit: 100 }),+ );+ yield* ledger.settle({+ reservationId: reservation.reservationId,+ state: "reported",+ inputTokens: 120,+ outputTokens: 30,+ reasoningTokens: 10,+ settledAt: "2026-08-30T20:01:00.000Z",+ });++ const summary = yield* ledger.summarize(botId);+ assert.equal(summary.consumedTokens, 150);+ assert.equal(summary.measurements.input.tokens, 120);+ assert.equal(summary.measurements.output.tokens, 30);+ }),+ );++ it.effect("charges one OM reservation and reports Observer and Reflector separately", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const botId = BotId.make("bot-composite-om");+ const threadId = ThreadId.make("thread-composite-om");+ const turnId = TurnId.make("turn-composite-om");+ const observer = yield* ledger.reserve(+ reserveInput("observer-composite", {+ sourceKey: "observer:turn-composite-om",+ botId,+ threadId,+ turnId,+ category: "observer",+ maximumTokens: 32_000,+ capLimit: 32_000,+ }),+ );+ yield* ledger.settle({+ reservationId: observer.reservationId,+ state: "reported",+ inputTokens: 100,+ outputTokens: 50,+ reasoningTokens: null,+ settledAt: "2026-08-30T20:01:00.000Z",+ });+ yield* ledger.recordMeasurement({+ reservationId: AkeruUsageReservationId.make("reflector-composite"),+ sourceKey: "reflector:turn-composite-om",+ botId,+ threadId,+ turnId,+ category: "reflector",+ inputTokens: 20,+ outputTokens: 10,+ reasoningTokens: null,+ provider: ProviderDriverKind.make("codex"),+ model: "gpt-5.6-sol",+ includedInReservation: true,+ createdAt: "2026-08-30T20:01:00.000Z",+ });++ const summary = yield* ledger.summarize(botId);+ assert.equal(summary.consumedTokens, 150);+ assert.equal(summary.reservedTokens, 0);+ assert.deepEqual(summary.measurements, {+ input: { tokens: 0, unavailableEntries: 0 },+ output: { tokens: 0, unavailableEntries: 0 },+ observer: { tokens: 120, unavailableEntries: 0 },+ reflector: { tokens: 30, unavailableEntries: 0 },+ });+ }),+ );++ it.effect("charges a standalone reported measurement once", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const botId = BotId.make("bot-standalone-measurement");+ const input = {+ reservationId: AkeruUsageReservationId.make("standalone-measurement"),+ sourceKey: "tool:standalone-measurement",+ botId,+ threadId: ThreadId.make("thread-standalone-measurement"),+ turnId: TurnId.make("turn-standalone-measurement"),+ category: "tool" as const,+ inputTokens: 20,+ outputTokens: 10,+ reasoningTokens: 5,+ provider: ProviderDriverKind.make("codex"),+ model: "gpt-5.6-sol",+ createdAt: "2026-08-30T20:01:00.000Z",+ };+ yield* ledger.recordMeasurement(input);+ yield* ledger.recordMeasurement(input);++ const summary = yield* ledger.summarize(botId);+ assert.equal(summary.consumedTokens, 30);+ assert.equal(summary.entries.length, 1);+ }),+ );++ it.effect("keeps unavailable OM work out of ordinary input and output counts", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const botId = BotId.make("bot-unavailable-categories");+ for (const [category, reservationId] of [+ ["turn", "unavailable-turn"],+ ["observer", "unavailable-observer"],+ ["reflector", "unavailable-reflector"],+ ] as const) {+ const reservation = yield* ledger.reserve(+ reserveInput(reservationId, {+ botId,+ sourceKey: reservationId,+ category,+ maximumTokens: 100,+ capLimit: 1_000,+ }),+ );+ yield* ledger.settle({+ reservationId: reservation.reservationId,+ state: "unavailable",+ reason: "Provider usage was unavailable.",+ settledAt: "2026-08-30T20:01:00.000Z",+ });+ }++ const summary = yield* ledger.summarize(botId);+ assert.equal(summary.measurements.input.unavailableEntries, 1);+ assert.equal(summary.measurements.output.unavailableEntries, 1);+ assert.equal(summary.measurements.observer.unavailableEntries, 1);+ assert.equal(summary.measurements.reflector.unavailableEntries, 1);+ }),+ );++ it.effect("meters delegated work against the performing bot", () =>+ Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const childId = BotId.make("bot-research");+ const parentId = BotId.make("bot-chief");+ const reservation = yield* ledger.reserve(+ reserveInput("delegate-child", {+ botId: childId,+ sourceKey: "delegate:chief:research",+ category: "delegated",+ maximumTokens: 200,+ capLimit: 1_000,+ }),+ );+ yield* ledger.settle({+ reservationId: reservation.reservationId,+ state: "reported",+ inputTokens: 80,+ outputTokens: 40,+ reasoningTokens: 0,+ settledAt: "2026-08-30T20:01:00.000Z",+ });++ const child = yield* ledger.summarize(childId);+ const parent = yield* ledger.summarize(parentId);+ assert.equal(child.measurements.input.tokens, 80);+ assert.equal(child.measurements.output.tokens, 40);+ assert.equal(child.consumedTokens, 120);+ assert.equal(parent.consumedTokens, 0);+ }),+ );+});++it("reconciles persisted reservations when the ledger restarts", () =>+ Effect.gen(function* () {+ const directory = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "akeru-usage-restart-"));+ const dbPath = NodePath.join(directory, "state.sqlite");+ const restartedLayer = () =>+ BotUsageLedgerLive.pipe(+ Layer.provideMerge(+ makeSqlitePersistenceLive(dbPath).pipe(Layer.provide(NodeServices.layer)),+ ),+ );+ const botId = BotId.make("bot-restart-usage");+ const threadId = ThreadId.make("thread-restart-usage");+ yield* Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ yield* ledger.reserve(+ reserveInput("unbound-before-restart", {+ botId,+ threadId,+ maximumTokens: 100,+ capLimit: 1_000,+ }),+ );+ yield* ledger.reserve(+ reserveInput("bound-before-restart", {+ botId,+ threadId,+ turnId: TurnId.make("turn-interrupted"),+ maximumTokens: 200,+ capLimit: 1_000,+ }),+ );+ yield* ledger.reserve(+ reserveInput("reported-before-restart", {+ botId,+ threadId,+ turnId: TurnId.make("turn-reported"),+ maximumTokens: 300,+ capLimit: 1_000,+ }),+ );+ yield* ledger.settleForTurn({+ botId,+ threadId,+ turnId: TurnId.make("turn-reported"),+ state: "reported",+ inputTokens: 40,+ outputTokens: 10,+ reasoningTokens: 20,+ settledAt: "2026-08-30T20:01:00.000Z",+ });+ }).pipe(Effect.provide(restartedLayer()));++ const { afterRestart, afterLateReport } = yield* Effect.gen(function* () {+ const ledger = yield* BotUsageLedger;+ const afterRestart = yield* ledger.summarize(botId);+ yield* ledger.settleForTurn({+ botId,+ threadId,+ turnId: TurnId.make("turn-reported"),+ state: "reported",+ inputTokens: 60,+ outputTokens: 20,+ reasoningTokens: 25,+ settledAt: "2026-08-30T20:02:00.000Z",+ });+ yield* ledger.finalizeForTurn({+ botId,+ threadId,+ turnId: TurnId.make("turn-reported"),+ settledAt: "2026-08-30T20:03:00.000Z",+ });+ return { afterRestart, afterLateReport: yield* ledger.summarize(botId) };+ }).pipe(Effect.provide(restartedLayer()));++ assert.equal(afterRestart.consumedTokens, 270);+ assert.equal(afterRestart.reservedTokens, 0);+ assert.equal(+ afterRestart.entries.find((entry) => entry.sourceKey.includes("unbound-before-restart"))+ ?.state,+ "released",+ );+ assert.equal(+ afterRestart.entries.find((entry) => entry.sourceKey.includes("bound-before-restart"))?.state,+ "unavailable",+ );+ assert.equal(+ afterRestart.entries.find((entry) => entry.sourceKey.includes("reported-before-restart"))+ ?.state,+ "reported",+ );+ assert.equal(afterLateReport.consumedTokens, 305);+ assert.equal(afterLateReport.reservedTokens, 0);+ NodeFS.rmSync(directory, { recursive: true, force: true });+ }).pipe(Effect.provide(NodeServices.layer), Effect.orDie));+// @effect-diagnostics nodeBuiltinImport:off+import * as NodeFS from "node:fs";+import * as NodeOS from "node:os";+import * as NodePath from "node:path";++import * as NodeServices from "@effect/platform-node/NodeServices";diff --git a/apps/server/src/usage/BotUsageLedger.ts b/apps/server/src/usage/BotUsageLedger.tsnew file mode 100644index 000000000..009afe9b9--- /dev/null+++ b/apps/server/src/usage/BotUsageLedger.ts@@ -0,0 +1,652 @@+import {+ AkeruBotUsageSummary,+ AkeruUsageEntry,+ type AkeruUsageCategory,+ type AkeruUsageReservationId,+ type BotId,+ type ProviderDriverKind,+ type ThreadId,+ type TurnId,+} from "@t3tools/contracts";+import * as Context from "effect/Context";+import * as DateTime from "effect/DateTime";+import * as Effect from "effect/Effect";+import * as Layer from "effect/Layer";+import * as Schema from "effect/Schema";+import * as Semaphore from "effect/Semaphore";+import * as SqlClient from "effect/unstable/sql/SqlClient";++import {+ type PersistenceDecodeError,+ PersistenceSqlError,+ toPersistenceDecodeError,+ toPersistenceSqlError,+} from "../persistence/Errors.ts";++export class BotUsageCapExceeded extends Schema.TaggedErrorClass<BotUsageCapExceeded>()(+ "BotUsageCapExceeded",+ {+ botId: Schema.String,+ limit: Schema.Number,+ consumedTokens: Schema.Number,+ reservedTokens: Schema.Number,+ requestedTokens: Schema.Number,+ },+) {+ override get message(): string {+ return `Bot ${this.botId} reached its ${this.limit}-token usage cap.`;+ }+}++export const AKERU_TURN_USAGE_RESERVATION_TOKENS = 32_000;++export interface ReserveBotUsageInput {+ readonly reservationId: AkeruUsageReservationId;+ readonly sourceKey: string;+ readonly botId: BotId;+ readonly threadId: ThreadId | null;+ readonly turnId: TurnId | null;+ readonly category: AkeruUsageCategory;+ readonly maximumTokens: number;+ readonly capLimit: number;+ readonly provider: ProviderDriverKind | null;+ readonly model: string | null;+ readonly createdAt: string;+}++type SettleBotUsageDetails =+ | {+ readonly state: "reported";+ readonly inputTokens: number;+ readonly outputTokens: number;+ readonly reasoningTokens: number | null;+ }+ | { readonly state: "unavailable"; readonly reason: string }+ | { readonly state: "released" };++export type SettleBotUsageInput = SettleBotUsageDetails & {+ readonly reservationId: AkeruUsageReservationId;+ readonly settledAt: string;+};++export type SettleBotUsageForTurnInput = SettleBotUsageDetails & {+ readonly botId: BotId;+ readonly threadId: ThreadId;+ readonly turnId: TurnId;+ readonly settledAt: string;+};++export type BotUsageLedgerError =+ | BotUsageCapExceeded+ | PersistenceSqlError+ | PersistenceDecodeError;++export interface BotUsageLedgerShape {+ readonly reserve: (+ input: ReserveBotUsageInput,+ ) => Effect.Effect<AkeruUsageEntry, BotUsageLedgerError>;+ readonly settle: (+ input: SettleBotUsageInput,+ ) => Effect.Effect<AkeruUsageEntry, Exclude<BotUsageLedgerError, BotUsageCapExceeded>>;+ readonly bindTurn: (input: {+ readonly reservationId: AkeruUsageReservationId;+ readonly turnId: TurnId;+ }) => Effect.Effect<AkeruUsageEntry, Exclude<BotUsageLedgerError, BotUsageCapExceeded>>;+ readonly settleForTurn: (+ input: SettleBotUsageForTurnInput,+ ) => Effect.Effect<+ ReadonlyArray<AkeruUsageEntry>,+ Exclude<BotUsageLedgerError, BotUsageCapExceeded>+ >;+ readonly finalizeForTurn: (input: {+ readonly botId: BotId;+ readonly threadId: ThreadId;+ readonly turnId: TurnId;+ readonly settledAt: string;+ }) => Effect.Effect<+ ReadonlyArray<AkeruUsageEntry>,+ Exclude<BotUsageLedgerError, BotUsageCapExceeded>+ >;+ readonly recordMeasurement: (input: {+ readonly reservationId: AkeruUsageReservationId;+ readonly sourceKey: string;+ readonly botId: BotId;+ readonly threadId: ThreadId | null;+ readonly turnId: TurnId | null;+ readonly category: AkeruUsageCategory;+ readonly inputTokens: number;+ readonly outputTokens: number;+ readonly reasoningTokens: number | null;+ readonly provider: ProviderDriverKind | null;+ readonly model: string | null;+ readonly includedInReservation?: boolean;+ readonly createdAt: string;+ }) => Effect.Effect<AkeruUsageEntry, Exclude<BotUsageLedgerError, BotUsageCapExceeded>>;+ readonly summarize: (+ botId: BotId,+ ) => Effect.Effect<AkeruBotUsageSummary, Exclude<BotUsageLedgerError, BotUsageCapExceeded>>;+}++export class BotUsageLedger extends Context.Service<BotUsageLedger, BotUsageLedgerShape>()(+ "akeru-bot/usage/BotUsageLedger",+) {}++const UsageRow = Schema.Struct({+ reservationId: Schema.String,+ sourceKey: Schema.String,+ botId: Schema.String,+ threadId: Schema.NullOr(Schema.String),+ turnId: Schema.NullOr(Schema.String),+ category: Schema.String,+ state: Schema.String,+ reservedTokens: Schema.Number,+ heldTokens: Schema.Number,+ inputTokens: Schema.NullOr(Schema.Number),+ outputTokens: Schema.NullOr(Schema.Number),+ reasoningTokens: Schema.NullOr(Schema.Number),+ provider: Schema.NullOr(Schema.String),+ model: Schema.NullOr(Schema.String),+ unavailableReason: Schema.NullOr(Schema.String),+ createdAt: Schema.String,+ settledAt: Schema.NullOr(Schema.String),+});+type UsageRow = typeof UsageRow.Type;++const entryColumns = (sql: SqlClient.SqlClient) =>+ sql.unsafe(`+ reservation_id AS "reservationId", source_key AS "sourceKey", bot_id AS "botId",+ thread_id AS "threadId", turn_id AS "turnId", category, state,+ reserved_tokens AS "reservedTokens", held_tokens AS "heldTokens",+ input_tokens AS "inputTokens",+ output_tokens AS "outputTokens", reasoning_tokens AS "reasoningTokens",+ provider, model, unavailable_reason AS "unavailableReason",+ created_at AS "createdAt", settled_at AS "settledAt"+`);++const selectEntryByReservation = (sql: SqlClient.SqlClient, reservationId: string) =>+ sql<UsageRow>`+ SELECT ${entryColumns(sql)}+ FROM akeru_bot_usage_entries+ WHERE reservation_id = ${reservationId}+ `;++const selectEntryBySource = (sql: SqlClient.SqlClient, botId: string, sourceKey: string) =>+ sql<UsageRow>`+ SELECT ${entryColumns(sql)}+ FROM akeru_bot_usage_entries+ WHERE bot_id = ${botId} AND source_key = ${sourceKey}+ `;++const selectEntryForTurn = (+ sql: SqlClient.SqlClient,+ botId: string,+ threadId: string,+ turnId: string,+) =>+ sql<UsageRow>`+ SELECT ${entryColumns(sql)}+ FROM akeru_bot_usage_entries+ WHERE bot_id = ${botId}+ AND thread_id = ${threadId}+ AND category = 'turn'+ AND (turn_id = ${turnId} OR (turn_id IS NULL AND state = 'reserved'))+ ORDER BY CASE WHEN turn_id = ${turnId} THEN 0 ELSE 1 END, created_at DESC+ LIMIT 1+ `;++const decodeEntry = (row: UsageRow) =>+ Schema.decodeUnknownEffect(AkeruUsageEntry)(row).pipe(+ Effect.mapError(toPersistenceDecodeError("BotUsageLedger.decodeEntry")),+ );++function validateTokens(operation: string, values: ReadonlyArray<number>) {+ const invalid = values.find((value) => !Number.isSafeInteger(value) || value < 0);+ return invalid === undefined+ ? Effect.void+ : new PersistenceSqlError({+ operation,+ detail: "Token values must be non-negative safe integers.",+ });+}++const make = Effect.gen(function* () {+ const sql = yield* SqlClient.SqlClient;+ const writeLock = yield* Semaphore.make(1);++ const settleCurrent = Effect.fn("BotUsageLedger.settleCurrent")(function* (+ current: UsageRow,+ input: SettleBotUsageDetails & { readonly settledAt: string },+ finalizeReported = true,+ ) {+ if (input.state === "reported") {+ yield* validateTokens("BotUsageLedger.settle", [+ input.inputTokens,+ input.outputTokens,+ ...(input.reasoningTokens === null ? [] : [input.reasoningTokens]),+ ]);+ }+ if (current.state === "released" || current.state === "unavailable") {+ return yield* decodeEntry(current);+ }++ const priorReported =+ current.state === "reported" ? (current.inputTokens ?? 0) + (current.outputTokens ?? 0) : 0;+ const nextReported =+ input.state === "reported"+ ? input.inputTokens + input.outputTokens+ : input.state === "unavailable"+ ? current.reservedTokens+ : 0;+ if (+ current.state === "reported" &&+ (input.state !== "reported" || nextReported <= priorReported)+ ) {+ return yield* decodeEntry(current);+ }++ const priorHeld = current.heldTokens;+ const nextHeld =+ input.state === "reported" && !finalizeReported+ ? Math.max(0, priorHeld - (nextReported - priorReported))+ : 0;+ const releasedReservation = priorHeld - nextHeld;+ const priorCharged = priorReported;+ const nextCharged = nextReported;+ const chargedDelta = nextCharged - priorCharged;+ yield* sql`+ UPDATE akeru_bot_usage_balances+ SET reserved_tokens = reserved_tokens - ${releasedReservation},+ consumed_tokens = consumed_tokens + ${chargedDelta},+ updated_at = ${input.settledAt}+ WHERE bot_id = ${current.botId}+ `;+ yield* sql`+ UPDATE akeru_bot_usage_entries SET+ state = ${input.state},+ held_tokens = ${nextHeld},+ input_tokens = ${input.state === "reported" ? input.inputTokens : null},+ output_tokens = ${input.state === "reported" ? input.outputTokens : null},+ reasoning_tokens = ${input.state === "reported" ? input.reasoningTokens : null},+ unavailable_reason = ${input.state === "unavailable" ? input.reason : null},+ settled_at = ${input.settledAt}+ WHERE reservation_id = ${current.reservationId}+ `;+ const settled = yield* selectEntryByReservation(sql, current.reservationId);+ return yield* decodeEntry(settled[0]!);+ });++ const reserve: BotUsageLedgerShape["reserve"] = (input) =>+ writeLock.withPermit(+ sql+ .withTransaction(+ Effect.gen(function* () {+ yield* validateTokens("BotUsageLedger.reserve", [input.maximumTokens, input.capLimit]);+ const prior = yield* selectEntryBySource(sql, input.botId, input.sourceKey);+ if (prior[0]) return yield* decodeEntry(prior[0]);++ yield* sql`+ INSERT INTO akeru_bot_usage_balances (bot_id, consumed_tokens, reserved_tokens, updated_at)+ VALUES (${input.botId}, 0, 0, ${input.createdAt})+ ON CONFLICT (bot_id) DO NOTHING+ `;+ const balance = yield* sql<{+ readonly consumedTokens: number;+ readonly reservedTokens: number;+ }>`+ SELECT consumed_tokens AS "consumedTokens", reserved_tokens AS "reservedTokens"+ FROM akeru_bot_usage_balances WHERE bot_id = ${input.botId}+ `;+ const current = balance[0]!;+ const available = input.capLimit - current.consumedTokens - current.reservedTokens;+ if (input.maximumTokens <= 0 || available <= 0) {+ return yield* new BotUsageCapExceeded({+ botId: input.botId,+ limit: input.capLimit,+ consumedTokens: current.consumedTokens,+ reservedTokens: current.reservedTokens,+ requestedTokens: input.maximumTokens,+ });+ }+ const reservedTokens = Math.min(input.maximumTokens, available);+ yield* sql`+ UPDATE akeru_bot_usage_balances+ SET reserved_tokens = reserved_tokens + ${reservedTokens}, updated_at = ${input.createdAt}+ WHERE bot_id = ${input.botId}+ `;+ yield* sql`+ INSERT INTO akeru_bot_usage_entries (+ reservation_id, source_key, bot_id, thread_id, turn_id, category, state,+ reserved_tokens, held_tokens, input_tokens, output_tokens, reasoning_tokens, provider,+ model, unavailable_reason, created_at, settled_at+ ) VALUES (+ ${input.reservationId}, ${input.sourceKey}, ${input.botId}, ${input.threadId},+ ${input.turnId}, ${input.category}, 'reserved', ${reservedTokens}, ${reservedTokens},+ NULL, NULL, NULL, ${input.provider}, ${input.model}, NULL, ${input.createdAt}, NULL+ )+ `;+ const rows = yield* selectEntryByReservation(sql, input.reservationId);+ return yield* decodeEntry(rows[0]!);+ }),+ )+ .pipe(+ Effect.mapError((cause) =>+ cause._tag === "BotUsageCapExceeded"+ ? cause+ : cause._tag === "PersistenceDecodeError"+ ? cause+ : toPersistenceSqlError("BotUsageLedger.reserve")(cause),+ ),+ ),+ );++ const settle: BotUsageLedgerShape["settle"] = (input) =>+ writeLock.withPermit(+ sql+ .withTransaction(+ Effect.gen(function* () {+ const rows = yield* selectEntryByReservation(sql, input.reservationId);+ const current = rows[0];+ if (!current) {+ return yield* toPersistenceSqlError("BotUsageLedger.settle:not-found")(+ input.reservationId,+ );+ }+ return yield* settleCurrent(current, input);+ }),+ )+ .pipe(+ Effect.mapError((cause) =>+ cause._tag === "PersistenceSqlError" || cause._tag === "PersistenceDecodeError"+ ? cause+ : toPersistenceSqlError("BotUsageLedger.settle")(cause),+ ),+ ),+ );++ const bindTurn: BotUsageLedgerShape["bindTurn"] = (input) =>+ writeLock.withPermit(+ sql+ .withTransaction(+ Effect.gen(function* () {+ const rows = yield* selectEntryByReservation(sql, input.reservationId);+ const current = rows[0];+ if (!current) {+ return yield* new PersistenceSqlError({+ operation: "BotUsageLedger.bindTurn",+ detail: "Usage reservation was not found.",+ });+ }+ if (current.turnId !== null && current.turnId !== input.turnId) {+ return yield* new PersistenceSqlError({+ operation: "BotUsageLedger.bindTurn",+ detail: "Usage reservation is already bound to another turn.",+ });+ }+ if (current.turnId === null) {+ yield* sql`+ UPDATE akeru_bot_usage_entries SET turn_id = ${input.turnId}+ WHERE reservation_id = ${input.reservationId} AND turn_id IS NULL+ `;+ }+ const bound = yield* selectEntryByReservation(sql, input.reservationId);+ return yield* decodeEntry(bound[0]!);+ }),+ )+ .pipe(+ Effect.mapError((cause) =>+ cause._tag === "PersistenceSqlError" || cause._tag === "PersistenceDecodeError"+ ? cause+ : toPersistenceSqlError("BotUsageLedger.bindTurn")(cause),+ ),+ ),+ );++ const settleForTurn: BotUsageLedgerShape["settleForTurn"] = (input) =>+ writeLock.withPermit(+ sql+ .withTransaction(+ Effect.gen(function* () {+ const rows = yield* selectEntryForTurn(sql, input.botId, input.threadId, input.turnId);+ const current = rows[0];+ if (!current) return [];+ if (current.turnId === null) {+ yield* sql`+ UPDATE akeru_bot_usage_entries SET turn_id = ${input.turnId}+ WHERE reservation_id = ${current.reservationId} AND turn_id IS NULL+ `;+ }+ return [yield* settleCurrent({ ...current, turnId: input.turnId }, input, false)];+ }),+ )+ .pipe(+ Effect.mapError((cause) =>+ cause._tag === "PersistenceSqlError" || cause._tag === "PersistenceDecodeError"+ ? cause+ : toPersistenceSqlError("BotUsageLedger.settleForTurn")(cause),+ ),+ ),+ );++ const finalizeForTurn: BotUsageLedgerShape["finalizeForTurn"] = (input) =>+ writeLock.withPermit(+ sql+ .withTransaction(+ Effect.gen(function* () {+ const rows = yield* selectEntryForTurn(sql, input.botId, input.threadId, input.turnId);+ const current = rows[0];+ if (!current) return [];+ if (current.state === "reserved") {+ return [+ yield* settleCurrent(current, {+ state: "unavailable",+ reason: "Provider completed without token usage.",+ settledAt: input.settledAt,+ }),+ ];+ }+ if (current.state !== "reported") return [yield* decodeEntry(current)];+ const held = current.heldTokens;+ if (held > 0) {+ yield* sql`+ UPDATE akeru_bot_usage_balances+ SET reserved_tokens = reserved_tokens - ${held}, updated_at = ${input.settledAt}+ WHERE bot_id = ${current.botId}+ `;+ }+ yield* sql`+ UPDATE akeru_bot_usage_entries+ SET held_tokens = 0, settled_at = ${input.settledAt}+ WHERE reservation_id = ${current.reservationId}+ `;+ const finalized = yield* selectEntryByReservation(sql, current.reservationId);+ return [yield* decodeEntry(finalized[0]!)];+ }),+ )+ .pipe(+ Effect.mapError((cause) =>+ cause._tag === "PersistenceSqlError" || cause._tag === "PersistenceDecodeError"+ ? cause+ : toPersistenceSqlError("BotUsageLedger.finalizeForTurn")(cause),+ ),+ ),+ );++ const recordMeasurement: BotUsageLedgerShape["recordMeasurement"] = (input) =>+ writeLock.withPermit(+ sql+ .withTransaction(+ Effect.gen(function* () {+ yield* validateTokens("BotUsageLedger.recordMeasurement", [+ input.inputTokens,+ input.outputTokens,+ ...(input.reasoningTokens === null ? [] : [input.reasoningTokens]),+ ]);+ const prior = yield* selectEntryBySource(sql, input.botId, input.sourceKey);+ if (prior[0]) return yield* decodeEntry(prior[0]);+ const measuredTokens = input.inputTokens + input.outputTokens;+ if (!input.includedInReservation) {+ yield* sql`+ INSERT INTO akeru_bot_usage_balances (+ bot_id, consumed_tokens, reserved_tokens, updated_at+ ) VALUES (${input.botId}, ${measuredTokens}, 0, ${input.createdAt})+ ON CONFLICT (bot_id) DO UPDATE SET+ consumed_tokens = consumed_tokens + ${measuredTokens},+ updated_at = ${input.createdAt}+ `;+ }+ yield* sql`+ INSERT INTO akeru_bot_usage_entries (+ reservation_id, source_key, bot_id, thread_id, turn_id, category, state,+ reserved_tokens, held_tokens, input_tokens, output_tokens, reasoning_tokens, provider,+ model, unavailable_reason, created_at, settled_at+ ) VALUES (+ ${input.reservationId}, ${input.sourceKey}, ${input.botId}, ${input.threadId},+ ${input.turnId}, ${input.category}, 'reported', 0, 0, ${input.inputTokens},+ ${input.outputTokens}, ${input.reasoningTokens}, ${input.provider}, ${input.model},+ NULL, ${input.createdAt}, ${input.createdAt}+ )+ `;+ const rows = yield* selectEntryByReservation(sql, input.reservationId);+ return yield* decodeEntry(rows[0]!);+ }),+ )+ .pipe(+ Effect.mapError((cause) =>+ cause._tag === "PersistenceSqlError" || cause._tag === "PersistenceDecodeError"+ ? cause+ : toPersistenceSqlError("BotUsageLedger.recordMeasurement")(cause),+ ),+ ),+ );++ const summarize: BotUsageLedgerShape["summarize"] = (botId) =>+ Effect.gen(function* () {+ const balances = yield* sql<{+ readonly consumedTokens: number;+ readonly reservedTokens: number;+ }>`+ SELECT consumed_tokens AS "consumedTokens", reserved_tokens AS "reservedTokens"+ FROM akeru_bot_usage_balances WHERE bot_id = ${botId}+ `;+ const rows = yield* sql<UsageRow>`+ SELECT ${entryColumns(sql)}+ FROM akeru_bot_usage_entries WHERE bot_id = ${botId}+ ORDER BY created_at DESC LIMIT 200+ `;+ const measurements = yield* sql<{+ readonly inputTokens: number;+ readonly outputTokens: number;+ readonly observerTokens: number;+ readonly reflectorTokens: number;+ readonly unavailableCoreEntries: number;+ readonly unavailableObserverEntries: number;+ readonly unavailableReflectorEntries: number;+ }>`+ SELECT+ COALESCE(SUM(CASE WHEN state = 'reported' AND category NOT IN ('observer', 'reflector')+ THEN input_tokens ELSE 0 END), 0) AS "inputTokens",+ COALESCE(SUM(CASE WHEN state = 'reported' AND category NOT IN ('observer', 'reflector')+ THEN output_tokens ELSE 0 END), 0) AS "outputTokens",+ MAX(0,+ COALESCE(SUM(CASE WHEN state = 'reported' AND category = 'observer'+ THEN input_tokens + output_tokens ELSE 0 END), 0)+ - COALESCE(SUM(CASE WHEN state = 'reported' AND category = 'reflector'+ THEN input_tokens + output_tokens ELSE 0 END), 0)+ ) AS "observerTokens",+ COALESCE(SUM(CASE WHEN state = 'reported' AND category = 'reflector'+ THEN input_tokens + output_tokens ELSE 0 END), 0) AS "reflectorTokens",+ COALESCE(SUM(CASE WHEN state = 'unavailable' AND category NOT IN ('observer', 'reflector')+ THEN 1 ELSE 0 END), 0) AS "unavailableCoreEntries",+ COALESCE(SUM(CASE WHEN state = 'unavailable' AND category = 'observer' THEN 1 ELSE 0 END), 0)+ AS "unavailableObserverEntries",+ COALESCE(SUM(CASE WHEN state = 'unavailable' AND category = 'reflector' THEN 1 ELSE 0 END), 0)+ AS "unavailableReflectorEntries"+ FROM akeru_bot_usage_entries WHERE bot_id = ${botId}+ `;+ const entries = yield* Effect.forEach(rows, decodeEntry);+ const totals = measurements[0]!;+ return yield* Schema.decodeUnknownEffect(AkeruBotUsageSummary)({+ botId,+ consumedTokens: balances[0]?.consumedTokens ?? 0,+ reservedTokens: balances[0]?.reservedTokens ?? 0,+ measurements: {+ input: { tokens: totals.inputTokens, unavailableEntries: totals.unavailableCoreEntries },+ output: {+ tokens: totals.outputTokens,+ unavailableEntries: totals.unavailableCoreEntries,+ },+ observer: {+ tokens: totals.observerTokens,+ unavailableEntries: totals.unavailableObserverEntries,+ },+ reflector: {+ tokens: totals.reflectorTokens,+ unavailableEntries: totals.unavailableReflectorEntries,+ },+ },+ entries,+ }).pipe(Effect.mapError(toPersistenceDecodeError("BotUsageLedger.summarize")));+ }).pipe(+ Effect.mapError((cause) =>+ cause._tag === "PersistenceDecodeError"+ ? cause+ : toPersistenceSqlError("BotUsageLedger.summarize")(cause),+ ),+ );++ const reconcileInterruptedReservations = writeLock.withPermit(+ sql+ .withTransaction(+ Effect.gen(function* () {+ const reconciledAt = DateTime.formatIso(yield* DateTime.now);+ const rows = yield* sql<UsageRow>`+ SELECT ${entryColumns(sql)}+ FROM akeru_bot_usage_entries+ WHERE held_tokens > 0+ `;+ for (const row of rows) {+ if (row.state === "reported") {+ yield* sql`+ UPDATE akeru_bot_usage_balances+ SET reserved_tokens = reserved_tokens - ${row.heldTokens}, updated_at = ${reconciledAt}+ WHERE bot_id = ${row.botId}+ `;+ yield* sql`+ UPDATE akeru_bot_usage_entries+ SET held_tokens = 0, settled_at = ${reconciledAt}+ WHERE reservation_id = ${row.reservationId}+ `;+ continue;+ }+ yield* settleCurrent(+ row,+ row.turnId === null+ ? { state: "released", settledAt: reconciledAt }+ : {+ state: "unavailable",+ reason: "Provider work was interrupted by a server restart.",+ settledAt: reconciledAt,+ },+ );+ }+ }),+ )+ .pipe(+ Effect.mapError(toPersistenceSqlError("BotUsageLedger.reconcileInterruptedReservations")),+ ),+ );++ yield* reconcileInterruptedReservations;++ return {+ reserve,+ settle,+ bindTurn,+ settleForTurn,+ finalizeForTurn,+ recordMeasurement,+ summarize,+ } satisfies BotUsageLedgerShape;+});++export const BotUsageLedgerLive = Layer.effect(BotUsageLedger, make);