@aexhq/sdk 0.13.6

package/dist/_contracts/run-cost.d.ts

@@ -0,0 +1,125 @@
+import type { CredentialMode } from "./managed-key.js";
+import type { RunProvider, RuntimeKind } from "./submission.js";
+export declare const RUN_COST_TELEMETRY_SCHEMA_VERSION = 1;
+export declare const RUN_USAGE_SAMPLE_SCHEMA_VERSION = 1;
+export declare const RUN_COST_SUMMARY_STATUSES: readonly ["pending", "partial", "complete", "unavailable", "not_applicable"];
+export type RunCostSummaryStatus = (typeof RUN_COST_SUMMARY_STATUSES)[number];
+export declare const RUN_USAGE_SAMPLE_UNITS: readonly ["token", "millisecond", "byte", "byte_millisecond", "count", "file", "credit_unit"];
+export type RunUsageSampleUnit = (typeof RUN_USAGE_SAMPLE_UNITS)[number];
+export declare const RUN_USAGE_SAMPLE_SOURCE_TYPES: readonly ["coordinator-event", "run-event", "usage-ledger", "output-object", "proxy-call", "runtime-job", "provider-session", "storage-accrual", "billing-reservation", "billing-settlement", "billing-release", "manual-adjustment"];
+export type RunUsageSampleSourceType = (typeof RUN_USAGE_SAMPLE_SOURCE_TYPES)[number];
+export declare const RUN_USAGE_SAMPLE_METRICS: readonly ["provider.input_tokens", "provider.output_tokens", "provider.cache_read_input_tokens", "provider.cache_creation_input_tokens", "provider.total_tokens", "runtime.queued_ms", "runtime.active_ms", "runtime.output_capture_ms", "runtime.cleanup_ms", "run.total_ms", "output.discovered_files", "output.captured_files", "output.failed_files", "output.captured_bytes", "retry.runtime_attempts", "retry.provider_poll", "retry.output_capture", "retry.output_upload", "capture.uploaded_files", "capture.failed_files", "capture.total_bytes", "storage.current_bytes", "storage.byte_milliseconds", "proxy.call_count", "proxy.failed_call_count", "proxy.request_bytes", "proxy.response_bytes", "proxy.duration_ms", "managed_key.reserved_credit_units", "managed_key.charged_credit_units", "managed_key.released_credit_units"];
+export type RunUsageSampleMetric = (typeof RUN_USAGE_SAMPLE_METRICS)[number];
+export interface RunUsageSampleSource {
+    readonly type: RunUsageSampleSourceType;
+    readonly id: string;
+    readonly observedAt?: string;
+}
+export interface RunUsageSample {
+    readonly schemaVersion: typeof RUN_USAGE_SAMPLE_SCHEMA_VERSION;
+    readonly sampleId?: string;
+    readonly runId?: string;
+    readonly metric: RunUsageSampleMetric;
+    readonly unit: RunUsageSampleUnit;
+    readonly quantity: number;
+    readonly source: RunUsageSampleSource;
+    readonly provider?: RunProvider | string;
+    readonly runtime?: RuntimeKind | string;
+    readonly model?: string;
+    readonly credentialMode?: CredentialMode;
+    readonly recordedAt?: string;
+}
+export type RunUsageSampleInput = Omit<RunUsageSample, "schemaVersion" | "unit"> & {
+    readonly unit?: RunUsageSampleUnit;
+};
+export interface RunCostSourceSummary {
+    readonly sampleCount: number;
+    readonly metrics?: readonly RunUsageSampleMetric[];
+    readonly sourceTypes?: readonly RunUsageSampleSourceType[];
+    readonly sourceSampleIds?: readonly string[];
+}
+export interface RunCostDurations {
+    readonly queuedMs?: number;
+    readonly runtimeMs?: number;
+    readonly outputCaptureMs?: number;
+    readonly cleanupMs?: number;
+    readonly totalMs?: number;
+}
+export interface RunCostOutputTelemetry {
+    readonly discoveredFiles?: number;
+    readonly capturedFiles?: number;
+    readonly failedFiles?: number;
+    readonly capturedBytes?: number;
+}
+export interface RunCostRetryTelemetry {
+    readonly runtimeAttempts?: number;
+    readonly providerPollRetries?: number;
+    readonly outputCaptureRetries?: number;
+    readonly outputUploadRetries?: number;
+}
+export interface RunCostCaptureTelemetry {
+    readonly attempted: boolean;
+    readonly uploadedFiles?: number;
+    readonly failedFiles?: number;
+    readonly totalBytes?: number;
+    readonly failureReasons?: readonly string[];
+}
+export interface RunCostProviderUsage {
+    readonly provider: RunProvider | string;
+    readonly model?: string;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadInputTokens?: number;
+    readonly cacheCreationInputTokens?: number;
+    readonly totalTokens?: number;
+    readonly sourceEventId?: string;
+    readonly sourceSampleIds?: readonly string[];
+}
+export interface RunCostStorageTelemetry {
+    readonly storedBytes?: number;
+    readonly byteMilliseconds?: number;
+}
+export interface RunCostProxyTelemetry {
+    readonly calls?: number;
+    readonly failedCalls?: number;
+    readonly requestBytes?: number;
+    readonly responseBytes?: number;
+    readonly durationMs?: number;
+}
+export interface RunCostManagedKeyBudgetTelemetry {
+    readonly credentialMode?: CredentialMode;
+    readonly reservedCreditUnits?: number;
+    readonly chargedCreditUnits?: number;
+    readonly releasedCreditUnits?: number;
+}
+export interface RunCostTelemetry {
+    readonly schemaVersion: typeof RUN_COST_TELEMETRY_SCHEMA_VERSION;
+    readonly runId?: string;
+    readonly provider?: RunProvider | string;
+    readonly runtime?: RuntimeKind | string;
+    readonly recordedAt?: string;
+    readonly status?: RunCostSummaryStatus;
+    readonly sourceSummary?: RunCostSourceSummary;
+    readonly durations?: RunCostDurations;
+    readonly outputs?: RunCostOutputTelemetry;
+    readonly retries?: RunCostRetryTelemetry;
+    readonly capture?: RunCostCaptureTelemetry;
+    readonly providerUsage?: readonly RunCostProviderUsage[];
+    readonly storage?: RunCostStorageTelemetry;
+    readonly proxy?: RunCostProxyTelemetry;
+    readonly managedKey?: RunCostManagedKeyBudgetTelemetry;
+}
+export type RunCostTelemetryInput = Omit<RunCostTelemetry, "schemaVersion">;
+export interface RunCostTelemetryFromUsageSamplesInput {
+    readonly runId?: string;
+    readonly provider?: RunProvider | string;
+    readonly runtime?: RuntimeKind | string;
+    readonly recordedAt?: string;
+    readonly status?: RunCostSummaryStatus;
+    readonly samples: readonly RunUsageSampleInput[];
+}
+export declare function buildRunUsageSample(input: RunUsageSampleInput): RunUsageSample;
+export declare function buildRunCostTelemetry(input: RunCostTelemetryInput): RunCostTelemetry;
+export declare function buildRunCostTelemetryFromUsageSamples(input: RunCostTelemetryFromUsageSamplesInput): RunCostTelemetry;
+export declare function summarizeUsageSamples(samples: readonly RunUsageSampleInput[]): RunCostSourceSummary;
+export declare function mergeRunCostTelemetry(base: RunCostTelemetry, next: RunCostTelemetryInput): RunCostTelemetry;