@harrym1707/sdk 0.0.0-stage → 0.2.1

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 (70) hide show
  1. package/LICENSE +98 -0
  2. package/README.md +48 -2
  3. package/bin/mesh-demo.mjs +105 -0
  4. package/bin/mesh-proxy.mjs +39 -0
  5. package/bin/mesh-quote.mjs +45 -0
  6. package/bin/mesh-report.mjs +47 -0
  7. package/index.cjs +6306 -0
  8. package/index.js +6204 -0
  9. package/package.json +39 -4
  10. package/types/blind-features.d.ts +28 -0
  11. package/types/cache-volatility-guard.d.ts +31 -0
  12. package/types/core/account-store.d.ts +7 -0
  13. package/types/core/accounts.d.ts +134 -0
  14. package/types/core/billing-worker.d.ts +113 -0
  15. package/types/core/budget.d.ts +216 -0
  16. package/types/core/cache-simulator.d.ts +271 -0
  17. package/types/core/confidence.d.ts +36 -0
  18. package/types/core/cost.d.ts +16 -0
  19. package/types/core/evaluator.d.ts +16 -0
  20. package/types/core/gateway.d.ts +75 -0
  21. package/types/core/geo-visibility.d.ts +25 -0
  22. package/types/core/github-oauth.d.ts +41 -0
  23. package/types/core/helicone.d.ts +6 -0
  24. package/types/core/index.d.ts +36 -0
  25. package/types/core/langfuse.d.ts +7 -0
  26. package/types/core/ledger-store.d.ts +62 -0
  27. package/types/core/litellm.d.ts +15 -0
  28. package/types/core/local-tier.d.ts +82 -0
  29. package/types/core/model-prices.d.ts +25 -0
  30. package/types/core/output-diagnostics.d.ts +39 -0
  31. package/types/core/price-catalogue.d.ts +168 -0
  32. package/types/core/provider-usage.d.ts +84 -0
  33. package/types/core/quote-report.d.ts +54 -0
  34. package/types/core/replay.d.ts +2 -0
  35. package/types/core/router.d.ts +9 -0
  36. package/types/core/routing.d.ts +282 -0
  37. package/types/core/savings-ledger.d.ts +349 -0
  38. package/types/core/savings-model.d.ts +132 -0
  39. package/types/core/stripe-billing.d.ts +67 -0
  40. package/types/core/stripe-client.d.ts +117 -0
  41. package/types/core/stripe-sink.d.ts +77 -0
  42. package/types/core/theo-coverage.d.ts +49 -0
  43. package/types/core/token-reduction.d.ts +219 -0
  44. package/types/core/tool-schema.d.ts +64 -0
  45. package/types/core/traffic.d.ts +182 -0
  46. package/types/core/triage.d.ts +70 -0
  47. package/types/core/types.d.ts +149 -0
  48. package/types/core/workflow-sessions.d.ts +50 -0
  49. package/types/cta.d.ts +60 -0
  50. package/types/evaluation-capture.d.ts +11 -0
  51. package/types/exact-cache.d.ts +20 -0
  52. package/types/graders.d.ts +53 -0
  53. package/types/index.d.ts +31 -0
  54. package/types/ledger-mirror.d.ts +38 -0
  55. package/types/openai.d.ts +23 -0
  56. package/types/proxy.d.ts +104 -0
  57. package/types/reduce-request.d.ts +272 -0
  58. package/types/replay-gate.d.ts +120 -0
  59. package/types/report.d.ts +33 -0
  60. package/types/routing.d.ts +11 -0
  61. package/types/savings-ledger.d.ts +22 -0
  62. package/types/savings-snapshot.d.ts +11 -0
  63. package/types/semantic-compaction.d.ts +84 -0
  64. package/types/telemetry.d.ts +6 -0
  65. package/types/theo-agent-store.d.ts +27 -0
  66. package/types/theo-agent.d.ts +247 -0
  67. package/types/theo-gate.d.ts +75 -0
  68. package/types/theo-policy.d.ts +219 -0
  69. package/types/types.d.ts +287 -0
  70. package/types/wrap.d.ts +60 -0
@@ -0,0 +1,271 @@
1
+ import { type TokenPrice } from "./cost.js";
2
+ import type { BillableEvent } from "./savings-ledger.js";
3
+ import { type TokenCounter } from "./token-reduction.js";
4
+ /**
5
+ * Provider prompt-cache simulator.
6
+ *
7
+ * Prefix caching is the largest lever MESH has, and on a fixture it was worth 29
8
+ * of 32 points. A claim that large cannot rest on a stub that simply says "the
9
+ * prefix was cached". This models the published rules, including the ones that
10
+ * make caching fail:
11
+ *
12
+ * - a minimum cacheable prefix (1,024 tokens on both providers; 2,048 on
13
+ * Claude Haiku), below which nothing caches at all
14
+ * - longest EXACT prefix matching, so one changed character early in the
15
+ * prompt discards everything after it
16
+ * - hit granularity (OpenAI grants hits in 128-token increments)
17
+ * - a time to live measured from last use, so traffic spread thinly over time
18
+ * never accumulates a hit rate
19
+ * - a write premium where the provider charges one (Anthropic bills a cache
20
+ * write at 1.25x base for the 5-minute TTL, 2x for the hour)
21
+ *
22
+ * The TTL is the honest part. A simulation that assumes every repeat hits will
23
+ * overstate caching badly for low-traffic workloads: with a 5-minute TTL and
24
+ * requests ten minutes apart, the cache never pays for itself and the write
25
+ * premium makes it worse than doing nothing. That outcome is reachable here.
26
+ *
27
+ * Sources: OpenAI's prompt-caching guide (automatic above 1,024 tokens, 128-token
28
+ * increments, longest exact prefix, 5-10 minutes of inactivity up to an hour) and
29
+ * Anthropic's (explicit breakpoints, 5-minute default TTL or 1 hour, writes at
30
+ * 1.25x or 2x base, reads at 0.1x).
31
+ */
32
+ export type CachePolicy = {
33
+ name: string;
34
+ /** Nothing below this caches at all. */
35
+ minimumCacheableTokens: number;
36
+ /** Hits are granted in whole multiples of this many tokens. */
37
+ incrementTokens: number;
38
+ /** Entry is dropped after this long without being used. */
39
+ ttlSeconds: number;
40
+ /** Charge for writing a prefix, as a multiple of the base input rate. */
41
+ writeMultiplier: number;
42
+ /** Charge for reading a cached prefix, as a multiple of the base input rate. */
43
+ readMultiplier: number;
44
+ };
45
+ /** Automatic, no write premium, hits in 128-token steps. */
46
+ export declare const OPENAI_CACHE: CachePolicy;
47
+ /** Explicit breakpoints, 5-minute TTL, writes at 1.25x base. */
48
+ export declare const ANTHROPIC_CACHE_5M: CachePolicy;
49
+ /**
50
+ * Anthropic with NO cache_control placed: the cache is opt-in, so nothing
51
+ * caches and every token bills at the full input rate. This is the measured
52
+ * reality of unstamped Claude traffic (the first live export recorded a
53
+ * five-turn agent with zero cache reads and zero writes), and therefore the
54
+ * honest baseline for valuing a MESH-placed stamp.
55
+ */
56
+ export declare const ANTHROPIC_NO_CACHE: CachePolicy;
57
+ /** The hour-long TTL, which doubles the write charge. */
58
+ export declare const ANTHROPIC_CACHE_1H: CachePolicy;
59
+ export type SimulatedRequest = {
60
+ /** Seconds since the run began. Drives TTL expiry. */
61
+ atSeconds: number;
62
+ /** The exact prompt text the provider would see, in order. */
63
+ prompt: string;
64
+ /** Output tokens the model produced, for costing. */
65
+ outputTokens: number;
66
+ };
67
+ export type SimulatedCall = {
68
+ atSeconds: number;
69
+ totalInputTokens: number;
70
+ cachedInputTokens: number;
71
+ writtenInputTokens: number;
72
+ freshInputTokens: number;
73
+ outputTokens: number;
74
+ costUsd: number;
75
+ /** Why nothing was cached, when nothing was. */
76
+ missReason?: "below-minimum" | "no-matching-prefix" | "expired" | "first-request";
77
+ };
78
+ export type SimulationResult = {
79
+ policy: string;
80
+ calls: SimulatedCall[];
81
+ totalCostUsd: number;
82
+ /** What the same traffic would cost with caching unavailable. */
83
+ uncachedCostUsd: number;
84
+ savingUsd: number;
85
+ savingPercent: number;
86
+ totalInputTokens: number;
87
+ cachedInputTokens: number;
88
+ /** Share of input tokens served from cache. */
89
+ hitRate: number;
90
+ expiries: number;
91
+ missReasons: Record<string, number>;
92
+ };
93
+ /**
94
+ * Run a request stream against a cache policy and price it.
95
+ *
96
+ * Deliberately pessimistic where the published behaviour is a range: the
97
+ * shorter documented TTL is used, and a prefix must clear the minimum AFTER
98
+ * being rounded down to the policy's increment.
99
+ */
100
+ export declare function simulateCache(requests: SimulatedRequest[], policy: CachePolicy, price: TokenPrice, options?: {
101
+ countTokens?: TokenCounter;
102
+ }): SimulationResult;
103
+ /**
104
+ * Context compaction, priced.
105
+ *
106
+ * An agent loop re-sends its whole transcript every turn, so the API bill grows
107
+ * with the square of the session. Harnesses fight that by COMPACTING: at some
108
+ * turn they throw the transcript away and replace it with a short summary, so
109
+ * the prefix shrinks and growth restarts from a smaller base.
110
+ *
111
+ * The move is not free, and the cost that hides from a naive token count is the
112
+ * one caching imposes. Prefix caching already defeats most of the quadratic tax
113
+ * on its own: once a transcript is cached, every later turn READS it at 0.1x and
114
+ * writes only the new tail. Compaction discards that cached prefix — the summary
115
+ * does not match the bytes it replaced, so the longest-exact-prefix match
116
+ * collapses to the stable system block, and everything after it is re-written at
117
+ * the full (or write-premium) rate. That rewrite, plus the one-off summarisation
118
+ * call that reads the transcript to produce the summary, is the price of
119
+ * compaction. It only pays back if the session runs long enough afterwards for
120
+ * the smaller prefix to save more than the rewrite cost.
121
+ *
122
+ * The counter-intuitive, and therefore worth-proving, result this models: under
123
+ * a WARM cache and fast turns, compaction can be a net LOSS, because the thing
124
+ * it shrinks was already being read at a tenth of its price. It wins when the
125
+ * cache is cold — slow human-in-the-loop turns that expire the TTL, or traffic
126
+ * with no cache_control placed at all — where the transcript really is re-sent
127
+ * at full price every turn. Both regimes are reachable here by choice of policy
128
+ * and turn spacing.
129
+ */
130
+ export type AgentSessionSpec = {
131
+ /** The stable system + tool block that leads every turn. Cached, never rewritten. */
132
+ systemPromptTokens: number;
133
+ /** How many model calls the session makes. */
134
+ turns: number;
135
+ /** New transcript appended before each turn (user message + tool results). */
136
+ userTurnTokens: number;
137
+ /** Model output each turn, which becomes input on the next turn. */
138
+ assistantTurnTokens: number;
139
+ /** Seconds between turns. Long gaps expire the cache TTL and change the verdict. */
140
+ secondsPerTurn: number;
141
+ };
142
+ export type CompactionSpec = {
143
+ /** The turn (1-based) whose prompt is the first to carry the summary. */
144
+ atTurn: number;
145
+ /** Size of the summary that replaces the discarded transcript. */
146
+ summaryTokens: number;
147
+ /**
148
+ * Charge the one-off call that reads the transcript to write the summary.
149
+ * Defaults to true; set false to isolate the cache-invalidation cost alone.
150
+ */
151
+ chargeSummarizationCall?: boolean;
152
+ };
153
+ export type CompactionEconomics = {
154
+ compactionTurn: number;
155
+ summaryTokens: number;
156
+ /** The session run straight through, no compaction. */
157
+ baseline: SimulationResult;
158
+ /** The same session with the transcript compacted at `compactionTurn`. */
159
+ withCompaction: SimulationResult;
160
+ /**
161
+ * The cache penalty of the compaction event, isolated from its size effect:
162
+ * the compaction turn's actual cost minus what that same prompt would have
163
+ * cost if every token had been served from cache. Always >= 0 — it is the
164
+ * price of the prefix collapsing to the system block on that one turn.
165
+ */
166
+ cacheInvalidationCostUsd: number;
167
+ /** Cost of the one-off call that reads the transcript to write the summary (0 if not charged). */
168
+ summarizationCostUsd: number;
169
+ /** baseline total minus compacted total. Positive means compaction paid off. */
170
+ netSavingUsd: number;
171
+ savingPercent: number;
172
+ worthwhile: boolean;
173
+ /**
174
+ * Turns after the compaction point before compaction turns net-positive, or
175
+ * null if it never does within the session's length.
176
+ */
177
+ breakEvenTurns: number | null;
178
+ };
179
+ /**
180
+ * Build a turn-by-turn agent session as a request stream, with the transcript
181
+ * growing by one segment each turn. With a `compaction`, turns from `atTurn`
182
+ * on lead with a summary in place of the discarded transcript, and (unless
183
+ * disabled) a summarisation call is inserted just before that turn.
184
+ */
185
+ export declare function buildAgentSession(spec: AgentSessionSpec, compaction?: CompactionSpec, options?: {
186
+ countTokens?: TokenCounter;
187
+ }): SimulatedRequest[];
188
+ /**
189
+ * Price a compaction decision: run the session with and without it under the
190
+ * same cache policy, and decompose the difference into the cache-invalidation
191
+ * cost, the summarisation cost, the net saving and the break-even horizon.
192
+ */
193
+ export declare function estimateCompactionEconomics(spec: AgentSessionSpec, compaction: CompactionSpec, policy: CachePolicy, price: TokenPrice, options?: {
194
+ countTokens?: TokenCounter;
195
+ }): CompactionEconomics;
196
+ /**
197
+ * Compaction economics computed from the ledger instead of a synthetic session.
198
+ *
199
+ * The ledger keeps no prompt text — only provider-verbatim token counts — so
200
+ * the string prefix model above cannot run on it. It does not need to: the
201
+ * ledger already records what the cache DID (cachedInputTokens per turn), so the
202
+ * realized per-turn input rate is known, and compaction can be priced as the
203
+ * removal of context from later turns valued at that realized rate.
204
+ *
205
+ * What compaction removes is a fixed block. Replacing the history accumulated by
206
+ * the compaction point with a shorter summary drops the same
207
+ * `context_before - preserved_prefix - summary` tokens from EVERY later turn's
208
+ * input. Those removed tokens are exactly the stable, repeated prefix — the part
209
+ * the provider was most likely serving from cache — so on a turn where the
210
+ * ledger shows cache reads they are valued at the cached rate, not the full
211
+ * one. That is a deliberate under-claim on cache-heavy traffic (the ledger's own
212
+ * convention): compaction is credited only with what the removed tokens actually
213
+ * cost, which on a warm cache is a tenth of their face value. The one-off
214
+ * summarisation call is charged at the FULL input rate, against compaction, so
215
+ * the net never flatters the lever.
216
+ */
217
+ /** One turn of a task, projected from a recorded ledger event to just what pricing needs. */
218
+ export type LedgerTurn = {
219
+ taskId?: string;
220
+ turnIndex: number;
221
+ /** For ordering turns that share a turnIndex; optional. */
222
+ timestampMs?: number;
223
+ inputTokens: number;
224
+ outputTokens: number;
225
+ cachedInputTokens: number;
226
+ };
227
+ export type LedgerCompactionSpec = {
228
+ /** The turn (1-based, within the task) that first carries the summary. */
229
+ atTurn: number;
230
+ /** Size of the summary that replaces the discarded history. */
231
+ summaryTokens: number;
232
+ /**
233
+ * The always-present prefix (system + tools) compaction keeps verbatim.
234
+ * Defaults to the smallest input seen in the task — a safe lower bound that,
235
+ * if anything, under-states what is removed and so under-claims the saving.
236
+ */
237
+ preservedPrefixTokens?: number;
238
+ };
239
+ export type LedgerCompactionEstimate = {
240
+ taskId?: string;
241
+ turns: number;
242
+ compactionTurn: number;
243
+ summaryTokens: number;
244
+ preservedPrefixTokens: number;
245
+ /** Tokens dropped from every post-compaction turn's input. */
246
+ removedTokensPerTurn: number;
247
+ postCompactionTurns: number;
248
+ /** Full task cost as recorded (sum of each turn priced at its realized usage). */
249
+ recordedCostUsd: number;
250
+ /** One-off cost of producing the summary, charged at the full input rate. */
251
+ summarizationCostUsd: number;
252
+ /** Realized value of the context compaction removes, summed over later turns. */
253
+ grossSavingUsd: number;
254
+ netSavingUsd: number;
255
+ savingPercent: number;
256
+ worthwhile: boolean;
257
+ /** Turns after the compaction point before the one-off cost is repaid, or null. */
258
+ breakEvenTurns: number | null;
259
+ };
260
+ /**
261
+ * Project recorded ledger events into per-task turn streams: keep the succeeded
262
+ * events that carry usage, group them by taskId, and order each group by turn.
263
+ * Events with no taskId are each treated as their own single-turn task.
264
+ */
265
+ export declare function ledgerTurnsByTask(events: readonly BillableEvent[]): Map<string, LedgerTurn[]>;
266
+ /**
267
+ * Price a compaction decision from a single task's recorded turns. `price` is
268
+ * the resolved catalogue rate for the task's model (look it up with
269
+ * `priceUsage` / `lookupPrice` and pass `.price`).
270
+ */
271
+ export declare function estimateCompactionFromLedger(turns: readonly LedgerTurn[], compaction: LedgerCompactionSpec, price: TokenPrice): LedgerCompactionEstimate;
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Confidence bounds for savings claims.
3
+ *
4
+ * Homed in core because every part of MESH that asserts "quality held" needs the
5
+ * same bound: the offline benchmark, and the replay gate that decides whether a
6
+ * lossy reduction may be switched on for real traffic. One implementation, so
7
+ * the statistics behind an invoice cannot drift from the statistics behind a
8
+ * benchmark.
9
+ */
10
+ export declare function mean(values: number[]): number;
11
+ /** Deterministic PRNG, so a bound is reproducible from its seed. */
12
+ export declare function seededRandom(seed: string): () => number;
13
+ /**
14
+ * Lower confidence bound on a mean, resampling whole groups.
15
+ *
16
+ * Groups matter: several records can come from one prompt or one task, and
17
+ * treating them as independent understates the spread and overstates the bound.
18
+ */
19
+ export declare function groupBootstrapLowerBound(deltas: number[], groups: string[], samples: number, seed: string, alpha?: number): number;
20
+ /**
21
+ * Simultaneous lower bounds across every candidate configuration.
22
+ *
23
+ * Scoring many candidates on one sample and keeping the best biases that winner
24
+ * upward: a per-candidate bound holds for a configuration chosen in advance, not
25
+ * for the maximum over a search. Measured on MMLU-Pro, the uncorrected bound let
26
+ * configurations through that then lost up to 3.26 pp on held-out data while
27
+ * reporting a safe bound.
28
+ *
29
+ * Groups are resampled once per draw and every candidate scored on that same
30
+ * resample, so candidates stay correlated as they are in truth. Each deviation
31
+ * is then divided by that candidate's own bootstrap standard error before the
32
+ * maximum is taken. Studentising is not optional: an unscaled maximum lets
33
+ * whichever candidate is noisiest set the band for the most precise one, which
34
+ * was tried first and was wrong.
35
+ */
36
+ export declare function simultaneousGroupBootstrapLowerBounds(deltasByConfiguration: number[][], groups: string[], samples: number, seed: string, alpha?: number): number[];
@@ -0,0 +1,16 @@
1
+ export type TokenPrice = {
2
+ inputPerMillion: number;
3
+ cachedInputPerMillion?: number;
4
+ /** Cache writes at the default (5m) TTL; Anthropic bills 1.25x base input. */
5
+ cacheWriteInputPerMillion?: number;
6
+ /** Cache writes at the 1h TTL; Anthropic bills 2x base input. */
7
+ cacheWrite1hInputPerMillion?: number;
8
+ outputPerMillion: number;
9
+ };
10
+ export declare function estimateTokenCost(inputTokens: number, outputTokens: number, price: TokenPrice, cacheUsage?: {
11
+ cachedInputTokens?: number;
12
+ /** TOTAL cache writes, inclusive of any 1h share below. */
13
+ cacheWriteInputTokens?: number;
14
+ /** The share of the writes above that carried the 1h TTL. */
15
+ cacheWrite1hInputTokens?: number;
16
+ }): number;
@@ -0,0 +1,16 @@
1
+ import type { EvaluationInput, Evaluator, QualityPolicy, QualityResult } from "./types.js";
2
+ /**
3
+ * Apply a quality policy to a measured result, returning the result with
4
+ * `passed` narrowed to whether every requirement is met.
5
+ *
6
+ * The error-rate and latency ceilings are fail-closed: a ceiling the result
7
+ * does not actually measure cannot be certified as met, so an unmeasured
8
+ * `maxErrorRate` or `maxLatencyMs` fails the gate rather than silently passing.
9
+ * This closes the "never silently reduce quality" hole where a candidate gated
10
+ * on error rate or latency would otherwise clear a gate it never proved.
11
+ */
12
+ export declare function applyQualityPolicy(result: QualityResult, policy: QualityPolicy): QualityResult;
13
+ export declare class ExactMatchEvaluator implements Evaluator {
14
+ name: string;
15
+ evaluate(input: EvaluationInput): Promise<QualityResult>;
16
+ }
@@ -0,0 +1,75 @@
1
+ import { type PriceCatalogue } from "./price-catalogue.js";
2
+ import type { IngestIssue, TrafficMeasurement, TrafficRecord } from "./traffic.js";
3
+ import type { StreamSignals } from "./triage.js";
4
+ /**
5
+ * The shared gateway layer every adapter feeds.
6
+ *
7
+ * LiteLLM, Helicone and Langfuse log different schemas, but the triage engine
8
+ * needs one shape: a traffic record plus the three things only a gateway or
9
+ * tracer knows (what it thinks the row cost, who the request was for, and
10
+ * whether its own cache answered). Each adapter is ~150 lines of field
11
+ * mapping; everything downstream - reconciliation, signals, classification,
12
+ * quoting - is written once here and in triage.ts, so a finding fixed for one
13
+ * connector is fixed for all of them.
14
+ */
15
+ export type GatewayRecord = {
16
+ record: TrafficRecord;
17
+ /** The tool's own cost figure for the row, as logged. */
18
+ reportedSpendUsd?: number;
19
+ /** The downstream customer the request was made for. */
20
+ endUser?: string;
21
+ teamId?: string;
22
+ };
23
+ export type GatewayParseResult = {
24
+ /** Rows that reached a provider; the analysable baseline. */
25
+ accepted: GatewayRecord[];
26
+ /**
27
+ * Rows the tool's own response cache answered. Not baseline: no provider
28
+ * call happened, and counting the would-have-been cost would claim a saving
29
+ * the customer's own stack already delivers.
30
+ */
31
+ cacheHits: GatewayRecord[];
32
+ issues: IngestIssue[];
33
+ };
34
+ export type SpendReconciliation = {
35
+ /** Rows where both a reported spend and a catalogue price existed. */
36
+ comparedRows: number;
37
+ reportedSpendUsd: number;
38
+ catalogueCostUsd: number;
39
+ /** Positive when the tool reports more spend than published rates support. */
40
+ driftPercent: number;
41
+ /** Rows whose reported spend deviates more than the tolerance. */
42
+ flagged: Array<{
43
+ id: string;
44
+ model: string;
45
+ reportedUsd: number;
46
+ catalogueUsd: number;
47
+ driftPercent: number;
48
+ }>;
49
+ /** Rows whose model the catalogue cannot price; excluded, never zeroed. */
50
+ unpricedRows: number;
51
+ /** What the tool's own response cache already saves, at catalogue rates. */
52
+ cacheHitRows: number;
53
+ cacheHitSavedUsd: number;
54
+ };
55
+ /**
56
+ * Reconcile a tool's reported spend against the dated price catalogue.
57
+ *
58
+ * A persistent drift means one of the two price sources is stale, and either
59
+ * way the customer's dashboards are wrong by that much. Rows already arriving
60
+ * provider-cached are priced at the cached rate, so a correct gateway figure
61
+ * is not flagged merely because caching made the true cost lower.
62
+ */
63
+ export declare function reconcileGatewaySpend(parsed: GatewayParseResult, catalogue: PriceCatalogue, options?: {
64
+ tolerancePercent?: number;
65
+ }): SpendReconciliation;
66
+ /**
67
+ * Derive segment-classification signals for one traffic stream.
68
+ *
69
+ * The measurement supplies what usage alone can show; the gateway extras add
70
+ * the dimensions only it knows: who each request was for, and how often its
71
+ * own response cache already answers.
72
+ */
73
+ export declare function signalsFromGateway(stream: GatewayRecord[], cacheHits: GatewayRecord[], measurement: TrafficMeasurement): StreamSignals;
74
+ /** Group parsed gateway rows into streams by the workload the tool tagged. */
75
+ export declare function groupByStream(entries: GatewayRecord[]): Map<string, GatewayRecord[]>;
@@ -0,0 +1,25 @@
1
+ export type GeoObservation = {
2
+ engine: string;
3
+ promptId: string;
4
+ timestamp: string;
5
+ mentioned: boolean;
6
+ cited?: boolean;
7
+ linked?: boolean;
8
+ correctDescription?: boolean;
9
+ categoryAssociated?: boolean;
10
+ competitorMentions?: string[];
11
+ citedDomains?: string[];
12
+ };
13
+ export type GeoVisibilityMetrics = {
14
+ observations: number;
15
+ mentions: number;
16
+ mentionRate: number;
17
+ citations: number;
18
+ citationRate: number;
19
+ links: number;
20
+ linkRate: number;
21
+ correctDescriptionRate: number | null;
22
+ categoryAssociationRate: number | null;
23
+ };
24
+ export declare function calculateGeoVisibilityMetrics(observations: GeoObservation[]): GeoVisibilityMetrics;
25
+ export declare function calculateGeoVisibilityByEngine(observations: GeoObservation[]): Record<string, GeoVisibilityMetrics>;
@@ -0,0 +1,41 @@
1
+ import type { GithubIdentity } from "./accounts.js";
2
+ /**
3
+ * GitHub OAuth — the one identity step in signup. First login auto-creates the
4
+ * account (no approval), so this module only needs to (a) build the authorize
5
+ * URL, (b) issue and verify a stateless CSRF `state`, and (c) exchange the
6
+ * returned code for a stable GitHub identity.
7
+ *
8
+ * The `state` is an HMAC-signed `nonce.timestamp` rather than server-side
9
+ * session storage, so the API stays stateless and horizontally scalable. The
10
+ * fetch calls are injectable so the whole exchange is unit-testable with no
11
+ * network.
12
+ *
13
+ * Only identity is read: numeric GitHub id (stable across renames), login, and
14
+ * a verified primary email when the user has shared one. The short-lived access
15
+ * token is used for those two reads and then discarded — never stored.
16
+ */
17
+ export type GithubOAuthConfig = {
18
+ clientId: string;
19
+ clientSecret: string;
20
+ /** Where GitHub redirects back with the code; must match the OAuth app setting. */
21
+ redirectUri: string;
22
+ /** Secret for signing the stateless `state` token. */
23
+ stateSecret: string;
24
+ /** Scopes requested. Default: read:user user:email (identity + email only). */
25
+ scope?: string;
26
+ };
27
+ /** Mint a signed, time-stamped CSRF state token. */
28
+ export declare function createOAuthState(secret: string, now?: number): string;
29
+ /** Verify a state token's signature and freshness (constant-time on the signature). */
30
+ export declare function verifyOAuthState(secret: string, state: string, now?: number, maxAgeMs?: number): boolean;
31
+ /** Build the GitHub authorize URL a browser is redirected to. Pure. */
32
+ export declare function buildAuthorizeUrl(config: GithubOAuthConfig, state: string): string;
33
+ export type OAuthFetch = typeof fetch;
34
+ /**
35
+ * Exchange an authorization code for a GitHub identity: swap code → access
36
+ * token, then read the user and their verified primary email. The token never
37
+ * leaves this function.
38
+ */
39
+ export declare function exchangeCodeForIdentity(config: GithubOAuthConfig, code: string, deps?: {
40
+ fetch?: OAuthFetch;
41
+ }): Promise<GithubIdentity>;
@@ -0,0 +1,6 @@
1
+ import type { GatewayParseResult } from "./gateway.js";
2
+ /**
3
+ * Parse Helicone request rows from /v1/request/query output or a CSV-to-JSON
4
+ * export. Rows that cannot be read are reported, never dropped silently.
5
+ */
6
+ export declare function parseHeliconeRequests(rows: unknown[], fallbackDate: string): GatewayParseResult;
@@ -0,0 +1,36 @@
1
+ export * from "./types.js";
2
+ export * from "./router.js";
3
+ export * from "./routing.js";
4
+ export * from "./evaluator.js";
5
+ export * from "./cost.js";
6
+ export * from "./confidence.js";
7
+ export * from "./cache-simulator.js";
8
+ export * from "./price-catalogue.js";
9
+ export * from "./token-reduction.js";
10
+ export * from "./tool-schema.js";
11
+ export * from "./savings-model.js";
12
+ export * from "./theo-coverage.js";
13
+ export * from "./savings-ledger.js";
14
+ export * from "./workflow-sessions.js";
15
+ export * from "./quote-report.js";
16
+ export * from "./traffic.js";
17
+ export * from "./triage.js";
18
+ export * from "./gateway.js";
19
+ export * from "./litellm.js";
20
+ export * from "./helicone.js";
21
+ export * from "./langfuse.js";
22
+ export * from "./model-prices.js";
23
+ export * from "./replay.js";
24
+ export * from "./provider-usage.js";
25
+ export * from "./stripe-sink.js";
26
+ export * from "./geo-visibility.js";
27
+ export * from "./output-diagnostics.js";
28
+ export * from "./stripe-billing.js";
29
+ export * from "./budget.js";
30
+ export * from "./security/index.js";
31
+ export * from "./accounts.js";
32
+ export * from "./account-store.js";
33
+ export * from "./ledger-store.js";
34
+ export * from "./github-oauth.js";
35
+ export * from "./stripe-client.js";
36
+ export * from "./billing-worker.js";
@@ -0,0 +1,7 @@
1
+ import type { GatewayParseResult } from "./gateway.js";
2
+ /**
3
+ * Parse Langfuse generation rows from the public API or an export. Rows that
4
+ * are not generations (spans, events) are skipped silently; rows that are
5
+ * generations but unreadable are reported.
6
+ */
7
+ export declare function parseLangfuseGenerations(rows: unknown[], fallbackDate: string): GatewayParseResult;
@@ -0,0 +1,62 @@
1
+ import { type LedgerRecord } from "./savings-ledger.js";
2
+ /**
3
+ * Server-side ledger storage with chain-verification-on-ingest.
4
+ *
5
+ * The proxy/SDK mirrors each hash-chained record it writes locally to the Mesh
6
+ * API; this is where the API stores it, per account, in an append-only JSONL
7
+ * spool. The one rule that makes "recompute it yourself" a guarantee rather
8
+ * than a promise: a record is stored ONLY if it is self-consistent AND
9
+ * continues the account's existing chain. A perturbed, forked, or gapped batch
10
+ * is a hard reject — it is never partially stored and never silently repaired.
11
+ *
12
+ * The mirror is fire-and-forget with retry, so the same records arrive more
13
+ * than once. Ingestion is therefore idempotent: records at or below the stored
14
+ * tail are recognised as replays and skipped (with a fork check against the
15
+ * tail), and only the genuine continuation is appended.
16
+ */
17
+ /** The last stored record's position, all the store needs to extend the chain. */
18
+ export type LedgerTail = {
19
+ seq: number;
20
+ eventHash: string;
21
+ };
22
+ export type IngestVerification = {
23
+ ok: true;
24
+ /** Records beyond the current tail that should be appended, in order. */
25
+ newRecords: LedgerRecord[];
26
+ /** Leading records recognised as already-stored replays. */
27
+ skipped: number;
28
+ /** The tail after appending newRecords. */
29
+ tail: LedgerTail;
30
+ } | {
31
+ ok: false;
32
+ reason: string;
33
+ seq: number;
34
+ };
35
+ /**
36
+ * Verify that `records` form a valid continuation of `tail` (undefined = empty
37
+ * chain, starting at genesis). Pure: no I/O, so the whole accept/replay/reject
38
+ * decision is unit-testable. Allows a leading overlap of already-stored
39
+ * sequences (idempotent retries) and rejects any gap, fork, or tampered hash.
40
+ */
41
+ export declare function verifyIngestBatch(tail: LedgerTail | undefined, records: readonly LedgerRecord[]): IngestVerification;
42
+ export type LedgerIngestResult = {
43
+ ok: true;
44
+ stored: number;
45
+ skipped: number;
46
+ tailSeq: number;
47
+ } | {
48
+ ok: false;
49
+ reason: string;
50
+ seq: number;
51
+ };
52
+ export interface LedgerStore {
53
+ append(accountId: string, records: readonly LedgerRecord[]): LedgerIngestResult;
54
+ readRecords(accountId: string): LedgerRecord[];
55
+ tail(accountId: string): LedgerTail | undefined;
56
+ }
57
+ /**
58
+ * File-backed ledger store: one append-only JSONL spool per account under
59
+ * `<dir>/<accountId>.jsonl`. Tails are cached in memory and lazily resumed from
60
+ * the spool, so a server restart picks the chain up where it left off.
61
+ */
62
+ export declare function openFileLedgerStore(dir: string): LedgerStore;
@@ -0,0 +1,15 @@
1
+ import { reconcileGatewaySpend, signalsFromGateway, type GatewayParseResult, type GatewayRecord } from "./gateway.js";
2
+ export type LiteLLMRecord = GatewayRecord;
3
+ export type LiteLLMParseResult = GatewayParseResult;
4
+ /**
5
+ * Parse LiteLLM spend-log rows, from /spend/logs output, a database export, or
6
+ * a StandardLoggingPayload stream. Rows that cannot be read are reported, never
7
+ * dropped silently.
8
+ */
9
+ export declare function parseLiteLLMSpendLogs(rows: unknown[], fallbackDate: string): LiteLLMParseResult;
10
+ /**
11
+ * Reconciliation and signal derivation are shared across every connector; see
12
+ * gateway.ts. Re-exported under the LiteLLM names existing callers use.
13
+ */
14
+ export declare const reconcileLiteLLMSpend: typeof reconcileGatewaySpend;
15
+ export declare const signalsFromLiteLLM: typeof signalsFromGateway;