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,167 @@
1
+ import { z } from 'zod';
2
+ import { createHash } from 'node:crypto';
3
+ type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
4
+ import type { Domain, DomainFacility, DomainGlobalSpec, DomainTableSpec } from '@deepseek-ai/dsh-storage-domain';
5
+ import type { CallFact } from './facts.ts';
6
+ import type { RouteIdentity } from '../shared/types.ts';
7
+ import type { CallObservation } from '../shared/performance.ts';
8
+ import type { NormalizedUsage } from '../shared/usage.ts';
9
+ import type { CallCost, PriceResolution } from '../shared/pricing.ts';
10
+ import type { EstimateSnapshot, RetainedTimeForecast } from '../shared/wire.ts';
11
+ import { snapshotSchema, retainedTimeForecastSchema } from '../shared/remote-contract.ts';
12
+ import { callRecordSchema } from './record-schema.ts';
13
+ import type { PluginConfig } from './config.ts';
14
+
15
+ export interface CallRecord {
16
+ id: string; savedAt: number; fact: CallFact; route: RouteIdentity;
17
+ usage: NormalizedUsage; cost: CallCost; resolution: PriceResolution;
18
+ observation: CallObservation | null;
19
+ }
20
+ export interface TaskRecord {
21
+ id: string; savedAt: number; current: EstimateSnapshot; sourceRevision?: number;
22
+ revisions: EstimateSnapshot[];
23
+ lastForecast?: RetainedTimeForecast | null;
24
+ learned: { calls: number; visibleOutputTokens: number; toolWorkMs: number; eligible: boolean } | null;
25
+ }
26
+ export interface Diagnostic { time: number; code: string; message: string }
27
+ const globalSchema = z.object({
28
+ config: z.record(z.string(), z.json()).nullable(),
29
+ resetAt: z.number().finite().nonnegative(),
30
+ baselineImport: z.string().max(2_000_000).nullable(),
31
+ }).strict();
32
+ const taskSchema = z.object({ id: z.string(), savedAt: z.number().finite().nonnegative(), current: snapshotSchema, sourceRevision: z.number().int().nonnegative().optional(),
33
+ revisions: z.array(snapshotSchema).max(128), lastForecast: retainedTimeForecastSchema.nullable().optional(), learned: z.object({ calls: z.number().int().nonnegative(), visibleOutputTokens: z.number().nonnegative(), toolWorkMs: z.number().nonnegative(), eligible: z.boolean() }).nullable() });
34
+ interface GlobalState { config: Record<string, JsonValue> | null; resetAt: number; baselineImport: string | null }
35
+ interface RepositorySpec {
36
+ name: string; version: number; layout: 'per-record'; invalidRecords: 'backup-and-skip';
37
+ global: DomainGlobalSpec<GlobalState>;
38
+ tables: { calls: DomainTableSpec<string, CallRecord>; tasks: DomainTableSpec<string, TaskRecord> };
39
+ }
40
+ // Widen Zod builders to their public value contracts before Domain's conditional types.
41
+ // Retaining every builder generic here causes needless recursive schema expansion in tsc.
42
+ const spec: RepositorySpec = { name: 'dsh_task_time_cost', version: 1, layout: 'per-record' as const,
43
+ invalidRecords: 'backup-and-skip' as const,
44
+ global: { schema: globalSchema, initial: { config: null, resetAt: 0, baselineImport: null } },
45
+ tables: { calls: { valueSchema: callRecordSchema }, tasks: { valueSchema: taskSchema } },
46
+ };
47
+ type Store = Domain<typeof spec>;
48
+ // Canonical session:sequence identities are values. Backend keys are safe on Windows and POSIX.
49
+ const storageKey = (id: string): string => createHash('sha256').update(id, 'utf8').digest('hex');
50
+
51
+ export class Repository {
52
+ private store: Store | null = null;
53
+ private queue: Promise<void> = Promise.resolve();
54
+ private closed = false;
55
+ readonly calls = new Map<string, CallRecord>();
56
+ readonly tasks = new Map<string, TaskRecord>();
57
+ readonly diagnostics: Diagnostic[] = [];
58
+ error: string | null = null;
59
+ resetAt = 0;
60
+ savedConfig: Record<string, unknown> | null = null;
61
+ baselineImport: string | null = null;
62
+ private readonly log: (message: string) => void;
63
+ private readonly now: () => number;
64
+ constructor(log: (message: string) => void, now = () => Date.now()) { this.log = log; this.now = now; }
65
+
66
+ async open(facility: DomainFacility): Promise<void> {
67
+ try {
68
+ this.store = await facility.open(spec);
69
+ const global = this.store.global.get();
70
+ this.resetAt = global.resetAt;
71
+ this.savedConfig = global.config;
72
+ this.baselineImport = global.baselineImport;
73
+ for (const [, record] of this.store.table('calls').entries()) this.calls.set(record.id, record);
74
+ for (const [, record] of this.store.table('tasks').entries()) this.tasks.set(record.id, record);
75
+ } catch (error) { this.fail('storage-open', error); }
76
+ }
77
+ get available(): boolean { return this.store !== null && this.error === null && !this.closed; }
78
+ diagnose(code: string, message: string): void {
79
+ // Only package-owned error codes and safe explanations enter persisted/exportable diagnostics.
80
+ this.diagnostics.push({ time: this.now(), code, message });
81
+ this.diagnostics.splice(0, Math.max(0, this.diagnostics.length - 100));
82
+ this.log(`[${code}] ${message}`);
83
+ }
84
+ fail(code: string, error: unknown): void {
85
+ const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
86
+ // Error details can contain provider URLs/arguments; the export gets only the operation code.
87
+ this.error ??= `Estimator unavailable (${code}). Check the DSH plugin log.`;
88
+ this.diagnose(code, this.error);
89
+ this.log(detail);
90
+ }
91
+ private enqueue(operation: () => Promise<void>): Promise<void> {
92
+ if (!this.available) return Promise.resolve();
93
+ const pending = this.queue.then(async () => { if (this.available) await operation(); });
94
+ this.queue = pending.catch(error => this.fail('storage-write', error));
95
+ return this.queue;
96
+ }
97
+ saveCall(record: CallRecord): Promise<void> {
98
+ const existing = this.calls.get(record.id);
99
+ if (existing) return Promise.resolve();
100
+ const validated = callRecordSchema.safeParse(record);
101
+ if (!validated.success) { this.fail('invalid-call-record', new Error('Invalid call metadata; the record was not persisted.')); return Promise.resolve(); }
102
+ record = validated.data;
103
+ this.calls.set(record.id, structuredClone(record));
104
+ return this.enqueue(async () => {
105
+ if (!this.store) throw new Error('Storage is not mounted');
106
+ await this.store.table('calls').put(storageKey(record.id), record);
107
+ });
108
+ }
109
+ /**
110
+ * Overwrite a derived record. Normalization and pricing are derivations of the
111
+ * adapter's own facts, so a corrected rule must be able to heal stored bytes
112
+ * instead of leaving two incompatible readings of the same call on disk.
113
+ */
114
+ replaceCall(record: CallRecord): Promise<void> {
115
+ const validated = callRecordSchema.safeParse(record);
116
+ if (!validated.success) { this.fail('invalid-call-record', new Error('Invalid call metadata; the healed record was not persisted.')); return Promise.resolve(); }
117
+ const healed = validated.data;
118
+ this.calls.set(healed.id, structuredClone(healed));
119
+ return this.enqueue(async () => {
120
+ if (!this.store) throw new Error('Storage is not mounted');
121
+ await this.store.table('calls').put(storageKey(healed.id), healed);
122
+ });
123
+ }
124
+ saveTask(record: TaskRecord): Promise<void> {
125
+ this.tasks.set(record.id, structuredClone(record));
126
+ return this.enqueue(async () => {
127
+ if (!this.store) throw new Error('Storage is not mounted');
128
+ await this.store.table('tasks').put(storageKey(record.id), record);
129
+ });
130
+ }
131
+ saveConfig(config: PluginConfig): Promise<void> {
132
+ this.savedConfig = JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
133
+ return this.enqueue(async () => { if (!this.store) throw new Error('Storage is not mounted'); await this.store.global.set({ config: this.savedConfig as Record<string, JsonValue>, resetAt: this.resetAt, baselineImport: this.baselineImport }); });
134
+ }
135
+ saveBaselineImport(text: string): Promise<void> {
136
+ this.baselineImport = text;
137
+ return this.enqueue(async () => { if (!this.store) throw new Error('Storage is not mounted'); await this.store.global.set({ config: this.savedConfig as Record<string, JsonValue> | null, resetAt: this.resetAt, baselineImport: text }); });
138
+ }
139
+ resetCalibration(): Promise<void> {
140
+ this.resetAt = this.now();
141
+ return this.enqueue(async () => {
142
+ if (!this.store) throw new Error('Storage is not mounted');
143
+ // Retain usage, resolved prices and task history. resetAt excludes older learning only.
144
+ await this.store.global.set({ config: this.savedConfig as Record<string, JsonValue> | null, resetAt: this.resetAt, baselineImport: this.baselineImport });
145
+ });
146
+ }
147
+ async prune(config: PluginConfig): Promise<void> {
148
+ const cutoff = this.now() - config.historyRetentionDays * 86_400_000;
149
+ const calls = [...this.calls.values()].sort((a, b) => b.savedAt - a.savedAt);
150
+ const buckets = new Map<string, number>();
151
+ const expiredCalls: string[] = [];
152
+ for (const call of calls) {
153
+ const key = JSON.stringify(call.route);
154
+ const count = (buckets.get(key) ?? 0) + 1; buckets.set(key, count);
155
+ if (call.savedAt < cutoff || count > config.maxSamplesPerBucket || buckets.size > 2000) { expiredCalls.push(call.id); this.calls.delete(call.id); }
156
+ }
157
+ const expiredTasks = [...this.tasks.values()].sort((a, b) => b.savedAt - a.savedAt).filter((task, index) => (task.savedAt < cutoff || index >= 2000) && !['running', 'waiting_user', 'queued'].includes(task.current.state)).map(task => task.id);
158
+ for (const id of expiredTasks) this.tasks.delete(id);
159
+ if (!expiredCalls.length && !expiredTasks.length) return;
160
+ await this.enqueue(async () => { if (!this.store) return; await this.store.table('calls').deleteMany(expiredCalls.map(storageKey)); await this.store.table('tasks').deleteMany(expiredTasks.map(storageKey)); });
161
+ }
162
+ async flush(): Promise<void> { await this.queue; }
163
+ async close(): Promise<void> {
164
+ await this.flush(); this.closed = true;
165
+ await this.store?.close(); this.store = null;
166
+ }
167
+ }
@@ -0,0 +1,99 @@
1
+ import { performance } from 'node:perf_hooks';
2
+ import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
3
+ import type { StreamStats, RouteFact } from './facts.ts';
4
+ import { emptyStreamStats, observeChunk } from './facts.ts';
5
+
6
+ export interface Clock { wall(): number; monotonic(): number }
7
+ export const systemClock: Clock = { wall: () => Date.now(), monotonic: () => performance.now() };
8
+ export interface PauseInterval { start: number; end: number }
9
+ export interface TaskRuntime {
10
+ key: string; anchorWall: number; anchorMono: number; paused: PauseInterval[];
11
+ pauseOwners: Set<object>; pauseStart: number | null; lastPredictionAt: number;
12
+ }
13
+ export interface LiveAttempt extends StreamStats {
14
+ id: string; sessionId: string; turn: number; step: number; route: RouteFact;
15
+ startedAt: number; startedMono: number; lastIndex: number;
16
+ }
17
+ export interface ToolTiming { id: string; sessionId: string; turn: number; startedAt: number; endedAt: number | null; workMs: number }
18
+
19
+ /** All process-local state has one Host owner. Clients never create observations. */
20
+ export class RuntimeObservations {
21
+ readonly tasks = new Map<string, TaskRuntime>();
22
+ readonly attempts = new Map<string, LiveAttempt>();
23
+ readonly tools = new Map<string, ToolTiming>();
24
+ readonly clock: Clock;
25
+ constructor(clock: Clock = systemClock) { this.clock = clock; }
26
+ task(sessionId: string, turn: number): TaskRuntime {
27
+ const key = `${sessionId}:${turn}`;
28
+ let runtime = this.tasks.get(key);
29
+ if (!runtime) {
30
+ runtime = { key, anchorWall: this.clock.wall(), anchorMono: this.clock.monotonic(), paused: [], pauseOwners: new Set(), pauseStart: null, lastPredictionAt: 0 };
31
+ this.tasks.set(key, runtime);
32
+ }
33
+ return runtime;
34
+ }
35
+ time(runtime: TaskRuntime): number { return runtime.anchorWall + Math.max(0, this.clock.monotonic() - runtime.anchorMono); }
36
+ pause(sessionId: string, turn: number): () => void {
37
+ const runtime = this.task(sessionId, turn);
38
+ const owner = {};
39
+ if (!runtime.pauseOwners.size) runtime.pauseStart = this.time(runtime);
40
+ runtime.pauseOwners.add(owner);
41
+ let released = false;
42
+ return () => {
43
+ if (released) return; released = true;
44
+ runtime.pauseOwners.delete(owner);
45
+ if (!runtime.pauseOwners.size && runtime.pauseStart !== null) {
46
+ runtime.paused.push({ start: runtime.pauseStart, end: this.time(runtime) });
47
+ runtime.pauseStart = null;
48
+ }
49
+ };
50
+ }
51
+ pausedMs(sessionId: string, turn: number, from: number, to: number): number {
52
+ const runtime = this.tasks.get(`${sessionId}:${turn}`);
53
+ if (!runtime) return 0;
54
+ let ms = 0;
55
+ for (const interval of runtime.paused) ms += Math.max(0, Math.min(to, interval.end) - Math.max(from, interval.start));
56
+ if (runtime.pauseStart !== null) ms += Math.max(0, to - Math.max(from, runtime.pauseStart));
57
+ return Math.min(Math.max(0, to - from), ms);
58
+ }
59
+ startAttempt(sessionId: string, frame: Extract<AssistantStreamFrame, { type: 'start' }>, route: RouteFact): void {
60
+ if (this.attempts.has(frame.attemptId)) return;
61
+ this.task(sessionId, frame.turn);
62
+ this.attempts.set(frame.attemptId, { ...emptyStreamStats(), id: frame.attemptId, sessionId, turn: frame.turn, step: frame.step, route: { ...route }, startedAt: this.clock.wall(), startedMono: this.clock.monotonic(), lastIndex: -1 });
63
+ }
64
+ chunk(frame: Extract<AssistantStreamFrame, { type: 'chunk' }>): void {
65
+ const attempt = this.attempts.get(frame.attemptId);
66
+ if (!attempt || frame.index <= attempt.lastIndex) return;
67
+ // Monotonic durations cannot be distorted by an OS clock correction.
68
+ const at = attempt.startedAt + Math.max(0, this.clock.monotonic() - attempt.startedMono);
69
+ const next = observeChunk(attempt, frame.chunk, at);
70
+ this.attempts.set(attempt.id, { ...attempt, ...next, lastIndex: frame.index });
71
+ }
72
+ endAttempt(id: string): { attempt: LiveAttempt; endedAt: number } | null {
73
+ const attempt = this.attempts.get(id);
74
+ if (!attempt) return null;
75
+ this.attempts.delete(id);
76
+ return { attempt, endedAt: attempt.startedAt + Math.max(0, this.clock.monotonic() - attempt.startedMono) };
77
+ }
78
+ activeAttempts(sessionId: string, turn: number): LiveAttempt[] { return [...this.attempts.values()].filter(attempt => attempt.sessionId === sessionId && attempt.turn === turn); }
79
+ beginTool(sessionId: string, turn: number, callId: string): ToolTiming {
80
+ const runtime = this.task(sessionId, turn);
81
+ const key = `${sessionId}:${callId}`;
82
+ const existing = this.tools.get(key);
83
+ if (existing) return existing;
84
+ const timing = { id: callId, sessionId, turn, startedAt: this.time(runtime), endedAt: null, workMs: 0 };
85
+ this.tools.set(key, timing);
86
+ return timing;
87
+ }
88
+ endTool(timing: ToolTiming): void {
89
+ const runtime = this.task(timing.sessionId, timing.turn);
90
+ timing.endedAt = this.time(runtime);
91
+ timing.workMs = Math.max(0, timing.endedAt - timing.startedAt - this.pausedMs(timing.sessionId, timing.turn, timing.startedAt, timing.endedAt));
92
+ }
93
+ cleanupSession(sessionId: string): void {
94
+ for (const [key, attempt] of this.attempts) if (attempt.sessionId === sessionId) this.attempts.delete(key);
95
+ for (const [key, tool] of this.tools) if (tool.sessionId === sessionId) this.tools.delete(key);
96
+ for (const [key] of this.tasks) if (key.startsWith(`${sessionId}:`)) this.tasks.delete(key);
97
+ }
98
+ clear(): void { this.tasks.clear(); this.attempts.clear(); this.tools.clear(); }
99
+ }
@@ -0,0 +1,45 @@
1
+ import { z } from 'zod';
2
+ import { estimateWorkload } from './workload.ts';
3
+ import type { PlanScenario, WorkloadPlan } from './workload.ts';
4
+ import type { RouteIdentity } from './types.ts';
5
+ import type { EstimatorConfig } from './config.ts';
6
+
7
+ const span = (max: number, minimum = 0) => z.object({ low: z.number().int().min(minimum).max(max), high: z.number().int().min(minimum).max(max) }).strict()
8
+ .refine(value => value.low <= value.high, 'Bounds must be ordered');
9
+ /** Numeric work metadata only: no free-form prompt, reasoning or file contents. */
10
+ export const aiPlanSchema = z.object({
11
+ remainingCalls: span(500, 1),
12
+ remainingOutputTokens: span(2_000_000),
13
+ remainingToolSeconds: span(86_400),
14
+ stage: z.enum(['planning', 'implementation', 'verification', 'finishing']),
15
+ }).strict();
16
+ export type AiPlanInput = z.infer<typeof aiPlanSchema>;
17
+ export type AiPlan = AiPlanInput & { afterCalls: number; submittedAt: number };
18
+
19
+ export function readAiPlanResult(text: string, afterCalls: number, submittedAt: number): AiPlan | null {
20
+ if (text.length > 4_000) return null;
21
+ try {
22
+ const result = z.object({ kind: z.literal('task-estimate-plan'), version: z.literal(1), plan: aiPlanSchema }).strict().parse(JSON.parse(text));
23
+ return { ...result.plan, afterCalls, submittedAt };
24
+ } catch { return null; }
25
+ }
26
+
27
+ /** Replace FUTURE work while preserving the settled request positions and costs. */
28
+ export function applyAiPlan(base: WorkloadPlan, ai: AiPlan, route: RouteIdentity, inputTokens: number | null, config: Partial<EstimatorConfig>): WorkloadPlan {
29
+ const future = estimateWorkload({ prompt: '', currentInputTokens: inputTokens }, route, { config,
30
+ rules: [{ id: 'executing-ai-plan', kind: base.kind, patterns: ['.*'] }],
31
+ templates: [{ kind: base.kind, requestCount: ai.remainingCalls, visibleOutputTokens: ai.remainingOutputTokens,
32
+ toolMs: { low: ai.remainingToolSeconds.low * 1_000, high: ai.remainingToolSeconds.high * 1_000 }, sourceKind: 'heuristic', sourceId: 'executing-ai-plan' }],
33
+ });
34
+ const shiftId = (id: string) => id.replace(/^(request|tool)-(\d+)$/, (_, prefix: string, number: string) => `${prefix}-${Number(number) + ai.afterCalls}`);
35
+ function scenario(value: PlanScenario): PlanScenario {
36
+ const placeholder = value.requests[0]!;
37
+ return { requests: [
38
+ ...Array.from({ length: ai.afterCalls }, (_, index) => ({ ...placeholder, id: `request-${index + 1}`, dependsOn: [] })),
39
+ ...value.requests.map(request => ({ ...request, id: shiftId(request.id), dependsOn: request.dependsOn.map(shiftId) })),
40
+ ], tools: value.tools.map(tool => ({ ...tool, id: shiftId(tool.id), dependsOn: tool.dependsOn.map(shiftId) })) };
41
+ }
42
+ return { ...future, low: scenario(future.low), high: scenario(future.high),
43
+ reasons: [...future.reasons.filter(reason => reason !== 'engineering-workload-template'), 'ai-workload-plan-reference'],
44
+ sourceIds: ['executing-ai-plan'], workloadSamples: 0 };
45
+ }
@@ -0,0 +1,43 @@
1
+ import { validateBaselines } from './baselines.ts';
2
+ import type { BaselineRecord, MetricValue } from './baselines.ts';
3
+ import { DEFAULT_TEMPLATES } from './workload.ts';
4
+ import type { WorkloadTemplate } from './workload.ts';
5
+ import type { RouteIdentity, SourceKind, Span } from './types.ts';
6
+ import { heuristicPerformance } from './performance.ts';
7
+ import type { PerformancePrior } from './performance.ts';
8
+ import type { EstimatorConfig } from './config.ts';
9
+
10
+ function applicable(record: BaselineRecord, route: RouteIdentity): boolean {
11
+ return Object.entries(record.appliesTo).every(([key, value]) => value === '*' || value === route[key as keyof RouteIdentity]);
12
+ }
13
+ function bounds(metric: MetricValue): Span {
14
+ if ('low' in metric) return { low: metric.low, high: metric.high };
15
+ if ('mean' in metric) return { low: metric.mean, high: metric.mean };
16
+ if ('value' in metric) return { low: metric.value, high: metric.value };
17
+ return { low: metric.p50, high: metric.p95 ?? metric.p90 ?? metric.p50 };
18
+ }
19
+ function center(metric: MetricValue): number { const range = bounds(metric); return (range.low + range.high) / 2; }
20
+ const sourcePriority: Record<SourceKind, number> = { 'local-measured': 0, 'public-measured': 1, heuristic: 2 };
21
+ function ordered(records: BaselineRecord[]): BaselineRecord[] { return [...records].sort((a, b) => sourcePriority[a.sourceKind] - sourcePriority[b.sourceKind] || Date.parse(b.date) - Date.parse(a.date)); }
22
+
23
+ /** Only complete workload records replace a template; a missing tool budget is never zero. */
24
+ export function templatesFromBaselines(records: BaselineRecord[], route: RouteIdentity, fallback: readonly WorkloadTemplate[] = DEFAULT_TEMPLATES): WorkloadTemplate[] {
25
+ validateBaselines(records);
26
+ return fallback.map(template => {
27
+ const record = ordered(records).find(record => record.taskKind === template.kind && applicable(record, route) && record.metrics.requestCount && record.metrics.visibleOutputTokens && record.metrics.toolMs);
28
+ if (!record) return structuredClone(template);
29
+ const requests = bounds(record.metrics.requestCount!);
30
+ return { kind: template.kind, requestCount: { low: Math.max(1, Math.floor(requests.low)), high: Math.max(1, Math.ceil(requests.high)) }, visibleOutputTokens: bounds(record.metrics.visibleOutputTokens!), toolMs: bounds(record.metrics.toolMs!), sourceKind: record.sourceKind, sourceId: `${record.seedId}@${record.dataVersion}:${record.statistic}` };
31
+ });
32
+ }
33
+
34
+ /** Means become labeled centers; this conversion does not create samples or quantiles. */
35
+ export function performancePriorsFromBaselines(records: BaselineRecord[], config: Partial<EstimatorConfig> = {}): PerformancePrior[] {
36
+ validateBaselines(records);
37
+ const fallback = heuristicPerformance(config);
38
+ return ordered(records).filter(record => ['firstContentMs', 'firstTextMs', 'visibleTps', 'totalCallMs'].some(name => name in record.metrics)).map(record => {
39
+ const metrics = record.metrics;
40
+ const origins = { firstContent: metrics.firstContentMs ? record.sourceKind : 'heuristic', firstText: metrics.firstTextMs ? record.sourceKind : 'heuristic', speed: metrics.visibleTps ? record.sourceKind : 'heuristic', total: metrics.totalCallMs ? record.sourceKind : 'heuristic' } as const;
41
+ return { id: `${record.seedId}@${record.dataVersion}:${record.statistic}`, sourceKind: record.sourceKind, sourceUrl: record.sourceUrl, dataVersion: record.dataVersion, sampleCount: record.sampleCount, timingBasis: record.timingBasis, appliesTo: { ...record.appliesTo }, firstContentMs: metrics.firstContentMs ? center(metrics.firstContentMs) : null, firstTextMs: metrics.firstTextMs ? center(metrics.firstTextMs) : null, visibleTps: metrics.visibleTps && center(metrics.visibleTps) > 0 ? center(metrics.visibleTps) : null, totalCallMs: metrics.totalCallMs ? center(metrics.totalCallMs) : fallback.totalCallMs, metricOrigins: origins };
42
+ });
43
+ }
@@ -0,0 +1,135 @@
1
+ import type { RequestMode, RouteApplicability, SourceMetadata, TaskKind } from './types.ts';
2
+ import { assertSpan } from './types.ts';
3
+
4
+ export const BASELINE_METRICS = ['requestCount', 'visibleOutputTokens', 'toolMs', 'firstContentMs', 'firstTextMs', 'visibleTps', 'totalCallMs', 'inputTokens'] as const;
5
+ export type BaselineMetric = typeof BASELINE_METRICS[number];
6
+ export type MetricValue = { low: number; high: number } | { mean: number } | { value: number } | { p50: number; p90?: number; p95?: number };
7
+ export interface BaselineRecord extends SourceMetadata {
8
+ seedId: string;
9
+ taskKind: TaskKind;
10
+ appliesTo: RouteApplicability;
11
+ metrics: Partial<Record<BaselineMetric, MetricValue>>;
12
+ }
13
+ const TASK_KINDS = ['question', 'writing', 'file-analysis', 'code', 'research', 'unknown'];
14
+ const ROUTE_FIELDS = ['providerId', 'endpointFingerprint', 'modelId', 'requestMode', 'reasoningEffort', 'serviceTier', 'inputBucket', 'cacheBucket', 'concurrencyBucket'] as const;
15
+ const MODES: RequestMode[] = ['text', 'tool', 'mixed', 'unknown', 'non-streaming'];
16
+
17
+ export function validateBaselines(records: BaselineRecord[]): void {
18
+ if (!Array.isArray(records)) throw new TypeError('Baseline records must be an array');
19
+ const keys = new Set<string>();
20
+ for (const record of records) {
21
+ if (!record || typeof record !== 'object') throw new TypeError('Invalid baseline record');
22
+ const key = JSON.stringify([record.seedId, record.dataVersion]);
23
+ if (!record.seedId || !record.dataVersion || keys.has(key)) throw new TypeError('Duplicate or missing baseline seed/version');
24
+ keys.add(key);
25
+ if (!TASK_KINDS.includes(record.taskKind) || !['heuristic', 'local-measured', 'public-measured'].includes(record.sourceKind)) throw new TypeError('Invalid baseline kind/source');
26
+ if (typeof record.date !== 'string' || !/^\d{4}-\d{2}-\d{2}(?:T.*)?$/.test(record.date) || !Number.isFinite(Date.parse(record.date))) throw new TypeError('Baseline date must be ISO');
27
+ if (!record.scope || !record.timingBasis || !['assumption-range', 'mean', 'sample', 'quantiles'].includes(record.statistic)) throw new TypeError('Missing baseline scope/statistic/timing basis');
28
+ if (record.sampleCount !== null && (!Number.isSafeInteger(record.sampleCount) || record.sampleCount < 1)) throw new TypeError('Sample count must be positive or null');
29
+ if (record.sourceKind === 'heuristic' && (record.sampleCount !== null || record.statistic !== 'assumption-range')) throw new TypeError('Heuristic assumptions must not claim measured samples/quantiles');
30
+ if (record.statistic === 'quantiles' && record.sampleCount === null) throw new TypeError('Quantiles require a supported sample count');
31
+ if (record.statistic === 'sample' && record.sampleCount !== 1) throw new TypeError('A single sample must declare sampleCount=1');
32
+ if (record.sourceUrl !== null) {
33
+ const url = new URL(record.sourceUrl);
34
+ if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new TypeError('Invalid source URL');
35
+ }
36
+ if (record.sourceKind === 'public-measured' && !record.sourceUrl) throw new TypeError('A public measurement requires its source URL');
37
+ if (!record.appliesTo || typeof record.appliesTo !== 'object' || Array.isArray(record.appliesTo)) throw new TypeError('Missing baseline applicability');
38
+ for (const [field, value] of Object.entries(record.appliesTo)) {
39
+ if (!ROUTE_FIELDS.includes(field as typeof ROUTE_FIELDS[number]) || typeof value !== 'string' || !value) throw new TypeError('Invalid baseline route field');
40
+ if (field === 'requestMode' && value !== '*' && !MODES.includes(value as RequestMode)) throw new TypeError('Invalid baseline mode');
41
+ }
42
+ if (!record.metrics || typeof record.metrics !== 'object' || Array.isArray(record.metrics) || !Object.keys(record.metrics).length) throw new TypeError('No baseline metrics');
43
+ for (const [name, metric] of Object.entries(record.metrics)) {
44
+ if (!BASELINE_METRICS.includes(name as BaselineMetric) || !metric || typeof metric !== 'object') throw new TypeError('Invalid baseline metric');
45
+ for (const value of Object.values(metric)) if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) throw new TypeError('Metrics must be finite and nonnegative');
46
+ const fields = Object.keys(metric).sort().join(',');
47
+ if (record.statistic === 'assumption-range') {
48
+ if (fields !== 'high,low') throw new TypeError('An assumption must provide a range');
49
+ assertSpan(metric as { low: number; high: number }, name);
50
+ } else if (record.statistic === 'mean') {
51
+ if (fields !== 'mean') throw new TypeError('A mean must not fabricate a range/quantiles');
52
+ } else if (record.statistic === 'sample') {
53
+ if (fields !== 'value') throw new TypeError('A sample must report its original value');
54
+ } else {
55
+ const q = metric as { p50: number; p90?: number; p95?: number };
56
+ if (!('p50' in q) || Object.keys(metric).some(field => !['p50', 'p90', 'p95'].includes(field)) || (q.p90 !== undefined && q.p90 < q.p50) || (q.p95 !== undefined && q.p95 < (q.p90 ?? q.p50))) throw new TypeError('Invalid supported quantiles');
57
+ }
58
+ }
59
+ }
60
+ }
61
+
62
+ /** Import is atomic: invalid content throws and leaves previous records untouched. */
63
+ export function importBaselines(text: string, format: 'json' | 'csv', previous: BaselineRecord[] = []): { records: BaselineRecord[]; imported: number; diagnostics: string[] } {
64
+ let incoming: BaselineRecord[];
65
+ if (format === 'json') {
66
+ const decoded = JSON.parse(text.replace(/^\uFEFF/, ''));
67
+ if (Array.isArray(decoded)) incoming = decoded;
68
+ else {
69
+ if (decoded?.schemaVersion !== 1 || !Array.isArray(decoded.records)) throw new TypeError('Unsupported baseline document');
70
+ incoming = decoded.records;
71
+ }
72
+ } else if (format === 'csv') incoming = csvBaselines(text);
73
+ else throw new TypeError('Unsupported baseline format');
74
+ validateBaselines(previous);
75
+ validateBaselines(incoming);
76
+ const merged = new Map(previous.map(record => [JSON.stringify([record.seedId, record.dataVersion]), structuredClone(record)]));
77
+ for (const record of incoming) merged.set(JSON.stringify([record.seedId, record.dataVersion]), structuredClone(record));
78
+ return { records: [...merged.values()], imported: incoming.length, diagnostics: [] };
79
+ }
80
+
81
+ export function parseCsv(text: string): string[][] {
82
+ text = text.replace(/^\uFEFF/, '');
83
+ const rows: string[][] = [];
84
+ let row: string[] = [];
85
+ let value = '';
86
+ let quoted = false;
87
+ let closedQuote = false;
88
+ for (let index = 0; index < text.length; index++) {
89
+ const character = text[index];
90
+ if (quoted) {
91
+ if (character === '"') {
92
+ if (text[index + 1] === '"') { value += '"'; index++; }
93
+ else { quoted = false; closedQuote = true; }
94
+ } else value += character;
95
+ continue;
96
+ }
97
+ if (closedQuote && ![',', '\r', '\n'].includes(character)) throw new TypeError('Unexpected content after a CSV quote');
98
+ if (character === '"') {
99
+ if (value) throw new TypeError('Unexpected quote in CSV field');
100
+ quoted = true;
101
+ } else if (character === ',') { row.push(value); value = ''; closedQuote = false; }
102
+ else if (character === '\r' || character === '\n') {
103
+ if (character === '\r' && text[index + 1] === '\n') index++;
104
+ row.push(value);
105
+ if (row.some(cell => cell.length)) rows.push(row);
106
+ row = []; value = ''; closedQuote = false;
107
+ } else value += character;
108
+ }
109
+ if (quoted) throw new TypeError('Unclosed CSV quote');
110
+ if (value || row.length || closedQuote) { row.push(value); if (row.some(cell => cell.length)) rows.push(row); }
111
+ return rows;
112
+ }
113
+
114
+ function csvBaselines(text: string): BaselineRecord[] {
115
+ const [headers, ...rows] = parseCsv(text);
116
+ if (!headers || new Set(headers).size !== headers.length) throw new TypeError('Missing/duplicate CSV headers');
117
+ const metadata = ['seedId', 'taskKind', 'date', 'sourceUrl', 'dataVersion', 'timingBasis', 'statistic', 'sampleCount', 'scope', 'sourceKind'];
118
+ const metricColumns = BASELINE_METRICS.flatMap(metric => ['low', 'high', 'mean', 'value', 'p50', 'p90', 'p95'].map(field => `${metric}.${field}`));
119
+ if (headers.some(header => !metadata.includes(header) && !ROUTE_FIELDS.includes(header as typeof ROUTE_FIELDS[number]) && !metricColumns.includes(header))) throw new TypeError('Unknown CSV column');
120
+ for (const required of metadata) if (!headers.includes(required)) throw new TypeError(`Missing CSV column: ${required}`);
121
+ return rows.map(cells => {
122
+ if (cells.length !== headers.length) throw new TypeError('CSV row width mismatch');
123
+ const fields = Object.fromEntries(headers.map((header, index) => [header, cells[index]]));
124
+ const appliesTo: Record<string, string> = {};
125
+ for (const route of ROUTE_FIELDS) if (fields[route]) appliesTo[route] = fields[route];
126
+ const metrics: Record<string, Record<string, number>> = {};
127
+ for (const column of metricColumns) {
128
+ if (fields[column] === undefined || fields[column] === '') continue;
129
+ const [metric, name] = column.split('.');
130
+ metrics[metric] ??= {};
131
+ metrics[metric][name] = Number(fields[column]);
132
+ }
133
+ return { ...Object.fromEntries(metadata.map(key => [key, fields[key]])), sourceUrl: fields.sourceUrl || null, sampleCount: fields.sampleCount === '' ? null : Number(fields.sampleCount), appliesTo, metrics } as unknown as BaselineRecord;
134
+ });
135
+ }
@@ -0,0 +1,32 @@
1
+ import type { PerformanceEstimate } from './performance.ts';
2
+ import type { RequestBudget } from './workload.ts';
3
+ import type { RouteIdentity } from './types.ts';
4
+
5
+ export interface CallSizeSample {
6
+ route: RouteIdentity;
7
+ inputTokens: number | null;
8
+ visibleOutputTokens: number | null;
9
+ cacheReadRatio: number | null;
10
+ durationMs: number;
11
+ }
12
+
13
+ /** Match token scale instead of dividing cumulative input/cache tokens by decode speed. */
14
+ export function selectCallSizePerformance(request: RequestBudget, base: PerformanceEstimate, samples: readonly CallSizeSample[], minSamples: number): PerformanceEstimate {
15
+ const route = request.route;
16
+ const similar = (value: number | null, range: { low: number; high: number } | null) => range === null
17
+ || value !== null && Number.isFinite(value) && value >= range.low / 2 && value <= Math.max(1, range.high) * 2;
18
+ const matched = samples.filter(sample => sample.route.providerId === route.providerId && sample.route.modelId === route.modelId
19
+ && sample.route.endpointFingerprint === route.endpointFingerprint && sample.route.requestMode === route.requestMode
20
+ && sample.route.reasoningEffort === route.reasoningEffort && sample.route.serviceTier === route.serviceTier
21
+ && Number.isFinite(sample.durationMs) && sample.durationMs >= 0
22
+ && similar(sample.inputTokens, request.inputTokens) && similar(sample.visibleOutputTokens, request.visibleOutputTokens)
23
+ && (request.cacheReadRatio === null || sample.cacheReadRatio !== null
24
+ && sample.cacheReadRatio >= Math.max(0, request.cacheReadRatio.low - 0.1)
25
+ && sample.cacheReadRatio <= Math.min(1, request.cacheReadRatio.high + 0.1)));
26
+ if (matched.length < minSamples) return { ...base, reasons: [...base.reasons, 'size-matched-samples-insufficient'] };
27
+ const durations = matched.map(sample => sample.durationMs).sort((a, b) => a - b);
28
+ return { ...base, totalCallMs: durations[Math.floor((durations.length - 1) / 2)]!,
29
+ totalCallSamplesMs: durations, samples: matched.length, sourceKind: 'local-measured',
30
+ metricOrigins: { ...base.metricOrigins, total: 'local-measured' },
31
+ reasons: [...base.reasons, 'size-matched-call-duration-reference'] };
32
+ }
@@ -0,0 +1,65 @@
1
+ import { alphaValue, nonnegative } from './types.ts';
2
+
3
+ export interface EstimatorConfig {
4
+ performanceAlpha: number;
5
+ workloadAlpha: number;
6
+ predictionRefreshMs: number;
7
+ timerRefreshMs: number;
8
+ historyRetentionDays: number;
9
+ profileStaleDays: number;
10
+ maxSamplesPerBucket: number;
11
+ minConditionalSamples: number;
12
+ heuristicFirstTextMs: number;
13
+ heuristicVisibleTps: number;
14
+ heuristicTotalCallMs: number;
15
+ referenceLowFactor: number;
16
+ referenceHighFactor: number;
17
+ minGenerationWindowMs: number;
18
+ maxVisibleTps: number;
19
+ toolResultTokensPerCall: { low: number; high: number };
20
+ extraPlanningCall: false;
21
+ magpieIntegration: boolean;
22
+ saveRawContent: boolean;
23
+ }
24
+
25
+ export const DEFAULT_CONFIG: Readonly<EstimatorConfig> = Object.freeze({
26
+ performanceAlpha: 0.2,
27
+ workloadAlpha: 0.2,
28
+ predictionRefreshMs: 5_000,
29
+ timerRefreshMs: 1_000,
30
+ historyRetentionDays: 90,
31
+ profileStaleDays: 7,
32
+ maxSamplesPerBucket: 200,
33
+ minConditionalSamples: 5,
34
+ heuristicFirstTextMs: 10_000,
35
+ heuristicVisibleTps: 80,
36
+ heuristicTotalCallMs: 30_000,
37
+ referenceLowFactor: 0.5,
38
+ referenceHighFactor: 2.5,
39
+ minGenerationWindowMs: 250,
40
+ maxVisibleTps: 2_000,
41
+ toolResultTokensPerCall: Object.freeze({ low: 0, high: 4_000 }),
42
+ extraPlanningCall: false,
43
+ magpieIntegration: false,
44
+ saveRawContent: false,
45
+ });
46
+
47
+ /** Rejects invalid saved values; returns a fresh, fully populated configuration. */
48
+ export function validateConfig(input: Partial<EstimatorConfig> = {}): EstimatorConfig {
49
+ for (const key of Object.keys(input)) {
50
+ if (!(key in DEFAULT_CONFIG)) throw new TypeError(`Unknown configuration field: ${key}`);
51
+ }
52
+ const config = { ...DEFAULT_CONFIG, ...input, toolResultTokensPerCall: { ...DEFAULT_CONFIG.toolResultTokensPerCall, ...input.toolResultTokensPerCall } };
53
+ alphaValue(config.performanceAlpha);
54
+ alphaValue(config.workloadAlpha);
55
+ const positive = ['predictionRefreshMs', 'timerRefreshMs', 'historyRetentionDays', 'profileStaleDays', 'maxSamplesPerBucket', 'minConditionalSamples', 'heuristicVisibleTps', 'referenceHighFactor', 'maxVisibleTps'] as const;
56
+ for (const key of positive) if (nonnegative(config[key], key) === 0) throw new TypeError(`${key} must be positive`);
57
+ for (const key of ['heuristicFirstTextMs', 'heuristicTotalCallMs', 'referenceLowFactor', 'minGenerationWindowMs'] as const) nonnegative(config[key], key);
58
+ for (const key of ['maxSamplesPerBucket', 'minConditionalSamples'] as const) if (!Number.isSafeInteger(config[key])) throw new TypeError(`${key} must be an integer`);
59
+ if (config.referenceLowFactor > 1 || config.referenceHighFactor < 1 || config.referenceLowFactor > config.referenceHighFactor) throw new TypeError('Reference factors must bracket 1');
60
+ const range = config.toolResultTokensPerCall;
61
+ if (!range || !Number.isSafeInteger(range.low) || !Number.isSafeInteger(range.high) || range.low < 0 || range.low > range.high) throw new TypeError('Invalid tool result Token range');
62
+ if (config.extraPlanningCall !== false) throw new TypeError('P0 does not make additional planning calls');
63
+ if (typeof config.magpieIntegration !== 'boolean' || typeof config.saveRawContent !== 'boolean') throw new TypeError('Expected boolean configuration');
64
+ return config;
65
+ }