@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,132 @@
1
+ import { type TokenPrice } from "./cost.js";
2
+ /**
3
+ * Composable cost-reduction model.
4
+ *
5
+ * A single lever looks unimpressive. Model routing on LLMRouterBench's MMLU-Pro
6
+ * returned 9.73% and bought it with quality. The levers below are different in
7
+ * two ways: most of them do not touch the answer, and they attack disjoint parts
8
+ * of a request, so they compose rather than compete.
9
+ *
10
+ * A request is modelled as segments, because each lever only reaches some of
11
+ * them. Tool-schema minification cannot help a RAG prompt with no tools, and
12
+ * prefix caching cannot help the one segment that changes every request. Summing
13
+ * headline percentages across levers double-counts; applying them to the
14
+ * segments they actually target does not.
15
+ *
16
+ * Order matters and is fixed: reducers shrink segments first, then caching prices
17
+ * whatever stable tokens remain. Minifying a tool catalogue and then caching it
18
+ * must charge the cache rate on the minified size, not the original.
19
+ *
20
+ * Every lever carries the published evidence for its reduction factor. Those
21
+ * factors come from their authors' benchmarks, not from MESH measuring them on
22
+ * your traffic, so a projection from this model is a hypothesis to verify by
23
+ * replay, never a realised saving. Realised savings come from provider-reported
24
+ * usage priced through the catalogue.
25
+ */
26
+ export type WorkloadSegment = "toolSchemas" | "systemPrompt" | "retrievedContext" | "history" | "userTurn" | "output";
27
+ export declare const INPUT_SEGMENTS: readonly WorkloadSegment[];
28
+ /**
29
+ * How confident a saving is before it is measured on the customer's own traffic.
30
+ *
31
+ * - `deterministic`: the request is provably equivalent, or the provider bills
32
+ * the same tokens at a lower rate. Nothing about the answer can change.
33
+ * - `needs-verification`: the prompt or the output budget changes, so quality
34
+ * has to be shown to hold by replay before the lever is enabled.
35
+ */
36
+ export type LeverRisk = "deterministic" | "needs-verification";
37
+ export type LeverEvidence = {
38
+ /** Where the reduction factor comes from. */
39
+ source: string;
40
+ /** What that source measured, in its own terms. */
41
+ claim: string;
42
+ };
43
+ export type Lever = {
44
+ id: string;
45
+ description: string;
46
+ risk: LeverRisk;
47
+ /** Segments this lever can reach; it has no effect on any other. */
48
+ targets: readonly WorkloadSegment[];
49
+ /** Share of targeted tokens removed, between 0 and 1. */
50
+ reduction: number;
51
+ /**
52
+ * How this lever changes the number of calls a task takes. 1 leaves it
53
+ * unchanged, 1.5 adds half a round trip per existing one, 0.3 removes most of
54
+ * them. Above 1 can make a lever net negative however much it trims per
55
+ * prompt, which is the whole reason this field exists: a published bench found
56
+ * progressive disclosure modelled at ~77% delivering ~13%, because the router
57
+ * it adds costs one extra round trip per novel tool call.
58
+ */
59
+ roundTripMultiplier?: number;
60
+ evidence: LeverEvidence;
61
+ };
62
+ export type WorkloadProfile = {
63
+ name: string;
64
+ /** Requests the projection covers; caching needs more than one to pay off. */
65
+ requests: number;
66
+ /** Mean tokens per request in each segment. */
67
+ segments: Record<WorkloadSegment, number>;
68
+ /**
69
+ * Segments byte-identical across requests, so a provider's prefix cache can
70
+ * serve them. Order is the prompt order: caching stops at the first segment
71
+ * that changes, so anything listed after a volatile segment cannot cache.
72
+ */
73
+ stableSegments: readonly WorkloadSegment[];
74
+ };
75
+ export type LeverContribution = {
76
+ lever: string;
77
+ risk: LeverRisk;
78
+ tokensRemoved: number;
79
+ costRemovedUsd: number;
80
+ /** Share of the baseline bill this lever alone removes, given the levers before it. */
81
+ sharePercent: number;
82
+ evidence: LeverEvidence;
83
+ };
84
+ export type SavingsProjection = {
85
+ workload: string;
86
+ requests: number;
87
+ baselineCostUsd: number;
88
+ projectedCostUsd: number;
89
+ savingUsd: number;
90
+ savingPercent: number;
91
+ /** The share achievable without any possibility of changing an answer. */
92
+ deterministicSavingPercent: number;
93
+ /** The additional share that requires a replay check before rollout. */
94
+ needsVerificationSavingPercent: number;
95
+ contributions: LeverContribution[];
96
+ inputTokensBefore: number;
97
+ inputTokensAfter: number;
98
+ outputTokensBefore: number;
99
+ outputTokensAfter: number;
100
+ cachedInputTokens: number;
101
+ /** Calls per task before any lever. */
102
+ roundTripsBefore: number;
103
+ /** Calls per task after every lever's effect on call count. */
104
+ roundTripsAfter: number;
105
+ warnings: string[];
106
+ };
107
+ /**
108
+ * Published levers, with the evidence for each factor.
109
+ *
110
+ * Factors are deliberately set at or below the conservative end of what each
111
+ * source reports. A model that projects a vendor's best-case number is the thing
112
+ * this project exists to argue against.
113
+ */
114
+ export declare const PUBLISHED_LEVERS: Record<string, Lever>;
115
+ /**
116
+ * Project the cost of a workload after a set of levers.
117
+ *
118
+ * Caching is applied last and only to stable segments that remain contiguous
119
+ * from the start of the prompt, because providers match on an exact prefix: the
120
+ * first segment that varies ends the cacheable region regardless of what follows.
121
+ */
122
+ export declare function projectSavings(profile: WorkloadProfile, levers: Lever[], price: TokenPrice, options?: {
123
+ minimumCacheableTokens?: number;
124
+ }): SavingsProjection;
125
+ /**
126
+ * Workload shapes the levers behave very differently on. The headline number a
127
+ * customer sees depends far more on which of these they are than on anything
128
+ * MESH does, which is why one global percentage would be misleading.
129
+ */
130
+ export declare const WORKLOAD_ARCHETYPES: Record<string, WorkloadProfile>;
131
+ /** Levers applicable to a profile, in the order they should be applied. */
132
+ export declare function leversFor(profile: WorkloadProfile): Lever[];
@@ -0,0 +1,67 @@
1
+ import type { Invoice } from "./savings-ledger.js";
2
+ /**
3
+ * Turning a recomputed MESH invoice into a Stripe charge — the honest way.
4
+ *
5
+ * This module is PURE: it converts an `Invoice` (the output of
6
+ * `recomputeInvoice`, itself a pure function over the customer's own
7
+ * hash-chained ledger) into a `StripeInvoicePlan` — the exact set of Stripe API
8
+ * calls that would bill it. No network here; the executor (mesh-bill script)
9
+ * runs the plan. Keeping it pure means the billing arithmetic is unit-tested
10
+ * without touching Stripe, and the plan can be shown to a human before anything
11
+ * is created.
12
+ *
13
+ * The invariants that matter for a verified-savings vendor:
14
+ * - A broken/unverified ledger NEVER bills. verdict carries DO_NOT_BILL.
15
+ * - A non-positive net period bills nothing (do_not_charge), and a carried
16
+ * deficit is surfaced, never hidden.
17
+ * - The amount is 1% (or the contracted feePercent) of NET verified savings,
18
+ * taken straight from the invoice — this module does not recompute savings,
19
+ * it only formats the already-verified number for Stripe.
20
+ * - The line-item description traces to the recomputable statement, so the
21
+ * customer can check the charge against their own ledger.
22
+ * - Every create call carries an idempotency key keyed on customer+period, so
23
+ * re-running a month cannot double-bill.
24
+ */
25
+ export type StripeBillingOptions = {
26
+ /** Stripe customer id (cus_…) the fee is billed to. */
27
+ stripeCustomerId: string;
28
+ /** Currency for the invoice. MESH fees are USD-denominated. */
29
+ currency?: string;
30
+ /**
31
+ * Whether to finalize+send the invoice or leave it as a reviewable DRAFT.
32
+ * Default "draft": nothing is ever charged without a human finalizing it.
33
+ */
34
+ mode?: "draft" | "finalize";
35
+ /** Label for the customer's statement, e.g. the spool set or app id. */
36
+ customerLabel?: string;
37
+ };
38
+ export type StripeInvoicePlan = {
39
+ action: "bill";
40
+ /** cus_… the invoice item + invoice attach to. */
41
+ customerId: string;
42
+ /** Integer minor units (cents) — Stripe never takes floats. */
43
+ amountCents: number;
44
+ currency: string;
45
+ /** Human-readable, traces to the recomputable statement. */
46
+ description: string;
47
+ /** Keyed on customer+period so a re-run cannot double-bill. */
48
+ idempotencyKey: string;
49
+ finalize: boolean;
50
+ /** Carried into the explanatory metadata on the Stripe objects. */
51
+ metadata: Record<string, string>;
52
+ } | {
53
+ action: "do_not_bill";
54
+ /** Why nothing is billed: do_not_charge, deficit carried, or chain broken. */
55
+ reason: string;
56
+ /** True only when the ledger failed verification — the hard stop. */
57
+ chainUnverified: boolean;
58
+ };
59
+ /**
60
+ * Build the Stripe plan for one recomputed invoice.
61
+ *
62
+ * `chainVerified` is passed in (not read from the invoice) because chain
63
+ * verification is the ledger layer's job: the caller verifies the spool and
64
+ * tells us. An unverified chain is a hard DO_NOT_BILL — a statement over an
65
+ * unverifiable ledger is not an invoice.
66
+ */
67
+ export declare function buildStripeInvoicePlan(invoice: Invoice, chainVerified: boolean, options: StripeBillingOptions): StripeInvoicePlan;
@@ -0,0 +1,117 @@
1
+ /**
2
+ * A dependency-free Stripe REST client — the one place MESH talks to Stripe.
3
+ *
4
+ * Promoted from the form-encoded `stripePost` in scripts/mesh-bill so the
5
+ * automated billing worker and the self-serve payment endpoints share one
6
+ * hardened client instead of re-rolling fetch calls. Everything is
7
+ * form-encoded, idempotency-keyed, and zero-dependency, matching the repo.
8
+ *
9
+ * SAFETY: the client refuses a live secret key (sk_live_…) unless `allowLive`
10
+ * is passed explicitly. The automated signup/metering/billing paths NEVER pass
11
+ * it, so no amount of configuration can make the unattended system charge real
12
+ * money — live billing stays the deliberate, human-gated mesh-bill --live path.
13
+ */
14
+ export type StripeMode = "test" | "live";
15
+ /** Nested form values (objects/arrays) flattened to Stripe's bracket notation. */
16
+ export type StripeForm = Record<string, string | number | boolean | undefined>;
17
+ export type StripeCustomer = {
18
+ id: string;
19
+ };
20
+ export type StripeCheckoutSession = {
21
+ id: string;
22
+ url: string | null;
23
+ status?: string;
24
+ };
25
+ export type StripeSetupIntent = {
26
+ id: string;
27
+ status: string;
28
+ client_secret: string | null;
29
+ payment_method: string | null;
30
+ };
31
+ export type StripeInvoiceItem = {
32
+ id: string;
33
+ };
34
+ export type StripeInvoice = {
35
+ id: string;
36
+ status: string;
37
+ amount_due?: number;
38
+ hosted_invoice_url?: string | null;
39
+ payment_intent?: string | null;
40
+ };
41
+ export type StripeRefund = {
42
+ id: string;
43
+ status: string;
44
+ };
45
+ /**
46
+ * The operations the billing worker depends on. Narrow on purpose so the
47
+ * worker can be unit-tested with a fake, and so the payment-choice branching is
48
+ * exercised without a Stripe account.
49
+ */
50
+ export interface BillingStripe {
51
+ readonly mode: StripeMode;
52
+ createInvoice(params: {
53
+ customerId: string;
54
+ currency: string;
55
+ collectionMethod: "charge_automatically" | "send_invoice";
56
+ description?: string;
57
+ daysUntilDue?: number;
58
+ defaultPaymentMethod?: string;
59
+ autoAdvance?: boolean;
60
+ metadata?: Record<string, string>;
61
+ idempotencyKey?: string;
62
+ }): Promise<StripeInvoice>;
63
+ createInvoiceItem(params: {
64
+ customerId: string;
65
+ invoiceId: string;
66
+ amountCents: number;
67
+ currency: string;
68
+ description: string;
69
+ metadata?: Record<string, string>;
70
+ idempotencyKey?: string;
71
+ }): Promise<StripeInvoiceItem>;
72
+ finalizeInvoice(invoiceId: string, idempotencyKey?: string): Promise<StripeInvoice>;
73
+ payInvoice(invoiceId: string, idempotencyKey?: string): Promise<StripeInvoice>;
74
+ }
75
+ /** The fuller surface the payment-setup and admin endpoints use. */
76
+ export interface StripeClient extends BillingStripe {
77
+ createCustomer(params: {
78
+ email?: string;
79
+ metadata?: Record<string, string>;
80
+ idempotencyKey?: string;
81
+ }): Promise<StripeCustomer>;
82
+ createMandateCheckoutSession(params: {
83
+ customerId: string;
84
+ paymentMethodTypes: string[];
85
+ successUrl: string;
86
+ cancelUrl: string;
87
+ currency: string;
88
+ idempotencyKey?: string;
89
+ }): Promise<StripeCheckoutSession>;
90
+ getCheckoutSession(sessionId: string): Promise<StripeCheckoutSession & {
91
+ setup_intent: string | null;
92
+ customer: string | null;
93
+ }>;
94
+ getSetupIntent(setupIntentId: string): Promise<StripeSetupIntent>;
95
+ setDefaultPaymentMethod(customerId: string, paymentMethodId: string): Promise<void>;
96
+ createRefund(params: {
97
+ paymentIntentId: string;
98
+ amountCents?: number;
99
+ idempotencyKey?: string;
100
+ }): Promise<StripeRefund>;
101
+ getInvoice(invoiceId: string): Promise<StripeInvoice>;
102
+ }
103
+ export declare class StripeApiError extends Error {
104
+ readonly status: number;
105
+ readonly type?: string | undefined;
106
+ readonly code?: string | undefined;
107
+ constructor(message: string, status: number, type?: string | undefined, code?: string | undefined);
108
+ }
109
+ /**
110
+ * Create the real Stripe client. `allowLive` defaults to false: a live key is
111
+ * refused unless the caller opts in deliberately (only the human-gated
112
+ * mesh-bill path ever does).
113
+ */
114
+ export declare function createStripeClient(secretKey: string, options?: {
115
+ allowLive?: boolean;
116
+ fetch?: typeof fetch;
117
+ }): StripeClient;
@@ -0,0 +1,77 @@
1
+ import { type BillableEvent, type InvoiceOptions } from "./savings-ledger.js";
2
+ /**
3
+ * The LOCAL Stripe meter sink: a pure projection from ledger events to Stripe
4
+ * Billing Meters event rows, written to a local JSONL file. No network calls,
5
+ * no API keys, no Stripe account - this is the file a billing integration
6
+ * would transmit, produced where the customer can read it first.
7
+ *
8
+ * Honesty properties, inherited rather than re-promised:
9
+ * - The projection selects and bills events through the SAME shared pipeline
10
+ * as recomputeInvoice (selectBillableEvents + leverUnbilledReason): deduped
11
+ * by requestId, failed tasks voided in full, unmeasured levers never
12
+ * counted, lossy levers only with approved gate verdicts, negatives netted.
13
+ * - Idempotent by construction: a doubled spool deduplicates to the same
14
+ * events, the same hourly windows, the same identifiers and the same values,
15
+ * so re-projection emits ZERO duplicate meter events - the output file is
16
+ * byte-identical. The identifier doubles as the Stripe-side idempotency key.
17
+ * - The canonical billing artifact remains the invoice. The projection's total
18
+ * equals the invoice's net verified savings over the same options (same
19
+ * floats, grouped hourly instead of by lever), and `totalCents` is exposed
20
+ * so the reconciliation is a one-line check.
21
+ */
22
+ export type StripeMeterEventRow = {
23
+ /** Stripe Billing Meter event name; one meter per deployment. */
24
+ event_name: string;
25
+ /**
26
+ * Deterministic idempotency identifier: sha256 of applicationId + window
27
+ * start. Stripe rejects duplicate identifiers within the dedupe horizon,
28
+ * which is exactly the re-transmission guard a replayed spool needs.
29
+ */
30
+ identifier: string;
31
+ /** Hour-window start, ISO UTC. */
32
+ timestamp: string;
33
+ payload: {
34
+ /**
35
+ * Customer mapping for the Stripe meter. Defaults to the applicationId
36
+ * verbatim; a real integration passes customerIdOf to map onto cus_ ids.
37
+ */
38
+ stripe_customer_id: string;
39
+ /** Net verified savings for the window, USD as a decimal string (6 dp). */
40
+ value: string;
41
+ };
42
+ };
43
+ export type StripeMeterProjectionOptions = Pick<InvoiceOptions, "period" | "gateVerdictOverrides" | "failedTaskIds"> & {
44
+ /** Meter event name. Default "mesh_net_verified_savings_usd". */
45
+ eventName?: string;
46
+ /** Map an applicationId to the Stripe customer id. Default: identity. */
47
+ customerIdOf?: (applicationId: string) => string;
48
+ };
49
+ export type StripeMeterProjection = {
50
+ rows: StripeMeterEventRow[];
51
+ /** Deduplicated events considered (inside the period, if one was given). */
52
+ eventsConsidered: number;
53
+ /** Events that contributed at least one billable lever to a row. */
54
+ eventsBilled: number;
55
+ duplicatesIgnored: number;
56
+ /** Events whose timestamp could not be bucketed into an hour window. */
57
+ eventsSkippedBadTimestamp: number;
58
+ /** Sum across rows, for reconciliation against the invoice. */
59
+ totalUsd: number;
60
+ totalCents: number;
61
+ };
62
+ /** Deterministic row identifier: hash(applicationId + window start). */
63
+ export declare function stripeMeterIdentifier(applicationId: string, windowStart: string): string;
64
+ /**
65
+ * Project ledger events onto hourly pre-aggregated Stripe meter rows. Pure:
66
+ * same events and options in, byte-identical rows out, however many times the
67
+ * spool was replayed or shuffled.
68
+ */
69
+ export declare function projectLedgerEventsToStripeMeterRows(events: readonly BillableEvent[], options?: StripeMeterProjectionOptions): StripeMeterProjection;
70
+ /**
71
+ * Write the projection to a local JSONL file, one meter row per line. A full
72
+ * deterministic rewrite, never an append: re-projecting the same spool writes
73
+ * the identical bytes, which is what makes a doubled spool emit zero duplicate
74
+ * meter events. Local only - nothing here (or anywhere in this module) opens a
75
+ * network connection or reads a key.
76
+ */
77
+ export declare function writeStripeMeterSink(path: string, rows: readonly StripeMeterEventRow[]): void;
@@ -0,0 +1,49 @@
1
+ import { type TokenPrice } from "./cost.js";
2
+ import { type LeverRisk, type WorkloadProfile } from "./savings-model.js";
3
+ export type LeverCoverage = {
4
+ leverId: string;
5
+ description: string;
6
+ risk: LeverRisk;
7
+ /** The lever targets at least one segment this workload actually has. */
8
+ applicable: boolean;
9
+ /** Theo applies it to this workload today (it is in leversFor). */
10
+ applied: boolean;
11
+ /**
12
+ * Projected saving from this lever alone on this workload, in USD and as a
13
+ * share of the baseline. For an applied lever this is its marginal saving in
14
+ * Theo's real stack; for an unapplied one it is the standalone projection. Both
15
+ * are hypotheses from the lever's published evidence — never a realised saving.
16
+ */
17
+ projectedSavingUsd: number;
18
+ projectedSavingPercent: number;
19
+ /** Why an applicable lever is not applied. Absent when applied, or not applicable. */
20
+ reason?: string;
21
+ };
22
+ export type CoverageReport = {
23
+ workload: string;
24
+ baselineCostUsd: number;
25
+ /** Theo's actual stacked projection on this workload (what leversFor delivers). */
26
+ realizedSavingUsd: number;
27
+ realizedSavingPercent: number;
28
+ /** The part of the realized saving that cannot change an answer — live immediately. */
29
+ realizedDeterministicPercent: number;
30
+ /** The part that needs a replay proof within the quality ceiling before it is enabled. */
31
+ realizedNeedsVerificationPercent: number;
32
+ /** Catalogue levers that can touch this workload (N). */
33
+ applicableLevers: number;
34
+ /** Of those, how many Theo applies (M). */
35
+ appliedLevers: number;
36
+ /** M / N as a percentage — the headline coverage figure. */
37
+ leverCoveragePercent: number;
38
+ /** Every catalogue lever, applied or not, sorted by projected headroom descending. */
39
+ levers: LeverCoverage[];
40
+ /** Applicable levers Theo does not apply, each with a reason. Sorted by headroom. */
41
+ gaps: LeverCoverage[];
42
+ };
43
+ /**
44
+ * Measure how much of the lever catalogue Theo reaches on one workload profile.
45
+ *
46
+ * Deterministic: the same profile, price and catalogue always produce the same
47
+ * report, so it is safe to diff across builds and to assert on in tests.
48
+ */
49
+ export declare function coverageForProfile(profile: WorkloadProfile, price: TokenPrice): CoverageReport;
@@ -0,0 +1,219 @@
1
+ import { type TokenPrice } from "./cost.js";
2
+ /**
3
+ * Token reduction: spend fewer tokens on the SAME model, rather than moving work
4
+ * to a weaker one. Model substitution trades quality for cost and needs a quality
5
+ * gate to be safe. Most of the levers here do not: removing a duplicated context
6
+ * block, or letting a provider's prefix cache serve a prompt you already paid
7
+ * for, changes the bill and not the answer.
8
+ *
9
+ * The economics that make this the primary lever rather than a secondary one,
10
+ * using rates captured in model-prices.ts:
11
+ * - Output tokens cost 5x input (Claude Sonnet 5.5) to 8x (gpt-5), so trimming
12
+ * an over-long answer is worth several times trimming the prompt.
13
+ * - Cached input costs 1/20th of fresh input (Sonnet 5.5: $2.00 -> $0.10), so a
14
+ * stable prefix served from cache is close to free.
15
+ *
16
+ * Token counting here is an ESTIMATE used to decide what to cut and to project a
17
+ * saving. It is never the basis of a realised-saving claim: those come from the
18
+ * provider's own reported usage, priced through the catalogue. A deployment
19
+ * should pass the tokenizer matching its model via `countTokens`, because a
20
+ * tokenizer pinned inside MESH would drift from the provider's own counting.
21
+ */
22
+ export type TokenCounter = (text: string) => number;
23
+ /**
24
+ * Tokenizer-free estimate. Byte-pair encoders average roughly 4 characters per
25
+ * token on English prose and nearer 3 on code, punctuation and JSON, so this
26
+ * counts word-like runs and separators separately instead of dividing the whole
27
+ * string by one constant. Expect roughly +/-15% against a real tokenizer; good
28
+ * enough to rank candidate reductions, not good enough to bill on.
29
+ */
30
+ export declare const approximateTokenCount: TokenCounter;
31
+ export type ReductionRisk = "lossless" | "low" | "moderate";
32
+ export type ReductionOutcome = {
33
+ reducer: string;
34
+ version: string;
35
+ risk: ReductionRisk;
36
+ text: string;
37
+ tokensBefore: number;
38
+ tokensAfter: number;
39
+ tokensSaved: number;
40
+ /** What the reducer removed, for review before anything is enabled. */
41
+ notes: string[];
42
+ };
43
+ export type Reducer = {
44
+ id: string;
45
+ version: string;
46
+ risk: ReductionRisk;
47
+ reduce: (text: string) => {
48
+ text: string;
49
+ notes: string[];
50
+ };
51
+ };
52
+ /**
53
+ * Removes exact duplicate blocks. Retrieval pipelines routinely send the same
54
+ * passage two or three times (overlapping chunks, a document that matched several
55
+ * queries, a system prompt echoed into the first user turn). Dropping later exact
56
+ * copies is lossless: the model already has the text.
57
+ *
58
+ * Only blocks at or above `minimumBlockTokens` are considered, so ordinary
59
+ * repeated phrasing is left alone.
60
+ *
61
+ * Duplicates are caught at two granularities: whole blocks separated by a
62
+ * blank line (as before), and, inside a block that survives that check,
63
+ * individual lines separated by a single newline. A RAG prompt that joins
64
+ * several retrieved excerpts with `picks.join("\n")` never produces a
65
+ * duplicated top-level block — the whole joined block is unique per request
66
+ * because the question text differs — but an excerpt pulled twice is still an
67
+ * exact duplicate line inside it, and dropping it is exactly as lossless as
68
+ * dropping a duplicate paragraph.
69
+ */
70
+ export declare function dedupeRepeatedBlocks(minimumBlockTokens?: number, countTokens?: TokenCounter): Reducer;
71
+ /**
72
+ * Collapses redundant whitespace outside fenced and inline code, where layout is
73
+ * meaningful. Individually small; free, and it compounds across every request.
74
+ */
75
+ export declare function collapseWhitespace(): Reducer;
76
+ /**
77
+ * Minifies pretty-printed JSON inside fenced ```json blocks. Agent tool results
78
+ * are frequently indented JSON, and JSON whitespace carries no meaning the model
79
+ * depends on, so re-serializing compactly removes indentation while preserving
80
+ * every key and value. Only blocks that parse as JSON are touched; anything else
81
+ * is left byte-identical. Values are preserved; numeric *formatting* is
82
+ * normalized (e.g. 1.0 -> 1), which is why this is a reduction of the serialized
83
+ * form, not a byte-identity transform — it is applied where the JSON's values,
84
+ * not its layout, are what the model needs.
85
+ */
86
+ export declare function minifyJsonBlocks(countTokens?: TokenCounter): Reducer;
87
+ /** Run reducers in order, reporting what each one saved. */
88
+ export declare function applyReducers(text: string, reducers: Reducer[], countTokens?: TokenCounter): {
89
+ text: string;
90
+ outcomes: ReductionOutcome[];
91
+ tokensBefore: number;
92
+ tokensAfter: number;
93
+ };
94
+ export type PrefixBreaker = {
95
+ /** What kind of per-request value is sitting inside the would-be stable prefix. */
96
+ kind: "timestamp" | "date" | "uuid" | "long-number" | "unknown";
97
+ example: string;
98
+ occurrences: number;
99
+ };
100
+ export type CachingProjection = {
101
+ status: "priced";
102
+ baselineCostUsd: number;
103
+ cachedCostUsd: number;
104
+ savingUsd: number;
105
+ savingPercent: number;
106
+ recoverableSavingUsd: number;
107
+ } | {
108
+ status: "unpriced";
109
+ reason: string;
110
+ };
111
+ export type CachingAnalysis = {
112
+ requests: number;
113
+ meanInputTokens: number;
114
+ /** Tokens identical across every sampled request, from the start of the prompt. */
115
+ sharedPrefixTokens: number;
116
+ /** Share of a request's input that the provider could serve from cache today. */
117
+ cacheablePrefixShare: number;
118
+ /**
119
+ * Shared prefix that would exist if the per-request values listed in
120
+ * `prefixBreakers` were moved out of the prefix. The gap between this and
121
+ * `sharedPrefixTokens` is the cost of a timestamp in a system prompt.
122
+ */
123
+ recoverablePrefixTokens: number;
124
+ prefixBreakers: PrefixBreaker[];
125
+ projection: CachingProjection;
126
+ };
127
+ export declare function commonPrefixLength(left: string, right: string): number;
128
+ /**
129
+ * Removes a repeated LEADING block from texts after the first, when that
130
+ * block is an exact match for the start of the first text in the group.
131
+ *
132
+ * This is the shape a continuous-learning / continuous-memory agent
133
+ * produces: the application glues the same memory or persistent-instruction
134
+ * block to the front of every turn, with only a short turn-specific
135
+ * remainder varying underneath it. `dedupeRepeatedBlocks` never catches
136
+ * this, because it only ever sees one text at a time and the memory block
137
+ * is not a standalone paragraph inside any single text - it is the shared
138
+ * PREFIX of several texts that each continue differently.
139
+ *
140
+ * LOSSY, not lossless, unlike `dedupeRepeatedBlocks`: a same-text duplicate
141
+ * sits right next to its twin, so the model reads both in the same breath.
142
+ * The duplicate removed here can be many turns upstream of the current one,
143
+ * which is a real behaviour change - a model that attends less to context
144
+ * far back in a long history may act differently with the block restated
145
+ * fresh every turn versus present once near the start. Callers must run
146
+ * this behind a replay-gate pass on their own traffic before billing it;
147
+ * it is never enabled by default.
148
+ *
149
+ * The cut point is always snapped to the last newline at or before the raw
150
+ * common-prefix length (never cut THROUGH a line), unless the match is a
151
+ * complete containment of one text inside the other, which needs no
152
+ * snapping because there is no partially-matched line to protect. This
153
+ * means a false positive - two texts that happen to start with the same
154
+ * few words before diverging mid-line, e.g. two turns both opening "Turn "
155
+ * - can only ever leave that differing line untouched, never truncate into it.
156
+ */
157
+ export declare function dedupeRepeatedLeadingBlock(texts: readonly string[], minimumBlockTokens?: number, countTokens?: TokenCounter): {
158
+ texts: string[];
159
+ notes: string[];
160
+ };
161
+ /**
162
+ * How much of a workload's prompt a provider's prefix cache could serve, and what
163
+ * is stopping it.
164
+ *
165
+ * Providers cache on an exact prefix match, so a single value that changes per
166
+ * request invalidates everything after it. A current-date line at the top of a
167
+ * system prompt can therefore cost the entire prompt's cache discount, which is
168
+ * the difference between paying full input rate and one twentieth of it. That
169
+ * failure is invisible in a cost dashboard: spend simply stays high.
170
+ *
171
+ * `requests` should be a representative sample of real prompts for one workload.
172
+ */
173
+ export declare function analysePromptCaching(requests: string[], options?: {
174
+ price?: TokenPrice;
175
+ countTokens?: TokenCounter;
176
+ /** Minimum prefix a provider will cache at all; OpenAI's floor is 1024 tokens. */
177
+ minimumCacheableTokens?: number;
178
+ }): CachingAnalysis;
179
+ export type OutputCapAdvice = {
180
+ observations: number;
181
+ /** Cap that would have truncated none of the observed responses. */
182
+ maxObserved: number;
183
+ recommendedCap: number;
184
+ /** Share of observed responses the recommended cap would have truncated. */
185
+ truncationRate: number;
186
+ meanOutputTokens: number;
187
+ /**
188
+ * Saving only materialises on responses that would have run past the cap, so
189
+ * this is deliberately conservative: it counts the tokens above the cap and
190
+ * nothing else.
191
+ */
192
+ projectedTokensSaved: number;
193
+ projectedSavingUsd?: number;
194
+ };
195
+ /**
196
+ * Recommend `max_output_tokens` from observed response lengths.
197
+ *
198
+ * Output is the expensive half of the bill (5x input on Sonnet 5.5, 8x on gpt-5),
199
+ * and an uncapped request lets a model ramble at that rate. A cap set at a high
200
+ * quantile of what a workload actually produces removes the tail without touching
201
+ * the responses that were already the right length.
202
+ *
203
+ * This caps length; it does not make answers shorter at equal quality. Any
204
+ * response that would have exceeded the cap gets truncated, so `truncationRate`
205
+ * is the number to judge it on, and a cap belongs behind a replay check before
206
+ * rollout.
207
+ */
208
+ export declare function recommendOutputCap(observedOutputTokens: number[], options?: {
209
+ quantile?: number;
210
+ price?: TokenPrice;
211
+ headroom?: number;
212
+ }): OutputCapAdvice;
213
+ export type ReductionSaving = {
214
+ inputTokensSaved: number;
215
+ outputTokensSaved: number;
216
+ savingUsd?: number;
217
+ };
218
+ /** Price a projected reduction. Returns tokens only when no price is supplied. */
219
+ export declare function priceReduction(inputTokensSaved: number, outputTokensSaved: number, price?: TokenPrice): ReductionSaving;