@harrym1707/sdk 0.1.1 → 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.
- package/LICENSE +4 -2
- package/index.cjs +1547 -164
- package/index.js +1520 -166
- package/package.json +1 -1
- package/types/cache-volatility-guard.d.ts +18 -4
- package/types/core/account-store.d.ts +7 -0
- package/types/core/accounts.d.ts +134 -0
- package/types/core/billing-worker.d.ts +113 -0
- package/types/core/budget.d.ts +216 -0
- package/types/core/evaluator.d.ts +10 -0
- package/types/core/github-oauth.d.ts +41 -0
- package/types/core/index.d.ts +10 -0
- package/types/core/ledger-store.d.ts +62 -0
- package/types/core/routing.d.ts +282 -0
- package/types/core/stripe-client.d.ts +117 -0
- package/types/core/token-reduction.d.ts +11 -0
- package/types/core/types.d.ts +11 -0
- package/types/core/workflow-sessions.d.ts +50 -0
- package/types/cta.d.ts +60 -0
- package/types/index.d.ts +6 -1
- package/types/ledger-mirror.d.ts +38 -0
- package/types/proxy.d.ts +43 -2
- package/types/reduce-request.d.ts +27 -2
- package/types/savings-ledger.d.ts +12 -2
- package/types/savings-snapshot.d.ts +11 -0
- package/types/theo-agent-store.d.ts +27 -0
- package/types/theo-agent.d.ts +247 -0
- package/types/theo-gate.d.ts +75 -0
- package/types/theo-policy.d.ts +100 -0
- package/types/types.d.ts +24 -0
- package/types/wrap.d.ts +8 -0
- package/types/cache-ttl-advisor.d.ts +0 -31
- package/types/core/replay-runner.d.ts +0 -11
- package/types/core/routing-simulation.d.ts +0 -24
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
import type { InferenceEvent, ModelTarget, QualityPolicy, QualityResult, RoutingDecision } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Stage 6 --- the Router.
|
|
4
|
+
*
|
|
5
|
+
* The control plane decides, per task class, whether a request is served by the
|
|
6
|
+
* baseline model or by an approved cheaper candidate, and advances or reverts
|
|
7
|
+
* that candidate along a staged rollout ladder. This module is the engine
|
|
8
|
+
* behind those decisions, built from the six components the spec names:
|
|
9
|
+
*
|
|
10
|
+
* PolicyLoader -- holds the active staged policy per task class.
|
|
11
|
+
* CandidateSelector -- the quality gate: may this candidate take traffic?
|
|
12
|
+
* Router -- the deterministic per-request decision.
|
|
13
|
+
* RolloutManager -- the pure 1% -> 100% ladder state machine.
|
|
14
|
+
* EscalationManager -- promotes a candidate up the ladder on good signal.
|
|
15
|
+
* RollbackManager -- reverts a candidate on a quality regression.
|
|
16
|
+
*
|
|
17
|
+
* Two invariants hold throughout:
|
|
18
|
+
*
|
|
19
|
+
* 1. Determinism. Once a policy is selected, `Router.route(request, policy)`
|
|
20
|
+
* is a pure function of the request and that policy: the same pair always
|
|
21
|
+
* yields the same `RoutingDecision`. No clocks, no `Math.random`. A
|
|
22
|
+
* request's cohort position is a stable hash, so it also never flip-flops
|
|
23
|
+
* as the rollout widens -- a request served by the candidate at 10% is
|
|
24
|
+
* still served by it at 25%.
|
|
25
|
+
*
|
|
26
|
+
* 2. Quality first. A cheaper candidate is activated ONLY when its quality
|
|
27
|
+
* policy (Stage 5) requirements are met on enough samples and a human has
|
|
28
|
+
* approved it; otherwise the request falls back to baseline. Cost is never
|
|
29
|
+
* reduced by silently reducing customer-defined output quality.
|
|
30
|
+
*/
|
|
31
|
+
/** The staged rollout ladder: the fraction of traffic the candidate may take at each rung. */
|
|
32
|
+
export declare const ROLLOUT_LADDER: readonly [0.01, 0.05, 0.1, 0.25, 0.5, 1];
|
|
33
|
+
/** Index of the final (100%) rung. */
|
|
34
|
+
export declare const ROLLOUT_LADDER_TOP: number;
|
|
35
|
+
/** `stageIndex` for a halted rollout: no candidate traffic, baseline only. */
|
|
36
|
+
export declare const ROLLOUT_HALTED_STAGE = -1;
|
|
37
|
+
/**
|
|
38
|
+
* Default floor for evaluation/observation sample sizes when a policy omits its
|
|
39
|
+
* own. A candidate is never qualified, escalated, or rolled back on one or two
|
|
40
|
+
* examples (Technical Architecture §6); 30 is the smallest sample that carries
|
|
41
|
+
* any statistical signal.
|
|
42
|
+
*/
|
|
43
|
+
export declare const DEFAULT_MINIMUM_SAMPLES = 30;
|
|
44
|
+
/**
|
|
45
|
+
* Where a candidate sits on the ladder right now. `stageIndex` is an index into
|
|
46
|
+
* `ROLLOUT_LADDER` while `status` is `"active"`; a `"halted"` rollout sends no
|
|
47
|
+
* candidate traffic regardless of the index.
|
|
48
|
+
*/
|
|
49
|
+
export type RolloutState = {
|
|
50
|
+
stageIndex: number;
|
|
51
|
+
status: "active" | "halted";
|
|
52
|
+
/** Trace of the transition that produced this state. */
|
|
53
|
+
lastReason?: string;
|
|
54
|
+
};
|
|
55
|
+
/** Stage 5 evaluation evidence standing behind a candidate. */
|
|
56
|
+
export type CandidateEvidence = {
|
|
57
|
+
/** Measured quality of the candidate from offline evaluation. */
|
|
58
|
+
quality: QualityResult;
|
|
59
|
+
/** How many evaluation samples the measurement rests on. */
|
|
60
|
+
sampleSize: number;
|
|
61
|
+
};
|
|
62
|
+
/** A cheaper model a policy may route to, with the bar it must clear first. */
|
|
63
|
+
export type RolloutCandidate = {
|
|
64
|
+
target: ModelTarget;
|
|
65
|
+
/** Fraction of baseline cost avoided, 0..1 (0.71 == 71% cheaper). */
|
|
66
|
+
estimatedCostReduction: number;
|
|
67
|
+
/** The quality bar this candidate must clear before any traffic (Stage 5). */
|
|
68
|
+
qualityPolicy: QualityPolicy;
|
|
69
|
+
/** Explicit human sign-off after reviewing the offline evaluation. */
|
|
70
|
+
approved: boolean;
|
|
71
|
+
/** Measured quality evidence from Stage 5. */
|
|
72
|
+
evidence: CandidateEvidence;
|
|
73
|
+
};
|
|
74
|
+
/**
|
|
75
|
+
* A compiled, runtime policy for one task class: the baseline, the single
|
|
76
|
+
* candidate under rollout, and where that candidate currently sits on the
|
|
77
|
+
* ladder. One candidate per policy keeps the cohort interval unambiguous; a
|
|
78
|
+
* second cheaper model is a new policy version.
|
|
79
|
+
*/
|
|
80
|
+
export type StagedRoutingPolicy = {
|
|
81
|
+
id: string;
|
|
82
|
+
version: number;
|
|
83
|
+
taskClass: string;
|
|
84
|
+
baseline: ModelTarget;
|
|
85
|
+
candidate: RolloutCandidate;
|
|
86
|
+
rollout: RolloutState;
|
|
87
|
+
enabled: boolean;
|
|
88
|
+
};
|
|
89
|
+
/**
|
|
90
|
+
* The minimum a request must carry for a routing decision. `requestId` is any
|
|
91
|
+
* stable, non-sensitive identity (request id, tenant+user, job id); it is the
|
|
92
|
+
* only thing the cohort hash reads, so the same identity always lands in the
|
|
93
|
+
* same cohort.
|
|
94
|
+
*/
|
|
95
|
+
export type RouterRequest = {
|
|
96
|
+
requestId: string;
|
|
97
|
+
taskClass?: string;
|
|
98
|
+
};
|
|
99
|
+
/** A live production quality signal observed at the current rollout stage. */
|
|
100
|
+
export type RolloutSignal = {
|
|
101
|
+
/** Measured quality of candidate traffic at the current stage. */
|
|
102
|
+
quality: QualityResult;
|
|
103
|
+
/** Observations gathered at the current stage. */
|
|
104
|
+
sampleSize: number;
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* Map a policy and a request identity to a stable position in [0, 1). Same
|
|
108
|
+
* inputs, same position, forever -- this is what makes routing deterministic
|
|
109
|
+
* and monotonic across rollout stages. The policy version is part of the key so
|
|
110
|
+
* a new policy version reshuffles cohorts (a fresh rollout), while every stage
|
|
111
|
+
* of one version shares one cohort assignment.
|
|
112
|
+
*/
|
|
113
|
+
export declare function cohortPosition(policy: Pick<StagedRoutingPolicy, "id" | "version">, requestId: string): number;
|
|
114
|
+
/**
|
|
115
|
+
* The human-readable `routeReason` (Technical Architecture §5). Carries the task
|
|
116
|
+
* class, the candidate, the quality evidence against its threshold, the
|
|
117
|
+
* estimated cost reduction, and the rollout percentage the decision was made at.
|
|
118
|
+
*/
|
|
119
|
+
export declare function formatRouteReason(policy: StagedRoutingPolicy, quality: QualityResult, rolloutFraction: number): string;
|
|
120
|
+
export type CandidateVerdict = {
|
|
121
|
+
qualified: true;
|
|
122
|
+
quality: QualityResult;
|
|
123
|
+
} | {
|
|
124
|
+
qualified: false;
|
|
125
|
+
reason: string;
|
|
126
|
+
quality: QualityResult;
|
|
127
|
+
};
|
|
128
|
+
/**
|
|
129
|
+
* Decides whether a candidate is allowed to take ANY traffic, independent of
|
|
130
|
+
* the rollout percentage. This is the enforcement point for the core invariant:
|
|
131
|
+
* a candidate qualifies only with human approval, enough samples, and a quality
|
|
132
|
+
* measurement that clears its own quality policy.
|
|
133
|
+
*/
|
|
134
|
+
export declare class CandidateSelector {
|
|
135
|
+
select(candidate: RolloutCandidate): CandidateVerdict;
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* The Router from the architecture spec: `route(request, policy)` returns a
|
|
139
|
+
* `RoutingDecision` and is a pure function of its inputs. Every path that does
|
|
140
|
+
* not route to the candidate falls back to baseline with a reason naming why.
|
|
141
|
+
*/
|
|
142
|
+
export declare class Router {
|
|
143
|
+
private readonly selector;
|
|
144
|
+
constructor(selector?: CandidateSelector);
|
|
145
|
+
route(request: RouterRequest, policy: StagedRoutingPolicy): RoutingDecision;
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* The pure ladder state machine. Every transition returns a NEW state; nothing
|
|
149
|
+
* is mutated in place, so a caller can keep the prior state to revert to.
|
|
150
|
+
*/
|
|
151
|
+
export declare class RolloutManager {
|
|
152
|
+
readonly ladder: readonly [0.01, 0.05, 0.1, 0.25, 0.5, 1];
|
|
153
|
+
/** A fresh rollout: active at the first rung (1%). */
|
|
154
|
+
initial(): RolloutState;
|
|
155
|
+
/** The traffic fraction this state grants the candidate (0 when halted). */
|
|
156
|
+
percentage(state: RolloutState): number;
|
|
157
|
+
/** True once the candidate is active at the final (100%) rung. */
|
|
158
|
+
isComplete(state: RolloutState): boolean;
|
|
159
|
+
/**
|
|
160
|
+
* Promote one rung. A halted rollout cannot advance (resume it first); the top
|
|
161
|
+
* rung is a no-op. Returns the input state unchanged when neither applies.
|
|
162
|
+
*/
|
|
163
|
+
advance(state: RolloutState, reason?: string): RolloutState;
|
|
164
|
+
/**
|
|
165
|
+
* Revert one rung. Stepping down from the first rung halts the rollout (no
|
|
166
|
+
* candidate traffic). This is the graduated rollback path.
|
|
167
|
+
*/
|
|
168
|
+
stepDown(state: RolloutState, reason?: string): RolloutState;
|
|
169
|
+
/** Full stop: no candidate traffic, baseline only, until resumed. */
|
|
170
|
+
halt(_state: RolloutState, reason?: string): RolloutState;
|
|
171
|
+
/** Resume a halted rollout back at the first rung. */
|
|
172
|
+
resume(_state: RolloutState, reason?: string): RolloutState;
|
|
173
|
+
}
|
|
174
|
+
/** How a rollback reverts: a full stop to baseline, or one rung down the ladder. */
|
|
175
|
+
export type RollbackMode = "halt" | "step_down";
|
|
176
|
+
export type RollbackDecision = {
|
|
177
|
+
triggered: boolean;
|
|
178
|
+
rollout: RolloutState;
|
|
179
|
+
reason: string;
|
|
180
|
+
};
|
|
181
|
+
/**
|
|
182
|
+
* The authority on quality regressions during rollout. It decides when a live
|
|
183
|
+
* signal breaches the candidate's quality bar and produces the reverted state.
|
|
184
|
+
*/
|
|
185
|
+
export declare class RollbackManager {
|
|
186
|
+
private readonly mode;
|
|
187
|
+
private readonly rolloutManager;
|
|
188
|
+
private readonly minimumSamples;
|
|
189
|
+
constructor(mode?: RollbackMode, rolloutManager?: RolloutManager, options?: {
|
|
190
|
+
minimumSamples?: number;
|
|
191
|
+
});
|
|
192
|
+
/** True when live candidate quality no longer clears the candidate's policy. */
|
|
193
|
+
shouldRollback(candidate: RolloutCandidate, signal: RolloutSignal): boolean;
|
|
194
|
+
/** Revert the policy's rollout (halt or step down, per the configured mode). */
|
|
195
|
+
rollback(policy: StagedRoutingPolicy, reason?: string): StagedRoutingPolicy;
|
|
196
|
+
/**
|
|
197
|
+
* Inspect a signal and, if it breaches quality on enough samples, produce the
|
|
198
|
+
* reverted state. A breach measured on fewer than `minimumSamples` is held,
|
|
199
|
+
* not acted on, so the ladder does not flap on one or two bad examples.
|
|
200
|
+
*/
|
|
201
|
+
decide(policy: StagedRoutingPolicy, signal: RolloutSignal): RollbackDecision;
|
|
202
|
+
}
|
|
203
|
+
export type EscalationAction = "advance" | "hold" | "rollback";
|
|
204
|
+
export type EscalationDecision = {
|
|
205
|
+
action: EscalationAction;
|
|
206
|
+
rollout: RolloutState;
|
|
207
|
+
reason: string;
|
|
208
|
+
};
|
|
209
|
+
/**
|
|
210
|
+
* Drives a candidate up the ladder from a live production quality signal. A
|
|
211
|
+
* regression always rolls back first (delegated to the RollbackManager); a
|
|
212
|
+
* healthy signal advances one rung once enough traffic has been observed at the
|
|
213
|
+
* current stage; otherwise it holds. Advancement itself never relaxes the
|
|
214
|
+
* quality gate -- the Router still re-checks quality on every request.
|
|
215
|
+
*/
|
|
216
|
+
export declare class EscalationManager {
|
|
217
|
+
private readonly rolloutManager;
|
|
218
|
+
private readonly rollbackManager;
|
|
219
|
+
private readonly minimumSamplesPerStage;
|
|
220
|
+
constructor(options?: {
|
|
221
|
+
minimumSamplesPerStage?: number;
|
|
222
|
+
}, rolloutManager?: RolloutManager, rollbackManager?: RollbackManager);
|
|
223
|
+
evaluate(policy: StagedRoutingPolicy, signal: RolloutSignal): EscalationDecision;
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Holds the active staged policy per task class. In production this is a
|
|
227
|
+
* local/Redis-backed cache the data plane reads on the hot path (Technical
|
|
228
|
+
* Architecture §2); here it is an in-memory registry with the same contract:
|
|
229
|
+
* lookups are cheap and deterministic, disabled policies are not served, and
|
|
230
|
+
* the latest version wins for a task class.
|
|
231
|
+
*
|
|
232
|
+
* Lifecycle updates from the EscalationManager / RollbackManager are persisted
|
|
233
|
+
* with `update`, which bumps nothing but the stored rollout state -- the policy
|
|
234
|
+
* id and version are stable across ladder movements within one version.
|
|
235
|
+
*/
|
|
236
|
+
export declare class PolicyLoader {
|
|
237
|
+
private readonly byId;
|
|
238
|
+
private readonly byTaskClass;
|
|
239
|
+
constructor(policies?: readonly StagedRoutingPolicy[]);
|
|
240
|
+
register(policy: StagedRoutingPolicy): void;
|
|
241
|
+
/** The active policy for a task class, or undefined when none is enabled. */
|
|
242
|
+
load(taskClass: string | undefined): StagedRoutingPolicy | undefined;
|
|
243
|
+
loadById(id: string): StagedRoutingPolicy | undefined;
|
|
244
|
+
/** Persist a lifecycle transition (new rollout state) for an existing policy. */
|
|
245
|
+
update(policy: StagedRoutingPolicy): void;
|
|
246
|
+
all(): StagedRoutingPolicy[];
|
|
247
|
+
}
|
|
248
|
+
/** Sink for the InferenceEvent stream (Technical Architecture §9). */
|
|
249
|
+
export type RoutingTelemetrySink = {
|
|
250
|
+
record(event: InferenceEvent): void | Promise<void>;
|
|
251
|
+
};
|
|
252
|
+
/**
|
|
253
|
+
* Turn a routing decision into the InferenceEvent the telemetry path carries.
|
|
254
|
+
* The decision's `reason` becomes `routeReason`, and the chosen target's
|
|
255
|
+
* provider/model are recorded so downstream pricing and the savings ledger see
|
|
256
|
+
* exactly where the request went.
|
|
257
|
+
*/
|
|
258
|
+
export declare function routingDecisionEvent(request: RouterRequest, decision: RoutingDecision, extra: {
|
|
259
|
+
applicationId: string;
|
|
260
|
+
timestamp: string;
|
|
261
|
+
inputTokens?: number;
|
|
262
|
+
outputTokens?: number;
|
|
263
|
+
costUsd?: number;
|
|
264
|
+
latencyMs?: number;
|
|
265
|
+
}): InferenceEvent;
|
|
266
|
+
/**
|
|
267
|
+
* Convenience wiring for the data plane: load the policy for a request's task
|
|
268
|
+
* class, route deterministically, and record the decision through the telemetry
|
|
269
|
+
* sink. Returns the decision. When no policy is active the request still routes
|
|
270
|
+
* to baseline (via a synthesised decision) and is still recorded, so every
|
|
271
|
+
* served request produces one inference event.
|
|
272
|
+
*/
|
|
273
|
+
export declare class RoutingService {
|
|
274
|
+
private readonly loader;
|
|
275
|
+
private readonly sink;
|
|
276
|
+
private readonly router;
|
|
277
|
+
constructor(loader: PolicyLoader, sink: RoutingTelemetrySink, router?: Router);
|
|
278
|
+
route(request: RouterRequest, baseline: ModelTarget, telemetry: {
|
|
279
|
+
applicationId: string;
|
|
280
|
+
timestamp: string;
|
|
281
|
+
}): Promise<RoutingDecision>;
|
|
282
|
+
}
|
|
@@ -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;
|
|
@@ -73,6 +73,17 @@ export declare function dedupeRepeatedBlocks(minimumBlockTokens?: number, countT
|
|
|
73
73
|
* meaningful. Individually small; free, and it compounds across every request.
|
|
74
74
|
*/
|
|
75
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;
|
|
76
87
|
/** Run reducers in order, reporting what each one saved. */
|
|
77
88
|
export declare function applyReducers(text: string, reducers: Reducer[], countTokens?: TokenCounter): {
|
|
78
89
|
text: string;
|
package/types/core/types.d.ts
CHANGED
|
@@ -7,12 +7,23 @@ export type QualityResult = {
|
|
|
7
7
|
score?: number;
|
|
8
8
|
checks: Record<string, boolean | number | string>;
|
|
9
9
|
reason?: string;
|
|
10
|
+
/** Measured error rate (0..1) behind this result, checked against `maxErrorRate`. */
|
|
11
|
+
errorRate?: number;
|
|
12
|
+
/** Measured latency in ms behind this result, checked against `maxLatencyMs`. */
|
|
13
|
+
latencyMs?: number;
|
|
10
14
|
};
|
|
11
15
|
export type QualityPolicy = {
|
|
12
16
|
minimumScore?: number;
|
|
13
17
|
requiredChecks?: string[];
|
|
14
18
|
maxErrorRate?: number;
|
|
15
19
|
maxLatencyMs?: number;
|
|
20
|
+
/**
|
|
21
|
+
* Minimum number of evaluation samples the quality measurement must rest on
|
|
22
|
+
* before a candidate may take any traffic. A policy is never activated on one
|
|
23
|
+
* or two examples (Technical Architecture §6). Defaults to
|
|
24
|
+
* `DEFAULT_MINIMUM_SAMPLES` when omitted.
|
|
25
|
+
*/
|
|
26
|
+
minimumSamples?: number;
|
|
16
27
|
};
|
|
17
28
|
export type RoutingCandidate = {
|
|
18
29
|
target: ModelTarget;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { type BillableEvent, type LedgerLeverKind } from "./savings-ledger.js";
|
|
2
|
+
/**
|
|
3
|
+
* Group ledger events into working sessions, so the dashboard can show Theo's
|
|
4
|
+
* activity per workflow instead of only in aggregate.
|
|
5
|
+
*
|
|
6
|
+
* MESH's proxy sees a stream of stateless API requests; the LLM APIs carry no
|
|
7
|
+
* task or conversation id, and Claude Code does not send one, so the ledger has
|
|
8
|
+
* no semantic "task" to group by (the `taskId` slot on an event exists for an
|
|
9
|
+
* out-of-band quality signal, and the proxy never fills it). The honest grouping
|
|
10
|
+
* available from the ledger alone is therefore two real dimensions:
|
|
11
|
+
*
|
|
12
|
+
* - `applicationId` — the `x-mesh-application` header, when a client sets it;
|
|
13
|
+
* - activity gaps — a run of requests with no long pause between them is one
|
|
14
|
+
* working session, split when the gap exceeds `gapMinutes`.
|
|
15
|
+
*
|
|
16
|
+
* This is a time-grouped working session, not an inferred semantic task, and the
|
|
17
|
+
* UI labels it as such. Each session's savings come from `recomputeInvoice` over
|
|
18
|
+
* exactly that session's events, so a session total is verified the same way the
|
|
19
|
+
* headline is — never an apportioned estimate.
|
|
20
|
+
*/
|
|
21
|
+
export type WorkflowSessionLever = {
|
|
22
|
+
leverId: string;
|
|
23
|
+
kind: LedgerLeverKind;
|
|
24
|
+
events: number;
|
|
25
|
+
savedUsd: number;
|
|
26
|
+
};
|
|
27
|
+
export type WorkflowSession = {
|
|
28
|
+
/** Stable within a ledger: application id + the session's first timestamp. */
|
|
29
|
+
id: string;
|
|
30
|
+
applicationId: string;
|
|
31
|
+
startedAt: string;
|
|
32
|
+
endedAt: string;
|
|
33
|
+
requests: number;
|
|
34
|
+
/** Distinct models seen, in first-seen order. */
|
|
35
|
+
models: string[];
|
|
36
|
+
netVerifiedSavingsUsd: number;
|
|
37
|
+
verdict: "charge" | "do_not_charge";
|
|
38
|
+
/** The Theo levers that fired this session, with their verified saving. */
|
|
39
|
+
levers: WorkflowSessionLever[];
|
|
40
|
+
succeeded: number;
|
|
41
|
+
failed: number;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* Cluster events into sessions, most recent first. Pure and deterministic: the
|
|
45
|
+
* same events and options always produce the same sessions.
|
|
46
|
+
*/
|
|
47
|
+
export declare function groupWorkflowSessions(events: readonly BillableEvent[], options?: {
|
|
48
|
+
gapMinutes?: number;
|
|
49
|
+
limit?: number;
|
|
50
|
+
}): WorkflowSession[];
|
package/types/cta.d.ts
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The savings CTA — the moment the product asks for the signup.
|
|
3
|
+
*
|
|
4
|
+
* MESH already computes a verified savings number from a hash-chained ledger
|
|
5
|
+
* the customer holds. This module turns that number into (a) a console call to
|
|
6
|
+
* action a runner can print on exit, and (b) a paste-able README badge, so the
|
|
7
|
+
* person running MESH self-identifies and the badge carries MESH into their
|
|
8
|
+
* repo. Everything here is honest: when the ledger says `do_not_charge`, the
|
|
9
|
+
* CTA says so and asks for nothing.
|
|
10
|
+
*
|
|
11
|
+
* This module is intentionally dependency-free (pure string/number logic) so
|
|
12
|
+
* both the SDK and the `mesh` CLI can import it directly without pulling the
|
|
13
|
+
* billing engine into their bundles. The core-dependent readers that build a
|
|
14
|
+
* {@link SavingsSnapshot} from a ledger spool live in `./savings-snapshot.js`.
|
|
15
|
+
*/
|
|
16
|
+
/** Where a developer running MESH goes to claim their verified savings. */
|
|
17
|
+
export declare const MESH_SIGNUP_URL = "https://www.mesh-technology.com";
|
|
18
|
+
export type SavingsSnapshot = {
|
|
19
|
+
/** Requests metered across every spool read. */
|
|
20
|
+
requests: number;
|
|
21
|
+
/** Net verified savings in USD (from provider usage, never an estimate). */
|
|
22
|
+
savedUsd: number;
|
|
23
|
+
/** What the metered traffic actually cost at the provider, in USD. */
|
|
24
|
+
spendUsd: number;
|
|
25
|
+
/** "charge" when MESH saved money; "do_not_charge" when it did not. */
|
|
26
|
+
verdict: "charge" | "do_not_charge";
|
|
27
|
+
/** False when any spool's hash chain failed to verify. */
|
|
28
|
+
chainOk: boolean;
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* Savings as a percentage of the un-reduced baseline (actual paid + saved),
|
|
32
|
+
* matching the README's "% lower cost" framing. Null when there is no spend to
|
|
33
|
+
* compare against.
|
|
34
|
+
*/
|
|
35
|
+
export declare function savingsPercent(snap: Pick<SavingsSnapshot, "savedUsd" | "spendUsd">): number | null;
|
|
36
|
+
export type SavingsCtaOptions = {
|
|
37
|
+
/** Where to claim savings; defaults to {@link MESH_SIGNUP_URL}. */
|
|
38
|
+
signupUrl?: string;
|
|
39
|
+
/** Branding prefix on each line; defaults to "⬢ MESH". */
|
|
40
|
+
mark?: string;
|
|
41
|
+
};
|
|
42
|
+
/**
|
|
43
|
+
* The console CTA. Honest by construction: a broken chain reports nothing, an
|
|
44
|
+
* empty spool invites a first request, a `do_not_charge` verdict asks for
|
|
45
|
+
* nothing, and only a real verified saving makes the ask.
|
|
46
|
+
*/
|
|
47
|
+
export declare function formatSavingsCta(snap: SavingsSnapshot, opts?: SavingsCtaOptions): string;
|
|
48
|
+
export type SavingsBadge = {
|
|
49
|
+
/** The shields.io image URL. */
|
|
50
|
+
imageUrl: string;
|
|
51
|
+
/** A ready-to-paste markdown image link to the signup page. */
|
|
52
|
+
markdown: string;
|
|
53
|
+
};
|
|
54
|
+
/**
|
|
55
|
+
* A paste-able README badge reflecting this spool's verified savings. Every
|
|
56
|
+
* user who adds it carries MESH into their repo — the distribution loop.
|
|
57
|
+
*/
|
|
58
|
+
export declare function savingsBadge(snap: SavingsSnapshot, opts?: {
|
|
59
|
+
signupUrl?: string;
|
|
60
|
+
}): SavingsBadge;
|
package/types/index.d.ts
CHANGED
|
@@ -14,11 +14,16 @@ export type { BillableEvent, Invoice, InvoiceLineItem, InvoiceOptions, InvoiceUn
|
|
|
14
14
|
export { capToolResultBody, digestStaleBody, reduceRequest } from "./reduce-request.js";
|
|
15
15
|
export { wrapMesh, type WrapMeshOptions, type MeshSavingsSummary, type MeshHandle, } from "./wrap.js";
|
|
16
16
|
export { extractBlindFeatures, type BlindFeatures } from "./blind-features.js";
|
|
17
|
-
export { policyToReductionConfig, withheldLevers, publishLever, defaultPolicy, knownLeverIds, type TheoPolicy, type TheoLever, type TheoGateProof, type TheoLeverClass, type WithheldLever, } from "./theo-policy.js";
|
|
17
|
+
export { policyToReductionConfig, leverToReductionConfig, withheldLevers, publishLever, defaultPolicy, knownLeverIds, routeMatches, isPolicyBundle, asBundle, policyForRoute, bundleToReductionConfig, upsertRoutePolicy, mergePolicyIntoBundle, type TheoPolicy, type TheoPolicyBundle, type TheoLever, type TheoGateProof, type TheoLeverClass, type WithheldLever, } from "./theo-policy.js";
|
|
18
|
+
export { createTheoMemory, observeWorkload, renderTheoReport, runTheoCycle, acceptProposal, rejectProposal, reconsiderLever, recentDriftRates, DRIFT_RISE_THRESHOLD, DRIFT_WINDOW_EVENTS, type DriftRates, type TheoProposalDecision, type TheoAutonomyLevel, type TheoMemory, type TheoHypothesis, type TheoFrontierOpportunity, type TheoExperiment, type TheoProposal, type TheoObservation, type TheoProof, type TheoAction, type TheoCycleResult, } from "./theo-agent.js";
|
|
19
|
+
export { defaultTheoMemoryPath, loadTheoMemory, saveTheoMemory, realisedFromSpoolDir, } from "./theo-agent-store.js";
|
|
20
|
+
export { proveCandidates, type ProveCandidatesOptions, type ProveCandidatesResult, } from "./theo-gate.js";
|
|
18
21
|
export { compactStaleContext, reduceRequestAsync } from "./semantic-compaction.js";
|
|
19
22
|
export type { SemanticCompactionConfig, SemanticCompactionResult, SemanticCompactor, } from "./semantic-compaction.js";
|
|
20
23
|
export { CachePrefixVolatilityGuard, type CacheStampDecision } from "./cache-volatility-guard.js";
|
|
21
24
|
export { renderLedgerReport, type LedgerReportOptions, type LedgerReportSpool } from "./report.js";
|
|
25
|
+
export { MESH_SIGNUP_URL, formatSavingsCta, savingsBadge, savingsPercent, type SavingsBadge, type SavingsCtaOptions, type SavingsSnapshot, } from "./cta.js";
|
|
26
|
+
export { savingsSnapshotFromEvents, savingsSnapshotFromSpoolDir, } from "./savings-snapshot.js";
|
|
22
27
|
export type { MeshHistoryCompactionConfig, MeshReductionChange, MeshReductionSummary, MeshTokenReductionConfig, } from "./reduce-request.js";
|
|
23
28
|
export { exactTextGrader, replayGate, replayUsage, responseText, responseToolCalls, toolNameGrader, toolSelectionGrader, } from "./replay-gate.js";
|
|
24
29
|
export type { ReplayCandidate, ReplayCandidateResult, ReplayComparison, ReplayGateOptions, ReplayGateResult, ReplayGrader, ReplayUsage, ToolCall, } from "./replay-gate.js";
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import type { LedgerRecord } from "../../core/dist/src/savings-ledger.js";
|
|
2
|
+
import type { MeshLedgerMirrorConfig } from "./types.js";
|
|
3
|
+
/**
|
|
4
|
+
* The client half of ledger mirroring: ship each locally-appended, hash-chained
|
|
5
|
+
* record to the Mesh metering API, without ever touching the request path.
|
|
6
|
+
*
|
|
7
|
+
* Contract (mirrors the existing fire-and-forget telemetry/ledger writes):
|
|
8
|
+
* - `enqueue` returns immediately; the network happens on a detached flush.
|
|
9
|
+
* - Records beyond the server's confirmed tail are buffered and re-sent as one
|
|
10
|
+
* contiguous batch, so a dropped or out-of-order push self-heals on the next
|
|
11
|
+
* append rather than leaving a permanent gap at the server.
|
|
12
|
+
* - The local spool is authoritative; the mirror is best-effort. On persistent
|
|
13
|
+
* failure or an overfull buffer it goes quiet — it never throws, never blocks,
|
|
14
|
+
* and never corrupts the local chain.
|
|
15
|
+
*/
|
|
16
|
+
export declare class LedgerMirror {
|
|
17
|
+
private readonly endpoint;
|
|
18
|
+
private readonly accountKey;
|
|
19
|
+
private readonly doFetch;
|
|
20
|
+
private readonly maxRetries;
|
|
21
|
+
private readonly maxPending;
|
|
22
|
+
/** Records with seq > confirmedTailSeq, awaiting confirmation. */
|
|
23
|
+
private pending;
|
|
24
|
+
private confirmedTailSeq;
|
|
25
|
+
private disabled;
|
|
26
|
+
/** A flush is requested again if records arrive while one is in flight. */
|
|
27
|
+
private dirty;
|
|
28
|
+
/** The in-flight flush, so callers (and tests) can await completion. */
|
|
29
|
+
private current?;
|
|
30
|
+
constructor(config: MeshLedgerMirrorConfig);
|
|
31
|
+
/** Buffer a record and schedule a flush. Never blocks or throws. */
|
|
32
|
+
enqueue(record: LedgerRecord): void;
|
|
33
|
+
/** Flush the pending buffer to the API, retrying a few times. Awaitable. */
|
|
34
|
+
flush(): Promise<void>;
|
|
35
|
+
private run;
|
|
36
|
+
/** POST one batch; returns the server's tailSeq on success, or undefined. */
|
|
37
|
+
private send;
|
|
38
|
+
}
|
package/types/proxy.d.ts
CHANGED
|
@@ -27,8 +27,27 @@ export type MeshProxyOptions = {
|
|
|
27
27
|
port?: number;
|
|
28
28
|
/** Directory for the hash-chained ledger spools (one per app + provider). */
|
|
29
29
|
ledgerDirectory: string;
|
|
30
|
-
/**
|
|
31
|
-
|
|
30
|
+
/**
|
|
31
|
+
* Reduction config applied to every proxied request. Pass a getter instead of
|
|
32
|
+
* a fixed config to have it re-read per request, so a policy Theo publishes
|
|
33
|
+
* takes effect without restarting the proxy (hot-reload). Lossless-only default.
|
|
34
|
+
*
|
|
35
|
+
* The getter receives the request's model id, so a route-aware policy bundle can
|
|
36
|
+
* return a different config per route (per-route ceilings and levers). A getter
|
|
37
|
+
* that ignores the argument keeps the single-policy behaviour.
|
|
38
|
+
*/
|
|
39
|
+
tokenReduction?: MeshTokenReductionConfig | ((modelId?: string) => MeshTokenReductionConfig);
|
|
40
|
+
/**
|
|
41
|
+
* The replay-gate verdicts behind the lossy levers the current policy enforces
|
|
42
|
+
* for this model id (see `bundleGateVerdicts`). Written onto each ledger event,
|
|
43
|
+
* so a lossy saving that was proven by the gate is billable and one that was
|
|
44
|
+
* not stays record-only. Called right after `tokenReduction` for the same
|
|
45
|
+
* request. Omit it and lossy savings are recorded but never billed.
|
|
46
|
+
*/
|
|
47
|
+
gateVerdicts?: (modelId?: string) => Record<string, {
|
|
48
|
+
ref: string;
|
|
49
|
+
verdict: "approved" | "rejected";
|
|
50
|
+
}>;
|
|
32
51
|
/** Override upstreams, e.g. a mock in tests or an OpenAI-compatible host. */
|
|
33
52
|
anthropicUpstream?: string;
|
|
34
53
|
openaiUpstream?: string;
|
|
@@ -40,6 +59,28 @@ export type MeshProxyOptions = {
|
|
|
40
59
|
* sealed inside an enclave). Off when unset — no features are computed.
|
|
41
60
|
*/
|
|
42
61
|
blindFeaturesKey?: string;
|
|
62
|
+
/**
|
|
63
|
+
* Mirror ledger events to a Mesh account. When both are set, each appended
|
|
64
|
+
* record is pushed fire-and-forget to `${meshApiUrl}/v1/ledger/events`,
|
|
65
|
+
* authenticated by the Mesh account key. The local spools stay authoritative,
|
|
66
|
+
* and the customer's provider key is never involved.
|
|
67
|
+
*/
|
|
68
|
+
meshApiUrl?: string;
|
|
69
|
+
meshAccountKey?: string;
|
|
70
|
+
/**
|
|
71
|
+
* Opt-in local request capture for Theo's replay gate. When set, each proxied
|
|
72
|
+
* request's ORIGINAL body (prompt content included) is appended as JSONL to
|
|
73
|
+
* `path`, owner-only, up to `limit` requests (default 50) AND `maxBytes` on
|
|
74
|
+
* disk (default 5 MiB, enforced against the file's actual size so it holds
|
|
75
|
+
* across restarts). This is the one place the proxy writes prompt content; it
|
|
76
|
+
* is OFF unless explicitly enabled, the file never leaves the machine, and
|
|
77
|
+
* `mesh theo --gate <path>` reads it.
|
|
78
|
+
*/
|
|
79
|
+
requestCapture?: {
|
|
80
|
+
path: string;
|
|
81
|
+
limit?: number;
|
|
82
|
+
maxBytes?: number;
|
|
83
|
+
};
|
|
43
84
|
};
|
|
44
85
|
export type MeshProxy = {
|
|
45
86
|
port: number;
|