diff --git a/apps/server/src/orchestration-v2/ProviderTurnStartService.test.ts b/apps/server/src/orchestration-v2/ProviderTurnStartService.test.ts index 7b0759ae99b0b..8e8c1123cab94 100644 --- a/apps/server/src/orchestration-v2/ProviderTurnStartService.test.ts +++ b/apps/server/src/orchestration-v2/ProviderTurnStartService.test.ts @@ -96,7 +96,7 @@ const layerWorktreeLocation = (worktreesDir = managedWorktreesDir) => Layer.mergeAll( Path.layer, Layer.mock(ServerConfig.ServerConfig)({ worktreesDir } as ServerConfig.ServerConfig["Service"]), - ServerSettings.layerTest(), + ServerSettings.layerTest({ sessionSpendGuard: { mode: "off" } }), ); function startWithMissingWorktree( @@ -293,6 +293,187 @@ it.each([ expect(harness.createWorktree).toHaveBeenCalledTimes(input.recreated ? 1 : 0); }); +function startWithSpendGuard(input: { + readonly title: string; + readonly creationSource: "web" | "mcp"; + readonly pullRequestLinkedAt?: string; + readonly providerTurns: ReadonlyArray<{ + readonly startedAt: string; + readonly inputTokens: number; + }>; +}) { + const threadId = ThreadId.make("thread_provider_turn_start_spend_guard"); + const runId = RunId.make("run_provider_turn_start_spend_guard"); + const attemptId = RunAttemptId.make("attempt_provider_turn_start_spend_guard"); + const rootNodeId = NodeId.make("node_provider_turn_start_spend_guard"); + const providerThreadId = ProviderThreadId.make("provider_thread_provider_turn_start_spend_guard"); + const messageId = MessageId.make("message_provider_turn_start_spend_guard"); + const projection = { + thread: { + id: threadId, + projectId: ProjectId.make("project_provider_turn_start_spend_guard"), + title: input.title, + modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5-codex" }, + worktreePath: "/tmp/provider-turn-start-spend-guard", + pullRequests: + input.pullRequestLinkedAt === undefined + ? [] + : [{ number: 1, source: "created", linkedAt: input.pullRequestLinkedAt }], + lineage: { parentThreadId: null, relationshipToParent: null, rootThreadId: threadId }, + }, + runs: [ + { id: RunId.make("run_provider_turn_start_spend_guard_first"), ordinal: 1 }, + { + id: runId, + status: "starting", + rootNodeId, + activeAttemptId: attemptId, + providerThreadId, + userMessageId: messageId, + ordinal: 2, + }, + ], + nodes: [{ id: rootNodeId, checkpointScopeId: CheckpointScopeId.make("scope_spend_guard") }], + attempts: [{ id: attemptId }], + providerThreads: [{ id: providerThreadId, providerSessionId: ProviderSessionId.make("s") }], + providerTurns: input.providerTurns.map((turn) => ({ + startedAt: DateTime.makeUnsafe(turn.startedAt), + completedAt: null, + tokenUsage: { usedTokens: 0, inputTokens: turn.inputTokens, updatedAt: turn.startedAt }, + })), + messages: [ + { + id: messageId, + role: "user", + text: "Status?", + attachments: [], + creationSource: input.creationSource, + }, + ], + checkpointScopes: [{ id: CheckpointScopeId.make("scope_spend_guard") }], + checkpoints: [], + contextHandoffs: [], + contextTransfers: [], + turnItems: [], + } as unknown as OrchestrationV2ThreadProjection; + const writeIfRunCurrent = vi.fn(() => + Effect.succeed({ committed: true, storedEvents: [] }), + ); + const startRootRun = vi.fn(() => Effect.void); + const layer = ProviderTurnStart.layer.pipe( + Layer.provide( + Layer.mergeAll( + Layer.mock(ContextHandoffService.ContextHandoffServiceV2)({}), + Layer.mock(EventSink.EventSinkV2)({ writeIfRunCurrent }), + IdAllocator.layer, + Layer.mock(TurnItemPositionStore.TurnItemPositionStoreV2)({}), + Layer.succeed(FileSystem.FileSystem, { + realPath: (target: string) => Effect.succeed(target), + } as never), + Path.layer, + Layer.mock(ServerConfig.ServerConfig)({ + worktreesDir: managedWorktreesDir, + } as ServerConfig.ServerConfig["Service"]), + ServerSettings.layerTest({ + sessionSpendGuard: { mode: "enforce", sessionCeilingUsd: 1, idleStopUsd: 50 }, + usagePriceOverrides: { + "gpt-5-codex": { inputCostPerMillionTokens: 1_000_000, outputCostPerMillionTokens: 0 }, + }, + }), + Layer.mock(GitWorkflow.GitWorkflowService)({}), + Layer.mock(ProjectService.ProjectService)({}), + Layer.mock(ProjectionStore.ProjectionStoreV2)({ + getThreadRecords: () => Effect.succeed(projection), + getTurnStartContext: () => Effect.succeed({ ...projection, hasConversation: true }), + }), + Layer.mock(ProviderSessionManager.ProviderSessionManagerV2)({}), + Layer.mock(ProviderAuthService.ProviderAuthService)({}), + Layer.mock(RunExecutionService.RunExecutionServiceV2)({ startRootRun }), + Layer.mock(RuntimePolicy.RuntimePolicyV2)({}), + ), + ), + ); + const refusal = () => { + const item = writeIfRunCurrent.mock.calls[0]?.[0].events.find( + (event) => event.type === "turn-item.updated", + )?.payload; + return item?.type === "error" ? item : undefined; + }; + return { + start: Effect.gen(function* () { + yield* (yield* ProviderTurnStart.ProviderTurnStartServiceV2).start({ threadId, runId }); + }).pipe(Effect.provide(layer)), + refusal, + startRootRun, + }; +} + +effectIt.effect("refuses an automated follow-up on a thread that still has the default title", () => + Effect.gen(function* () { + const harness = startWithSpendGuard({ + title: "New thread", + creationSource: "mcp", + providerTurns: [], + }); + yield* harness.start; + expect(harness.refusal()).toMatchObject({ + title: "Turn refused by the session spend guard", + failure: { message: expect.stringContaining("default title") }, + }); + expect(harness.startRootRun).not.toHaveBeenCalled(); + }), +); + +effectIt.effect( + "refuses the next automated turn at the session ceiling even after a linked pull request", + () => + Effect.gen(function* () { + const harness = startWithSpendGuard({ + title: "Manager work", + creationSource: "mcp", + pullRequestLinkedAt: "2099-01-01T00:00:00.000Z", + providerTurns: [ + { startedAt: "2099-01-01T00:00:01.000Z", inputTokens: 1 }, + { startedAt: "2099-01-01T00:00:02.000Z", inputTokens: 1 }, + ], + }); + yield* harness.start; + const refusal = harness.refusal(); + expect(refusal?.title).toBe("Turn refused by the session spend guard"); + expect(refusal?.failure.message).toContain("session ceiling"); + expect(refusal?.failure.message).not.toContain("idle limit"); + expect(harness.startRootRun).not.toHaveBeenCalled(); + }), +); + +effectIt.effect("lets a founder's own turn through at the session ceiling", () => + Effect.gen(function* () { + const harness = startWithSpendGuard({ + title: "Manager work", + creationSource: "web", + providerTurns: [{ startedAt: "2099-01-01T00:00:01.000Z", inputTokens: 1 }], + }); + yield* Effect.exit(harness.start); + expect(harness.refusal()?.title).not.toBe("Turn refused by the session spend guard"); + }), +); + +effectIt.effect("counts every provider turn in the thread toward the session ceiling", () => + Effect.gen(function* () { + const harness = startWithSpendGuard({ + title: "Manager work", + creationSource: "mcp", + providerTurns: Array.from({ length: 501 }, (_, index) => ({ + startedAt: "2099-01-01T00:00:00.000Z", + inputTokens: index === 0 ? 1 : 0, + })), + }); + yield* harness.start; + expect(harness.refusal()?.failure.message).toContain("session ceiling"); + expect(harness.startRootRun).not.toHaveBeenCalled(); + }), +); + const restoreLeaseExists = vi.fn(() => Effect.succeed(false)); const restoreLeaseCreateWorktree = vi.fn(() => Effect.succeed({} as never)); const layerRestoreLeaseTest = layerThreadWorktreeRestore.pipe( diff --git a/apps/server/src/orchestration-v2/ProviderTurnStartService.ts b/apps/server/src/orchestration-v2/ProviderTurnStartService.ts index 5996a090bf4bd..aff5a8869220a 100644 --- a/apps/server/src/orchestration-v2/ProviderTurnStartService.ts +++ b/apps/server/src/orchestration-v2/ProviderTurnStartService.ts @@ -66,6 +66,14 @@ import { } from "@t3tools/provider-core/server/failure"; import * as RunExecutionService from "./RunExecutionService.ts"; import * as RuntimePolicy from "./RuntimePolicy.ts"; +import { + checkLaunch, + refusesAutomatedTurn, + describeSpendStop, + evaluateThreadSpend, + SPEND_GUARD_REFUSAL_TITLE, + UNTITLED_LAUNCH_REFUSAL, +} from "./SessionSpendGuard.ts"; import * as TurnItemPositionStore from "./TurnItemPositionStore.ts"; import { isRestartNoteContinuation, @@ -197,6 +205,7 @@ export const layer: Layer.Layer< const providerSessions = yield* ProviderSessionManager.ProviderSessionManagerV2; const runExecution = yield* RunExecutionService.RunExecutionServiceV2; const runtimePolicy = yield* RuntimePolicy.RuntimePolicyV2; + const serverSettings = yield* ServerSettings.ServerSettingsService; const restoreMissingWorktree = yield* makeRestoreMissingWorktree; const turnItemPositions = yield* TurnItemPositionStore.TurnItemPositionStoreV2; @@ -552,6 +561,47 @@ export const layer: Layer.Layer< }); }, ); + const guardSettings = yield* serverSettings.getSettings; + const launchRefusal = checkLaunch({ + title: projection.thread.title, + titlePending: projection.thread.titleRegeneration != null, + hasOtherUserMessages: projection.runs.some((candidate) => candidate.ordinal < run.ordinal), + creationSource: message.creationSource, + mode: guardSettings.sessionSpendGuard.mode, + }); + if (launchRefusal !== null) { + yield* settleStartFailure({ + signal: "spend-guard-refused", + title: SPEND_GUARD_REFUSAL_TITLE, + error: new Error(UNTITLED_LAUNCH_REFUSAL), + message: UNTITLED_LAUNCH_REFUSAL, + }); + return; + } + if (refusesAutomatedTurn(guardSettings.sessionSpendGuard.mode, message.creationSource)) { + const { checkpoints } = yield* projectionStore.getThreadRecords(input.threadId, [ + "checkpoints", + ]); + const spend = evaluateThreadSpend( + { + thread: projection.thread, + providerTurns: projection.providerTurns, + checkpoints, + turnItems: [], + }, + guardSettings, + ); + if (spend.level === "stop") { + const detail = describeSpendStop(spend, guardSettings.sessionSpendGuard); + yield* settleStartFailure({ + signal: "spend-guard-refused", + title: SPEND_GUARD_REFUSAL_TITLE, + error: new Error(detail), + message: detail, + }); + return; + } + } if ( providerMessage.attachments.length === 0 && providerMessage.text.trimStart().startsWith("/") diff --git a/apps/server/src/orchestration-v2/SessionSpendGuard.test.ts b/apps/server/src/orchestration-v2/SessionSpendGuard.test.ts new file mode 100644 index 0000000000000..eae258d366f13 --- /dev/null +++ b/apps/server/src/orchestration-v2/SessionSpendGuard.test.ts @@ -0,0 +1,325 @@ +import { describe, expect, it } from "vite-plus/test"; +import { ProviderInstanceId, ServerSettings } from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; +import * as Schema from "effect/Schema"; + +import { + checkLaunch, + describeSpendStop, + evaluateSpendGuard, + evaluateThreadSpend, + priceProviderTurns, + rateForModel, + spendGuardMarkers, + spendGuardNoticeId, + UNTITLED_LAUNCH_REFUSAL, + workSignalAts, + type SpendEntry, + type SpendGuardInput, + type SpendGuardMarker, +} from "./SessionSpendGuard.ts"; +import { spendGuardNotice, wakeSettledThread } from "./SessionSpendGuardReactor.ts"; + +const decodeSettings = Schema.decodeUnknownSync(ServerSettings); + +const rate = { + inputCostPerToken: 1, + outputCostPerToken: 2, + cacheReadCostPerToken: 0.1, +}; + +const settings = { + ...decodeSettings({}).sessionSpendGuard, + idleFlagUsd: 3, + idleStopUsd: 5, + sessionCeilingUsd: 10, +}; + +const at = (iso: string) => DateTime.makeUnsafe(iso); + +const priced = (createdAt: string, usd: number): SpendEntry => ({ createdAt, usd }); + +const marker = ( + kind: SpendGuardMarker["kind"], + createdAt: string, + reason: SpendGuardMarker["reason"] = "idle", +): SpendGuardMarker => ({ kind, reason, createdAt }); + +const evaluate = (overrides: Partial = {}) => + evaluateSpendGuard({ + spend: [], + markers: [], + workSignalAts: [], + settings, + ...overrides, + }); + +describe("priceProviderTurns", () => { + it("prices uncached input, cache read, output, and other usage", () => { + expect( + priceProviderTurns( + [ + { + startedAt: at("2026-01-01T00:00:00.000Z"), + completedAt: at("2026-01-01T00:05:00.000Z"), + turnTokenUsage: { + usageScope: "main_agent", + usageStatus: "complete", + hasSubagents: true, + inputTokens: 10, + cachedInputTokens: 4, + outputTokens: 2, + otherUsage: { inputTokens: 1, outputTokens: 1 }, + }, + }, + ], + rate, + ), + ).toEqual([{ createdAt: "2026-01-01T00:00:00.000Z", usd: 13.4 }]); + }); + + it("falls back to the context snapshot and skips a turn with no counts", () => { + expect( + priceProviderTurns( + [ + { + startedAt: at("2026-01-01T00:01:00.000Z"), + completedAt: null, + tokenUsage: { + usedTokens: 9, + inputTokens: 5, + updatedAt: "2026-01-01T00:01:30.000Z", + }, + }, + { + startedAt: at("2026-01-01T00:02:00.000Z"), + completedAt: null, + turnTokenUsage: { + usageScope: "main_agent", + usageStatus: "unavailable", + hasSubagents: false, + }, + }, + ], + rate, + ), + ).toEqual([{ createdAt: "2026-01-01T00:01:00.000Z", usd: 5 }]); + }); +}); + +describe("spendGuardMarkers", () => { + it("reads only spend guard notices", () => { + expect( + spendGuardMarkers([ + { + id: spendGuardNoticeId("thread-1", "stopped", "ceiling", "a") as never, + type: "system_notice", + startedAt: at("2026-01-01T00:01:00.000Z"), + }, + { + id: "server-recovery:thread-1" as never, + type: "system_notice", + startedAt: at("2026-01-01T00:02:00.000Z"), + }, + ]), + ).toEqual([marker("stopped", "2026-01-01T00:01:00.000Z", "ceiling")]); + }); +}); + +describe("evaluateSpendGuard", () => { + it("counts idle spend only after the latest pull request or file-changing checkpoint", () => { + const signals = workSignalAts({ + thread: { + pullRequests: [ + { linkedAt: "2026-01-01T00:02:00.000Z", source: "manual" }, + { linkedAt: "2026-01-01T00:09:00.000Z", source: "stack-dismissed" }, + ] as never, + }, + checkpoints: [ + { capturedAt: at("2026-01-01T00:03:00.000Z"), files: [{}] as never }, + { capturedAt: at("2026-01-01T00:08:00.000Z"), files: [] }, + ], + }); + const result = evaluate({ + workSignalAts: signals, + spend: [ + priced("2026-01-01T00:01:00.000Z", 2), + priced("2026-01-01T00:02:30.000Z", 1), + priced("2026-01-01T00:04:00.000Z", 6), + ], + }); + expect(result.idleSince).toBe("2026-01-01T00:03:00.000Z"); + expect(result.sessionUsd).toBe(9); + expect(result.idleUsd).toBe(6); + expect(result.level).toBe("stop"); + expect(result.stopReason).toBe("idle"); + }); + + it("flags idle spend without stopping when mode is flag", () => { + const result = evaluate({ + settings: { ...settings, mode: "flag" }, + spend: [priced("2026-01-01T00:01:00.000Z", 6)], + }); + expect(result).toMatchObject({ level: "flag", stopReason: "idle", idleUsd: 6 }); + }); + + it("stops for the session ceiling ahead of the idle limit", () => { + const result = evaluate({ + spend: [priced("2026-01-01T00:01:00.000Z", 10)], + }); + expect(result).toMatchObject({ level: "stop", stopReason: "ceiling", sessionUsd: 10 }); + }); + + it("stops at the session ceiling when a recent pull request keeps idle spend under the idle limit", () => { + const result = evaluate({ + workSignalAts: ["2026-01-01T00:02:00.000Z"], + spend: [priced("2026-01-01T00:01:00.000Z", 6), priced("2026-01-01T00:03:00.000Z", 4)], + }); + expect(result.idleUsd).toBe(4); + expect(result.sessionUsd).toBe(10); + expect(result.level).toBe("stop"); + expect(result.stopReason).toBe("ceiling"); + }); + + it("does not stop or flag when the guard is off", () => { + const result = evaluate({ + settings: { ...settings, mode: "off" }, + spend: [priced("2026-01-01T00:01:00.000Z", 20)], + }); + expect(result).toMatchObject({ level: "ok", stopReason: null }); + }); + + it("remembers a flag or stop only until the next idle boundary", () => { + const idle = evaluate({ + workSignalAts: ["2026-01-01T00:02:00.000Z"], + markers: [ + marker("flagged", "2026-01-01T00:01:00.000Z"), + marker("stopped", "2026-01-01T00:01:30.000Z", "idle"), + marker("stopped", "2026-01-01T00:03:00.000Z", "ceiling"), + marker("flagged", "2026-01-01T00:04:00.000Z"), + ], + }); + expect(idle.flaggedSinceIdle).toBe(true); + expect(idle.stoppedSinceIdle).toBe(false); + expect(idle.stoppedForCeiling).toBe(true); + expect(idle.flaggedForCeiling).toBe(false); + }); + + it("keeps a ceiling flag visible when an earlier idle flag is already recorded", () => { + const flagged = evaluate({ + settings: { ...settings, mode: "flag" }, + workSignalAts: ["2026-01-01T00:02:00.000Z"], + markers: [marker("flagged", "2026-01-01T00:03:00.000Z", "idle")], + spend: [priced("2026-01-01T00:01:00.000Z", 6), priced("2026-01-01T00:04:00.000Z", 4)], + }); + expect(flagged).toMatchObject({ + level: "flag", + stopReason: "ceiling", + flaggedSinceIdle: true, + flaggedForCeiling: false, + idleUsd: 4, + sessionUsd: 10, + }); + expect(spendGuardNotice(flagged, settings)).toMatchObject({ + kind: "flagged", + reason: "ceiling", + }); + const recorded = evaluate({ + settings: { ...settings, mode: "flag" }, + spend: [priced("2026-01-01T00:01:00.000Z", 10)], + markers: [marker("flagged", "2026-01-01T00:02:00.000Z", "ceiling")], + }); + expect(recorded.flaggedForCeiling).toBe(true); + expect(recorded.stopReason).toBe("ceiling"); + expect(spendGuardNotice(recorded, settings)).toBeNull(); + }); +}); + +describe("spendGuardNotice", () => { + it("records each flag or stop once per window", () => { + const stop = evaluate({ spend: [priced("2026-01-01T00:01:00.000Z", 6)] }); + expect(spendGuardNotice(stop, settings)).toMatchObject({ kind: "stopped", reason: "idle" }); + const recorded = evaluate({ + spend: [priced("2026-01-01T00:01:00.000Z", 6)], + markers: [marker("stopped", "2026-01-01T00:02:00.000Z", "idle")], + }); + expect(spendGuardNotice(recorded, settings)).toBeNull(); + const flag = evaluate({ spend: [priced("2026-01-01T00:01:00.000Z", 4)] }); + expect(spendGuardNotice(flag, settings)).toMatchObject({ kind: "flagged", reason: "idle" }); + }); + + it("wakes a settled thread and leaves an active one alone", () => { + const now = at("2026-01-01T00:05:00.000Z"); + const settled = { settledOverride: "settled", settledAt: now } as never; + expect(wakeSettledThread(settled, now)).toMatchObject({ + settledOverride: null, + settledAt: null, + unsettledAt: now, + }); + expect(wakeSettledThread({ settledOverride: null } as never, now)).toBeNull(); + }); +}); + +describe("launch and stop copy", () => { + const base = { + title: "New thread", + titlePending: false, + hasOtherUserMessages: true, + creationSource: "mcp" as const, + mode: "enforce" as const, + }; + + it("refuses an untitled automated follow-up", () => { + expect(checkLaunch(base)).toBe("untitled"); + expect(checkLaunch({ ...base, creationSource: "server" })).toBe("untitled"); + expect(checkLaunch({ ...base, title: "Named thread" })).toBeNull(); + expect(checkLaunch({ ...base, titlePending: true })).toBeNull(); + expect(checkLaunch({ ...base, hasOtherUserMessages: false })).toBeNull(); + expect(checkLaunch({ ...base, creationSource: "web" })).toBeNull(); + expect(checkLaunch({ ...base, mode: "flag" })).toBeNull(); + }); + + it("describes how to continue", () => { + const evaluation = evaluate({ spend: [priced("2026-01-01T00:01:00.000Z", 6)] }); + expect(describeSpendStop(evaluation, settings)).toContain("$6.00"); + expect(describeSpendStop(evaluation, settings)).toContain("$5.00"); + expect(UNTITLED_LAUNCH_REFUSAL).toContain("default title"); + }); +}); + +describe("evaluateThreadSpend", () => { + it("uses the model override and otherwise the fallback rate", () => { + const decoded = decodeSettings({ + sessionSpendGuard: { idleStopUsd: 1, sessionCeilingUsd: 100 }, + usagePriceOverrides: { + "custom-model": { + inputCostPerMillionTokens: 1_000_000, + outputCostPerMillionTokens: 0, + }, + }, + }); + const evaluation = evaluateThreadSpend( + { + thread: { + pullRequests: [], + modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "custom-model" }, + }, + providerTurns: [ + { + startedAt: at("2026-01-01T00:01:00.000Z"), + completedAt: null, + tokenUsage: { usedTokens: 2, inputTokens: 2, updatedAt: "2026-01-01T00:01:00.000Z" }, + }, + ], + checkpoints: [], + turnItems: [], + }, + decoded, + ); + expect(evaluation.sessionUsd).toBe(2); + expect( + rateForModel("missing", decoded.usagePriceOverrides, decoded.sessionSpendGuard.fallbackRate) + .inputCostPerToken, + ).toBe(10 / 1_000_000); + }); +}); diff --git a/apps/server/src/orchestration-v2/SessionSpendGuard.ts b/apps/server/src/orchestration-v2/SessionSpendGuard.ts new file mode 100644 index 0000000000000..f3772ce2c48ab --- /dev/null +++ b/apps/server/src/orchestration-v2/SessionSpendGuard.ts @@ -0,0 +1,251 @@ +import type { + OrchestrationV2AppThread, + OrchestrationV2Checkpoint, + OrchestrationV2ConversationMessage, + OrchestrationV2ProviderTurn, + OrchestrationV2TurnItem, + ServerSettings, + SessionSpendGuardSettings, + UsageModelPriceOverride, +} from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; + +import { createOverrideRateTable, lookupRate, type ModelRate } from "../usage/usagePricing.ts"; + +export const SPEND_GUARD_FLAGGED_KIND = "flagged"; +export const SPEND_GUARD_STOPPED_KIND = "stopped"; +const SPEND_GUARD_NOTICE_PREFIX = "spend-guard"; +export const SPEND_GUARD_REFUSAL_TITLE = "Turn refused by the session spend guard"; + +export type SpendGuardLevel = "ok" | "flag" | "stop"; +export type SpendGuardStopReason = "idle" | "ceiling"; +export type SpendGuardMarkerKind = + | typeof SPEND_GUARD_FLAGGED_KIND + | typeof SPEND_GUARD_STOPPED_KIND; + +export type SpendRate = Pick< + ModelRate, + "inputCostPerToken" | "outputCostPerToken" | "cacheReadCostPerToken" +>; + +export interface SpendEntry { + readonly createdAt: string; + readonly usd: number; +} + +export interface SpendGuardMarker { + readonly kind: SpendGuardMarkerKind; + readonly reason: SpendGuardStopReason; + readonly createdAt: string; +} + +export interface SpendGuardEvaluation { + readonly level: SpendGuardLevel; + readonly stopReason: SpendGuardStopReason | null; + readonly sessionUsd: number; + readonly idleUsd: number; + readonly idleSince: string | null; + readonly flaggedSinceIdle: boolean; + readonly flaggedForCeiling: boolean; + readonly stoppedSinceIdle: boolean; + readonly stoppedForCeiling: boolean; +} + +export interface SpendGuardInput { + readonly spend: ReadonlyArray; + readonly markers: ReadonlyArray; + readonly workSignalAts: ReadonlyArray; + readonly settings: SessionSpendGuardSettings; +} + +export function rateForModel( + model: string, + overrides: Readonly>, + fallback: UsageModelPriceOverride, +): ModelRate { + return ( + lookupRate(createOverrideRateTable(overrides), model) ?? + createOverrideRateTable({ fallback }).get("fallback")! + ); +} + +export function workSignalAts(input: { + readonly thread: Pick; + readonly checkpoints: ReadonlyArray>; +}): ReadonlyArray { + return [ + ...(input.thread.pullRequests ?? []) + .filter((link) => link.source !== "stack-dismissed") + .map((link) => link.linkedAt), + ...input.checkpoints + .filter((checkpoint) => checkpoint.files.length > 0) + .map((checkpoint) => DateTime.formatIso(checkpoint.capturedAt)), + ]; +} + +export function priceProviderTurns( + turns: ReadonlyArray< + Pick + >, + rate: SpendRate, +): ReadonlyArray { + const priced: Array = []; + for (const turn of turns) { + const usage = turn.turnTokenUsage ?? turn.tokenUsage; + if (usage === undefined) continue; + if (usage.inputTokens === undefined && usage.outputTokens === undefined) continue; + const input = usage.inputTokens ?? 0; + const cached = Math.min(usage.cachedInputTokens ?? 0, input); + const other = turn.turnTokenUsage?.otherUsage; + const usd = + (input - cached) * rate.inputCostPerToken + + cached * rate.cacheReadCostPerToken + + (usage.outputTokens ?? 0) * rate.outputCostPerToken + + (other?.inputTokens ?? 0) * rate.inputCostPerToken + + (other?.outputTokens ?? 0) * rate.outputCostPerToken; + const at = turn.startedAt ?? turn.completedAt; + const createdAt = at === null ? (turn.tokenUsage?.updatedAt ?? null) : DateTime.formatIso(at); + if (usd > 0 && createdAt !== null) priced.push({ createdAt, usd }); + } + return priced; +} + +export function spendGuardNoticeId( + threadId: string, + kind: SpendGuardMarkerKind, + reason: SpendGuardStopReason, + unique: string, +): string { + return `${SPEND_GUARD_NOTICE_PREFIX}:${kind}:${reason}:${threadId}:${unique}`; +} + +export function spendGuardMarkers( + turnItems: ReadonlyArray>, +): ReadonlyArray { + return turnItems.flatMap((item) => { + if (item.type !== "system_notice" || item.startedAt === null) return []; + const [prefix, kind, reason] = item.id.split(":"); + if (prefix !== SPEND_GUARD_NOTICE_PREFIX) return []; + if (kind !== SPEND_GUARD_FLAGGED_KIND && kind !== SPEND_GUARD_STOPPED_KIND) return []; + if (reason !== "idle" && reason !== "ceiling") return []; + return [{ kind, reason, createdAt: DateTime.formatIso(item.startedAt) }]; + }); +} + +function latest(values: ReadonlyArray): string | null { + return values.reduce( + (current, value) => (current === null || value > current ? value : current), + null, + ); +} + +export function evaluateSpendGuard(input: SpendGuardInput): SpendGuardEvaluation { + const idleSince = latest(input.workSignalAts); + const afterIdle = (createdAt: string) => idleSince === null || createdAt > idleSince; + const sessionUsd = input.spend.reduce((sum, entry) => sum + entry.usd, 0); + const idleUsd = input.spend + .filter((entry) => afterIdle(entry.createdAt)) + .reduce((sum, entry) => sum + entry.usd, 0); + const flaggedSinceIdle = input.markers.some( + (marker) => marker.kind === SPEND_GUARD_FLAGGED_KIND && afterIdle(marker.createdAt), + ); + const flaggedForCeiling = input.markers.some( + (marker) => marker.kind === SPEND_GUARD_FLAGGED_KIND && marker.reason === "ceiling", + ); + const stoppedSinceIdle = input.markers.some( + (marker) => + marker.kind === SPEND_GUARD_STOPPED_KIND && + marker.reason === "idle" && + afterIdle(marker.createdAt), + ); + const stoppedForCeiling = input.markers.some( + (marker) => marker.kind === SPEND_GUARD_STOPPED_KIND && marker.reason === "ceiling", + ); + const { mode, idleFlagUsd, idleStopUsd, sessionCeilingUsd } = input.settings; + const base = { + sessionUsd, + idleUsd, + idleSince, + flaggedSinceIdle, + flaggedForCeiling, + stoppedSinceIdle, + stoppedForCeiling, + }; + if (mode === "off") return { ...base, level: "ok", stopReason: null }; + const stopReason: SpendGuardStopReason | null = + sessionUsd >= sessionCeilingUsd ? "ceiling" : idleUsd >= idleStopUsd ? "idle" : null; + if (stopReason !== null && mode === "enforce") { + return { ...base, level: "stop", stopReason }; + } + if (stopReason !== null || idleUsd >= idleFlagUsd) { + return { ...base, level: "flag", stopReason }; + } + return { ...base, level: "ok", stopReason: null }; +} + +export function evaluateThreadSpend( + input: { + readonly thread: Pick; + readonly providerTurns: ReadonlyArray< + Pick< + OrchestrationV2ProviderTurn, + "startedAt" | "completedAt" | "tokenUsage" | "turnTokenUsage" + > + >; + readonly checkpoints: ReadonlyArray>; + readonly turnItems: ReadonlyArray>; + }, + settings: Pick, +): SpendGuardEvaluation { + return evaluateSpendGuard({ + spend: priceProviderTurns( + input.providerTurns, + rateForModel( + input.thread.modelSelection.model, + settings.usagePriceOverrides, + settings.sessionSpendGuard.fallbackRate, + ), + ), + markers: spendGuardMarkers(input.turnItems), + workSignalAts: workSignalAts(input), + settings: settings.sessionSpendGuard, + }); +} + +export function describeSpendStop( + evaluation: SpendGuardEvaluation, + settings: SessionSpendGuardSettings, +): string { + const usd = (value: number) => `$${value.toFixed(2)}`; + return evaluation.stopReason === "ceiling" + ? `This thread has spent about ${usd(evaluation.sessionUsd)}, past its ${usd(settings.sessionCeilingUsd)} session ceiling. Raise sessionSpendGuard.sessionCeilingUsd to continue.` + : `This thread has spent about ${usd(evaluation.idleUsd)} with no linked pull request or file-changing turn, past the ${usd(settings.idleStopUsd)} idle limit. Link a pull request or change files to continue.`; +} + +export interface LaunchCheckInput { + readonly title: string; + readonly titlePending: boolean; + readonly hasOtherUserMessages: boolean; + readonly creationSource: OrchestrationV2ConversationMessage["creationSource"]; + readonly mode: SessionSpendGuardSettings["mode"]; +} + +const INTERACTIVE_SOURCES: ReadonlySet = + new Set(["web", "mobile"]); + +export function refusesAutomatedTurn( + mode: SessionSpendGuardSettings["mode"], + creationSource: OrchestrationV2ConversationMessage["creationSource"], +) { + return mode === "enforce" && !INTERACTIVE_SOURCES.has(creationSource); +} + +export function checkLaunch(input: LaunchCheckInput): "untitled" | null { + if (!refusesAutomatedTurn(input.mode, input.creationSource)) return null; + const untitled = input.title.trim() === "" || input.title.trim() === "New thread"; + if (untitled && !input.titlePending && input.hasOtherUserMessages) return "untitled"; + return null; +} + +export const UNTITLED_LAUNCH_REFUSAL = + "Automated turns are refused on a thread that still has the default title after its first turn. Give the thread a title, then send again."; diff --git a/apps/server/src/orchestration-v2/SessionSpendGuardReactor.ts b/apps/server/src/orchestration-v2/SessionSpendGuardReactor.ts new file mode 100644 index 0000000000000..9cb354e644470 --- /dev/null +++ b/apps/server/src/orchestration-v2/SessionSpendGuardReactor.ts @@ -0,0 +1,208 @@ +import { + CommandId, + type OrchestrationV2AppThread, + type OrchestrationV2DomainEvent, + type OrchestrationV2Run, + type SessionSpendGuardSettings, + type ThreadId, + TurnItemId, +} from "@t3tools/contracts"; +import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator"; +import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker"; +import * as Cause from "effect/Cause"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as Stream from "effect/Stream"; + +import { forkParked } from "../serverActivation.ts"; +import * as ServerSettings from "../serverSettings.ts"; +import * as EventSink from "./EventSink.ts"; +import * as Orchestrator from "./Orchestrator.ts"; +import * as ProjectionStore from "./ProjectionStore.ts"; +import { + describeSpendStop, + evaluateThreadSpend, + SPEND_GUARD_FLAGGED_KIND, + SPEND_GUARD_STOPPED_KIND, + type SpendGuardEvaluation, + type SpendGuardMarkerKind, + type SpendGuardStopReason, + spendGuardNoticeId, +} from "./SessionSpendGuard.ts"; + +export interface SpendGuardNotice { + readonly kind: SpendGuardMarkerKind; + readonly reason: SpendGuardStopReason; + readonly title: string; + readonly message: string; +} + +export function spendGuardNotice( + evaluation: SpendGuardEvaluation, + settings: SessionSpendGuardSettings, +): SpendGuardNotice | null { + if (evaluation.level === "stop" && evaluation.stopReason !== null) { + const alreadyStopped = + evaluation.stopReason === "ceiling" + ? evaluation.stoppedForCeiling + : evaluation.stoppedSinceIdle; + if (alreadyStopped) return null; + return { + kind: SPEND_GUARD_STOPPED_KIND, + reason: evaluation.stopReason, + title: + evaluation.stopReason === "ceiling" + ? "Stopped: session spend ceiling reached" + : "Stopped: spending with no pull request or file changes", + message: describeSpendStop(evaluation, settings), + }; + } + if (evaluation.level === "flag" && evaluation.stopReason === "ceiling") { + if (evaluation.flaggedForCeiling) return null; + return { + kind: SPEND_GUARD_FLAGGED_KIND, + reason: "ceiling", + title: "Session spend ceiling reached", + message: describeSpendStop(evaluation, settings), + }; + } + if (evaluation.level === "flag" && !evaluation.flaggedSinceIdle) { + return { + kind: SPEND_GUARD_FLAGGED_KIND, + reason: "idle", + title: "Spending with no pull request or file changes", + message: `This thread has spent about $${evaluation.idleUsd.toFixed(2)} since its last linked pull request or file-changing turn. It stops at $${settings.idleStopUsd.toFixed(2)}.`, + }; + } + return null; +} + +export function wakeSettledThread( + thread: OrchestrationV2AppThread, + now: DateTime.Utc, +): OrchestrationV2AppThread | null { + return thread.settledOverride === "settled" + ? { ...thread, settledOverride: null, settledAt: null, unsettledAt: now, updatedAt: now } + : null; +} + +const isLive = (run: OrchestrationV2Run) => run.status === "starting" || run.status === "running"; + +export const make = Effect.gen(function* () { + const orchestrator = yield* Orchestrator.OrchestratorV2; + const eventSink = yield* EventSink.EventSinkV2; + const projections = yield* ProjectionStore.ProjectionStoreV2; + const settingsService = yield* ServerSettings.ServerSettingsService; + const ids = yield* IdAllocator.IdAllocatorV2; + const pending = new Set(); + + const check = Effect.fn("SessionSpendGuardReactor.check")(function* (threadId: ThreadId) { + pending.delete(threadId); + const settings = yield* settingsService.getSettings; + if (settings.sessionSpendGuard.mode === "off") return; + const records = yield* projections.getThreadRecords( + threadId, + ["runs", "providerTurns", "checkpoints", "turnItems"], + { turnItemTypes: ["system_notice"] }, + ); + const evaluation = evaluateThreadSpend(records, settings); + const notice = spendGuardNotice(evaluation, settings.sessionSpendGuard); + if (notice === null) return; + const run = records.runs.reduce( + (latest, candidate) => + latest === undefined || candidate.ordinal > latest.ordinal ? candidate : latest, + undefined, + ); + if (run === undefined) return; + const now = yield* DateTime.now; + const thread = wakeSettledThread(records.thread, now); + const noticeEventId = yield* ids.allocate.event({ threadId }); + yield* eventSink.write({ + events: [ + ...(thread === null + ? [] + : [ + { + id: yield* ids.allocate.event({ threadId }), + type: "thread.unsettled" as const, + threadId, + providerInstanceId: thread.providerInstanceId, + occurredAt: now, + payload: thread, + }, + ]), + { + id: noticeEventId, + type: "turn-item.updated", + threadId, + runId: run.id, + ...(run.rootNodeId === null ? {} : { nodeId: run.rootNodeId }), + providerInstanceId: run.providerInstanceId, + occurredAt: now, + payload: { + id: TurnItemId.make( + spendGuardNoticeId(threadId, notice.kind, notice.reason, noticeEventId), + ), + threadId, + runId: run.id, + nodeId: run.rootNodeId, + providerThreadId: null, + providerTurnId: null, + nativeItemRef: null, + parentItemId: null, + ordinal: 0, + status: "completed", + title: notice.title, + startedAt: now, + completedAt: now, + updatedAt: now, + type: "system_notice", + level: notice.kind === SPEND_GUARD_STOPPED_KIND ? "error" : "warning", + message: notice.message, + }, + } satisfies OrchestrationV2DomainEvent, + ], + }); + if (notice.kind !== SPEND_GUARD_STOPPED_KIND || notice.reason !== "ceiling") return; + for (const live of records.runs.filter(isLive)) { + yield* orchestrator.dispatch({ + type: "run.interrupt", + commandId: CommandId.make(`server:spend-guard-interrupt:${threadId}:${live.id}`), + threadId, + runId: live.id, + reason: notice.message, + }); + } + }); + + const worker = yield* makeDrainableWorker((threadId: ThreadId) => + check(threadId).pipe( + Effect.catchCauseIf( + (cause) => !Cause.hasInterruptsOnly(cause), + (cause) => + Effect.logWarning("session spend guard check failed", { + threadId, + cause: Cause.pretty(cause), + }), + ), + ), + ); + + const processEvent = (event: OrchestrationV2DomainEvent) => { + if ( + event.type !== "provider-turn.updated" || + (event.payload.turnTokenUsage === undefined && event.payload.tokenUsage === undefined) || + pending.has(event.threadId) + ) { + return Effect.void; + } + pending.add(event.threadId); + return worker.enqueue(event.threadId); + }; + + const start = Effect.fn("SessionSpendGuardReactor.start")(function* () { + yield* forkParked(Stream.runForEach(orchestrator.streamDomainEvents, processEvent)); + }); + + return { start, drain: worker.drain }; +}); diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts index 07dc1cb1cf3bc..1a7895b0cd954 100644 --- a/apps/server/src/server.ts +++ b/apps/server/src/server.ts @@ -213,11 +213,13 @@ import * as CursorUsageAccounts from "@t3tools/provider-cursor/server/CursorUsag import * as UsageService from "./usage/UsageService.ts"; import * as CodexUsageHistory from "./usage/CodexUsageHistory.ts"; import * as RuntimeLayer from "./orchestration-v2/runtimeLayer.ts"; +import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator"; import * as ProjectStore from "./orchestration-v2/ProjectStore.ts"; import * as ThreadSearch from "./orchestration-v2/ThreadSearch.ts"; import * as ThreadSettlementService from "./orchestration-v2/ThreadSettlementService.ts"; import * as CompactionLoopGuard from "./orchestration-v2/CompactionLoopGuard.ts"; import * as IdleCompactionService from "./orchestration-v2/IdleCompactionService.ts"; +import * as SessionSpendGuardReactor from "./orchestration-v2/SessionSpendGuardReactor.ts"; import * as ThreadPullRequestService from "./orchestration-v2/ThreadPullRequestService.ts"; import * as RunFinalizationService from "./orchestration-v2/RunFinalizationService.ts"; import * as ProjectionMaintenance from "./orchestration-v2/ProjectionMaintenance.ts"; @@ -634,6 +636,14 @@ const layerIdleCompactionWorker = Layer.effectDiscard( IdleCompactionService.make.pipe(Effect.flatMap((service) => service.start())), ).pipe(Layer.provide(ProjectionStoreV2.layer)); +const layerSessionSpendGuardWorker = Layer.effectDiscard( + SessionSpendGuardReactor.make.pipe(Effect.flatMap((service) => service.start())), +).pipe( + Layer.provide( + Layer.mergeAll(ProjectionStoreV2.layer, RuntimeLayer.layerEventSink, IdAllocator.layer), + ), +); + const layerCompactionLoopGuard = Layer.effectDiscard( CompactionLoopGuard.make.pipe(Effect.flatMap((service) => service.start())), ).pipe(Layer.provide(ProjectionStoreV2.layer)); @@ -693,6 +703,7 @@ const layerRuntimeCoreDependenciesBase = Layer.mergeAll( HeldHooksWaker.layer, layerThreadSettlementWorker, layerIdleCompactionWorker, + layerSessionSpendGuardWorker, layerCompactionLoopGuard, StorageCleanup.layer.pipe(Layer.provide(ProjectionStoreV2.layer)), DatabaseStorage.layer.pipe( diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts index e7cea79c7663e..baa4703410748 100644 --- a/packages/contracts/src/settings.test.ts +++ b/packages/contracts/src/settings.test.ts @@ -410,6 +410,33 @@ describe("ServerSettings.sourceControlWritingStyle", () => { }); }); +describe("session spend guard", () => { + it("enforces the idle and session ceilings by default", () => { + expect(decodeServerSettings({}).sessionSpendGuard).toMatchObject({ + mode: "enforce", + idleFlagUsd: 25, + idleStopUsd: 50, + sessionCeilingUsd: 200, + fallbackRate: { + inputCostPerMillionTokens: 10, + outputCostPerMillionTokens: 50, + cacheReadCostPerMillionTokens: 1, + cacheWriteCostPerMillionTokens: 12.5, + }, + }); + }); + + it("patches one field and rejects a non-positive amount", () => { + expect(decodeServerSettingsPatch({ sessionSpendGuard: { mode: "flag" } })).toEqual({ + sessionSpendGuard: { mode: "flag" }, + }); + expect(() => decodeServerSettings({ sessionSpendGuard: { idleStopUsd: 0 } })).toThrow(); + expect(() => + decodeServerSettingsPatch({ sessionSpendGuard: { sessionCeilingUsd: -1 } }), + ).toThrow(); + }); +}); + describe("ServerSettings environment icon", () => { it("decodes a kind from a newer server as null instead of failing the snapshot", () => { expect(decodeServerSettings({ environmentIcon: "toaster" }).environmentIcon).toBeNull(); diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts index 57d324d5879a9..8e08976ff6b7a 100644 --- a/packages/contracts/src/settings.ts +++ b/packages/contracts/src/settings.ts @@ -726,6 +726,29 @@ export function makeProviderSettingsSchema