@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.
- package/LICENSE +98 -0
- package/README.md +48 -2
- package/bin/mesh-demo.mjs +105 -0
- package/bin/mesh-proxy.mjs +39 -0
- package/bin/mesh-quote.mjs +45 -0
- package/bin/mesh-report.mjs +47 -0
- package/index.cjs +6306 -0
- package/index.js +6204 -0
- package/package.json +39 -4
- package/types/blind-features.d.ts +28 -0
- package/types/cache-volatility-guard.d.ts +31 -0
- 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/cache-simulator.d.ts +271 -0
- package/types/core/confidence.d.ts +36 -0
- package/types/core/cost.d.ts +16 -0
- package/types/core/evaluator.d.ts +16 -0
- package/types/core/gateway.d.ts +75 -0
- package/types/core/geo-visibility.d.ts +25 -0
- package/types/core/github-oauth.d.ts +41 -0
- package/types/core/helicone.d.ts +6 -0
- package/types/core/index.d.ts +36 -0
- package/types/core/langfuse.d.ts +7 -0
- package/types/core/ledger-store.d.ts +62 -0
- package/types/core/litellm.d.ts +15 -0
- package/types/core/local-tier.d.ts +82 -0
- package/types/core/model-prices.d.ts +25 -0
- package/types/core/output-diagnostics.d.ts +39 -0
- package/types/core/price-catalogue.d.ts +168 -0
- package/types/core/provider-usage.d.ts +84 -0
- package/types/core/quote-report.d.ts +54 -0
- package/types/core/replay.d.ts +2 -0
- package/types/core/router.d.ts +9 -0
- package/types/core/routing.d.ts +282 -0
- package/types/core/savings-ledger.d.ts +349 -0
- package/types/core/savings-model.d.ts +132 -0
- package/types/core/stripe-billing.d.ts +67 -0
- package/types/core/stripe-client.d.ts +117 -0
- package/types/core/stripe-sink.d.ts +77 -0
- package/types/core/theo-coverage.d.ts +49 -0
- package/types/core/token-reduction.d.ts +219 -0
- package/types/core/tool-schema.d.ts +64 -0
- package/types/core/traffic.d.ts +182 -0
- package/types/core/triage.d.ts +70 -0
- package/types/core/types.d.ts +149 -0
- package/types/core/workflow-sessions.d.ts +50 -0
- package/types/cta.d.ts +60 -0
- package/types/evaluation-capture.d.ts +11 -0
- package/types/exact-cache.d.ts +20 -0
- package/types/graders.d.ts +53 -0
- package/types/index.d.ts +31 -0
- package/types/ledger-mirror.d.ts +38 -0
- package/types/openai.d.ts +23 -0
- package/types/proxy.d.ts +104 -0
- package/types/reduce-request.d.ts +272 -0
- package/types/replay-gate.d.ts +120 -0
- package/types/report.d.ts +33 -0
- package/types/routing.d.ts +11 -0
- package/types/savings-ledger.d.ts +22 -0
- package/types/savings-snapshot.d.ts +11 -0
- package/types/semantic-compaction.d.ts +84 -0
- package/types/telemetry.d.ts +6 -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 +219 -0
- package/types/types.d.ts +287 -0
- package/types/wrap.d.ts +60 -0
package/types/index.d.ts
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
export { serviceTierOf, withMesh } from "./openai.js";
|
|
2
|
+
export * from "./types.js";
|
|
3
|
+
export { chooseRoute } from "./routing.js";
|
|
4
|
+
export { ExactResponseCache } from "./exact-cache.js";
|
|
5
|
+
export { createLocalJsonlCapture } from "./evaluation-capture.js";
|
|
6
|
+
export { billableEventFromRequest, createSavingsLedger } from "./savings-ledger.js";
|
|
7
|
+
export type { SavingsLedger } from "./savings-ledger.js";
|
|
8
|
+
export { startMeshProxy, usageFromSse } from "./proxy.js";
|
|
9
|
+
export type { MeshProxy, MeshProxyOptions } from "./proxy.js";
|
|
10
|
+
export { buildQuoteReport, parseGatewayExport, renderQuoteReport } from "./core/index.js";
|
|
11
|
+
export type { QuoteExportFormat, QuoteReport, QuoteStreamReport } from "./core/index.js";
|
|
12
|
+
export { auditEventPricing, canonicalJson, catalogueVersion, chainLedgerRecord, ledgerEventHash, LEDGER_GENESIS_HASH, priceLedgerUsage, publishedModelPrices, recomputeInvoice, verifyLedgerChain, } from "./core/index.js";
|
|
13
|
+
export type { BillableEvent, Invoice, InvoiceLineItem, InvoiceOptions, InvoiceUnbilledItem, LedgerChainVerification, LedgerExecutionMode, LedgerGateVerdict, LedgerLever, LedgerLeverKind, LedgerPricing, LedgerPricingAudit, LedgerPricingInput, LedgerRecord, LedgerUsage, PriceCatalogue, } from "./core/index.js";
|
|
14
|
+
export { capToolResultBody, digestStaleBody, reduceRequest } from "./reduce-request.js";
|
|
15
|
+
export { wrapMesh, type WrapMeshOptions, type MeshSavingsSummary, type MeshHandle, } from "./wrap.js";
|
|
16
|
+
export { extractBlindFeatures, type BlindFeatures } from "./blind-features.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";
|
|
21
|
+
export { compactStaleContext, reduceRequestAsync } from "./semantic-compaction.js";
|
|
22
|
+
export type { SemanticCompactionConfig, SemanticCompactionResult, SemanticCompactor, } from "./semantic-compaction.js";
|
|
23
|
+
export { CachePrefixVolatilityGuard, type CacheStampDecision } from "./cache-volatility-guard.js";
|
|
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";
|
|
27
|
+
export type { MeshHistoryCompactionConfig, MeshReductionChange, MeshReductionSummary, MeshTokenReductionConfig, } from "./reduce-request.js";
|
|
28
|
+
export { exactTextGrader, replayGate, replayUsage, responseText, responseToolCalls, toolNameGrader, toolSelectionGrader, } from "./replay-gate.js";
|
|
29
|
+
export type { ReplayCandidate, ReplayCandidateResult, ReplayComparison, ReplayGateOptions, ReplayGateResult, ReplayGrader, ReplayUsage, ToolCall, } from "./replay-gate.js";
|
|
30
|
+
export { agentGrader, compositeGrader, textSimilarityGrader, truncationAwareGrader, } from "./graders.js";
|
|
31
|
+
export type { TruncationOptions, WeightedGrader } from "./graders.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
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { MeshOptions } from "./types.js";
|
|
2
|
+
type AnyObject = Record<PropertyKey, any>;
|
|
3
|
+
/**
|
|
4
|
+
* The served-tier detection the ledger event is built from: the tier the
|
|
5
|
+
* provider ANSWERED with (OpenAI's top-level response.service_tier, Anthropic's
|
|
6
|
+
* usage.service_tier), never the tier the request asked for. Exported so the
|
|
7
|
+
* measurement harness prices the SERVED tier through this exact code path
|
|
8
|
+
* rather than reimplementing it: a flex request answered "default" must bill
|
|
9
|
+
* standard everywhere, and a response with no tier evidence reports undefined.
|
|
10
|
+
*/
|
|
11
|
+
export declare function serviceTierOf(response: AnyObject | undefined): string | undefined;
|
|
12
|
+
/**
|
|
13
|
+
* Wrap a provider client and preserve its response shapes.
|
|
14
|
+
*
|
|
15
|
+
* Three surfaces route through ONE shared handler: OpenAI Responses
|
|
16
|
+
* (responses.create), OpenAI Chat Completions (chat.completions.create), and
|
|
17
|
+
* an Anthropic-SDK-shaped client (messages.create). Reduction, routing, the
|
|
18
|
+
* exact cache, telemetry, evaluation capture and the savings ledger are all
|
|
19
|
+
* the same code on every surface - the adapters differ only in which output-cap
|
|
20
|
+
* field a routing candidate uses and which provider label the event records.
|
|
21
|
+
*/
|
|
22
|
+
export declare function withMesh<T extends AnyObject>(client: T, options: MeshOptions): T;
|
|
23
|
+
export {};
|
package/types/proxy.d.ts
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import { type MeshTokenReductionConfig } from "./reduce-request.js";
|
|
2
|
+
/**
|
|
3
|
+
* MESH proxy mode: point an application's base_url here instead of changing
|
|
4
|
+
* its code. The proxy applies the configured token reduction to each request,
|
|
5
|
+
* forwards it to the real provider with the CALLER's own credentials, returns
|
|
6
|
+
* the provider's bytes untouched, and appends one hash-chained ledger event
|
|
7
|
+
* per completed request — the same recomputable record the SDK wrapper writes.
|
|
8
|
+
*
|
|
9
|
+
* The contract, enforced rather than promised:
|
|
10
|
+
* - MESH never holds keys. Auth headers pass through verbatim; nothing is
|
|
11
|
+
* stored. Prompts are analysed in-process and never written anywhere — the
|
|
12
|
+
* ledger records usage numbers, lever names and hashes, not content.
|
|
13
|
+
* - Nothing here may break a request. Reduction never throws (a failure
|
|
14
|
+
* returns the original request); a ledger failure silently disables the
|
|
15
|
+
* meter; only an unreachable upstream produces an error, and it is the
|
|
16
|
+
* upstream's own status and body wherever one exists.
|
|
17
|
+
* - Responses stream through as they arrive. Usage for the ledger is parsed
|
|
18
|
+
* from the SSE events after the last byte has already been forwarded; a
|
|
19
|
+
* stream whose usage cannot be read produces an UNPRICED event, never a
|
|
20
|
+
* guessed one.
|
|
21
|
+
* - Lossless levers only by default. Lossy levers and tier/cache stamps are
|
|
22
|
+
* per-deployment configuration, exactly as in the SDK.
|
|
23
|
+
*/
|
|
24
|
+
type AnyObject = Record<string, unknown>;
|
|
25
|
+
export type MeshProxyOptions = {
|
|
26
|
+
/** Port to listen on; 0 picks a free one (reported by start()). */
|
|
27
|
+
port?: number;
|
|
28
|
+
/** Directory for the hash-chained ledger spools (one per app + provider). */
|
|
29
|
+
ledgerDirectory: string;
|
|
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
|
+
}>;
|
|
51
|
+
/** Override upstreams, e.g. a mock in tests or an OpenAI-compatible host. */
|
|
52
|
+
anthropicUpstream?: string;
|
|
53
|
+
openaiUpstream?: string;
|
|
54
|
+
/**
|
|
55
|
+
* Enable the provably-blind learning stream: when set, each request also
|
|
56
|
+
* appends an IRREVERSIBLE feature record (keyed HMAC hashes + structural
|
|
57
|
+
* counts, never any prompt content) to a `<app>-<provider>.features.jsonl`
|
|
58
|
+
* spool. This is the hmac key; it must live only in the gateway (ideally
|
|
59
|
+
* sealed inside an enclave). Off when unset — no features are computed.
|
|
60
|
+
*/
|
|
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
|
+
};
|
|
84
|
+
};
|
|
85
|
+
export type MeshProxy = {
|
|
86
|
+
port: number;
|
|
87
|
+
url: string;
|
|
88
|
+
close: () => Promise<void>;
|
|
89
|
+
};
|
|
90
|
+
/**
|
|
91
|
+
* Merge the usage scattered across a surface's SSE events into one response-
|
|
92
|
+
* shaped object normalizeProviderUsage can read. Returns undefined when the
|
|
93
|
+
* stream carried no readable usage — the event is then unpriced, never guessed.
|
|
94
|
+
*/
|
|
95
|
+
export declare function usageFromSse(provider: "anthropic" | "openai", sseText: string): AnyObject | undefined;
|
|
96
|
+
/**
|
|
97
|
+
* Assistant text of a streamed response, for output-waste metering: the
|
|
98
|
+
* concatenated text deltas of whichever surface produced the stream. Used
|
|
99
|
+
* only after the bytes were already forwarded; never stored.
|
|
100
|
+
*/
|
|
101
|
+
export declare function outputTextFromSse(provider: "anthropic" | "openai", sseText: string): string;
|
|
102
|
+
/** Start the MESH proxy. Resolves once the server is listening. */
|
|
103
|
+
export declare function startMeshProxy(options: MeshProxyOptions): Promise<MeshProxy>;
|
|
104
|
+
export {};
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
import { type TokenCounter } from "../../core/dist/src/token-reduction.js";
|
|
2
|
+
/**
|
|
3
|
+
* Reduce a request before it is sent.
|
|
4
|
+
*
|
|
5
|
+
* This is the part of MESH that actually lowers a bill rather than measuring how
|
|
6
|
+
* much it could be lowered. It runs on every request, independent of model
|
|
7
|
+
* routing: the levers here spend fewer tokens on the model the caller already
|
|
8
|
+
* chose, so coupling them to a model swap would be backwards.
|
|
9
|
+
*
|
|
10
|
+
* Every transform here is lossless by default. Tool definitions keep their
|
|
11
|
+
* descriptions, only formatting and schema plumbing go, duplicate blocks are
|
|
12
|
+
* exact duplicates, and prefix repair moves text rather than deleting it. The
|
|
13
|
+
* lossy options exist but are opt-in and reported as such, because descriptions
|
|
14
|
+
* are how a model chooses between tools.
|
|
15
|
+
*
|
|
16
|
+
* Nothing here may break a request. Any failure returns the original untouched.
|
|
17
|
+
*/
|
|
18
|
+
export type MeshReductionChange = {
|
|
19
|
+
lever: string;
|
|
20
|
+
lossless: boolean;
|
|
21
|
+
estimatedTokensSaved: number;
|
|
22
|
+
detail: string;
|
|
23
|
+
};
|
|
24
|
+
/** Reasoning/output effort levels Anthropic's `output_config.effort` accepts. */
|
|
25
|
+
export type MeshOutputEffort = "low" | "medium" | "high" | "xhigh" | "max";
|
|
26
|
+
export type MeshReductionSummary = {
|
|
27
|
+
/** Estimated input tokens before reduction, by MESH's own counter. */
|
|
28
|
+
estimatedTokensBefore: number;
|
|
29
|
+
estimatedTokensAfter: number;
|
|
30
|
+
estimatedTokensSaved: number;
|
|
31
|
+
/** Of the above, the share from transforms that cannot change the answer. */
|
|
32
|
+
estimatedLosslessTokensSaved: number;
|
|
33
|
+
changes: MeshReductionChange[];
|
|
34
|
+
/** True when reduction was attempted but the request was returned unchanged. */
|
|
35
|
+
skipped: boolean;
|
|
36
|
+
skippedReason?: string;
|
|
37
|
+
};
|
|
38
|
+
export type MeshHistoryCompactionConfig = {
|
|
39
|
+
/**
|
|
40
|
+
* Compaction starts once the conversation has at least this many user turns.
|
|
41
|
+
* Short conversations are left alone: there is nothing stale to compact.
|
|
42
|
+
*/
|
|
43
|
+
minimumTurns?: number;
|
|
44
|
+
/** The most recent turns whose content is always left verbatim. */
|
|
45
|
+
keepRecentTurns?: number;
|
|
46
|
+
/**
|
|
47
|
+
* The compaction boundary only advances in steps of this many turns, so the
|
|
48
|
+
* set of compacted messages is identical across several consecutive requests
|
|
49
|
+
* and the provider's exact-prefix cache can keep matching through them.
|
|
50
|
+
*/
|
|
51
|
+
epochTurns?: number;
|
|
52
|
+
};
|
|
53
|
+
export type MeshTokenReductionConfig = {
|
|
54
|
+
/**
|
|
55
|
+
* Tool and MCP schema minification. `true` applies the lossless tier only.
|
|
56
|
+
* Pass an object to opt into description trimming, which is a behaviour change.
|
|
57
|
+
*/
|
|
58
|
+
toolSchemas?: boolean | {
|
|
59
|
+
descriptions?: "keep" | "truncate" | "drop";
|
|
60
|
+
maximumDescriptionTokens?: number;
|
|
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[];
|
|
81
|
+
/** Remove exact duplicate blocks from instructions and message text. */
|
|
82
|
+
duplicateContext?: boolean;
|
|
83
|
+
/**
|
|
84
|
+
* Move per-request values (timestamps, request ids) out of the front of the
|
|
85
|
+
* instructions so the stable remainder becomes a cacheable prefix. Providers
|
|
86
|
+
* match an exact prefix, so one changing value at the top of an otherwise
|
|
87
|
+
* identical system prompt costs the whole prompt's cache discount.
|
|
88
|
+
*/
|
|
89
|
+
repairCachePrefix?: boolean;
|
|
90
|
+
/**
|
|
91
|
+
* Replace stale tool-result and assistant bodies in old turns with short
|
|
92
|
+
* deterministic digests. Error messages, file paths and the headline sentence
|
|
93
|
+
* survive verbatim; the rest is summarised by a byte count. The boundary only
|
|
94
|
+
* moves in frozen epochs, so consecutive requests re-emit the compacted
|
|
95
|
+
* history byte-identically and the provider cache re-writes once per epoch,
|
|
96
|
+
* never once per turn. `true` uses the defaults; pass an object to tune.
|
|
97
|
+
*/
|
|
98
|
+
historyCompaction?: boolean | MeshHistoryCompactionConfig;
|
|
99
|
+
/**
|
|
100
|
+
* Replace a repeated LEADING block in same-role messages after the first
|
|
101
|
+
* with a short reference marker, keeping each message's differing
|
|
102
|
+
* remainder verbatim. This is the shape a continuous-learning /
|
|
103
|
+
* continuous-memory agent produces: the application glues the same
|
|
104
|
+
* memory or persistent-instruction block to the front of every turn, so
|
|
105
|
+
* the history carries N-1 byte-identical copies that no existing lever
|
|
106
|
+
* catches (`duplicateContext` only ever sees one message's text at a
|
|
107
|
+
* time, never the text several messages back that a later one repeats).
|
|
108
|
+
*
|
|
109
|
+
* LOSSY, unlike `duplicateContext`: the duplicate removed here is never
|
|
110
|
+
* adjacent to its twin, so a model that attends less to context far back
|
|
111
|
+
* in a long history may behave differently with the block present once
|
|
112
|
+
* near the start versus restated fresh every turn. This must be proven
|
|
113
|
+
* on the customer's own traffic through `replayGate` before it is ever
|
|
114
|
+
* billed, and is never enabled by default. The cut is always snapped to
|
|
115
|
+
* a line boundary (see `dedupeRepeatedLeadingBlock`), so a false match on
|
|
116
|
+
* two messages that merely open with the same few words can never
|
|
117
|
+
* truncate into the line where they actually differ. `true` uses the
|
|
118
|
+
* default 64-token minimum block size; pass an object to tune it. Applies
|
|
119
|
+
* only to messages whose content is a plain string or whose first content
|
|
120
|
+
* block is `{type: "text", text}`; anything else is left untouched.
|
|
121
|
+
*/
|
|
122
|
+
crossTurnMemoryDedup?: boolean | {
|
|
123
|
+
minimumBlockTokens?: number;
|
|
124
|
+
};
|
|
125
|
+
/**
|
|
126
|
+
* Cap oversized tool-result and assistant bodies at injection, BEFORE first
|
|
127
|
+
* send. A fresh oversized result is billed once at the FULL input rate and
|
|
128
|
+
* only its cached rebills are discounted, so this reaches tokens that
|
|
129
|
+
* history compaction (which touches already-cached turns) never can. The
|
|
130
|
+
* headline sentence, error mentions, file paths and MESH's own markers
|
|
131
|
+
* survive verbatim; the rest collapses to a char-count marker. Pure,
|
|
132
|
+
* deterministic and idempotent, so consecutive requests re-emit identical
|
|
133
|
+
* bytes and the provider cache keeps matching. Lossy by definition and
|
|
134
|
+
* reported as such. `true` uses the 600-token default; pass an object to
|
|
135
|
+
* tune `maximumTokens` (integer, at least 64).
|
|
136
|
+
*/
|
|
137
|
+
freshToolResultCap?: boolean | {
|
|
138
|
+
maximumTokens?: number;
|
|
139
|
+
};
|
|
140
|
+
/**
|
|
141
|
+
* Output budget, applied through the field each surface honours: Responses
|
|
142
|
+
* max_output_tokens (set only when absent), Chat Completions
|
|
143
|
+
* max_completion_tokens (set only when the caller set no cap in any
|
|
144
|
+
* spelling), Anthropic Messages max_tokens (downward-only clamp of the
|
|
145
|
+
* caller's required value). Output is the dearer half of the bill.
|
|
146
|
+
*/
|
|
147
|
+
maxOutputTokens?: number;
|
|
148
|
+
/**
|
|
149
|
+
* Output effort governor: Anthropic's `output_config.effort`
|
|
150
|
+
* ("low" | "medium" | "high" | "xhigh" | "max"; default "high"). The one
|
|
151
|
+
* output-side lever that is PROVIDER-SANCTIONED rather than a prompt hack — a
|
|
152
|
+
* lower effort makes the model think less and answer terser (less preamble,
|
|
153
|
+
* fewer and more-consolidated tool calls), cutting the dearest half of the
|
|
154
|
+
* bill: output tokens price 4-8x input. This is MESH's honest equivalent of a
|
|
155
|
+
* competitor that "trims the model's replies": the model decides how to be
|
|
156
|
+
* briefer, we do not truncate or rewrite its words.
|
|
157
|
+
*
|
|
158
|
+
* It is a TOP-LEVEL request field, outside the cached prefix (tools -> system
|
|
159
|
+
* -> messages), so a STABLE value never invalidates a prompt cache — unlike
|
|
160
|
+
* editing the system prompt to beg for brevity, which rewrites the cached
|
|
161
|
+
* prefix every turn. (A value that CHANGED between turns would invalidate the
|
|
162
|
+
* messages cache, so this is a per-workload setting, never flipped mid-run.)
|
|
163
|
+
*
|
|
164
|
+
* LOSSY: it changes the answer's depth and length, so it is off by default,
|
|
165
|
+
* must clear a TASK-COMPLETION replay gate before any saving is billed
|
|
166
|
+
* (exactTextGrader is meaningless here — a terser answer is different text by
|
|
167
|
+
* definition), and is only ever the caller's per-workload flag. Applied only
|
|
168
|
+
* on Claude models whose published effort range includes the requested level
|
|
169
|
+
* (an unsupported level is a 400, and this reducer must never break a
|
|
170
|
+
* request); an unsupported pairing is recorded and skipped, never stamped. A
|
|
171
|
+
* caller who set `output_config.effort` themselves is left untouched. The
|
|
172
|
+
* OpenAI `reasoning.effort` sibling is a planned follow-on, not wired here.
|
|
173
|
+
*/
|
|
174
|
+
outputEffort?: MeshOutputEffort;
|
|
175
|
+
/**
|
|
176
|
+
* Execution tier for requests the caller has flagged latency-tolerant.
|
|
177
|
+
* "flex" sets OpenAI's service_tier on the request (batch-level pricing, 50%
|
|
178
|
+
* off input and output, on a synchronous API with a possible 429 fallback to
|
|
179
|
+
* standard). The answer is unchanged - same model, same tokens - so this is
|
|
180
|
+
* deterministic for cost; only latency changes, which is why it must be the
|
|
181
|
+
* CALLER's flag per workload and is never set by default. Applied only when
|
|
182
|
+
* the request does not already carry a service_tier, only on OpenAI-shaped
|
|
183
|
+
* requests (service_tier is not an Anthropic field), and only for models the
|
|
184
|
+
* published catalogue resolves - a tier delta on an unpriceable model could
|
|
185
|
+
* never be verified, so it is never stamped.
|
|
186
|
+
*/
|
|
187
|
+
executionTier?: "flex";
|
|
188
|
+
/**
|
|
189
|
+
* Anthropic prompt-cache stamping. Anthropic's cache is OPT-IN: a Claude
|
|
190
|
+
* request with no cache_control gets no caching at all and re-pays full
|
|
191
|
+
* rate for its entire history every turn (the first live export measured a
|
|
192
|
+
* five-turn agent with zero cache traffic). This lever stamps
|
|
193
|
+
* `cache_control: {type: "ephemeral", ttl}` on the STABLE prefix of an
|
|
194
|
+
* Anthropic-shaped request (a `claude-*` model with a `messages` array):
|
|
195
|
+
* always on the system prompt when one exists, and on the last message only
|
|
196
|
+
* for multi-turn requests, whose history is re-sent verbatim next turn. A
|
|
197
|
+
* one-shot request with no system prompt is never stamped — its prefix
|
|
198
|
+
* never repeats, so a breakpoint could only buy write premiums (the first
|
|
199
|
+
* live export measured exactly that loss).
|
|
200
|
+
*
|
|
201
|
+
* Pick the TTL by call spacing. "5m" (writes 1.25x base, reads 0.1x) is the
|
|
202
|
+
* multi-turn agent setting: turns arrive seconds apart, so every turn after
|
|
203
|
+
* the first reads its history at a tenth of the price. "1h" (writes 2x)
|
|
204
|
+
* pays exactly when calls arrive MORE than ~5 minutes but less than an hour
|
|
205
|
+
* apart - the regime where a 5m entry expires between calls and every call
|
|
206
|
+
* rewrites. Applied only when the request carries no cache_control of its
|
|
207
|
+
* own: a caller who placed breakpoints has chosen their own caching and
|
|
208
|
+
* silently raising their write rate would change their bill. Never set by
|
|
209
|
+
* default; like executionTier, it must be the caller's per-workload flag.
|
|
210
|
+
*/
|
|
211
|
+
cacheTtl?: "5m" | "1h";
|
|
212
|
+
/**
|
|
213
|
+
* Cross-turn volatility guard for the cache stamp (see
|
|
214
|
+
* cache-volatility-guard.ts). The reducer is a pure per-request function
|
|
215
|
+
* and cannot see that a conversation's prefix churns between turns; the
|
|
216
|
+
* guard can, and a churning prefix turns the stamp into pure write premium
|
|
217
|
+
* (the second live export measured exactly that loss). The proxy and
|
|
218
|
+
* withMesh install one automatically whenever cacheTtl is set; it is
|
|
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`).
|
|
223
|
+
*/
|
|
224
|
+
cacheVolatilityGuard?: {
|
|
225
|
+
observe(request: unknown, context?: {
|
|
226
|
+
stampedPrefix?: unknown;
|
|
227
|
+
}): {
|
|
228
|
+
stamp: boolean;
|
|
229
|
+
messageBreakpoint?: boolean;
|
|
230
|
+
reason?: string;
|
|
231
|
+
};
|
|
232
|
+
};
|
|
233
|
+
countTokens?: TokenCounter;
|
|
234
|
+
onReduction?: (summary: MeshReductionSummary) => void;
|
|
235
|
+
};
|
|
236
|
+
/**
|
|
237
|
+
* Digest one stale body. Pure function of the text, so every later request in
|
|
238
|
+
* the same epoch re-emits exactly the same bytes, which is what lets the
|
|
239
|
+
* provider's exact-prefix cache match across the compacted region.
|
|
240
|
+
*
|
|
241
|
+
* Kept verbatim: the headline (first sentence), any sentence that mentions an
|
|
242
|
+
* error, and any sentence containing a file path. Everything else collapses to
|
|
243
|
+
* a byte count. If that would not actually shorten the text, the original is
|
|
244
|
+
* returned untouched.
|
|
245
|
+
*/
|
|
246
|
+
export declare function digestStaleBody(text: string): string;
|
|
247
|
+
/**
|
|
248
|
+
* Cap one oversized tool-result body at injection time, BEFORE it is first
|
|
249
|
+
* sent. A fresh result is billed once at the FULL input rate; only its cached
|
|
250
|
+
* rebills get the provider discount, so this is the one lever that removes
|
|
251
|
+
* full-rate tokens rather than nibbling 0.1x rebills of an already-cached copy.
|
|
252
|
+
*
|
|
253
|
+
* Pure and idempotent: a body at or under `maximumTokens` is returned
|
|
254
|
+
* untouched (identity, no marker), and capping a capped body changes nothing,
|
|
255
|
+
* because every surviving segment - the headline, error mentions, file paths
|
|
256
|
+
* and MESH's own markers - is a keeper on the second pass too. The same keep
|
|
257
|
+
* rules as stale compaction apply, so later turns still find the reference
|
|
258
|
+
* they depend on; a capper that lost the latest result's headline would fail
|
|
259
|
+
* tasks, which is exactly the quality bar working.
|
|
260
|
+
*/
|
|
261
|
+
export declare function capToolResultBody(text: string, maximumTokens: number, countTokens: TokenCounter): string;
|
|
262
|
+
/**
|
|
263
|
+
* Apply reduction to one request.
|
|
264
|
+
*
|
|
265
|
+
* Returns the original request and a `skipped` summary if anything goes wrong,
|
|
266
|
+
* because a cheaper request that fails is worth less than an expensive one that
|
|
267
|
+
* works.
|
|
268
|
+
*/
|
|
269
|
+
export declare function reduceRequest(request: unknown, config?: MeshTokenReductionConfig): {
|
|
270
|
+
request: unknown;
|
|
271
|
+
summary: MeshReductionSummary;
|
|
272
|
+
};
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { type TokenPrice } from "../../core/dist/src/cost.js";
|
|
2
|
+
import { type MeshTokenReductionConfig } from "./reduce-request.js";
|
|
3
|
+
export type ReplayComparison = {
|
|
4
|
+
request: unknown;
|
|
5
|
+
baselineResponse: unknown;
|
|
6
|
+
candidateResponse: unknown;
|
|
7
|
+
};
|
|
8
|
+
/** Returns 1 when the candidate is as good as the baseline, 0 when unusable. */
|
|
9
|
+
export type ReplayGrader = (comparison: ReplayComparison) => number | Promise<number>;
|
|
10
|
+
export type ReplayCandidate = {
|
|
11
|
+
label: string;
|
|
12
|
+
config: MeshTokenReductionConfig;
|
|
13
|
+
};
|
|
14
|
+
export type ReplayGateOptions = {
|
|
15
|
+
/** A representative sample of real requests. */
|
|
16
|
+
requests: unknown[];
|
|
17
|
+
/** Sends a request and returns the provider's response. */
|
|
18
|
+
call: (request: unknown) => Promise<unknown>;
|
|
19
|
+
candidates: ReplayCandidate[];
|
|
20
|
+
grade: ReplayGrader;
|
|
21
|
+
/** Mean quality the gate may give up, against the unreduced baseline. Default 0.02. */
|
|
22
|
+
maximumQualityDrop?: number;
|
|
23
|
+
bootstrapSamples?: number;
|
|
24
|
+
seed?: string;
|
|
25
|
+
/**
|
|
26
|
+
* Group label per request. Several requests drawn from one prompt or task are
|
|
27
|
+
* correlated, and treating them as independent overstates the bound.
|
|
28
|
+
*/
|
|
29
|
+
groupOf?: (request: unknown, index: number) => string;
|
|
30
|
+
/** Recorded baseline responses, to avoid paying for the baseline run again. */
|
|
31
|
+
baselineResponses?: unknown[];
|
|
32
|
+
/** Rate used to express savings in money as well as tokens. */
|
|
33
|
+
price?: TokenPrice;
|
|
34
|
+
/**
|
|
35
|
+
* Called before the baseline run and before each candidate run.
|
|
36
|
+
*
|
|
37
|
+
* Providers hold state between calls: a prefix cache is cold on the first
|
|
38
|
+
* request and warm afterwards. Without a reset between runs the baseline
|
|
39
|
+
* warms the cache that the candidates then benefit from, which flatters every
|
|
40
|
+
* candidate and makes the baseline look worse than it is. Use this to clear
|
|
41
|
+
* whatever state would otherwise leak across runs.
|
|
42
|
+
*/
|
|
43
|
+
beforeRun?: (label: string) => void | Promise<void>;
|
|
44
|
+
};
|
|
45
|
+
export type ReplayUsage = {
|
|
46
|
+
/** Total input billed, inclusive of anything served from cache. */
|
|
47
|
+
inputTokens: number;
|
|
48
|
+
outputTokens: number;
|
|
49
|
+
/** Input served from the provider's cache, billed at the cached rate. */
|
|
50
|
+
cachedInputTokens: number;
|
|
51
|
+
/** Input written into the cache, which some providers bill at a premium. */
|
|
52
|
+
cacheWriteInputTokens: number;
|
|
53
|
+
};
|
|
54
|
+
export type ReplayCandidateResult = {
|
|
55
|
+
label: string;
|
|
56
|
+
config: MeshTokenReductionConfig;
|
|
57
|
+
graded: number;
|
|
58
|
+
/** Requests where either side failed, excluded from the verdict. */
|
|
59
|
+
failed: number;
|
|
60
|
+
meanQualityDelta: number;
|
|
61
|
+
lower95QualityDelta: number;
|
|
62
|
+
approved: boolean;
|
|
63
|
+
rejectionReason?: string;
|
|
64
|
+
baselineUsage: ReplayUsage;
|
|
65
|
+
candidateUsage: ReplayUsage;
|
|
66
|
+
inputTokensSaved: number;
|
|
67
|
+
outputTokensSaved: number;
|
|
68
|
+
tokenSavingPercent: number;
|
|
69
|
+
costSavedUsd?: number;
|
|
70
|
+
costSavingPercent?: number;
|
|
71
|
+
};
|
|
72
|
+
export type ReplayGateResult = {
|
|
73
|
+
candidates: ReplayCandidateResult[];
|
|
74
|
+
/** The most aggressive candidate that held quality, if any did. */
|
|
75
|
+
approved?: ReplayCandidateResult;
|
|
76
|
+
maximumQualityDrop: number;
|
|
77
|
+
/** Provider calls this replay made, so its cost is visible. */
|
|
78
|
+
calls: number;
|
|
79
|
+
notes: string[];
|
|
80
|
+
};
|
|
81
|
+
/**
|
|
82
|
+
* Pull usage out of a Responses, Chat Completions or Anthropic Messages shape.
|
|
83
|
+
*
|
|
84
|
+
* Cached tokens must be read, not ignored. Pricing all input at the full rate
|
|
85
|
+
* makes prefix caching worth exactly zero to the gate, which would mean the
|
|
86
|
+
* largest lossless lever could never be measured or credited.
|
|
87
|
+
*
|
|
88
|
+
* The parsing itself now lives in packages/core (normalizeProviderUsage), the
|
|
89
|
+
* single shared normaliser the SDK wrapper and the ledger read through too, so
|
|
90
|
+
* the gate and the meter can never disagree about what a response cost. This
|
|
91
|
+
* wrapper keeps the gate's historical contract: the usage, or undefined.
|
|
92
|
+
*/
|
|
93
|
+
export declare function replayUsage(response: unknown): ReplayUsage | undefined;
|
|
94
|
+
/** Concatenate the assistant text of a response, ignoring structure. */
|
|
95
|
+
export declare function responseText(response: unknown): string;
|
|
96
|
+
export type ToolCall = {
|
|
97
|
+
name: string;
|
|
98
|
+
argumentsJson: string;
|
|
99
|
+
};
|
|
100
|
+
/** Tool calls a response made, normalised so two responses can be compared. */
|
|
101
|
+
export declare function responseToolCalls(response: unknown): ToolCall[];
|
|
102
|
+
/** Scores 1 only when the assistant text matches exactly. */
|
|
103
|
+
export declare const exactTextGrader: ReplayGrader;
|
|
104
|
+
/**
|
|
105
|
+
* Scores on whether the same tools were called with the same arguments.
|
|
106
|
+
*
|
|
107
|
+
* The grader that matters for tool-description trimming, because that lever's
|
|
108
|
+
* risk is precisely that the model picks a different tool. Text graders miss it:
|
|
109
|
+
* two different tool choices can produce similarly-worded replies.
|
|
110
|
+
*/
|
|
111
|
+
export declare const toolSelectionGrader: ReplayGrader;
|
|
112
|
+
/** Scores 1 when the same tool names were called, ignoring their arguments. */
|
|
113
|
+
export declare const toolNameGrader: ReplayGrader;
|
|
114
|
+
/**
|
|
115
|
+
* Replay a sample both ways and report which candidates may be enabled.
|
|
116
|
+
*
|
|
117
|
+
* Returns every candidate's verdict, not only the winner, so a rejection can be
|
|
118
|
+
* read as rejected-at-what-cost rather than merely absent.
|
|
119
|
+
*/
|
|
120
|
+
export declare function replayGate(options: ReplayGateOptions): Promise<ReplayGateResult>;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { type LedgerRecord } from "./core/index.js";
|
|
2
|
+
/**
|
|
3
|
+
* The customer-facing monthly statement: one self-contained HTML page
|
|
4
|
+
* rendered from the customer's own ledger spools.
|
|
5
|
+
*
|
|
6
|
+
* This is the invoice as MESH means it: every figure on the page is the
|
|
7
|
+
* output of `recomputeInvoice` over records the customer holds, the chain
|
|
8
|
+
* verification status is printed at the top (a broken chain renders DO NOT
|
|
9
|
+
* PAY, not a number), exclusions and unbilled levers are itemised rather
|
|
10
|
+
* than hidden, negative levers appear as negative, estimates carry their
|
|
11
|
+
* label, and the command to recompute everything independently is printed
|
|
12
|
+
* on the statement itself. No network access, no external assets.
|
|
13
|
+
*/
|
|
14
|
+
export type LedgerReportSpool = {
|
|
15
|
+
/** Display name, usually the spool filename. */
|
|
16
|
+
name: string;
|
|
17
|
+
records: readonly LedgerRecord[];
|
|
18
|
+
};
|
|
19
|
+
export type LedgerReportOptions = {
|
|
20
|
+
/** Restrict to one invoice period (YYYY-MM). Omitted: all events. */
|
|
21
|
+
period?: string;
|
|
22
|
+
/** MESH's contracted share of net verified savings. Default 1 (percent). */
|
|
23
|
+
feePercent?: number;
|
|
24
|
+
/**
|
|
25
|
+
* Verified-savings deficit carried in from prior statements (cumulative
|
|
26
|
+
* netting: fees never exceed aggregate verified savings). Applied at the
|
|
27
|
+
* statement total, shown as its own line.
|
|
28
|
+
*/
|
|
29
|
+
carryForwardDeficitUsd?: number;
|
|
30
|
+
/** Timestamp printed on the statement; injectable for deterministic tests. */
|
|
31
|
+
generatedAt?: string;
|
|
32
|
+
};
|
|
33
|
+
export declare function renderLedgerReport(spools: readonly LedgerReportSpool[], options?: LedgerReportOptions): string;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { MeshRequestContext, MeshRoutingConfig } from "./types.js";
|
|
2
|
+
export type MeshRoute = {
|
|
3
|
+
model: string;
|
|
4
|
+
requestedModel: string;
|
|
5
|
+
policyId?: string;
|
|
6
|
+
reason: "no_matching_policy" | "missing_stable_key" | "baseline" | "candidate_quality_and_cost_gates_passed";
|
|
7
|
+
estimatedCostSavingsPercent?: number;
|
|
8
|
+
maxOutputTokens?: number;
|
|
9
|
+
contextProfileId?: string;
|
|
10
|
+
};
|
|
11
|
+
export declare function chooseRoute(config: MeshRoutingConfig | undefined, request: Record<PropertyKey, any>, taskClass: string | undefined, context?: MeshRequestContext): MeshRoute;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { type PriceCatalogue } from "../../core/dist/src/price-catalogue.js";
|
|
2
|
+
import { type BillableEvent, type LedgerGateVerdict } from "../../core/dist/src/savings-ledger.js";
|
|
3
|
+
import type { MeshRequestEvent, MeshSavingsLedgerConfig } from "./types.js";
|
|
4
|
+
/** Build the append-only billable record for one completed request. Pure. */
|
|
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
|
+
};
|
|
16
|
+
export type SavingsLedger = {
|
|
17
|
+
/** Synchronously appends one chained record. Never throws. */
|
|
18
|
+
emit: (event: MeshRequestEvent, context?: SavingsLedgerEmitContext) => void;
|
|
19
|
+
readonly path: string;
|
|
20
|
+
};
|
|
21
|
+
/** Create the opt-in JSONL savings meter. Construction never throws on I/O. */
|
|
22
|
+
export declare function createSavingsLedger(config: MeshSavingsLedgerConfig): SavingsLedger;
|