@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.
@@ -59,6 +59,25 @@ export type MeshTokenReductionConfig = {
59
59
  descriptions?: "keep" | "truncate" | "drop";
60
60
  maximumDescriptionTokens?: number;
61
61
  };
62
+ /**
63
+ * Drop whole tool definitions by name — the "unused-tool removal" lever. A
64
+ * typical MCP server exposes 20-30 tools at 300-500 tokens each, and six
65
+ * connected servers run to 60,000-90,000 tokens of catalogue PER request; a
66
+ * workload that only ever calls a handful pays for all of them every turn.
67
+ * Each named tool is removed from the catalogue (Anthropic `{name}` and OpenAI
68
+ * `{type:"function",function:{name}}` shapes alike) before schema minification
69
+ * runs on the survivors. Past tool_use/tool_result turns in the history are
70
+ * untouched — providers do not require a tool's definition to be present to
71
+ * replay its earlier calls.
72
+ *
73
+ * LOSSY: removing a tool removes the model's ability to call it, so this holds
74
+ * ONLY where the tool is genuinely unreachable for the workload. The names are
75
+ * never guessed — they come from an operator who knows their workload (Theo is
76
+ * content-blind and cannot read tool names) and must clear a replay gate on the
77
+ * customer's own traffic before any saving is billed. Off by default; an empty
78
+ * or absent list is a no-op, and a name not present is skipped.
79
+ */
80
+ dropTools?: string[];
62
81
  /** Remove exact duplicate blocks from instructions and message text. */
63
82
  duplicateContext?: boolean;
64
83
  /**
@@ -197,11 +216,17 @@ export type MeshTokenReductionConfig = {
197
216
  * guard can, and a churning prefix turns the stamp into pure write premium
198
217
  * (the second live export measured exactly that loss). The proxy and
199
218
  * withMesh install one automatically whenever cacheTtl is set; it is
200
- * consulted with the RAW request before any stamp is placed.
219
+ * consulted before any stamp is placed, with the RAW request (for the
220
+ * history check) and the content the system breakpoint would cover (for the
221
+ * prefix check). It may withhold everything (`stamp: false`) or only the
222
+ * breakpoint on the newest message (`messageBreakpoint: false`).
201
223
  */
202
224
  cacheVolatilityGuard?: {
203
- observe(request: unknown): {
225
+ observe(request: unknown, context?: {
226
+ stampedPrefix?: unknown;
227
+ }): {
204
228
  stamp: boolean;
229
+ messageBreakpoint?: boolean;
205
230
  reason?: string;
206
231
  };
207
232
  };
@@ -1,11 +1,21 @@
1
1
  import { type PriceCatalogue } from "../../core/dist/src/price-catalogue.js";
2
- import { type BillableEvent } from "../../core/dist/src/savings-ledger.js";
2
+ import { type BillableEvent, type LedgerGateVerdict } from "../../core/dist/src/savings-ledger.js";
3
3
  import type { MeshRequestEvent, MeshSavingsLedgerConfig } from "./types.js";
4
4
  /** Build the append-only billable record for one completed request. Pure. */
5
5
  export declare function billableEventFromRequest(event: MeshRequestEvent, config: MeshSavingsLedgerConfig, catalogue: PriceCatalogue, pinnedCatalogueVersion: string): BillableEvent;
6
+ /** Per-request facts the ledger cannot know at construction time. */
7
+ export type SavingsLedgerEmitContext = {
8
+ /**
9
+ * Replay-gate verdicts for the lossy levers the policy in force for THIS
10
+ * request enforces, keyed by lever id. Merged over the config's static
11
+ * `gateVerdicts`. The proxy passes these because the policy hot-reloads and
12
+ * differs per route, so one fixed map per ledger would be wrong.
13
+ */
14
+ gateVerdicts?: Record<string, LedgerGateVerdict>;
15
+ };
6
16
  export type SavingsLedger = {
7
17
  /** Synchronously appends one chained record. Never throws. */
8
- emit: (event: MeshRequestEvent) => void;
18
+ emit: (event: MeshRequestEvent, context?: SavingsLedgerEmitContext) => void;
9
19
  readonly path: string;
10
20
  };
11
21
  /** Create the opt-in JSONL savings meter. Construction never throws on I/O. */
@@ -0,0 +1,11 @@
1
+ import { type BillableEvent } from "./core/index.js";
2
+ import type { SavingsSnapshot } from "./cta.js";
3
+ /** Fold a set of ledger events into a snapshot. `chainOk` carries through. */
4
+ export declare function savingsSnapshotFromEvents(events: readonly BillableEvent[], chainOk?: boolean): SavingsSnapshot;
5
+ /**
6
+ * Summarise every ledger spool in a directory (the proxy writes one JSONL per
7
+ * app + provider). Any spool whose hash chain does not verify is excluded and
8
+ * flips `chainOk` to false, so a tampered or truncated spool is never silently
9
+ * folded into the number.
10
+ */
11
+ export declare function savingsSnapshotFromSpoolDir(dir: string): SavingsSnapshot;
@@ -0,0 +1,27 @@
1
+ import type { TheoMemory } from "./theo-agent.js";
2
+ /**
3
+ * The impure edge of the Theo agent: load and save his per-customer memory, and
4
+ * read realised savings from the ledger. The reasoning in `theo-agent.ts` stays
5
+ * pure; everything that touches the disk is here.
6
+ *
7
+ * Memory is a single JSON document per customer, kept alongside the ledger it is
8
+ * about (default `<ledgerDir>/theo/<customer>.json`). It never contains prompt or
9
+ * response content — only Theo's policy, hypotheses, experiment log and proposals.
10
+ */
11
+ /** Default location for a customer's Theo memory, beside their ledger. */
12
+ export declare function defaultTheoMemoryPath(ledgerDir: string, customer: string): string;
13
+ /** Load Theo's memory, or null if it is absent or unreadable. */
14
+ export declare function loadTheoMemory(path: string): TheoMemory | null;
15
+ /** Persist Theo's memory, creating the directory if needed. */
16
+ export declare function saveTheoMemory(path: string, memory: TheoMemory): void;
17
+ /**
18
+ * Realised, verified figures for the report, read from the ledger spools the
19
+ * proxy wrote. A tampered or truncated spool is excluded by the chain check
20
+ * inside `savingsSnapshotFromSpoolDir`, so these numbers are never inflated.
21
+ */
22
+ export declare function realisedFromSpoolDir(ledgerDir: string): {
23
+ savingsUsd: number;
24
+ spendUsd: number;
25
+ requests: number;
26
+ chainOk: boolean;
27
+ };
@@ -0,0 +1,247 @@
1
+ import type { TokenPrice } from "../../core/dist/src/cost.js";
2
+ import { type WorkloadProfile } from "../../core/dist/src/savings-model.js";
3
+ import type { BlindFeatures } from "./blind-features.js";
4
+ import { type TheoLeverClass, type TheoPolicy } from "./theo-policy.js";
5
+ /**
6
+ * Theo — the persistent, per-customer token-engineer agent.
7
+ *
8
+ * This is the running loop the R&D sketch (docs/rnd/theo-token-engineer-agent.md)
9
+ * describes, built on primitives that already exist: blind features (Observe),
10
+ * the savings model (Hypothesise), the replay gate (Prove), and the per-user
11
+ * policy the proxy enforces (Decide). The prototype in evals/theo-loop.ts proved
12
+ * the shape offline; this turns it into a stateful agent with memory and a
13
+ * configurable autonomy level.
14
+ *
15
+ * Two invariants hold in code, not by trust:
16
+ *
17
+ * 1. **This module is pure.** It never reads the clock, the disk or the
18
+ * network, and it never calls a provider. Persistence lives in
19
+ * `theo-agent-store.ts`; proving a lever lives at the call site (the replay
20
+ * gate). The cycle CONSUMES proofs it is handed and never invents one.
21
+ *
22
+ * 2. **Theo never enables a saving he has not proven.** Only the three truly
23
+ * lossless levers run unconditionally (they cannot change the answer). Every
24
+ * other lever is withheld until a replay-gate proof shows, on the customer's
25
+ * own traffic, that quality held within the route's ceiling — and even then
26
+ * Theo only auto-publishes it at the `optimise` autonomy level. The
27
+ * enforcement point is `publishLever` in theo-policy.ts, which refuses a
28
+ * lossy lever with no gate proof.
29
+ */
30
+ /**
31
+ * How much Theo may do on his own, lowest to highest. This is the "Improve" dial
32
+ * from the product guide:
33
+ *
34
+ * observe — identify opportunities, change nothing.
35
+ * recommend — auto-apply lossless; surface proven lossy levers as proposals.
36
+ * test — recommend, and additionally initiate gate experiments (emit the
37
+ * requests for the next lossy candidates to prove).
38
+ * optimise — auto-publish a lossy lever once it has a passing proof within the
39
+ * route's quality ceiling (pre-approved, reversible).
40
+ */
41
+ export type TheoAutonomyLevel = "observe" | "recommend" | "test" | "optimise";
42
+ /** A lossy lever Theo believes is worth proving next. The share is a prior for
43
+ * ORDERING only — it is never shown to the customer as a saving. */
44
+ export type TheoHypothesis = {
45
+ lever: string;
46
+ class: TheoLeverClass;
47
+ priorSharePercent: number;
48
+ rationale: string;
49
+ };
50
+ /** An opportunity the savings model sees that the proxy cannot yet enforce as a
51
+ * discrete lever (new reducer code or an app-side change — the parked frontier). */
52
+ export type TheoFrontierOpportunity = {
53
+ concept: string;
54
+ priorSharePercent: number;
55
+ note: string;
56
+ };
57
+ /** One replay-gate outcome, kept so a lever is never re-tested from scratch. */
58
+ export type TheoExperiment = {
59
+ lever: string;
60
+ ranAt: string;
61
+ passed: boolean;
62
+ savingPercent?: number;
63
+ qualityDeltaPercent?: number;
64
+ grader?: string;
65
+ note?: string;
66
+ };
67
+ /** A proven lossy lever awaiting the customer's approval (recommend/test modes). */
68
+ export type TheoProposal = {
69
+ lever: string;
70
+ savingPercent: number;
71
+ qualityDeltaPercent: number;
72
+ grader: string;
73
+ provenAt: string;
74
+ message: string;
75
+ };
76
+ export type TheoCycleLogEntry = {
77
+ at: string;
78
+ autonomy: TheoAutonomyLevel;
79
+ observed: string;
80
+ actions: number;
81
+ };
82
+ /** Everything Theo remembers about one customer's environment. Persisted as JSON. */
83
+ export type TheoMemory = {
84
+ schemaVersion: 1;
85
+ customer: string;
86
+ autonomy: TheoAutonomyLevel;
87
+ /** The live policy the proxy enforces. Theo's only lever on the world. */
88
+ policy: TheoPolicy;
89
+ /** The most recently observed workload shape. */
90
+ profile?: WorkloadProfile;
91
+ /** Ranked lossy candidates not yet active. */
92
+ hypotheses: TheoHypothesis[];
93
+ /** Opportunities beyond the enforceable repertoire. */
94
+ frontier: TheoFrontierOpportunity[];
95
+ /** Append-only log of gate outcomes. */
96
+ experiments: TheoExperiment[];
97
+ /** Open proposals the customer has not yet accepted or rejected. */
98
+ proposals: TheoProposal[];
99
+ /** Per applied lossy lever: the retry and failure rates measured when it was
100
+ * proven, so a later rise in either can be detected as quality drift. */
101
+ driftBaselines: Record<string, {
102
+ retryRate: number;
103
+ failureRate: number;
104
+ at: string;
105
+ }>;
106
+ /** Levers Theo auto-rolled-back after drift; not re-proposed this session. */
107
+ rolledBack: string[];
108
+ /** Proposals the customer turned down. Theo neither re-proves nor re-proposes
109
+ * these until the customer asks him to reconsider. Optional so memory files
110
+ * written before this field existed still load. */
111
+ declined?: string[];
112
+ log: TheoCycleLogEntry[];
113
+ updatedAt: string;
114
+ };
115
+ /** What Theo sees this cycle. The profile comes from Observe (blind features);
116
+ * the realised figures come from the ledger and feed the report only. */
117
+ export type TheoObservation = {
118
+ profile: WorkloadProfile;
119
+ price: TokenPrice;
120
+ realisedSavingsUsd?: number;
121
+ realisedSpendUsd?: number;
122
+ /** Fraction of recent requests that were retries (duplicate of a prior one) —
123
+ * a behavioural-drift signal. When it rises after a lever is applied, Theo
124
+ * rolls that lever back. Omit it and that signal simply does not fire. */
125
+ retryRate?: number;
126
+ /** Fraction of recent requests that FAILED (provider error) — a second drift
127
+ * signal, caught the same way. Omit it to ignore it. */
128
+ failureRate?: number;
129
+ };
130
+ /** A measured gate result the caller obtained (from `replayGate`) and hands to
131
+ * the cycle. Theo trusts the measurement; he never produces one himself. */
132
+ export type TheoProof = {
133
+ lever: string;
134
+ /** Measured saving on the customer's own traffic, from provider usage. */
135
+ savingPercent: number;
136
+ /** Measured quality delta; its magnitude is compared to the route ceiling. */
137
+ qualityDeltaPercent: number;
138
+ grader: string;
139
+ provenAt: string;
140
+ };
141
+ export type TheoAction = {
142
+ kind: "lossless-active";
143
+ levers: string[];
144
+ } | {
145
+ kind: "policy-published";
146
+ version: number;
147
+ lever: string;
148
+ } | {
149
+ kind: "proposal-opened";
150
+ lever: string;
151
+ savingPercent: number;
152
+ qualityDeltaPercent: number;
153
+ } | {
154
+ kind: "gate-requested";
155
+ levers: string[];
156
+ } | {
157
+ kind: "proof-rejected";
158
+ lever: string;
159
+ reason: string;
160
+ } | {
161
+ kind: "rolled-back";
162
+ lever: string;
163
+ reason: string;
164
+ };
165
+ export type TheoCycleResult = {
166
+ memory: TheoMemory;
167
+ actions: TheoAction[];
168
+ report: string;
169
+ };
170
+ /** How far the retry rate may rise above an applied lever's baseline before Theo
171
+ * treats it as quality drift and rolls the lever back (absolute fraction).
172
+ * Exported so surfaces (e.g. the dashboard's health panel) flag "watch" against
173
+ * the SAME line Theo actually rolls back on — one source of truth, not a copy. */
174
+ export declare const DRIFT_RISE_THRESHOLD = 0.05;
175
+ /** How many of the MOST RECENT ledger events the drift signals are measured
176
+ * over. A whole-history rate dilutes a fresh regression until it can no longer
177
+ * cross the threshold; a bounded window caps that dilution, so a rise shows
178
+ * within this many requests however long the history is. Untuned, like the
179
+ * threshold above. */
180
+ export declare const DRIFT_WINDOW_EVENTS = 200;
181
+ export type DriftRates = {
182
+ /** Events the rates were measured over (at most the window). */
183
+ sampleSize: number;
184
+ retryRate: number;
185
+ failureRate: number;
186
+ };
187
+ /**
188
+ * The two behavioural-drift signals over the most recent `windowEvents` ledger
189
+ * events: the share that were byte-identical retries and the share that failed
190
+ * at the provider. Pure. The ONE definition shared by Theo's rollback check and
191
+ * the dashboard's health panel, so the two can never disagree.
192
+ */
193
+ export declare function recentDriftRates(events: readonly {
194
+ timestamp: string;
195
+ status: string;
196
+ duplicateOfRequestId?: string;
197
+ }[], windowEvents?: number): DriftRates;
198
+ /**
199
+ * OBSERVE — fold blind features into a workload profile. Learned from irreversible
200
+ * features only; no prompt, code or response is ever read. Output tokens are not
201
+ * present in a request, so they are supplied from the ledger (mean per request).
202
+ */
203
+ export declare function observeWorkload(features: readonly BlindFeatures[], options?: {
204
+ name?: string;
205
+ outputTokensMean?: number;
206
+ }): WorkloadProfile;
207
+ /** A fresh agent for a new customer: strict, lossless-only, nothing proven yet. */
208
+ export declare function createTheoMemory(customer: string, autonomy: TheoAutonomyLevel, at: string): TheoMemory;
209
+ /**
210
+ * Run one Theo cycle: Observe -> Hypothesise -> (consume) Prove -> Decide -> Report.
211
+ * Pure: returns a new memory, the actions taken, and a human-readable report.
212
+ * `now` is the caller's clock; `input.proofs` are gate results the caller obtained.
213
+ */
214
+ export declare function runTheoCycle(memory: TheoMemory, input: {
215
+ observation: TheoObservation;
216
+ proofs?: readonly TheoProof[];
217
+ }, now: string): TheoCycleResult;
218
+ export type TheoProposalDecision = {
219
+ ok: true;
220
+ memory: TheoMemory;
221
+ message: string;
222
+ } | {
223
+ ok: false;
224
+ reason: string;
225
+ };
226
+ /**
227
+ * The customer accepts an open proposal: the lever is published into the policy
228
+ * carrying the proof it was proposed with, and its drift baselines are recorded
229
+ * so a later rise rolls it back. Pure — returns a new memory.
230
+ *
231
+ * Acceptance re-checks the proof against the CURRENT ceiling (it may have been
232
+ * tightened since the proposal opened) and refuses a lever that was rolled back
233
+ * after drift, so accepting can never enable something the gate would not.
234
+ */
235
+ export declare function acceptProposal(memory: TheoMemory, lever: string, rates: {
236
+ retryRate?: number;
237
+ failureRate?: number;
238
+ }, now: string): TheoProposalDecision;
239
+ /**
240
+ * The customer turns an open proposal down: it is closed and the lever is
241
+ * remembered as declined, so Theo neither re-proves nor re-proposes it. Pure.
242
+ */
243
+ export declare function rejectProposal(memory: TheoMemory, lever: string, now: string): TheoProposalDecision;
244
+ /** Undo a decline: Theo may prove and propose the lever again. Pure. */
245
+ export declare function reconsiderLever(memory: TheoMemory, lever: string, now: string): TheoProposalDecision;
246
+ /** A short, honest status line set for the customer — no unproven numbers. */
247
+ export declare function renderTheoReport(memory: TheoMemory, observation: TheoObservation, actions: readonly TheoAction[]): string;
@@ -0,0 +1,75 @@
1
+ import type { TokenPrice } from "../../core/dist/src/cost.js";
2
+ import { type ReplayGrader } from "./replay-gate.js";
3
+ import type { TheoProof } from "./theo-agent.js";
4
+ /**
5
+ * The replay gate, wired to Theo.
6
+ *
7
+ * `runTheoCycle` consumes proofs but never produces one. This is where a proof
8
+ * comes from: replay a sample of the customer's OWN requests both ways — baseline
9
+ * and candidate-reduced — against the real provider, and measure what actually
10
+ * happened. Token savings and cost come from the provider's reported usage on
11
+ * both runs; quality from a grader comparing the two responses. A candidate is a
12
+ * proof only if the bill fell AND the measured quality drop stayed within budget.
13
+ *
14
+ * This is the one impure corner of the agent: it needs a `call` that reaches the
15
+ * provider (with the customer's key) and a sample of real requests. Both stay on
16
+ * the customer's machine; nothing is uploaded. Replay costs money — each request
17
+ * is sent again — so the call count is reported, and recorded baseline responses
18
+ * can be supplied to avoid paying for the baseline run twice.
19
+ */
20
+ export type ProveCandidatesOptions = {
21
+ /** Enforceable lossy lever ids to prove — typically Theo's ranked hypotheses. */
22
+ levers: readonly string[];
23
+ /** A representative sample of the customer's real requests. */
24
+ requests: readonly unknown[];
25
+ /** Sends a request to the provider and returns the response. */
26
+ call: (request: unknown) => Promise<unknown>;
27
+ /** Clock for each proof's provenAt. */
28
+ now: string;
29
+ /**
30
+ * Mean quality the gate may give up, as a FRACTION (0.02 = a 2% drop). Pass the
31
+ * route's quality ceiling / 100 so the gate and Theo's ceiling agree. Default 0.02.
32
+ */
33
+ maximumQualityDrop?: number;
34
+ /** Recorded baseline responses (one per request) to avoid paying for the baseline run. */
35
+ baselineResponses?: readonly unknown[];
36
+ /** Rate, so the gate judges the BILL (cache writes/reads included), not only tokens. */
37
+ price?: TokenPrice;
38
+ /** Quality grader. Default `agentGrader()`: a changed tool call fails hard, else coverage. */
39
+ grader?: ReplayGrader;
40
+ /** A short name for the grader, recorded on the proof. Default "agent". */
41
+ graderName?: string;
42
+ /** Group correlated requests (e.g. by task) so the quality bound is not overstated. */
43
+ groupOf?: (request: unknown, index: number) => string;
44
+ /**
45
+ * Exploration budget: the maximum number of paid provider calls this run may
46
+ * make. The gate sends roughly requests × (candidates + 1 baseline) calls
47
+ * (the baseline is free when recorded responses are supplied), so the sample
48
+ * is trimmed to fit. Omit for no cap. Protects against a runaway provider bill
49
+ * when Theo proves on its own.
50
+ */
51
+ maxProviderCalls?: number;
52
+ };
53
+ export type ProveCandidatesResult = {
54
+ /** One proof per candidate the gate approved — ready to hand to `runTheoCycle`. */
55
+ proofs: TheoProof[];
56
+ /** Candidates the gate rejected, with why (quality or no saving). */
57
+ rejections: Array<{
58
+ lever: string;
59
+ reason: string;
60
+ }>;
61
+ /** Provider calls this replay made, so its cost is visible. */
62
+ calls: number;
63
+ /** Set when the exploration budget trimmed the sample. */
64
+ note?: string;
65
+ };
66
+ /**
67
+ * Prove a set of candidate lossy levers on the customer's own traffic.
68
+ *
69
+ * Runs ONE replay gate across all candidates so the baseline is paid for once and
70
+ * the quality bound holds simultaneously across the search (picking the best of
71
+ * several otherwise flatters the winner). Each approved candidate becomes a
72
+ * {@link TheoProof}; the measured quality bound (one-sided, ≤ 0) is carried as a
73
+ * percentage so Theo's ceiling check compares like with like.
74
+ */
75
+ export declare function proveCandidates(options: ProveCandidatesOptions): Promise<ProveCandidatesResult>;
@@ -51,6 +51,15 @@ export type WithheldLever = {
51
51
  lever: string;
52
52
  reason: string;
53
53
  };
54
+ /**
55
+ * Hard upper bound on any route's quality ceiling. Enforcement clamps to this, so
56
+ * however loose a policy's `qualityCeilingPercent` is set (by config, a tier dial,
57
+ * or a tampered file), a lossy lever whose measured quality drop exceeds this is
58
+ * never enforced. A floor under "never degrade" that no misconfiguration crosses.
59
+ */
60
+ export declare const MAX_QUALITY_CEILING_PERCENT = 5;
61
+ /** The effective ceiling: the route's, clamped to the hard maximum (and ≥ 0). */
62
+ export declare function effectiveQualityCeiling(ceilingPercent: number): number;
54
63
  /**
55
64
  * Turn a policy into the reduction config the proxy enforces.
56
65
  *
@@ -60,6 +69,97 @@ export type WithheldLever = {
60
69
  * enforcement point of "never enable a saving we have not proven within budget."
61
70
  */
62
71
  export declare function policyToReductionConfig(policy: TheoPolicy): MeshTokenReductionConfig;
72
+ /** A ledger gate verdict, structurally the ledger's `LedgerGateVerdict` (kept
73
+ * local so this module stays dependency-free). */
74
+ export type PolicyGateVerdict = {
75
+ ref: string;
76
+ verdict: "approved";
77
+ };
78
+ /**
79
+ * The replay-gate verdicts behind the lossy levers this policy ENFORCES, keyed by
80
+ * lever id, for the savings ledger. Exactly the levers `policyToReductionConfig`
81
+ * applies: a lossy lever with a proof inside the (hard-capped) ceiling. A lever
82
+ * that is withheld gets no verdict, so its savings can never bill. The ref names
83
+ * the proof — grader and the time it was measured — so an invoice line can be
84
+ * traced back to the gate run that justified it.
85
+ */
86
+ export declare function policyGateVerdicts(policy: TheoPolicy): Record<string, PolicyGateVerdict>;
87
+ /**
88
+ * Build the reducer config for a SINGLE lever, bypassing the policy's proof gate.
89
+ *
90
+ * This exists to CONSTRUCT a candidate for the replay gate to measure — it is not
91
+ * an enforcement path. Production enforcement still goes only through
92
+ * `policyToReductionConfig`, which withholds any lossy lever that lacks a passing
93
+ * proof within the route's ceiling. Reuses `applyLever` so the gate measures the
94
+ * exact transform the proxy would later enforce.
95
+ */
96
+ export declare function leverToReductionConfig(lever: TheoLever): MeshTokenReductionConfig;
97
+ /**
98
+ * A bundle of policies for one user: a DEFAULT policy plus zero or more
99
+ * route-specific overrides. A "route" is matched against the request's model id,
100
+ * so a user can run a strict ceiling on their agent's planning model and a looser
101
+ * one on a cheap summariser — each route carries its OWN ceiling, levers and
102
+ * proofs, and the hard cap (`MAX_QUALITY_CEILING_PERCENT`) still binds every one.
103
+ *
104
+ * Back-compatible: a stored single `TheoPolicy` is read as a bundle whose default
105
+ * is that policy and whose route list is empty (`asBundle`), so existing policy
106
+ * files and the single-policy enforcement path keep working unchanged.
107
+ */
108
+ export type TheoPolicyBundle = {
109
+ schemaVersion: 1;
110
+ user: string;
111
+ /** Applied to any request whose model id matches no route. */
112
+ default: TheoPolicy;
113
+ /** Route-specific policies; each MUST carry a `route` matcher. First match wins. */
114
+ routes?: TheoPolicy[];
115
+ updatedAt: string;
116
+ };
117
+ /**
118
+ * Whether a route matcher applies to a model id. Three forms, deliberately small:
119
+ * - `"*"` or `""` — matches every model (a catch-all route).
120
+ * - a trailing `*` — prefix match (`"claude-*"` matches `"claude-sonnet-5-5"`).
121
+ * - anything else — an exact model-id match.
122
+ * No regex: a policy file is config a user hand-edits, so matching stays obvious.
123
+ */
124
+ export declare function routeMatches(pattern: string, modelId: string): boolean;
125
+ /** Is this stored value a bundle (has a `default` policy) rather than a single policy? */
126
+ export declare function isPolicyBundle(value: unknown): value is TheoPolicyBundle;
127
+ /**
128
+ * Normalise a stored document to a bundle. A single `TheoPolicy` becomes a bundle
129
+ * with that policy as its default and no routes; a bundle passes through. One read
130
+ * path for both the legacy single-policy file and the new per-route bundle.
131
+ */
132
+ export declare function asBundle(stored: TheoPolicy | TheoPolicyBundle): TheoPolicyBundle;
133
+ /**
134
+ * The policy governing a given model id: the FIRST route whose matcher applies,
135
+ * else the bundle's default. Order in `routes` is the precedence, so put specific
136
+ * matchers before catch-alls.
137
+ */
138
+ export declare function policyForRoute(bundle: TheoPolicyBundle, modelId: string): TheoPolicy;
139
+ /**
140
+ * The reduction config the proxy enforces for a given model id under a bundle.
141
+ * Routes through `policyForRoute` then the single-policy enforcement gate, so the
142
+ * per-route ceiling and every safety guarantee (proof required, hard cap) apply to
143
+ * the SELECTED route exactly as they do to a single policy.
144
+ */
145
+ export declare function bundleToReductionConfig(bundle: TheoPolicyBundle, modelId: string): MeshTokenReductionConfig;
146
+ /** The gate verdicts for the route governing a model id (see `policyGateVerdicts`). */
147
+ export declare function bundleGateVerdicts(bundle: TheoPolicyBundle, modelId: string): Record<string, PolicyGateVerdict>;
148
+ /**
149
+ * Insert or replace a route policy in a bundle, returning a NEW bundle (never
150
+ * mutating the input). The policy must carry a `route`; a policy for an existing
151
+ * route replaces it, matched by the exact matcher string.
152
+ */
153
+ export declare function upsertRoutePolicy(bundle: TheoPolicyBundle, policy: TheoPolicy, at: string): TheoPolicyBundle;
154
+ /**
155
+ * Land a policy Theo has evolved into a bundle WITHOUT clobbering the rest of it,
156
+ * returning a NEW bundle. With a `route`, the policy becomes that route's override
157
+ * (every other route and the default preserved); without one, it replaces the
158
+ * bundle's default (every route preserved). This is what `mesh theo --apply`
159
+ * writes: Theo optimises one model at a time, so he can publish to that model's
160
+ * route and leave the others exactly as they were.
161
+ */
162
+ export declare function mergePolicyIntoBundle(existing: TheoPolicyBundle | undefined, policy: TheoPolicy, route: string | undefined, at: string): TheoPolicyBundle;
63
163
  /** The lossy levers present in the policy but NOT enforced, with the reason — for Theo's UX. */
64
164
  export declare function withheldLevers(policy: TheoPolicy): WithheldLever[];
65
165
  /**
package/types/types.d.ts CHANGED
@@ -175,9 +175,33 @@ export type MeshEvaluationCaptureConfig = {
175
175
  * into the request path. The spool is the billing source of truth a customer
176
176
  * recomputes themselves with `recomputeInvoice`.
177
177
  */
178
+ /**
179
+ * Mirror appended ledger records to a Mesh metering API. When present, each
180
+ * record is pushed fire-and-forget (with retry) to `${apiUrl}/v1/ledger/events`
181
+ * AFTER the local append, authenticated by the Mesh account key. The push never
182
+ * blocks or throws into the request path, and the local spool is always kept so
183
+ * the customer can still recompute every figure themselves.
184
+ *
185
+ * The account key is NOT the provider API key — it only identifies the Mesh
186
+ * account. The provider key never reaches the Mesh API.
187
+ */
188
+ export type MeshLedgerMirrorConfig = {
189
+ /** Mesh API base URL, e.g. https://www.mesh-technology.com. */
190
+ apiUrl: string;
191
+ /** Mesh account key (mesh_sk_…). */
192
+ accountKey: string;
193
+ /** Injectable fetch for tests; defaults to the global fetch. */
194
+ fetch?: typeof fetch;
195
+ /** Retry attempts per flush before the batch waits for the next append. Default 3. */
196
+ maxRetries?: number;
197
+ /** Max unconfirmed records buffered before the mirror quietly stops (local spool is unaffected). Default 5000. */
198
+ maxPending?: number;
199
+ };
178
200
  export type MeshSavingsLedgerConfig = {
179
201
  /** Append-only JSONL file; parent directories are created on first write. */
180
202
  path: string;
203
+ /** Optional mirror of each appended record to the Mesh metering API. */
204
+ mirror?: MeshLedgerMirrorConfig;
181
205
  /** Provider key used to resolve rates in the catalogue. Default "openai". */
182
206
  provider?: string;
183
207
  /** Rates to pin event pricing against. Default: the published catalogue. */
package/types/wrap.d.ts CHANGED
@@ -30,6 +30,14 @@ export type WrapMeshOptions = {
30
30
  tokenReduction?: MeshTokenReductionConfig;
31
31
  /** Opt into the Anthropic prompt-cache stamp on multi-turn traffic ("5m" | "1h"). */
32
32
  cacheTtl?: "5m" | "1h";
33
+ /**
34
+ * Mirror ledger events to a Mesh account. Set both to push each metered
35
+ * event to `${meshApiUrl}/v1/ledger/events`, authenticated by the Mesh
36
+ * account key from signup. Reads MESH_API_URL / MESH_ACCOUNT_KEY from the
37
+ * environment when omitted. The provider key is never sent to Mesh.
38
+ */
39
+ meshApiUrl?: string;
40
+ meshAccountKey?: string;
33
41
  };
34
42
  export type MeshSavingsSummary = {
35
43
  /** Requests metered through MESH for this app. */
@@ -1,31 +0,0 @@
1
- export type CacheTtlRecommendation = {
2
- ttl: "5m" | "1h";
3
- /** Why this TTL was chosen, for the stamp's change record. */
4
- reason: string;
5
- };
6
- export type CacheTtlAdvisorOptions = {
7
- /** LRU bound on tracked conversations. Default 1000. */
8
- maxConversations?: number;
9
- /** Gaps needed before the advisor will move off the 5m default. Default 3. */
10
- minObservations?: number;
11
- /** Recommend 1h once the realized gap p90 exceeds this many seconds. Default 300 (5m). */
12
- upgradeGapP90Seconds?: number;
13
- /** Most recent gaps retained per conversation for the p90. Default 20. */
14
- windowGaps?: number;
15
- };
16
- export declare class CacheTtlAdvisor {
17
- /** Insertion-ordered; re-inserted on touch, so the first key is the LRU. */
18
- private readonly conversations;
19
- private readonly maxConversations;
20
- private readonly minObservations;
21
- private readonly upgradeGapP90Seconds;
22
- private readonly windowGaps;
23
- constructor(options?: CacheTtlAdvisorOptions);
24
- /**
25
- * Record this request's arrival and recommend a TTL for its conversation.
26
- * Call once per request. `nowSeconds` is injectable for tests; at runtime it
27
- * defaults to the wall clock.
28
- */
29
- recommend(request: unknown, nowSeconds?: number): CacheTtlRecommendation;
30
- private evict;
31
- }
@@ -1,11 +0,0 @@
1
- import type { ReplayAdapter, ReplayInputCase, ReplayRecord, ReplayTarget } from "./types.js";
2
- export type ReplayRunFailure = {
3
- id: string;
4
- side: "baseline" | "candidate";
5
- message: string;
6
- };
7
- export type ReplayRunResult = {
8
- records: ReplayRecord[];
9
- failures: ReplayRunFailure[];
10
- };
11
- export declare function runReplayCases(cases: ReplayInputCase[], baseline: ReplayTarget, candidate: ReplayTarget, adapter: ReplayAdapter): Promise<ReplayRunResult>;
@@ -1,24 +0,0 @@
1
- import type { ModelTarget } from "./types.js";
2
- export type RoutingSimulationInput = {
3
- requestIds: string[];
4
- baseline: ModelTarget;
5
- candidate: ModelTarget;
6
- stages: Array<{
7
- rolloutPercentage: number;
8
- /** Synthetic failure rate for demonstrating the rollback gate. */
9
- candidateErrorRate: number;
10
- }>;
11
- maximumErrorRate: number;
12
- minimumSamples: number;
13
- };
14
- export type RoutingSimulationStage = {
15
- rolloutPercentage: number;
16
- assigned: number;
17
- candidateErrors: number;
18
- observedErrorRate: number | null;
19
- status: "advanced" | "rolled_back" | "insufficient_sample";
20
- };
21
- /** Stable FNV-1a assignment: the same request key always lands in the same cohort. */
22
- export declare function rolloutBucket(requestId: string): number;
23
- /** Offline only: simulates canary assignment and rollback using synthetic outcomes. */
24
- export declare function simulateRouting(input: RoutingSimulationInput): RoutingSimulationStage[];