dsh-task-time-cost 0.0.0-stage → 0.2.8-beta.2
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/CHANGELOG.md +29 -0
- package/COMPATIBILITY.md +26 -0
- package/CONTRIBUTING.md +11 -0
- package/LICENSE +21 -0
- package/README.en.md +60 -0
- package/README.md +59 -2
- package/THIRD_PARTY_NOTICES.md +113 -0
- package/cordis.patch.yml +4 -0
- package/data/baselines.json +12 -0
- package/data/defaults.json +21 -0
- package/data/models-dev-prices.json +1 -0
- package/data/prices.json +7 -0
- package/data/sources.json +15 -0
- package/docs/public/DETAIL.md +1 -0
- package/docs/public/DETAIL.zh.md +1 -0
- package/docs/public/acceptance.md +26 -0
- package/docs/public/guide.en.md +33 -0
- package/docs/public/guide.zh.md +35 -0
- package/docs/public/preview.svg +1 -0
- package/docs/public/privacy.md +13 -0
- package/docs/public/publishing.md +9 -0
- package/icon.svg +1 -0
- package/lib/client.js +175 -0
- package/lib/index.js +22948 -0
- package/lib/index.js.map +7 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +122 -4
- package/scripts/import-public-prices.mjs +35 -0
- package/src/client/INTEGRATION.md +61 -0
- package/src/client/config.ts +24 -0
- package/src/client/details.tsx +126 -0
- package/src/client/format.ts +218 -0
- package/src/client/index.tsx +225 -0
- package/src/client/locale.ts +353 -0
- package/src/client/management.tsx +246 -0
- package/src/client/placement.ts +26 -0
- package/src/client/remote.ts +59 -0
- package/src/client/store.ts +210 -0
- package/src/client/styles.ts +94 -0
- package/src/client/use-panel-placement.ts +54 -0
- package/src/client-entry.ts +12 -0
- package/src/host/config-entry.ts +47 -0
- package/src/host/config.ts +85 -0
- package/src/host/engine.ts +580 -0
- package/src/host/facts.ts +170 -0
- package/src/host/forecast-cost.ts +16 -0
- package/src/host/index.ts +269 -0
- package/src/host/record-schema.ts +175 -0
- package/src/host/repository.ts +167 -0
- package/src/host/runtime.ts +99 -0
- package/src/shared/ai-plan.ts +45 -0
- package/src/shared/baseline-selection.ts +43 -0
- package/src/shared/baselines.ts +135 -0
- package/src/shared/call-size.ts +32 -0
- package/src/shared/config.ts +65 -0
- package/src/shared/forecast.ts +91 -0
- package/src/shared/index.ts +12 -0
- package/src/shared/ledger.ts +38 -0
- package/src/shared/money.ts +46 -0
- package/src/shared/performance.ts +216 -0
- package/src/shared/pricing.ts +293 -0
- package/src/shared/public-prices.ts +57 -0
- package/src/shared/remote-contract.ts +72 -0
- package/src/shared/retained-time.ts +14 -0
- package/src/shared/time.ts +207 -0
- package/src/shared/types.ts +66 -0
- package/src/shared/usage.ts +232 -0
- package/src/shared/wire.ts +134 -0
- package/src/shared/workload.ts +265 -0
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
import { validateConfig } from './config.ts';
|
|
2
|
+
import type { EstimatorConfig } from './config.ts';
|
|
3
|
+
import { assertSpan, mergeOrigins, nonnegative } from './types.ts';
|
|
4
|
+
import type { EstimateOrigin, RouteIdentity, Span, TaskKind } from './types.ts';
|
|
5
|
+
import type { PerformanceEstimate } from './performance.ts';
|
|
6
|
+
import type { PlanScenario, RequestBudget, WorkloadPlan } from './workload.ts';
|
|
7
|
+
|
|
8
|
+
export interface RequestProgress {
|
|
9
|
+
phase: 'not-started' | 'waiting' | 'text' | 'call' | 'completed';
|
|
10
|
+
elapsedMs: number;
|
|
11
|
+
generatedTextTokens?: number;
|
|
12
|
+
}
|
|
13
|
+
export interface RequestTime { remainingMs: Span | null; reasons: string[] }
|
|
14
|
+
export interface ScheduleUnit { id: string; durationMs: Span; dependsOn: string[]; resource?: string }
|
|
15
|
+
export interface ScheduleOptions { maxConcurrency?: number; resourceLimits?: Record<string, number> }
|
|
16
|
+
export interface ScheduledUnit { id: string; startMs: Span; endMs: Span }
|
|
17
|
+
export interface ScheduleResult { makespanMs: Span; totalWorkMs: Span; units: ScheduledUnit[] }
|
|
18
|
+
export interface PlanTimeOptions extends ScheduleOptions { progress?: Record<string, RequestProgress>; completedIds?: string[]; config?: Partial<EstimatorConfig> }
|
|
19
|
+
export interface PlanTime { remainingMs: Span | null; schedule: ScheduleResult | null; reasons: string[]; origin: EstimateOrigin; localPerformanceSamples: number }
|
|
20
|
+
|
|
21
|
+
export function estimateRequestTime(request: RequestBudget, performance: PerformanceEstimate, progress: RequestProgress = { phase: 'not-started', elapsedMs: 0 }, config: Partial<EstimatorConfig> = {}): RequestTime {
|
|
22
|
+
const c = validateConfig(config);
|
|
23
|
+
nonnegative(progress.elapsedMs, 'elapsedMs');
|
|
24
|
+
if (progress.generatedTextTokens !== undefined) nonnegative(progress.generatedTextTokens, 'generatedTextTokens');
|
|
25
|
+
if (progress.phase === 'completed') return { remainingMs: { low: 0, high: 0 }, reasons: ['request-completed'] };
|
|
26
|
+
const reasons = [...performance.reasons];
|
|
27
|
+
const bodyCompatible = request.route.requestMode === 'text' && request.visibleTextTokens !== null && performance.firstTextMs !== null && performance.visibleTps !== null && performance.visibleTps > 0;
|
|
28
|
+
if (bodyCompatible) {
|
|
29
|
+
assertSpan(request.visibleTextTokens!, 'visibleTextTokens');
|
|
30
|
+
const generated = progress.generatedTextTokens ?? 0;
|
|
31
|
+
const body = { low: Math.max(0, request.visibleTextTokens!.low - generated) / performance.visibleTps! * 1000, high: Math.max(0, request.visibleTextTokens!.high - generated) / performance.visibleTps! * 1000 };
|
|
32
|
+
if (progress.phase === 'text') {
|
|
33
|
+
if (generated >= request.visibleTextTokens!.high) return { remainingMs: null, reasons: [...reasons, 'output-budget-exhausted-task-still-running'] };
|
|
34
|
+
return { remainingMs: { low: body.low * c.referenceLowFactor, high: body.high * c.referenceHighFactor }, reasons: [...reasons, 'text-stage-no-repeat-wait', 'reasoning-already-in-first-text-wait'] };
|
|
35
|
+
}
|
|
36
|
+
const wait = remainingWait(performance.firstTextMs!, performance.firstTextWaitSamplesMs, progress, c);
|
|
37
|
+
if (wait.remainingMs === null) return { remainingMs: null, reasons: [...reasons, ...wait.reasons] };
|
|
38
|
+
return { remainingMs: { low: wait.remainingMs.low + body.low * c.referenceLowFactor, high: wait.remainingMs.high + body.high * c.referenceHighFactor }, reasons: [...reasons, ...wait.reasons, 'first-text-plus-body', 'reasoning-already-in-first-text-wait'] };
|
|
39
|
+
}
|
|
40
|
+
reasons.push('same-mode-total-call-fallback');
|
|
41
|
+
const total = remainingWait(performance.totalCallMs, performance.totalCallSamplesMs, progress, c);
|
|
42
|
+
return { remainingMs: total.remainingMs, reasons: [...reasons, ...total.reasons] };
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function remainingWait(center: number, samples: number[], progress: RequestProgress, config: EstimatorConfig): RequestTime {
|
|
46
|
+
nonnegative(center, 'duration prior');
|
|
47
|
+
const observed = samples.filter(value => Number.isFinite(value) && value >= 0).sort((a, b) => a - b);
|
|
48
|
+
const initial = observed.length >= config.minConditionalSamples ? {
|
|
49
|
+
low: observed[Math.floor((observed.length - 1) * 0.2)]!, high: observed[Math.ceil((observed.length - 1) * 0.8)]!,
|
|
50
|
+
} : { low: center * config.referenceLowFactor, high: center * config.referenceHighFactor };
|
|
51
|
+
if (progress.phase === 'not-started') return { remainingMs: initial, reasons: [
|
|
52
|
+
...(observed.length >= config.minConditionalSamples ? ['observed-call-duration-reference'] : []), 'reference-range-not-calibrated-confidence',
|
|
53
|
+
] };
|
|
54
|
+
const elapsed = progress.elapsedMs;
|
|
55
|
+
const conditional = samples.filter(value => Number.isFinite(value) && value > elapsed).sort((a, b) => a - b);
|
|
56
|
+
if (conditional.length >= config.minConditionalSamples) return { remainingMs: {
|
|
57
|
+
low: conditional[Math.floor((conditional.length - 1) * 0.2)]! - elapsed,
|
|
58
|
+
high: conditional[Math.ceil((conditional.length - 1) * 0.8)]! - elapsed,
|
|
59
|
+
}, reasons: ['conditional-observed-remaining-range', 'reference-range-not-calibrated-confidence'] };
|
|
60
|
+
if (elapsed >= initial.high) return { remainingMs: null, reasons: ['reference-range-exhausted-reassessing'] };
|
|
61
|
+
return { remainingMs: { low: Math.max(0, initial.low - elapsed), high: initial.high - elapsed }, reasons: ['waiting-for-model-response', 'conditional-samples-insufficient'] };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Deterministic non-preemptive list scheduling. Dependencies are mandatory, not inferred. */
|
|
65
|
+
export function schedule(units: ScheduleUnit[], options: ScheduleOptions = {}): ScheduleResult {
|
|
66
|
+
const maxConcurrency = options.maxConcurrency ?? Infinity;
|
|
67
|
+
if (maxConcurrency !== Infinity && (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1)) throw new TypeError('maxConcurrency must be a positive integer');
|
|
68
|
+
for (const limit of Object.values(options.resourceLimits ?? {})) if (!Number.isSafeInteger(limit) || limit < 1) throw new TypeError('Resource limits must be positive integers');
|
|
69
|
+
const byId = new Map<string, ScheduleUnit>();
|
|
70
|
+
for (const unit of units) {
|
|
71
|
+
if (!unit.id || byId.has(unit.id)) throw new TypeError('Schedule ids must be unique');
|
|
72
|
+
assertSpan(unit.durationMs, unit.id);
|
|
73
|
+
if (!Array.isArray(unit.dependsOn) || new Set(unit.dependsOn).size !== unit.dependsOn.length) throw new TypeError('Dependencies must be unique');
|
|
74
|
+
byId.set(unit.id, unit);
|
|
75
|
+
}
|
|
76
|
+
for (const unit of units) for (const dependency of unit.dependsOn) if (!byId.has(dependency) || dependency === unit.id) throw new TypeError(`Invalid dependency: ${dependency}`);
|
|
77
|
+
const topo = new Set<string>();
|
|
78
|
+
while (topo.size < units.length) {
|
|
79
|
+
const next = units.find(unit => !topo.has(unit.id) && unit.dependsOn.every(id => topo.has(id)));
|
|
80
|
+
if (!next) throw new TypeError('Dependency cycle');
|
|
81
|
+
topo.add(next.id);
|
|
82
|
+
}
|
|
83
|
+
function run(bound: 'low' | 'high'): Map<string, { start: number; end: number }> {
|
|
84
|
+
const result = new Map<string, { start: number; end: number }>();
|
|
85
|
+
const running = new Map<string, { end: number; resource?: string }>();
|
|
86
|
+
const done = new Set<string>();
|
|
87
|
+
let now = 0;
|
|
88
|
+
while (done.size < units.length) {
|
|
89
|
+
for (const [id, item] of running) if (item.end <= now) { done.add(id); running.delete(id); }
|
|
90
|
+
let launched = false;
|
|
91
|
+
for (const unit of units) {
|
|
92
|
+
if (result.has(unit.id) || !unit.dependsOn.every(id => done.has(id)) || running.size >= maxConcurrency) continue;
|
|
93
|
+
const sameResource = [...running.values()].filter(item => item.resource === unit.resource).length;
|
|
94
|
+
if (unit.resource && sameResource >= (options.resourceLimits?.[unit.resource] ?? Infinity)) continue;
|
|
95
|
+
const end = now + unit.durationMs[bound];
|
|
96
|
+
result.set(unit.id, { start: now, end });
|
|
97
|
+
if (end === now) done.add(unit.id);
|
|
98
|
+
else running.set(unit.id, { end, resource: unit.resource });
|
|
99
|
+
launched = true;
|
|
100
|
+
}
|
|
101
|
+
if (done.size === units.length) break;
|
|
102
|
+
// A zero-duration dependency can make an earlier array item ready at this same instant.
|
|
103
|
+
if (launched && units.some(unit => !result.has(unit.id) && unit.dependsOn.every(id => done.has(id)) && running.size < maxConcurrency && (!unit.resource || [...running.values()].filter(item => item.resource === unit.resource).length < (options.resourceLimits?.[unit.resource] ?? Infinity)))) continue;
|
|
104
|
+
if (!running.size) throw new TypeError('Schedule could not make progress');
|
|
105
|
+
now = Math.min(...[...running.values()].map(item => item.end));
|
|
106
|
+
}
|
|
107
|
+
return result;
|
|
108
|
+
}
|
|
109
|
+
const low = run('low');
|
|
110
|
+
const high = run('high');
|
|
111
|
+
const lowMakespan = Math.max(0, ...[...low.values()].map(item => item.end));
|
|
112
|
+
const highMakespan = Math.max(lowMakespan, ...[...high.values()].map(item => item.end));
|
|
113
|
+
return {
|
|
114
|
+
makespanMs: { low: lowMakespan, high: highMakespan },
|
|
115
|
+
totalWorkMs: { low: units.reduce((sum, unit) => sum + unit.durationMs.low, 0), high: units.reduce((sum, unit) => sum + unit.durationMs.high, 0) },
|
|
116
|
+
units: units.map(unit => ({ id: unit.id, startMs: { low: Math.min(low.get(unit.id)!.start, high.get(unit.id)!.start), high: Math.max(low.get(unit.id)!.start, high.get(unit.id)!.start) }, endMs: { low: Math.min(low.get(unit.id)!.end, high.get(unit.id)!.end), high: Math.max(low.get(unit.id)!.end, high.get(unit.id)!.end) } })),
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
export function estimatePlanTime(scenario: PlanScenario, performanceFor: (route: RouteIdentity, request?: RequestBudget) => PerformanceEstimate, options: PlanTimeOptions = {}): PlanTime {
|
|
121
|
+
const completed = new Set(options.completedIds ?? []);
|
|
122
|
+
for (const [id, progress] of Object.entries(options.progress ?? {})) if (progress.phase === 'completed') completed.add(id);
|
|
123
|
+
const units: ScheduleUnit[] = [];
|
|
124
|
+
const reasons: string[] = [];
|
|
125
|
+
const origins: EstimateOrigin[] = [];
|
|
126
|
+
let unknown = false;
|
|
127
|
+
let localPerformanceSamples = 0;
|
|
128
|
+
for (const request of scenario.requests) {
|
|
129
|
+
if (completed.has(request.id)) continue;
|
|
130
|
+
const performance = performanceFor(request.route, request);
|
|
131
|
+
const estimate = estimateRequestTime(request, performance, options.progress?.[request.id], options.config);
|
|
132
|
+
const bodyMetrics = request.route.requestMode === 'text' && request.visibleTextTokens !== null && performance.firstTextMs !== null && performance.visibleTps !== null;
|
|
133
|
+
origins.push(bodyMetrics ? mergeOrigins([performance.metricOrigins.firstText, performance.metricOrigins.speed]) : performance.metricOrigins.total);
|
|
134
|
+
localPerformanceSamples = Math.max(localPerformanceSamples, performance.samples);
|
|
135
|
+
reasons.push(...estimate.reasons);
|
|
136
|
+
if (estimate.remainingMs === null) unknown = true;
|
|
137
|
+
else units.push({ id: request.id, durationMs: estimate.remainingMs, dependsOn: request.dependsOn.filter(id => !completed.has(id)), resource: 'model' });
|
|
138
|
+
}
|
|
139
|
+
for (const tool of scenario.tools) {
|
|
140
|
+
if (completed.has(tool.id)) continue;
|
|
141
|
+
units.push({ id: tool.id, durationMs: tool.durationMs, dependsOn: tool.dependsOn.filter(id => !completed.has(id)), resource: tool.resource ?? 'tool' });
|
|
142
|
+
origins.push(tool.sourceKind);
|
|
143
|
+
}
|
|
144
|
+
if (unknown) return { remainingMs: null, schedule: null, reasons: [...new Set(reasons)], origin: mergeOrigins(origins), localPerformanceSamples };
|
|
145
|
+
const result = schedule(units, options);
|
|
146
|
+
return { remainingMs: result.makespanMs, schedule: result, reasons: [...new Set(reasons)], origin: mergeOrigins(origins), localPerformanceSamples };
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
export function estimateWorkloadTime(plan: WorkloadPlan, performanceFor: (route: RouteIdentity, request?: RequestBudget) => PerformanceEstimate, options: PlanTimeOptions = {}): PlanTime {
|
|
150
|
+
const low = estimatePlanTime(plan.low, performanceFor, options);
|
|
151
|
+
const high = estimatePlanTime(plan.high, performanceFor, options);
|
|
152
|
+
return { remainingMs: low.remainingMs && high.remainingMs ? { low: Math.min(low.remainingMs.low, high.remainingMs.low), high: Math.max(low.remainingMs.high, high.remainingMs.high) } : null, schedule: high.schedule, reasons: [...new Set([...plan.reasons, ...low.reasons, ...high.reasons])], origin: mergeOrigins([plan.origin, low.origin, high.origin]), localPerformanceSamples: Math.max(low.localPerformanceSamples, high.localPerformanceSamples) };
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
export interface ContinuationSample {
|
|
156
|
+
elapsedActiveMs: number;
|
|
157
|
+
completedRequests: number;
|
|
158
|
+
}
|
|
159
|
+
export interface ContinuationInput {
|
|
160
|
+
elapsedActiveMs: number;
|
|
161
|
+
completedRequests: number;
|
|
162
|
+
activeRequests: number;
|
|
163
|
+
/** One finished task per sample, already matched by task kind and route. */
|
|
164
|
+
history?: readonly ContinuationSample[];
|
|
165
|
+
minSamples?: number;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Conditional residual duration from comparable completed local tasks. A call
|
|
170
|
+
* count is not percentage complete: adding calls must never by itself imply
|
|
171
|
+
* that a task is nearly finished. Only past tasks which reached the observed
|
|
172
|
+
* call count AND outlasted the current elapsed time can supply a residual.
|
|
173
|
+
*
|
|
174
|
+
* The central 20–80% empirical range limits single-outlier effects. It remains
|
|
175
|
+
* a reference, not a calibrated confidence interval. With insufficient eligible
|
|
176
|
+
* tasks the result is unknown; retired machine-specific multipliers are never
|
|
177
|
+
* used as a universal forecast or to keep an exhausted plan looking valid.
|
|
178
|
+
*/
|
|
179
|
+
export function estimateContinuation(input: ContinuationInput): Span | null {
|
|
180
|
+
nonnegative(input.elapsedActiveMs, 'elapsedActiveMs');
|
|
181
|
+
nonnegative(input.completedRequests, 'completedRequests');
|
|
182
|
+
nonnegative(input.activeRequests, 'activeRequests');
|
|
183
|
+
const minSamples = input.minSamples ?? 5;
|
|
184
|
+
if (!Number.isSafeInteger(minSamples) || minSamples < 1) throw new TypeError('Invalid minimum continuation samples');
|
|
185
|
+
const observed = input.completedRequests + input.activeRequests;
|
|
186
|
+
if (input.elapsedActiveMs === 0 || observed === 0) return null;
|
|
187
|
+
const remaining = (input.history ?? []).filter(sample => Number.isFinite(sample.elapsedActiveMs)
|
|
188
|
+
&& Number.isSafeInteger(sample.completedRequests) && sample.completedRequests >= observed
|
|
189
|
+
&& sample.elapsedActiveMs > input.elapsedActiveMs)
|
|
190
|
+
.map(sample => sample.elapsedActiveMs - input.elapsedActiveMs).sort((a, b) => a - b);
|
|
191
|
+
if (remaining.length < minSamples) return null;
|
|
192
|
+
// Outward order statistics avoid interpolating invented second-level detail.
|
|
193
|
+
return { low: remaining[Math.floor((remaining.length - 1) * 0.2)]!, high: remaining[Math.ceil((remaining.length - 1) * 0.8)]! };
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
export function calculateElapsed(input: { startedAtMs: number; nowMs: number; endedAtMs?: number; pauses?: { startMs: number; endMs: number | null }[] }): { elapsedWallMs: number; elapsedActiveMs: number; elapsedPausedMs: number } {
|
|
197
|
+
const end = input.endedAtMs ?? input.nowMs;
|
|
198
|
+
if (![input.startedAtMs, end].every(Number.isFinite) || end < input.startedAtMs) throw new TypeError('Invalid task interval');
|
|
199
|
+
const intervals = (input.pauses ?? []).map(pause => {
|
|
200
|
+
if (!Number.isFinite(pause.startMs) || (pause.endMs !== null && (!Number.isFinite(pause.endMs) || pause.endMs < pause.startMs))) throw new TypeError('Invalid pause interval');
|
|
201
|
+
return { start: Math.max(input.startedAtMs, pause.startMs), end: Math.min(end, pause.endMs ?? end) };
|
|
202
|
+
}).filter(interval => interval.end > interval.start).sort((a, b) => a.start - b.start);
|
|
203
|
+
let paused = 0;
|
|
204
|
+
let lastEnd = input.startedAtMs;
|
|
205
|
+
for (const interval of intervals) { paused += Math.max(0, interval.end - Math.max(lastEnd, interval.start)); lastEnd = Math.max(lastEnd, interval.end); }
|
|
206
|
+
return { elapsedWallMs: end - input.startedAtMs, elapsedActiveMs: end - input.startedAtMs - paused, elapsedPausedMs: paused };
|
|
207
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
export type Span = { low: number; high: number };
|
|
2
|
+
export type SourceKind = 'public-measured' | 'local-measured' | 'heuristic';
|
|
3
|
+
export type EstimateOrigin = SourceKind | 'mixed';
|
|
4
|
+
export type RequestMode = 'text' | 'tool' | 'mixed' | 'unknown' | 'non-streaming';
|
|
5
|
+
export type TaskKind = 'question' | 'writing' | 'file-analysis' | 'code' | 'research' | 'unknown';
|
|
6
|
+
export type Outcome = 'completed' | 'failed' | 'cancelled' | 'interrupted' | 'timeout' | 'truncated';
|
|
7
|
+
export type CostStatus = 'complete' | 'partial' | 'unpriced' | 'free';
|
|
8
|
+
export type ForecastCostStatus = 'reference' | 'partial' | 'unavailable' | 'free';
|
|
9
|
+
export type Money = { currency: string; amount: string };
|
|
10
|
+
export type MoneyRange = { currency: string; range: { low: string; high: string } };
|
|
11
|
+
|
|
12
|
+
/** modelId is the pricing/performance identity, never a display alias. */
|
|
13
|
+
export interface RouteIdentity {
|
|
14
|
+
providerId: string;
|
|
15
|
+
endpointFingerprint: string;
|
|
16
|
+
modelId: string;
|
|
17
|
+
requestMode: RequestMode;
|
|
18
|
+
reasoningEffort: string;
|
|
19
|
+
serviceTier: string;
|
|
20
|
+
inputBucket?: string;
|
|
21
|
+
cacheBucket?: string;
|
|
22
|
+
concurrencyBucket?: string;
|
|
23
|
+
mixedRoute?: boolean;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export type RouteApplicability = { [K in keyof RouteIdentity]?: RouteIdentity[K] | '*' };
|
|
27
|
+
|
|
28
|
+
export interface SourceMetadata {
|
|
29
|
+
sourceKind: SourceKind;
|
|
30
|
+
sourceUrl: string | null;
|
|
31
|
+
dataVersion: string;
|
|
32
|
+
date: string;
|
|
33
|
+
scope: string;
|
|
34
|
+
sampleCount: number | null;
|
|
35
|
+
timingBasis: string;
|
|
36
|
+
statistic: 'assumption-range' | 'mean' | 'sample' | 'quantiles';
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export function assertSpan(value: Span, name = 'range'): Span {
|
|
40
|
+
if (!value || !Number.isFinite(value.low) || !Number.isFinite(value.high) || value.low < 0 || value.low > value.high) {
|
|
41
|
+
throw new TypeError(`${name} must be finite, nonnegative, and ordered`);
|
|
42
|
+
}
|
|
43
|
+
return value;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export function nonnegative(value: number, name: string): number {
|
|
47
|
+
if (!Number.isFinite(value) || value < 0) throw new TypeError(`${name} must be finite and nonnegative`);
|
|
48
|
+
return value;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export function alphaValue(alpha: number): number {
|
|
52
|
+
if (!Number.isFinite(alpha) || alpha <= 0 || alpha > 1) throw new TypeError('alpha must be in (0, 1]');
|
|
53
|
+
return alpha;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export function ewma(previous: number, observed: number, alpha = 0.2): number {
|
|
57
|
+
alphaValue(alpha);
|
|
58
|
+
nonnegative(previous, 'previous');
|
|
59
|
+
nonnegative(observed, 'observed');
|
|
60
|
+
return (1 - alpha) * previous + alpha * observed;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export function mergeOrigins(origins: EstimateOrigin[]): EstimateOrigin {
|
|
64
|
+
const distinct = new Set(origins);
|
|
65
|
+
return distinct.size === 1 ? origins[0] : distinct.size === 0 ? 'heuristic' : 'mixed';
|
|
66
|
+
}
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
export const INPUT_CATEGORIES = ['inputTokens', 'cacheReadTokens', 'cacheWrite5mTokens', 'cacheWrite1hTokens', 'cacheWriteUnknownTokens'] as const;
|
|
2
|
+
export const BILLABLE_CATEGORIES = [...INPUT_CATEGORIES, 'outputTokens'] as const;
|
|
3
|
+
export type InputCategory = typeof INPUT_CATEGORIES[number];
|
|
4
|
+
export type BillableCategory = typeof BILLABLE_CATEGORIES[number];
|
|
5
|
+
|
|
6
|
+
/** Adapter-neutral fields. SDK-specific field names must be mapped by the Host. */
|
|
7
|
+
export interface RawUsage {
|
|
8
|
+
inputTokens?: number | null;
|
|
9
|
+
cacheReadTokens?: number | null;
|
|
10
|
+
/** Total cache creation, including 1h writes; never additive to its splits. */
|
|
11
|
+
cacheWriteTokens?: number | null;
|
|
12
|
+
cacheWrite5mTokens?: number | null;
|
|
13
|
+
cacheWrite1hTokens?: number | null;
|
|
14
|
+
outputTokens?: number | null;
|
|
15
|
+
reasoningTokens?: number | null;
|
|
16
|
+
visibleOutputTokens?: number | null;
|
|
17
|
+
totalTokens?: number | null;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export interface UsageSemantics {
|
|
21
|
+
schema: 'dsh' | 'inclusive-input';
|
|
22
|
+
outputIncludesReasoning: boolean | 'unknown';
|
|
23
|
+
/** Only name fields whose source contract explicitly defines omission as zero. */
|
|
24
|
+
missingMeansZero?: (keyof RawUsage)[];
|
|
25
|
+
/** Null when an aggregate cache-write count has no reliable TTL semantics. */
|
|
26
|
+
defaultCacheWriteTtl?: '5m' | '1h' | null;
|
|
27
|
+
/**
|
|
28
|
+
* Derive `outputIncludesReasoning` from arithmetic the adapter itself
|
|
29
|
+
* reported when the configuration leaves it unknown. Never guesses: without
|
|
30
|
+
* a matching total the answer stays unknown and the usage stays partial.
|
|
31
|
+
*/
|
|
32
|
+
inferOutputIncludesReasoning?: boolean;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export interface NormalizedUsage extends Record<BillableCategory, number | null> {
|
|
36
|
+
reasoningTokens: number | null;
|
|
37
|
+
visibleOutputTokens: number | null;
|
|
38
|
+
promptTokens: number | null;
|
|
39
|
+
totalTokens: number | null;
|
|
40
|
+
status: 'complete' | 'partial' | 'unknown';
|
|
41
|
+
exact: boolean;
|
|
42
|
+
diagnostics: string[];
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export function normalizeUsage(raw: RawUsage, semantics: UsageSemantics): NormalizedUsage {
|
|
46
|
+
if (!['dsh', 'inclusive-input'].includes(semantics.schema)) throw new TypeError('Unknown usage schema');
|
|
47
|
+
if (![true, false, 'unknown'].includes(semantics.outputIncludesReasoning)) throw new TypeError('Invalid output semantics');
|
|
48
|
+
const diagnostics: string[] = [];
|
|
49
|
+
const invalid = new Set<string>();
|
|
50
|
+
function read(key: keyof RawUsage): number | null {
|
|
51
|
+
const value = raw[key];
|
|
52
|
+
if (value == null) return semantics.missingMeansZero?.includes(key) ? 0 : null;
|
|
53
|
+
if (!Number.isSafeInteger(value) || value < 0) {
|
|
54
|
+
diagnostics.push(`invalid:${key}`);
|
|
55
|
+
invalid.add(key);
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
return value;
|
|
59
|
+
}
|
|
60
|
+
let input = read('inputTokens');
|
|
61
|
+
let readTokens = read('cacheReadTokens');
|
|
62
|
+
const writeTotal = read('cacheWriteTokens');
|
|
63
|
+
let write5m = read('cacheWrite5mTokens');
|
|
64
|
+
let write1h = read('cacheWrite1hTokens');
|
|
65
|
+
let writeUnknown: number | null = null;
|
|
66
|
+
const output = read('outputTokens');
|
|
67
|
+
const reasoning = read('reasoningTokens');
|
|
68
|
+
let visible = read('visibleOutputTokens');
|
|
69
|
+
const reportedTotal = read('totalTokens');
|
|
70
|
+
|
|
71
|
+
if (writeTotal === 0) {
|
|
72
|
+
if ((write5m ?? 0) > 0 || (write1h ?? 0) > 0) {
|
|
73
|
+
diagnostics.push('conflict:cache-write-total');
|
|
74
|
+
write5m = write1h = writeUnknown = null;
|
|
75
|
+
} else write5m = write1h = writeUnknown = 0;
|
|
76
|
+
} else if (writeTotal !== null) {
|
|
77
|
+
if ((write5m ?? 0) + (write1h ?? 0) > writeTotal) {
|
|
78
|
+
diagnostics.push('conflict:cache-write-total');
|
|
79
|
+
write5m = write1h = writeUnknown = null;
|
|
80
|
+
} else if (write5m !== null && write1h !== null) {
|
|
81
|
+
writeUnknown = writeTotal - write5m - write1h;
|
|
82
|
+
} else if (write1h !== null && semantics.defaultCacheWriteTtl === '5m') {
|
|
83
|
+
write5m = writeTotal - write1h;
|
|
84
|
+
writeUnknown = 0;
|
|
85
|
+
} else if (write5m !== null && semantics.defaultCacheWriteTtl === '1h') {
|
|
86
|
+
write1h = writeTotal - write5m;
|
|
87
|
+
writeUnknown = 0;
|
|
88
|
+
} else {
|
|
89
|
+
const remainder = writeTotal - (write5m ?? 0) - (write1h ?? 0);
|
|
90
|
+
if (semantics.defaultCacheWriteTtl === '5m' && write5m === null && write1h === null) {
|
|
91
|
+
write5m = writeTotal;
|
|
92
|
+
write1h = 0;
|
|
93
|
+
writeUnknown = 0;
|
|
94
|
+
} else if (semantics.defaultCacheWriteTtl === '1h' && write5m === null && write1h === null) {
|
|
95
|
+
write1h = writeTotal;
|
|
96
|
+
write5m = 0;
|
|
97
|
+
writeUnknown = 0;
|
|
98
|
+
} else {
|
|
99
|
+
write5m ??= 0;
|
|
100
|
+
write1h ??= 0;
|
|
101
|
+
writeUnknown = remainder;
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
} else if (write5m !== null && write1h !== null) {
|
|
105
|
+
// Both exhaustive TTL buckets explicitly reported by the adapter.
|
|
106
|
+
writeUnknown = 0;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
const cacheTotal = sumKnown([readTokens, write5m, write1h, writeUnknown]);
|
|
110
|
+
if (semantics.schema === 'inclusive-input' && input !== null) {
|
|
111
|
+
if (cacheTotal === null) input = null;
|
|
112
|
+
else if (input < cacheTotal) {
|
|
113
|
+
diagnostics.push('conflict:inclusive-input-smaller-than-cache');
|
|
114
|
+
input = null;
|
|
115
|
+
} else input -= cacheTotal;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
let billableOutput: number | null = null;
|
|
119
|
+
let outputIncludesReasoning = semantics.outputIncludesReasoning;
|
|
120
|
+
if (outputIncludesReasoning === 'unknown' && semantics.inferOutputIncludesReasoning) {
|
|
121
|
+
// Absent cache-write fields are not a reason to skip the check: sum what the
|
|
122
|
+
// adapter reported, and let the total decide.
|
|
123
|
+
const knownPrompt = [input, readTokens, write5m, write1h, writeUnknown].every(value => value === null || Number.isSafeInteger(value))
|
|
124
|
+
? [input, readTokens, write5m, write1h, writeUnknown].reduce<number>((sum, value) => sum + (value ?? 0), 0) : null;
|
|
125
|
+
const inferred = inferOutputIncludesReasoning({ outputTokens: output, reasoningTokens: reasoning, totalTokens: reportedTotal }, knownPrompt);
|
|
126
|
+
if (inferred !== null) { outputIncludesReasoning = inferred; diagnostics.push(`inferred:output-reasoning-${inferred ? 'inclusive' : 'exclusive'}`); }
|
|
127
|
+
}
|
|
128
|
+
if (outputIncludesReasoning === true) {
|
|
129
|
+
billableOutput = output;
|
|
130
|
+
if (output !== null && reasoning !== null) {
|
|
131
|
+
if (reasoning > output) diagnostics.push('conflict:reasoning-larger-than-output');
|
|
132
|
+
else if (visible === null) visible = output - reasoning;
|
|
133
|
+
else if (visible + reasoning > output) diagnostics.push('conflict:visible-plus-reasoning');
|
|
134
|
+
}
|
|
135
|
+
} else if (outputIncludesReasoning === false) {
|
|
136
|
+
billableOutput = sumKnown([output, reasoning]);
|
|
137
|
+
visible ??= output;
|
|
138
|
+
if (visible !== null && output !== null && visible > output) diagnostics.push('conflict:visible-larger-than-output');
|
|
139
|
+
} else {
|
|
140
|
+
diagnostics.push('unknown:output-reasoning-inclusion');
|
|
141
|
+
}
|
|
142
|
+
if (diagnostics.some(d => d.startsWith('conflict:reasoning') || d.startsWith('conflict:visible'))) billableOutput = null;
|
|
143
|
+
|
|
144
|
+
// A reported total of exactly zero with every reported field also zero proves
|
|
145
|
+
// that nothing was consumed: there is no split left to guess, so the omitted
|
|
146
|
+
// cache fields are zero rather than unknown.
|
|
147
|
+
const allReportedZero = reportedTotal === 0 && [input, readTokens, write5m, write1h, writeUnknown, billableOutput]
|
|
148
|
+
.every(value => value === null || value === 0);
|
|
149
|
+
if (allReportedZero) {
|
|
150
|
+
input ??= 0; readTokens ??= 0; write5m ??= 0; write1h ??= 0; writeUnknown ??= 0; billableOutput ??= 0;
|
|
151
|
+
diagnostics.push('inferred:empty-usage-report');
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
// The reported total exactly equalling input + output leaves no room for any
|
|
155
|
+
// cache activity at all, so an omitted cache field is zero, not unknown.
|
|
156
|
+
if (!allReportedZero && semantics.inferOutputIncludesReasoning && reportedTotal !== null && input !== null && billableOutput !== null
|
|
157
|
+
&& readTokens === null && write5m === null && write1h === null && writeUnknown === null
|
|
158
|
+
&& reportedTotal === input + billableOutput) {
|
|
159
|
+
readTokens = 0; write5m = 0; write1h = 0; writeUnknown = 0;
|
|
160
|
+
diagnostics.push('inferred:no-cache-activity');
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// A reported total that no other category accounts for is the cache-write
|
|
164
|
+
// remainder: the adapter omitted the field because the provider does not
|
|
165
|
+
// bill the write separately, not because the price is unknown.
|
|
166
|
+
if (!allReportedZero && semantics.inferOutputIncludesReasoning && reportedTotal !== null && input !== null && readTokens !== null && billableOutput !== null
|
|
167
|
+
&& write5m === null && write1h === null && writeUnknown === null) {
|
|
168
|
+
const residual = reportedTotal - input - readTokens - billableOutput;
|
|
169
|
+
if (Number.isSafeInteger(residual) && residual >= 0) { write5m = 0; write1h = 0; writeUnknown = residual; diagnostics.push('inferred:cache-write-from-total'); }
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
const promptTokens = sumKnown([input, readTokens, write5m, write1h, writeUnknown]);
|
|
173
|
+
|
|
174
|
+
const calculatedTotal = sumKnown([promptTokens, billableOutput]);
|
|
175
|
+
if (reportedTotal !== null && calculatedTotal !== null && reportedTotal !== calculatedTotal) diagnostics.push('conflict:totalTokens');
|
|
176
|
+
const fields = [input, readTokens, write5m, write1h, writeUnknown, billableOutput];
|
|
177
|
+
const complete = fields.every(value => value !== null);
|
|
178
|
+
const conflict = diagnostics.some(d => d.startsWith('conflict:'));
|
|
179
|
+
return {
|
|
180
|
+
inputTokens: input,
|
|
181
|
+
cacheReadTokens: readTokens,
|
|
182
|
+
cacheWrite5mTokens: write5m,
|
|
183
|
+
cacheWrite1hTokens: write1h,
|
|
184
|
+
cacheWriteUnknownTokens: writeUnknown,
|
|
185
|
+
outputTokens: billableOutput,
|
|
186
|
+
reasoningTokens: reasoning,
|
|
187
|
+
visibleOutputTokens: visible,
|
|
188
|
+
promptTokens,
|
|
189
|
+
totalTokens: conflict ? null : calculatedTotal,
|
|
190
|
+
status: complete && !conflict ? 'complete' : fields.some(value => value !== null) ? 'partial' : 'unknown',
|
|
191
|
+
exact: complete && !conflict && invalid.size === 0,
|
|
192
|
+
diagnostics,
|
|
193
|
+
};
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
export function sumKnown(values: (number | null)[]): number | null {
|
|
197
|
+
if (values.some(value => value === null)) return null;
|
|
198
|
+
const sum = (values as number[]).reduce((total, value) => total + value, 0);
|
|
199
|
+
return Number.isSafeInteger(sum) ? sum : null;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Sum the values that were actually reported, ignoring the requests that
|
|
204
|
+
* reported nothing at all.
|
|
205
|
+
*
|
|
206
|
+
* `sumKnown` answers "is this total exact"; this answers "how much did we
|
|
207
|
+
* observe". A single adapter response without usage numbers must not erase the
|
|
208
|
+
* other 400 settled requests, so the total stays a real subtotal and the caller
|
|
209
|
+
* reports partial coverage instead of an unknown quantity.
|
|
210
|
+
*/
|
|
211
|
+
export function subtotalKnown(values: (number | null)[]): number | null {
|
|
212
|
+
const reported = values.filter((value): value is number => value !== null);
|
|
213
|
+
if (reported.length === 0) return null;
|
|
214
|
+
const sum = reported.reduce((total, value) => total + value, 0);
|
|
215
|
+
return Number.isSafeInteger(sum) ? sum : null;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Infer whether a reported output count already includes reasoning tokens.
|
|
220
|
+
*
|
|
221
|
+
* Uses only arithmetic the adapter itself reported: when `totalTokens` equals
|
|
222
|
+
* prompt + output the output is inclusive; when it equals prompt + output +
|
|
223
|
+
* reasoning the output is exclusive. Anything else is not evidence, so the
|
|
224
|
+
* caller keeps its configured semantics instead of guessing.
|
|
225
|
+
*/
|
|
226
|
+
export function inferOutputIncludesReasoning(raw: RawUsage, promptTokens: number | null): boolean | null {
|
|
227
|
+
const { totalTokens: total, outputTokens: output, reasoningTokens: reasoning } = raw;
|
|
228
|
+
if (!Number.isSafeInteger(total) || !Number.isSafeInteger(output) || promptTokens === null) return null;
|
|
229
|
+
if (promptTokens + output! === total) return true;
|
|
230
|
+
if (Number.isSafeInteger(reasoning) && (reasoning as number) > 0 && promptTokens + output! + (reasoning as number) === total) return false;
|
|
231
|
+
return null;
|
|
232
|
+
}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/** Package-owned DTOs. These are not DSH SDK types. All amounts are decimal strings. */
|
|
2
|
+
export type Span = { low: number; high: number };
|
|
3
|
+
export type TaskState = 'queued' | 'running' | 'waiting_user' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
|
|
4
|
+
export type Money = { currency: string; amount: string };
|
|
5
|
+
export type MoneyRange = { currency: string; range: { low: string; high: string } };
|
|
6
|
+
export type TokenBreakdown = {
|
|
7
|
+
input: number | null; cacheRead: number | null; cacheWrite: number | null;
|
|
8
|
+
output: number | null; reasoning: number | null;
|
|
9
|
+
};
|
|
10
|
+
export interface EstimateSnapshot {
|
|
11
|
+
taskKey: string;
|
|
12
|
+
sessionId: string;
|
|
13
|
+
turn: number;
|
|
14
|
+
revision: number;
|
|
15
|
+
algorithmVersion: string;
|
|
16
|
+
state: TaskState;
|
|
17
|
+
taskType: string;
|
|
18
|
+
updatedAt: number;
|
|
19
|
+
startedAt: number;
|
|
20
|
+
endedAt: number | null;
|
|
21
|
+
elapsedWallMs: number;
|
|
22
|
+
elapsedActiveMs: number;
|
|
23
|
+
elapsedPausedMs: number;
|
|
24
|
+
remainingMs: Span | null;
|
|
25
|
+
estimatedTotalMs: Span | null;
|
|
26
|
+
estimateOrigin: 'heuristic' | 'public-measured' | 'local-measured' | 'mixed';
|
|
27
|
+
localPerformanceSamples: number;
|
|
28
|
+
workloadSamples: number;
|
|
29
|
+
observedTokenStatus: 'complete' | 'partial' | 'unknown';
|
|
30
|
+
observedTokens: number | null;
|
|
31
|
+
tokens: TokenBreakdown;
|
|
32
|
+
estimatedTotalTokens: Span | null;
|
|
33
|
+
/** Planned visible generation, including tool arguments; excludes hidden reasoning. */
|
|
34
|
+
estimatedRemainingOutputTokens?: Span | null;
|
|
35
|
+
knownCost: Money[];
|
|
36
|
+
estimatedTotalCost: MoneyRange[] | null;
|
|
37
|
+
observedCostStatus: 'complete' | 'partial' | 'unpriced' | 'free';
|
|
38
|
+
forecastCostStatus: 'reference' | 'partial' | 'unavailable' | 'free';
|
|
39
|
+
unpricedCalls: number;
|
|
40
|
+
incompleteForecastUnits: number;
|
|
41
|
+
calls: { completed: number; active: number; failed: number; expected: Span };
|
|
42
|
+
tools: { completed: number; active: number; workMs: number };
|
|
43
|
+
performance: {
|
|
44
|
+
providerId: string; modelId: string; endpointFingerprint: string;
|
|
45
|
+
requestMode: string; reasoningEffort: string; serviceTier: string;
|
|
46
|
+
firstContentMs: number | null; firstTextMs: number | null; visibleTps: number | null;
|
|
47
|
+
totalCallMs: number | null; source: string; stale: boolean;
|
|
48
|
+
/** Optional only for stored snapshots predating metric-specific provenance. */
|
|
49
|
+
trust?: 'observed' | 'reference';
|
|
50
|
+
metricOrigins?: { firstContent: 'heuristic' | 'public-measured' | 'local-measured'; firstText: 'heuristic' | 'public-measured' | 'local-measured'; speed: 'heuristic' | 'public-measured' | 'local-measured'; total: 'heuristic' | 'public-measured' | 'local-measured' };
|
|
51
|
+
} | null;
|
|
52
|
+
priceSources: string[];
|
|
53
|
+
initial: { estimatedTotalMs: Span | null; estimatedTotalCost: MoneyRange[] | null } | null;
|
|
54
|
+
error: string | null;
|
|
55
|
+
reasons: string[];
|
|
56
|
+
scope: 'current_turn';
|
|
57
|
+
/** Whole-session elapsed/remaining, filled by the Host when other turns of this session are known. */
|
|
58
|
+
sessionElapsedMs?: number;
|
|
59
|
+
sessionRemainingMs?: Span | null;
|
|
60
|
+
sessionTurns?: number;
|
|
61
|
+
}
|
|
62
|
+
export interface HistoryItem {
|
|
63
|
+
taskKey: string; sessionId: string; turn: number; taskType: string; state: TaskState;
|
|
64
|
+
startedAt: number; elapsedActiveMs: number; elapsedPausedMs: number; knownCost: Money[];
|
|
65
|
+
initialMs: Span | null; durationErrorMs: number | null;
|
|
66
|
+
}
|
|
67
|
+
export interface RetainedTimeForecast {
|
|
68
|
+
taskKey: string;
|
|
69
|
+
remainingMs: Span;
|
|
70
|
+
estimatedTotalMs: Span | null;
|
|
71
|
+
updatedAt: number;
|
|
72
|
+
}
|
|
73
|
+
export interface EstimatorView {
|
|
74
|
+
snapshot: EstimateSnapshot | null;
|
|
75
|
+
/** Display reference only; never used for current usage, costs or calibration. */
|
|
76
|
+
lastForecast?: RetainedTimeForecast;
|
|
77
|
+
available: boolean;
|
|
78
|
+
error: string | null;
|
|
79
|
+
}
|
|
80
|
+
export interface ManagementView {
|
|
81
|
+
config: Record<string, unknown>;
|
|
82
|
+
history: HistoryItem[];
|
|
83
|
+
profiles: ProfileSummary[];
|
|
84
|
+
diagnostics: { time: number; code: string; message: string }[];
|
|
85
|
+
storage: 'ready' | 'unavailable';
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Calibration summary for one provider/route bucket. Values are smoothed local
|
|
89
|
+
* centers; the sample counts decide whether a metric is an observation or still
|
|
90
|
+
* a prior, so the UI must never present a prior-only value as a measurement.
|
|
91
|
+
*/
|
|
92
|
+
export interface ProfileSummary {
|
|
93
|
+
key: string;
|
|
94
|
+
providerId: string;
|
|
95
|
+
modelId: string;
|
|
96
|
+
endpointFingerprint: string;
|
|
97
|
+
requestMode: string;
|
|
98
|
+
reasoningEffort: string;
|
|
99
|
+
serviceTier: string;
|
|
100
|
+
/** Explicit buckets keep two rows of the same model distinguishable. */
|
|
101
|
+
inputBucket?: string;
|
|
102
|
+
cacheBucket?: string;
|
|
103
|
+
concurrencyBucket?: string;
|
|
104
|
+
/** Upstream identity was unknown or mixed for this bucket. */
|
|
105
|
+
mixedRoute?: boolean;
|
|
106
|
+
firstContentMs: number | null;
|
|
107
|
+
firstTextMs: number | null;
|
|
108
|
+
/** Local speed center; null until a call contributed an accepted speed sample. */
|
|
109
|
+
visibleTps: number | null;
|
|
110
|
+
/** Prior speed that the estimator would fall back to when no local speed exists. */
|
|
111
|
+
priorVisibleTps: number | null;
|
|
112
|
+
totalCallMs: number;
|
|
113
|
+
totalCallSamples: number;
|
|
114
|
+
firstTextSamples: number;
|
|
115
|
+
speedSamples: number;
|
|
116
|
+
failedCalls: number;
|
|
117
|
+
/** End of the newest accepted local observation; null until one exists. */
|
|
118
|
+
testedAt: number | null;
|
|
119
|
+
sourceKind: 'heuristic' | 'public-measured' | 'local-measured';
|
|
120
|
+
}
|
|
121
|
+
export type ManagementAction = 'read' | 'saveConfig' | 'export' | 'resetCalibration' | 'importBaselines';
|
|
122
|
+
export interface ManagementResult {
|
|
123
|
+
ok: boolean;
|
|
124
|
+
message: string;
|
|
125
|
+
data?: ManagementView;
|
|
126
|
+
exported?: string;
|
|
127
|
+
}
|
|
128
|
+
export interface EstimatorRemote {
|
|
129
|
+
snapshot(sessionId: string, turn: number | null, signal?: AbortSignal): Promise<RemoteResult<EstimatorView>>;
|
|
130
|
+
manage(action: ManagementAction, payload: string, signal?: AbortSignal): Promise<RemoteResult<ManagementResult>>;
|
|
131
|
+
}
|
|
132
|
+
export type RemoteResult<T> = { ok: true; value: T } | { ok: false; error: { message: string; code: string } };
|
|
133
|
+
export const ALGORITHM_VERSION = 'p0-0.2.4';
|
|
134
|
+
export const PACKAGE_NAME = 'dsh-task-time-cost';
|