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.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 this
diff --git a/apps/server/src/orchestration/runtimeLayer.ts b/apps/server/src/orchestration/runtimeLayer.ts
index 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/Layers
import { 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 runtime
diff --git a/apps/server/src/persistence/Migrations.ts b/apps/server/src/persistence/Migrations.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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);