@opengeni/worker-bundle 0.20.1 → 0.22.0-canary.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/dist/activities/agent-turn/admission.d.ts +52 -0
  2. package/dist/activities/agent-turn/agent-build.d.ts +89 -0
  3. package/dist/activities/agent-turn/claim.d.ts +67 -0
  4. package/dist/activities/agent-turn/codex-capacity.d.ts +40 -0
  5. package/dist/activities/agent-turn/codex.d.ts +32 -0
  6. package/dist/activities/agent-turn/compaction-prep.d.ts +88 -0
  7. package/dist/activities/agent-turn/credential-leases.d.ts +56 -0
  8. package/dist/activities/agent-turn/errors.d.ts +253 -0
  9. package/dist/activities/agent-turn/failure-settlement.d.ts +33 -0
  10. package/dist/activities/agent-turn/file-resources.d.ts +37 -0
  11. package/dist/activities/agent-turn/finalization.d.ts +42 -0
  12. package/dist/activities/agent-turn/github-repository-bindings.d.ts +105 -0
  13. package/dist/activities/agent-turn/governance-model.d.ts +66 -0
  14. package/dist/activities/agent-turn/history-sink.d.ts +52 -0
  15. package/dist/activities/agent-turn/history.d.ts +63 -0
  16. package/dist/activities/agent-turn/media-artifacts.d.ts +145 -0
  17. package/dist/activities/agent-turn/model-usage.d.ts +218 -0
  18. package/dist/activities/agent-turn/quiescence.d.ts +135 -0
  19. package/dist/activities/agent-turn/run-credentials.d.ts +84 -0
  20. package/dist/activities/agent-turn/run.d.ts +3 -0
  21. package/dist/activities/agent-turn/sandbox-establish.d.ts +93 -0
  22. package/dist/activities/agent-turn/sandbox-provision.d.ts +89 -0
  23. package/dist/activities/agent-turn/sandbox-route.d.ts +151 -0
  24. package/dist/activities/agent-turn/sandbox-runtime.d.ts +44 -0
  25. package/dist/activities/agent-turn/stream-attempt.d.ts +107 -0
  26. package/dist/activities/agent-turn/tool-environment.d.ts +142 -0
  27. package/dist/activities/agent-turn/tool-policy.d.ts +127 -0
  28. package/dist/activities/agent-turn/tool-result-spill.d.ts +59 -0
  29. package/dist/activities/agent-turn/turn-context.d.ts +144 -0
  30. package/dist/activities/agent-turn/xai-capacity.d.ts +2 -0
  31. package/dist/activities/agent-turn.d.ts +12 -954
  32. package/dist/activities/automations.d.ts +16 -0
  33. package/dist/activities/common.d.ts +1 -1
  34. package/dist/activities/connector-attachments.d.ts +13 -0
  35. package/dist/activities/documents.d.ts +1 -0
  36. package/dist/activities/environment.d.ts +26 -15
  37. package/dist/activities/generated-images.d.ts +1 -1
  38. package/dist/activities/git-credential-renewal.d.ts +3 -1
  39. package/dist/activities/goals.d.ts +4 -1
  40. package/dist/activities/google-drive-provider.d.ts +29 -0
  41. package/dist/activities/google-drive-publication.d.ts +66 -0
  42. package/dist/activities/image-generation-references.d.ts +2 -0
  43. package/dist/activities/incident-telemetry-authority.d.ts +52 -0
  44. package/dist/activities/incident-telemetry-preflight.d.ts +71 -0
  45. package/dist/activities/knowledge-source-sync-driver.d.ts +21 -0
  46. package/dist/activities/knowledge-source-sync.d.ts +33 -1
  47. package/dist/activities/mcp-credentials.d.ts +9 -3
  48. package/dist/activities/open-suffix-resume.d.ts +77 -0
  49. package/dist/activities/packs.d.ts +3 -11
  50. package/dist/activities/parent-wake.d.ts +19 -0
  51. package/dist/activities/retained-screenshot-reaper.d.ts +1 -1
  52. package/dist/activities/retained-screenshots.d.ts +1 -1
  53. package/dist/activities/rig-verification.d.ts +1 -1
  54. package/dist/activities/run-input.d.ts +16 -7
  55. package/dist/activities/sandbox-images.d.ts +1 -14
  56. package/dist/activities/sandbox-lease.d.ts +21 -3
  57. package/dist/activities/scheduled-tasks.d.ts +47 -0
  58. package/dist/activities/types.d.ts +23 -2
  59. package/dist/activities/video-media-validation.d.ts +1 -1
  60. package/dist/activities/video-output-retention.d.ts +1 -2
  61. package/dist/activities/xai-auth.d.ts +3 -0
  62. package/dist/{activities-control-SMKF2OBE.js → activities-control-DKG22ONJ.js} +2946 -549
  63. package/dist/activities-control-DKG22ONJ.js.map +1 -0
  64. package/dist/activities-control.d.ts +6 -2
  65. package/dist/activities-turn-4IMC3MAA.js +21326 -0
  66. package/dist/activities-turn-4IMC3MAA.js.map +1 -0
  67. package/dist/activities.d.ts +7 -3
  68. package/dist/artifact-materializer-entry.js +41 -22
  69. package/dist/artifact-materializer-entry.js.map +1 -1
  70. package/dist/{chunk-N5TJIFCE.js → chunk-CE7TPKBS.js} +468 -1
  71. package/dist/chunk-CE7TPKBS.js.map +1 -0
  72. package/dist/chunk-CNYGVRKF.js +4698 -0
  73. package/dist/chunk-CNYGVRKF.js.map +1 -0
  74. package/dist/connection-provider-use.d.ts +18 -0
  75. package/dist/editable-artifact-materializer.d.ts +4 -3
  76. package/dist/github-rest-mcp.d.ts +26 -0
  77. package/dist/index.d.ts +10 -2
  78. package/dist/index.js +58 -14
  79. package/dist/index.js.map +1 -1
  80. package/dist/knowledge-source-sync-activity-policy.d.ts +2 -0
  81. package/dist/model-context-contributions.d.ts +8 -4
  82. package/dist/observability-metrics.d.ts +63 -4
  83. package/dist/opensandbox-kubernetes-inventory.d.ts +21 -0
  84. package/dist/personal-github-git-credentials.d.ts +9 -0
  85. package/dist/pr-review-credentials.d.ts +6 -0
  86. package/dist/sandbox-archive-storage.d.ts +45 -0
  87. package/dist/sandbox-resume.d.ts +65 -6
  88. package/dist/sandbox-routing.d.ts +38 -2
  89. package/dist/scheduled-alert-occurrence.d.ts +33 -0
  90. package/dist/workflow-bundle.js +87 -28
  91. package/dist/workflows/activities.d.ts +1 -0
  92. package/dist/workflows/automations.d.ts +6 -0
  93. package/dist/workflows/document-index.d.ts +1 -0
  94. package/dist/workflows.d.ts +1 -0
  95. package/package.json +17 -17
  96. package/src/activities/agent-turn/admission.ts +292 -0
  97. package/src/activities/agent-turn/agent-build.ts +802 -0
  98. package/src/activities/agent-turn/claim.ts +590 -0
  99. package/src/activities/agent-turn/codex-capacity.ts +720 -0
  100. package/src/activities/agent-turn/codex.ts +94 -0
  101. package/src/activities/agent-turn/compaction-prep.ts +722 -0
  102. package/src/activities/agent-turn/credential-leases.ts +240 -0
  103. package/src/activities/agent-turn/errors.ts +1068 -0
  104. package/src/activities/agent-turn/failure-settlement.ts +1436 -0
  105. package/src/activities/agent-turn/file-resources.ts +227 -0
  106. package/src/activities/agent-turn/finalization.ts +754 -0
  107. package/src/activities/agent-turn/github-repository-bindings.ts +300 -0
  108. package/src/activities/agent-turn/governance-model.ts +465 -0
  109. package/src/activities/agent-turn/history-sink.ts +139 -0
  110. package/src/activities/agent-turn/history.ts +200 -0
  111. package/src/activities/agent-turn/media-artifacts.ts +359 -0
  112. package/src/activities/agent-turn/model-usage.ts +823 -0
  113. package/src/activities/agent-turn/quiescence.ts +353 -0
  114. package/src/activities/agent-turn/run-credentials.ts +761 -0
  115. package/src/activities/agent-turn/run.ts +1530 -0
  116. package/src/activities/agent-turn/sandbox-establish.ts +1207 -0
  117. package/src/activities/agent-turn/sandbox-provision.ts +569 -0
  118. package/src/activities/agent-turn/sandbox-route.ts +358 -0
  119. package/src/activities/agent-turn/sandbox-runtime.ts +731 -0
  120. package/src/activities/agent-turn/stream-attempt.ts +1670 -0
  121. package/src/activities/agent-turn/tool-environment.ts +729 -0
  122. package/src/activities/agent-turn/tool-policy.ts +216 -0
  123. package/src/activities/agent-turn/tool-result-spill.ts +265 -0
  124. package/src/activities/agent-turn/turn-context.ts +281 -0
  125. package/src/activities/agent-turn/xai-capacity.ts +229 -0
  126. package/src/activities/agent-turn.ts +12 -12575
  127. package/src/activities/api-integrations.ts +3 -0
  128. package/src/activities/automations.ts +214 -0
  129. package/src/activities/codemode-dispatcher.ts +12 -1
  130. package/src/activities/common.ts +1 -5
  131. package/src/activities/connector-attachments.ts +168 -0
  132. package/src/activities/context-compaction.ts +18 -0
  133. package/src/activities/documents.ts +6 -4
  134. package/src/activities/environment.ts +151 -55
  135. package/src/activities/generated-images.ts +26 -11
  136. package/src/activities/git-credential-renewal.ts +13 -3
  137. package/src/activities/goals.ts +85 -19
  138. package/src/activities/google-drive-provider.ts +178 -0
  139. package/src/activities/google-drive-publication.ts +938 -0
  140. package/src/activities/image-generation-references.ts +11 -2
  141. package/src/activities/incident-telemetry-authority.ts +327 -0
  142. package/src/activities/incident-telemetry-preflight.ts +317 -0
  143. package/src/activities/knowledge-source-sync-driver.ts +23 -0
  144. package/src/activities/knowledge-source-sync.ts +556 -40
  145. package/src/activities/mcp-credentials.ts +191 -17
  146. package/src/activities/open-suffix-resume.ts +422 -0
  147. package/src/activities/packs.ts +12 -60
  148. package/src/activities/parent-wake.ts +64 -14
  149. package/src/activities/retained-screenshot-reaper.ts +6 -3
  150. package/src/activities/retained-screenshots.ts +15 -47
  151. package/src/activities/rig-verification.ts +1 -1
  152. package/src/activities/run-input.ts +128 -136
  153. package/src/activities/sandbox-images.ts +7 -166
  154. package/src/activities/sandbox-lease.ts +406 -15
  155. package/src/activities/scheduled-tasks.ts +2103 -411
  156. package/src/activities/session-state.ts +10 -2
  157. package/src/activities/types.ts +32 -2
  158. package/src/activities/video-media-validation.ts +3 -3
  159. package/src/activities/video-output-retention.ts +2 -57
  160. package/src/activities/xai-auth.ts +8 -0
  161. package/src/activities-control.ts +2 -0
  162. package/src/activities.ts +3 -0
  163. package/src/activity-services.ts +13 -4
  164. package/src/connection-provider-use.ts +36 -0
  165. package/src/editable-artifact-materializer-subprocess.ts +25 -14
  166. package/src/editable-artifact-materializer.ts +29 -18
  167. package/src/github-rest-mcp.ts +713 -0
  168. package/src/http.ts +16 -6
  169. package/src/index.ts +40 -5
  170. package/src/knowledge-source-sync-activity-policy.ts +2 -0
  171. package/src/model-context-contributions.ts +33 -10
  172. package/src/observability-metrics.ts +357 -0
  173. package/src/opensandbox-kubernetes-inventory.ts +292 -0
  174. package/src/personal-github-git-credentials.ts +331 -0
  175. package/src/pr-review-credentials.ts +163 -0
  176. package/src/sandbox-archive-storage.ts +159 -0
  177. package/src/sandbox-resume.ts +449 -63
  178. package/src/sandbox-routing.ts +314 -16
  179. package/src/scheduled-alert-occurrence.ts +176 -0
  180. package/src/workflows/activities.ts +18 -2
  181. package/src/workflows/automations.ts +11 -0
  182. package/src/workflows/session.ts +13 -3
  183. package/src/workflows.ts +1 -0
  184. package/dist/activities-control-SMKF2OBE.js.map +0 -1
  185. package/dist/activities-turn-IDS3WEHA.js +0 -16532
  186. package/dist/activities-turn-IDS3WEHA.js.map +0 -1
  187. package/dist/chunk-N5TJIFCE.js.map +0 -1
  188. package/dist/chunk-P6Z2SLAA.js +0 -3092
  189. package/dist/chunk-P6Z2SLAA.js.map +0 -1
@@ -0,0 +1,823 @@
1
+ import {
2
+ applyCreditDebitUpToBalance,
3
+ recordUsageEvent,
4
+ recordModelCallFact,
5
+ type AppendEventInput,
6
+ type CanonicalTurnStartupMilestoneReceipt,
7
+ } from "@opengeni/db";
8
+ import {
9
+ modelResponseServiceTierFromSdkEvent,
10
+ modelTerminalResponseFromSdkEvent,
11
+ normalizeModelCallUsage,
12
+ type ModelResponseUsage,
13
+ type ModelCallUsageInput,
14
+ type ModelCallUsageNormalization,
15
+ } from "@opengeni/runtime";
16
+ import {
17
+ calculateGatewayReportedCostBreakdown,
18
+ calculateModelUsageCostBreakdown,
19
+ configuredModelPricingSchedules,
20
+ responseSatisfiesLatencyMode,
21
+ OPENGENI_GATEWAY_MODELS,
22
+ OPENGENI_GATEWAY_PROVIDER_ID,
23
+ type ModelUsageInput,
24
+ type ModelProviderApi,
25
+ type Settings,
26
+ } from "@opengeni/config";
27
+ import { CODEX_PROVIDER_ID } from "@opengeni/codex";
28
+ import type { TurnActivityServices as ActivityServices } from "../types";
29
+ import {
30
+ modelCallAccountContext,
31
+ recordCreditMicros,
32
+ recordModelCacheTokens,
33
+ recordModelInputTokens,
34
+ } from "../../observability-metrics";
35
+ import {
36
+ type LatencyMode,
37
+ type ModelContextContributionSummary,
38
+ type SessionEvent,
39
+ } from "@opengeni/contracts";
40
+ import { safeErrorDiagnostic } from "./errors";
41
+
42
+ export function modelUsageSourceKey(input: {
43
+ responseId?: string | null | undefined;
44
+ dispatchId: string | null;
45
+ positionalKey: string;
46
+ }): string {
47
+ if (input.responseId) {
48
+ return input.responseId;
49
+ }
50
+ return input.dispatchId ? `${input.dispatchId}:${input.positionalKey}` : input.positionalKey;
51
+ }
52
+
53
+ export function providerContextTokens(
54
+ usage:
55
+ | {
56
+ inputTokens?: number;
57
+ outputTokens?: number;
58
+ totalTokens?: number;
59
+ }
60
+ | null
61
+ | undefined,
62
+ ): number | null {
63
+ const total = normalizeModelCallUsage(usage).totalTokens;
64
+ return total !== null && total > 0 ? total : null;
65
+ }
66
+
67
+ /**
68
+ * A provider call has already consumed tokens by the time its usage frame is
69
+ * available. Losing the Codex credential lease at the renewal checkpoint must
70
+ * stop the result from becoming authoritative, but it must not erase accounting
71
+ * truth for the call that already happened. Meter first, then surface the lost
72
+ * lease, then write attempt-owned token/context signals. A replaced attempt can
73
+ * reject those signals without erasing the provider usage already incurred.
74
+ */
75
+ export async function recordCompletedModelCallBeforeOwnershipFences(input: {
76
+ renewLease: () => Promise<void>;
77
+ recordUsage: () => Promise<void>;
78
+ leaseLost: () => boolean;
79
+ leaseLostMessage: string;
80
+ recordAttemptSignals?: () => Promise<void>;
81
+ }): Promise<void> {
82
+ await input.renewLease();
83
+ await input.recordUsage();
84
+ if (input.leaseLost()) {
85
+ throw new Error(input.leaseLostMessage);
86
+ }
87
+ await input.recordAttemptSignals?.();
88
+ }
89
+
90
+ export type TurnEventPublisher = (
91
+ events: Array<Omit<AppendEventInput, "producerId" | "producerSeq" | "turnId">>,
92
+ immediate?: boolean,
93
+ ) => Promise<{
94
+ events: SessionEvent[];
95
+ accepted: boolean;
96
+ canonicalStartupMilestones: CanonicalTurnStartupMilestoneReceipt[];
97
+ }>;
98
+
99
+ export type ModelResponseEventState = {
100
+ responseCount: number;
101
+ contextSignal: { revision: number; totalTokens: number } | null;
102
+ claimedSourceKeys: Set<string>;
103
+ };
104
+
105
+ export type CompactionModelUsageEventState = {
106
+ usageCount: number;
107
+ claimedSourceKeys: Set<string>;
108
+ };
109
+
110
+ export function createModelResponseEventState(
111
+ claimedSourceKeys: Set<string> = new Set<string>(),
112
+ ): ModelResponseEventState {
113
+ return {
114
+ responseCount: 0,
115
+ contextSignal: null,
116
+ claimedSourceKeys,
117
+ };
118
+ }
119
+
120
+ export function createCompactionModelUsageEventState(
121
+ claimedSourceKeys: Set<string> = new Set<string>(),
122
+ ): CompactionModelUsageEventState {
123
+ return { usageCount: 0, claimedSourceKeys };
124
+ }
125
+
126
+ export function modelResponseContextSignal(
127
+ state: ModelResponseEventState,
128
+ ): { revision: number; totalTokens: number } | null {
129
+ return state.contextSignal;
130
+ }
131
+
132
+ export function assertModelResponseLatencyMode(input: {
133
+ event: Parameters<typeof modelResponseServiceTierFromSdkEvent>[0];
134
+ requested: LatencyMode;
135
+ model: string;
136
+ /** When set to Codex ChatGPT auth, response `service_tier` is not an honor signal. */
137
+ providerId?: string;
138
+ }): void {
139
+ if (input.requested === "standard") {
140
+ return;
141
+ }
142
+ // ChatGPT-auth Codex (subscription): Fast maps to request `service_tier=priority`
143
+ // (see openai/codex ServiceTier::Fast.request_value). The backend may still return
144
+ // `response.service_tier=default`; OpenAI maintainers document that this does not
145
+ // mean Fast was ignored. Native CLI also does not fail closed on that field.
146
+ if (input.providerId === CODEX_PROVIDER_ID) {
147
+ return;
148
+ }
149
+ const serviceTierEvent = modelResponseServiceTierFromSdkEvent(input.event);
150
+ if (
151
+ !serviceTierEvent ||
152
+ (serviceTierEvent.source === "normalized" && serviceTierEvent.serviceTier === null)
153
+ ) {
154
+ return;
155
+ }
156
+ if (!responseSatisfiesLatencyMode(input.requested, serviceTierEvent.serviceTier)) {
157
+ throw new Error(
158
+ `Provider did not honor ${input.requested} latency mode for ${input.model}: response service_tier=${serviceTierEvent.serviceTier ?? "missing"}`,
159
+ );
160
+ }
161
+ }
162
+
163
+ /**
164
+ * Process one SDK terminal-response event through the production authority path.
165
+ *
166
+ * The pinned Responses SDK mirrors one provider terminal response as both a
167
+ * normalized `response_done` and a raw `model/response.completed` event. Claim
168
+ * the stable response/source key before lease renewal or any side effect, and
169
+ * use that one positional ordinal for both response identity and same-run
170
+ * context binding. A response without usage still clears attempt-owned token
171
+ * state. When usage exists, the durable `agent.model.usage` source-key fence
172
+ * remains the cross-restart authority: a replay may retry the idempotent billing
173
+ * write, but it cannot advance metrics, context, or attempt-owned signals.
174
+ */
175
+ export async function processModelResponseTerminalEvent(input: {
176
+ event: Parameters<typeof modelTerminalResponseFromSdkEvent>[0];
177
+ state: ModelResponseEventState;
178
+ dispatchId: string | null;
179
+ settings: Settings;
180
+ db: ActivityServices["db"];
181
+ observability: ActivityServices["observability"];
182
+ publish: TurnEventPublisher | null;
183
+ accountId: string;
184
+ workspaceId: string;
185
+ sessionId: string;
186
+ turnId: string;
187
+ turnAttemptId: string;
188
+ provider: string;
189
+ providerApi: ModelProviderApi;
190
+ model: string;
191
+ latencyMode?: LatencyMode;
192
+ metricProvider: string;
193
+ externallyBilled: boolean;
194
+ servingCredentialId: string | null;
195
+ priorSessionCredentialId: string | null;
196
+ emittedSourceKeys: Set<string>;
197
+ renewLease: () => Promise<void>;
198
+ leaseLost: () => boolean;
199
+ leaseLostMessage: string;
200
+ setLastInputTokens: (tokens: number | null) => Promise<void>;
201
+ contextContributions?: readonly ModelContextContributionSummary[] | null;
202
+ }): Promise<
203
+ | { status: "not_response" }
204
+ | { status: "duplicate"; sourceKey: string }
205
+ | {
206
+ status: "processed";
207
+ sourceKey: string;
208
+ authoritative: boolean;
209
+ usageReported: boolean;
210
+ }
211
+ > {
212
+ const terminal = modelTerminalResponseFromSdkEvent(input.event);
213
+ if (!terminal) {
214
+ return { status: "not_response" };
215
+ }
216
+
217
+ const responseOrdinal = input.state.responseCount + 1;
218
+ const sourceKey = modelUsageSourceKey({
219
+ responseId: terminal.responseId,
220
+ dispatchId: input.dispatchId,
221
+ positionalKey: `response-${responseOrdinal}`,
222
+ });
223
+ if (input.state.claimedSourceKeys.has(sourceKey)) {
224
+ return { status: "duplicate", sourceKey };
225
+ }
226
+ input.state.claimedSourceKeys.add(sourceKey);
227
+ input.state.responseCount = responseOrdinal;
228
+
229
+ const responseUsage = terminal.usage;
230
+
231
+ const normalizedUsage = normalizeModelCallUsage(responseUsage?.usage);
232
+ const accountContext = modelCallAccountContext({
233
+ servingCredentialId: input.servingCredentialId,
234
+ priorSessionCredentialId: input.priorSessionCredentialId,
235
+ isFirstCallOfTurn: responseOrdinal === 1,
236
+ });
237
+ // A terminal response without usage still authoritatively replaces the
238
+ // attempt-owned context signal. There is simply no billing event to claim.
239
+ let authoritative = responseUsage === null;
240
+ await recordCompletedModelCallBeforeOwnershipFences({
241
+ renewLease: input.renewLease,
242
+ leaseLost: input.leaseLost,
243
+ leaseLostMessage: input.leaseLostMessage,
244
+ recordUsage: async () => {
245
+ if (!responseUsage) return;
246
+ const billing = await recordModelUsageAndDebitCredits(input.settings, input.db, {
247
+ accountId: input.accountId,
248
+ workspaceId: input.workspaceId,
249
+ sessionId: input.sessionId,
250
+ turnId: input.turnId,
251
+ turnAttemptId: input.turnAttemptId,
252
+ model: input.model,
253
+ externallyBilled: input.externallyBilled,
254
+ usage: responseUsage.usage,
255
+ normalizedUsage,
256
+ gatewayManaged: input.provider === OPENGENI_GATEWAY_PROVIDER_ID,
257
+ gatewayBilling: responseUsage.gatewayBilling,
258
+ sourceKey,
259
+ ...(input.latencyMode ? { latencyMode: input.latencyMode } : {}),
260
+ observability: input.observability,
261
+ });
262
+ authoritative = await emitModelCallUsage({
263
+ observability: input.observability,
264
+ publish: input.publish,
265
+ accountId: input.accountId,
266
+ workspaceId: input.workspaceId,
267
+ sessionId: input.sessionId,
268
+ turnId: input.turnId,
269
+ provider: input.provider,
270
+ providerApi: input.providerApi,
271
+ model: input.model,
272
+ sourceKey,
273
+ usage: responseUsage,
274
+ normalizedUsage,
275
+ servingAccountHash: accountContext.servingAccountHash,
276
+ accountChangedFromPrevCall: accountContext.accountChangedFromPrevCall,
277
+ emittedSourceKeys: input.emittedSourceKeys,
278
+ });
279
+ if (authoritative && billing) {
280
+ await recordAuthoritativeModelCallFact({
281
+ db: input.db,
282
+ observability: input.observability,
283
+ accountId: input.accountId,
284
+ workspaceId: input.workspaceId,
285
+ sessionId: input.sessionId,
286
+ turnId: input.turnId,
287
+ turnAttemptId: input.turnAttemptId,
288
+ sourceKey,
289
+ provider: input.provider,
290
+ providerApi: input.providerApi,
291
+ model: input.model,
292
+ billing,
293
+ ...(input.contextContributions !== undefined
294
+ ? { contextContributions: input.contextContributions }
295
+ : {}),
296
+ });
297
+ }
298
+ const observedInput = normalizedUsage.telemetry.inputTokens;
299
+ if (authoritative && observedInput !== null && observedInput > 0) {
300
+ recordModelInputTokens(input.observability, input.metricProvider, observedInput);
301
+ }
302
+ },
303
+ recordAttemptSignals: async () => {
304
+ if (!authoritative) return;
305
+ const observedTotal = normalizedUsage.totalTokens;
306
+ input.state.contextSignal =
307
+ observedTotal !== null && observedTotal > 0
308
+ ? { revision: responseOrdinal, totalTokens: observedTotal }
309
+ : null;
310
+ const observedInput = normalizedUsage.telemetry.inputTokens;
311
+ await input.setLastInputTokens(
312
+ observedInput !== null && observedInput > 0 ? observedInput : null,
313
+ );
314
+ },
315
+ });
316
+ return {
317
+ status: "processed",
318
+ sourceKey,
319
+ authoritative,
320
+ usageReported: responseUsage !== null,
321
+ };
322
+ }
323
+
324
+ /**
325
+ * Apply the same source-key authority ordering to the compaction summarizer's
326
+ * usage callback. The summarizer can retry or mirror a terminal response just
327
+ * like the main stream, so claim before lease renewal, billing, durable usage,
328
+ * logging, or cache metrics. Durable source-key idempotency remains the
329
+ * cross-process authority after a worker restart.
330
+ */
331
+ export async function processCompactionModelUsageEvent(input: {
332
+ usage: ModelResponseUsage;
333
+ state: CompactionModelUsageEventState;
334
+ dispatchId: string | null;
335
+ settings: Settings;
336
+ db: ActivityServices["db"];
337
+ observability: ActivityServices["observability"];
338
+ publish: TurnEventPublisher | null;
339
+ accountId: string;
340
+ workspaceId: string;
341
+ sessionId: string;
342
+ turnId: string;
343
+ turnAttemptId: string;
344
+ provider: string;
345
+ providerApi: ModelProviderApi;
346
+ model: string;
347
+ externallyBilled: boolean;
348
+ servingCredentialId: string | null;
349
+ priorSessionCredentialId: string | null;
350
+ emittedSourceKeys: Set<string>;
351
+ renewLease: () => Promise<void>;
352
+ leaseLost: () => boolean;
353
+ leaseLostMessage: string;
354
+ contextContributions?: readonly ModelContextContributionSummary[] | null;
355
+ }): Promise<
356
+ | { status: "duplicate"; sourceKey: string }
357
+ | { status: "processed"; sourceKey: string; authoritative: boolean }
358
+ > {
359
+ const usageOrdinal = input.state.usageCount + 1;
360
+ const sourceKey = modelUsageSourceKey({
361
+ responseId: input.usage.responseId,
362
+ dispatchId: input.dispatchId,
363
+ positionalKey: `compaction-${usageOrdinal}`,
364
+ });
365
+ if (input.state.claimedSourceKeys.has(sourceKey)) {
366
+ return { status: "duplicate", sourceKey };
367
+ }
368
+ input.state.claimedSourceKeys.add(sourceKey);
369
+ input.state.usageCount = usageOrdinal;
370
+
371
+ const accountContext = modelCallAccountContext({
372
+ servingCredentialId: input.servingCredentialId,
373
+ priorSessionCredentialId: input.priorSessionCredentialId,
374
+ isFirstCallOfTurn: usageOrdinal === 1,
375
+ });
376
+ const normalizedUsage = normalizeModelCallUsage(input.usage.usage);
377
+ let authoritative = false;
378
+ await recordCompletedModelCallBeforeOwnershipFences({
379
+ renewLease: input.renewLease,
380
+ leaseLost: input.leaseLost,
381
+ leaseLostMessage: input.leaseLostMessage,
382
+ recordUsage: async () => {
383
+ const billing = await recordModelUsageAndDebitCredits(input.settings, input.db, {
384
+ accountId: input.accountId,
385
+ workspaceId: input.workspaceId,
386
+ sessionId: input.sessionId,
387
+ turnId: input.turnId,
388
+ turnAttemptId: input.turnAttemptId,
389
+ model: input.model,
390
+ externallyBilled: input.externallyBilled,
391
+ usage: input.usage.usage,
392
+ normalizedUsage,
393
+ gatewayManaged: input.provider === OPENGENI_GATEWAY_PROVIDER_ID,
394
+ gatewayBilling: input.usage.gatewayBilling,
395
+ sourceKey,
396
+ observability: input.observability,
397
+ });
398
+ authoritative = await emitModelCallUsage({
399
+ observability: input.observability,
400
+ publish: input.publish,
401
+ accountId: input.accountId,
402
+ workspaceId: input.workspaceId,
403
+ sessionId: input.sessionId,
404
+ turnId: input.turnId,
405
+ provider: input.provider,
406
+ providerApi: input.providerApi,
407
+ model: input.model,
408
+ sourceKey,
409
+ usage: input.usage,
410
+ normalizedUsage,
411
+ servingAccountHash: accountContext.servingAccountHash,
412
+ accountChangedFromPrevCall: accountContext.accountChangedFromPrevCall,
413
+ emittedSourceKeys: input.emittedSourceKeys,
414
+ });
415
+ if (authoritative && billing) {
416
+ await recordAuthoritativeModelCallFact({
417
+ db: input.db,
418
+ observability: input.observability,
419
+ accountId: input.accountId,
420
+ workspaceId: input.workspaceId,
421
+ sessionId: input.sessionId,
422
+ turnId: input.turnId,
423
+ turnAttemptId: input.turnAttemptId,
424
+ sourceKey,
425
+ provider: input.provider,
426
+ providerApi: input.providerApi,
427
+ model: input.model,
428
+ billing,
429
+ ...(input.contextContributions !== undefined
430
+ ? { contextContributions: input.contextContributions }
431
+ : {}),
432
+ });
433
+ }
434
+ },
435
+ });
436
+ return { status: "processed", sourceKey, authoritative };
437
+ }
438
+
439
+ export async function emitModelCallUsage(input: {
440
+ observability: ActivityServices["observability"];
441
+ publish: TurnEventPublisher | null;
442
+ accountId: string;
443
+ workspaceId: string;
444
+ sessionId: string;
445
+ turnId: string;
446
+ provider: string;
447
+ providerApi: ModelProviderApi;
448
+ model: string;
449
+ sourceKey: string;
450
+ usage: ModelResponseUsage | { usage?: unknown | null } | null;
451
+ normalizedUsage?: ModelCallUsageNormalization;
452
+ // Prompt-cache research dimensions (log-only; NEVER on a metric label or a
453
+ // durable event). The opaque serving-account tag and whether it changed since
454
+ // the session's previous call — the account-switch hypothesis for cache misses.
455
+ servingAccountHash?: string;
456
+ accountChangedFromPrevCall?: boolean;
457
+ emittedSourceKeys?: Set<string>;
458
+ }): Promise<boolean> {
459
+ const usage =
460
+ input.usage && typeof input.usage === "object" && "usage" in input.usage
461
+ ? (input.usage as { usage?: unknown }).usage
462
+ : null;
463
+ if (!usage || typeof usage !== "object") {
464
+ return false;
465
+ }
466
+ if (input.emittedSourceKeys?.has(input.sourceKey)) return false;
467
+ const normalizedUsage =
468
+ input.normalizedUsage ?? normalizeModelCallUsage(usage as ModelCallUsageInput);
469
+ const telemetry = normalizedUsage.telemetry;
470
+ const appended = await input.publish?.(
471
+ [
472
+ {
473
+ type: "agent.model.usage",
474
+ payload: {
475
+ accountId: input.accountId,
476
+ workspaceId: input.workspaceId,
477
+ sessionId: input.sessionId,
478
+ turnId: input.turnId,
479
+ provider: input.provider,
480
+ providerApi: input.providerApi,
481
+ model: input.model,
482
+ sourceKey: input.sourceKey,
483
+ ...telemetry,
484
+ },
485
+ },
486
+ ],
487
+ true,
488
+ );
489
+ input.emittedSourceKeys?.add(input.sourceKey);
490
+ const authoritative = appended?.events.some(
491
+ (event) =>
492
+ event.type === "agent.model.usage" &&
493
+ event.turnAssociation === "current" &&
494
+ event.payload !== null &&
495
+ typeof event.payload === "object" &&
496
+ (event.payload as Record<string, unknown>).sourceKey === input.sourceKey,
497
+ );
498
+ if (!authoritative) return false;
499
+ try {
500
+ input.observability.info("model call usage", {
501
+ provider: input.provider,
502
+ providerApi: input.providerApi,
503
+ model: input.model,
504
+ inputTokens: telemetry.inputTokens,
505
+ outputTokens: telemetry.outputTokens,
506
+ cachedTokens: telemetry.cachedTokens,
507
+ cacheWriteTokens: telemetry.cacheWriteTokens,
508
+ reasoningTokens: telemetry.reasoningTokens,
509
+ ...(input.servingAccountHash !== undefined
510
+ ? { servingAccountHash: input.servingAccountHash }
511
+ : {}),
512
+ ...(input.accountChangedFromPrevCall !== undefined
513
+ ? { accountChangedFromPrevCall: input.accountChangedFromPrevCall }
514
+ : {}),
515
+ });
516
+ if (normalizedUsage.rejectedFields.length > 0) {
517
+ input.observability.warn("model call usage fields rejected", {
518
+ provider: input.provider,
519
+ providerApi: input.providerApi,
520
+ model: input.model,
521
+ rejectedFields: normalizedUsage.rejectedFields.join(","),
522
+ });
523
+ }
524
+ } catch {
525
+ // Durable event + billing already committed; logging is best-effort only.
526
+ }
527
+ try {
528
+ applyCodexCacheTelemetry(input.observability, input.provider, normalizedUsage);
529
+ } catch {
530
+ // Durable event + billing already committed; metrics are best-effort only.
531
+ }
532
+ return true;
533
+ }
534
+
535
+ /**
536
+ * Apply one authoritative, normalized model-call usage frame to the shared
537
+ * prompt-cache metrics. The durable source-key fence in `emitModelCallUsage`
538
+ * owns idempotency; this helper must never receive raw provider values.
539
+ */
540
+ export function applyCodexCacheTelemetry(
541
+ observability: ActivityServices["observability"],
542
+ provider: string,
543
+ normalizedUsage: ModelCallUsageNormalization,
544
+ ): void {
545
+ recordModelCacheTokens(observability, provider, {
546
+ cachedTokens: normalizedUsage.telemetry.cachedTokens,
547
+ cacheWriteTokens: normalizedUsage.telemetry.cacheWriteTokens,
548
+ promptTokens: normalizedUsage.telemetry.inputTokens,
549
+ });
550
+ }
551
+
552
+ export type ModelUsageBillingRecord = {
553
+ billingPath: "opengeni_credits" | "external";
554
+ /** Same quantity written to usage_events.model.cost when present; else 0. */
555
+ pricedCostMicros: number;
556
+ /** Hypothetical provider-rate USD micros; never an OpenGeni charge. */
557
+ estimatedProviderCostMicros: number | null;
558
+ pricingSource: "configured_list_price" | "gateway_reported" | null;
559
+ normalizedUsage: ModelCallUsageNormalization;
560
+ upstreamProvider?: string;
561
+ };
562
+
563
+ // Exported for unit testing the external-billing bypass; not part of the activity surface.
564
+ export async function recordModelUsageAndDebitCredits(
565
+ settings: Settings,
566
+ db: ActivityServices["db"],
567
+ input: {
568
+ accountId: string;
569
+ workspaceId: string;
570
+ sessionId: string;
571
+ turnId: string;
572
+ turnAttemptId: string;
573
+ model: string;
574
+ externallyBilled: boolean;
575
+ gatewayManaged?: boolean;
576
+ gatewayBilling?: ModelResponseUsage["gatewayBilling"];
577
+ usage?: ModelUsageInput | ModelCallUsageInput | null;
578
+ normalizedUsage?: ModelCallUsageNormalization;
579
+ sourceKey: string;
580
+ latencyMode?: LatencyMode;
581
+ observability?: ActivityServices["observability"];
582
+ },
583
+ ): Promise<ModelUsageBillingRecord | null> {
584
+ if (!input.usage) {
585
+ return null;
586
+ }
587
+ const normalizedUsage = input.normalizedUsage ?? normalizeModelCallUsage(input.usage);
588
+ const sanitizedUsage = sanitizedModelUsageInput(normalizedUsage);
589
+ const inputTokens = sanitizedUsage.inputTokens ?? 0;
590
+ const outputTokens = sanitizedUsage.outputTokens ?? 0;
591
+ const totalTokens = sanitizedUsage.totalTokens ?? 0;
592
+ const gatewayBilling = input.gatewayManaged ? input.gatewayBilling : undefined;
593
+ if (gatewayBilling) {
594
+ const gatewayModel = Object.values(OPENGENI_GATEWAY_MODELS).find(
595
+ (candidate) => candidate.productId === input.model,
596
+ );
597
+ if (
598
+ !gatewayModel ||
599
+ !(gatewayModel.providers as readonly string[]).includes(gatewayBilling.finalProvider)
600
+ ) {
601
+ throw new Error(
602
+ `AI Gateway reported unapproved provider ${gatewayBilling.finalProvider} for ${input.model}`,
603
+ );
604
+ }
605
+ }
606
+ const pricingSchedules = configuredModelPricingSchedules(settings);
607
+ const configuredPricingModel = pricingSchedules[input.model]
608
+ ? input.model
609
+ : input.model.startsWith("codex/") && pricingSchedules[input.model.slice("codex/".length)]
610
+ ? input.model.slice("codex/".length)
611
+ : null;
612
+ const pricingBreakdown = gatewayBilling
613
+ ? calculateGatewayReportedCostBreakdown(
614
+ settings,
615
+ input.model,
616
+ gatewayBilling.inferenceCostUsd,
617
+ { inputTokens },
618
+ )
619
+ : configuredPricingModel
620
+ ? calculateModelUsageCostBreakdown(settings, configuredPricingModel, sanitizedUsage, {
621
+ latencyMode: input.latencyMode ?? "standard",
622
+ })
623
+ : null;
624
+ const hasCompleteCoreTokenTelemetry =
625
+ normalizedUsage.telemetry.inputTokens !== null &&
626
+ normalizedUsage.telemetry.outputTokens !== null;
627
+ const estimatedProviderCostMicros = gatewayBilling
628
+ ? (pricingBreakdown?.providerCostMicros ?? null)
629
+ : hasCompleteCoreTokenTelemetry
630
+ ? (pricingBreakdown?.providerCostMicros ?? null)
631
+ : null;
632
+ const pricingSource = gatewayBilling
633
+ ? ("gateway_reported" as const)
634
+ : estimatedProviderCostMicros !== null
635
+ ? ("configured_list_price" as const)
636
+ : null;
637
+ // An externally billed turn is paid outside OpenGeni, so it
638
+ // consumes ZERO OpenGeni credits and must never feed an OpenGeni cap. A
639
+ // codex/<slug> model has no entry in configuredModelPricing, so the normal path
640
+ // below would throw "Missing model pricing". We:
641
+ // - do NOT emit the cap-feeding `model.tokens` event (ensureRunAllowed and
642
+ // the API tokens:consume cap sum `model.tokens` with NO cost dimension, so
643
+ // any row would count against maxMonthlyTokensPerWorkspace);
644
+ // - record a `model.cost = 0` audit marker (harmless to the monthly cost cap);
645
+ // - optionally calculate a non-charging provider estimate for Insights when
646
+ // core token telemetry is complete, but never debit credits.
647
+ if (input.externallyBilled) {
648
+ await recordUsageEvent(db, {
649
+ accountId: input.accountId,
650
+ workspaceId: input.workspaceId,
651
+ eventType: "model.cost",
652
+ quantity: 0,
653
+ unit: "usd_micros",
654
+ sourceResourceType: "model_response",
655
+ sourceResourceId: `${input.turnId}:${input.sourceKey}`,
656
+ sessionId: input.sessionId,
657
+ turnId: input.turnId,
658
+ turnAttemptId: input.turnAttemptId,
659
+ idempotencyKey: `usage:model.cost:${input.turnId}:${input.sourceKey}`,
660
+ });
661
+ return {
662
+ billingPath: "external",
663
+ pricedCostMicros: 0,
664
+ estimatedProviderCostMicros,
665
+ pricingSource,
666
+ normalizedUsage,
667
+ };
668
+ }
669
+ if (totalTokens > 0) {
670
+ await recordUsageEvent(db, {
671
+ accountId: input.accountId,
672
+ workspaceId: input.workspaceId,
673
+ eventType: "model.tokens",
674
+ quantity: totalTokens,
675
+ unit: "tokens",
676
+ sourceResourceType: "model_response",
677
+ sourceResourceId: `${input.turnId}:${input.sourceKey}`,
678
+ sessionId: input.sessionId,
679
+ turnId: input.turnId,
680
+ turnAttemptId: input.turnAttemptId,
681
+ idempotencyKey: `usage:model.tokens:${input.turnId}:${input.sourceKey}`,
682
+ });
683
+ }
684
+ const shouldDebit = settings.billingMode === "stripe" || settings.usageLimitsMode === "managed";
685
+ if (!shouldDebit || (totalTokens === 0 && !gatewayBilling)) {
686
+ return {
687
+ billingPath: "opengeni_credits",
688
+ pricedCostMicros: 0,
689
+ estimatedProviderCostMicros,
690
+ pricingSource,
691
+ normalizedUsage,
692
+ ...(gatewayBilling ? { upstreamProvider: gatewayBilling.finalProvider } : {}),
693
+ };
694
+ }
695
+ if (!pricingBreakdown) {
696
+ throw new Error(`Missing model pricing for ${input.model}`);
697
+ }
698
+ const costMicros = pricingBreakdown.creditCostMicros;
699
+ await recordUsageEvent(db, {
700
+ accountId: input.accountId,
701
+ workspaceId: input.workspaceId,
702
+ eventType: "model.cost",
703
+ quantity: costMicros,
704
+ unit: "usd_micros",
705
+ sourceResourceType: "model_response",
706
+ sourceResourceId: `${input.turnId}:${input.sourceKey}`,
707
+ sessionId: input.sessionId,
708
+ turnId: input.turnId,
709
+ turnAttemptId: input.turnAttemptId,
710
+ idempotencyKey: `usage:model.cost:${input.turnId}:${input.sourceKey}`,
711
+ });
712
+ if (costMicros > 0) {
713
+ const result = await applyCreditDebitUpToBalance(db, {
714
+ accountId: input.accountId,
715
+ workspaceId: input.workspaceId,
716
+ type: "model_usage_debit",
717
+ requestedAmountMicros: costMicros,
718
+ sourceType: "model_response",
719
+ sourceId: `${input.turnId}:${input.sourceKey}`,
720
+ idempotencyKey: `credit:model_usage_debit:${input.turnId}:${input.sourceKey}`,
721
+ metadata: {
722
+ model: input.model,
723
+ sessionId: input.sessionId,
724
+ turnId: input.turnId,
725
+ sourceKey: input.sourceKey,
726
+ latencyMode: input.latencyMode ?? "standard",
727
+ inputTokens,
728
+ outputTokens,
729
+ totalTokens,
730
+ // Additive: the prompt-cache slice of this call's input tokens, so the
731
+ // per-call debit record carries cache efficiency alongside the token
732
+ // counts. 0 when the provider did not report cached tokens.
733
+ cachedTokens: normalizedUsage.telemetry.cachedTokens ?? 0,
734
+ ...(gatewayBilling ? { gatewayProvider: gatewayBilling.finalProvider } : {}),
735
+ },
736
+ });
737
+ recordCreditMicros(input.observability, "usage", result.debitedMicros);
738
+ }
739
+ return {
740
+ billingPath: "opengeni_credits",
741
+ pricedCostMicros: costMicros,
742
+ estimatedProviderCostMicros,
743
+ pricingSource,
744
+ normalizedUsage,
745
+ ...(gatewayBilling ? { upstreamProvider: gatewayBilling.finalProvider } : {}),
746
+ };
747
+ }
748
+
749
+ /** Soft-fail Insights fact write — never throws into the billing/emit path. */
750
+ export async function recordAuthoritativeModelCallFact(input: {
751
+ db: ActivityServices["db"];
752
+ observability: ActivityServices["observability"];
753
+ accountId: string;
754
+ workspaceId: string;
755
+ sessionId: string;
756
+ turnId: string;
757
+ turnAttemptId: string;
758
+ sourceKey: string;
759
+ provider: string;
760
+ providerApi: ModelProviderApi;
761
+ model: string;
762
+ billing: ModelUsageBillingRecord;
763
+ contextContributions?: readonly ModelContextContributionSummary[] | null;
764
+ }): Promise<void> {
765
+ try {
766
+ const telemetry = input.billing.normalizedUsage.telemetry;
767
+ await recordModelCallFact(input.db, {
768
+ accountId: input.accountId,
769
+ workspaceId: input.workspaceId,
770
+ sessionId: input.sessionId,
771
+ turnId: input.turnId,
772
+ turnAttemptId: input.turnAttemptId,
773
+ sourceKey: input.sourceKey,
774
+ provider: input.billing.upstreamProvider ?? input.provider,
775
+ providerApi: input.providerApi,
776
+ model: input.model,
777
+ billingPath: input.billing.billingPath,
778
+ pricedCostMicros: input.billing.pricedCostMicros,
779
+ estimatedProviderCostMicros: input.billing.estimatedProviderCostMicros,
780
+ pricingSource: input.billing.pricingSource,
781
+ inputTokens: telemetry.inputTokens,
782
+ outputTokens: telemetry.outputTokens,
783
+ cachedTokens: telemetry.cachedTokens,
784
+ cacheWriteTokens: telemetry.cacheWriteTokens,
785
+ reasoningTokens: telemetry.reasoningTokens,
786
+ totalTokens: input.billing.normalizedUsage.totalTokens,
787
+ ...(input.contextContributions !== undefined
788
+ ? { contextContributions: input.contextContributions }
789
+ : {}),
790
+ });
791
+ } catch (error) {
792
+ input.observability.warn("model call fact persist failed", {
793
+ ...safeErrorDiagnostic(error),
794
+ });
795
+ }
796
+ }
797
+
798
+ export function sanitizedModelUsageInput(normalized: ModelCallUsageNormalization): ModelUsageInput {
799
+ return {
800
+ ...(normalized.telemetry.inputTokens !== null
801
+ ? { inputTokens: normalized.telemetry.inputTokens }
802
+ : {}),
803
+ ...(normalized.telemetry.outputTokens !== null
804
+ ? { outputTokens: normalized.telemetry.outputTokens }
805
+ : {}),
806
+ ...(normalized.totalTokens !== null ? { totalTokens: normalized.totalTokens } : {}),
807
+ ...(normalized.telemetry.cachedTokens !== null
808
+ ? {
809
+ inputTokensDetails: {
810
+ cached_tokens: normalized.telemetry.cachedTokens,
811
+ },
812
+ }
813
+ : {}),
814
+ ...(normalized.requestUsageEntries
815
+ ? { requestUsageEntries: normalized.requestUsageEntries }
816
+ : {}),
817
+ };
818
+ }
819
+
820
+ export function startOfUtcMonth(): Date {
821
+ const now = new Date();
822
+ return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
823
+ }