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.
Files changed (70) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/COMPATIBILITY.md +26 -0
  3. package/CONTRIBUTING.md +11 -0
  4. package/LICENSE +21 -0
  5. package/README.en.md +60 -0
  6. package/README.md +59 -2
  7. package/THIRD_PARTY_NOTICES.md +113 -0
  8. package/cordis.patch.yml +4 -0
  9. package/data/baselines.json +12 -0
  10. package/data/defaults.json +21 -0
  11. package/data/models-dev-prices.json +1 -0
  12. package/data/prices.json +7 -0
  13. package/data/sources.json +15 -0
  14. package/docs/public/DETAIL.md +1 -0
  15. package/docs/public/DETAIL.zh.md +1 -0
  16. package/docs/public/acceptance.md +26 -0
  17. package/docs/public/guide.en.md +33 -0
  18. package/docs/public/guide.zh.md +35 -0
  19. package/docs/public/preview.svg +1 -0
  20. package/docs/public/privacy.md +13 -0
  21. package/docs/public/publishing.md +9 -0
  22. package/icon.svg +1 -0
  23. package/lib/client.js +175 -0
  24. package/lib/index.js +22948 -0
  25. package/lib/index.js.map +7 -0
  26. package/locale/en.json +7 -0
  27. package/locale/zh.json +7 -0
  28. package/package.json +122 -4
  29. package/scripts/import-public-prices.mjs +35 -0
  30. package/src/client/INTEGRATION.md +61 -0
  31. package/src/client/config.ts +24 -0
  32. package/src/client/details.tsx +126 -0
  33. package/src/client/format.ts +218 -0
  34. package/src/client/index.tsx +225 -0
  35. package/src/client/locale.ts +353 -0
  36. package/src/client/management.tsx +246 -0
  37. package/src/client/placement.ts +26 -0
  38. package/src/client/remote.ts +59 -0
  39. package/src/client/store.ts +210 -0
  40. package/src/client/styles.ts +94 -0
  41. package/src/client/use-panel-placement.ts +54 -0
  42. package/src/client-entry.ts +12 -0
  43. package/src/host/config-entry.ts +47 -0
  44. package/src/host/config.ts +85 -0
  45. package/src/host/engine.ts +580 -0
  46. package/src/host/facts.ts +170 -0
  47. package/src/host/forecast-cost.ts +16 -0
  48. package/src/host/index.ts +269 -0
  49. package/src/host/record-schema.ts +175 -0
  50. package/src/host/repository.ts +167 -0
  51. package/src/host/runtime.ts +99 -0
  52. package/src/shared/ai-plan.ts +45 -0
  53. package/src/shared/baseline-selection.ts +43 -0
  54. package/src/shared/baselines.ts +135 -0
  55. package/src/shared/call-size.ts +32 -0
  56. package/src/shared/config.ts +65 -0
  57. package/src/shared/forecast.ts +91 -0
  58. package/src/shared/index.ts +12 -0
  59. package/src/shared/ledger.ts +38 -0
  60. package/src/shared/money.ts +46 -0
  61. package/src/shared/performance.ts +216 -0
  62. package/src/shared/pricing.ts +293 -0
  63. package/src/shared/public-prices.ts +57 -0
  64. package/src/shared/remote-contract.ts +72 -0
  65. package/src/shared/retained-time.ts +14 -0
  66. package/src/shared/time.ts +207 -0
  67. package/src/shared/types.ts +66 -0
  68. package/src/shared/usage.ts +232 -0
  69. package/src/shared/wire.ts +134 -0
  70. 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';