@mupt-ai/dari-gateway 0.1.0 → 0.2.1

package/dist/telemetry/billing_finalization.d.ts

@@ -0,0 +1,64 @@
+import type { InteractionUsage } from "../interaction/types.js";
+import type { ProviderKeySource } from "../types.js";
+export type RoutingBillingTerminalOutcome = "completed" | "customer_canceled" | "provider_failed" | "selection";
+export type RoutingBillingProviderAttemptFacts = {
+    provider: string;
+    model: string;
+    provider_key_source: ProviderKeySource;
+    role: "primary" | "fallback";
+    attempt: number;
+    outcome: "completed" | "provider_failed" | "customer_canceled";
+    provider_request_id: string | null;
+    provider_input_tokens: number | null;
+    provider_cache_read_tokens: number | null;
+    provider_cache_write_tokens: number | null;
+    provider_output_tokens: number | null;
+    provider_input_cost_usd: string | null;
+    provider_cache_read_cost_usd: string | null;
+    provider_cache_write_cost_usd: string | null;
+    provider_output_cost_usd: string | null;
+    provider_cost_usd: string | null;
+    provider_pricing_known: boolean;
+    usage_estimated: boolean;
+};
+export type RoutingBillingFinalizationPayload = {
+    request_id: string;
+    organization_id: string;
+    event_schema_version: 1;
+    provider_attempts: RoutingBillingProviderAttemptFacts[];
+    benchmark_replay_cost_usd: string | null;
+    benchmark_pricing_known: boolean;
+    terminal_outcome: RoutingBillingTerminalOutcome;
+    finalized_at: string;
+};
+export type FrozenRoutingBillingTerminal = {
+    readPayload(): RoutingBillingFinalizationPayload;
+};
+type BillingFinalizationIdentity = {
+    requestId: string;
+    organizationId: string;
+};
+/**
+ * One request-scoped terminal register. The first terminal facts and timestamp
+ * win; every later response hook, catch, or duplicate provider terminal event
+ * observes the same serialized bytes, which the routing report carries as the
+ * request's billing facts.
+ */
+export declare class RoutingBillingFinalization {
+    private readonly identity;
+    private terminal;
+    constructor(identity: BillingFinalizationIdentity);
+    freeze(terminalOutcome: RoutingBillingTerminalOutcome, providerAttempts: readonly RoutingBillingProviderAttemptFacts[], benchmarkReplayCostUsd: number | null): FrozenRoutingBillingTerminal;
+}
+export declare function routingBillingProviderAttemptFacts(args: {
+    provider: string;
+    model: string;
+    providerKeySource: ProviderKeySource;
+    role: "primary" | "fallback";
+    attempt: number;
+    outcome: "completed" | "provider_failed" | "customer_canceled";
+    providerMessage: Record<string, unknown> | null;
+    usage: InteractionUsage | Record<string, unknown> | null;
+    providerPricingKnown: boolean;
+}): RoutingBillingProviderAttemptFacts;
+export {};

package/dist/telemetry/billing_finalization.js

@@ -0,0 +1,96 @@
+import { finiteNumber, isRecord, tokenCount } from "./ingest_values.js";
+const BILLING_EVENT_SCHEMA_VERSION = 1;
+/**
+ * One request-scoped terminal register. The first terminal facts and timestamp
+ * win; every later response hook, catch, or duplicate provider terminal event
+ * observes the same serialized bytes, which the routing report carries as the
+ * request's billing facts.
+ */
+export class RoutingBillingFinalization {
+    identity;
+    terminal = null;
+    constructor(identity) {
+        this.identity = identity;
+    }
+    freeze(terminalOutcome, providerAttempts, benchmarkReplayCostUsd) {
+        if (this.terminal !== null)
+            return this.terminal;
+        const finalizedAt = new Date().toISOString();
+        const benchmarkCost = nonnegativeMoney(benchmarkReplayCostUsd);
+        const payload = {
+            request_id: this.identity.requestId,
+            organization_id: this.identity.organizationId,
+            event_schema_version: BILLING_EVENT_SCHEMA_VERSION,
+            provider_attempts: [...providerAttempts],
+            benchmark_replay_cost_usd: benchmarkCost,
+            benchmark_pricing_known: benchmarkCost !== null,
+            terminal_outcome: terminalOutcome,
+            finalized_at: finalizedAt,
+        };
+        const serializedPayload = JSON.stringify(payload);
+        const terminal = {
+            readPayload: () => JSON.parse(serializedPayload),
+        };
+        this.terminal = terminal;
+        return terminal;
+    }
+}
+export function routingBillingProviderAttemptFacts(args) {
+    const usage = args.usage;
+    const cost = usage !== null && isRecord(usage.cost) ? usage.cost : null;
+    const inputCost = cost === null ? null : nonnegativeMoney(cost.input);
+    const cacheReadCost = cost === null ? null : nonnegativeMoney(cost.cacheRead);
+    const cacheWriteCost = cost === null ? null : nonnegativeMoney(cost.cacheWrite);
+    const outputCost = cost === null ? null : nonnegativeMoney(cost.output);
+    const totalCost = cost === null ? null : nonnegativeMoney(cost.total);
+    const providerPricingKnown = args.providerPricingKnown &&
+        inputCost !== null &&
+        cacheReadCost !== null &&
+        cacheWriteCost !== null &&
+        outputCost !== null &&
+        totalCost !== null;
+    const costs = providerPricingKnown
+        ? {
+            input: inputCost,
+            cacheRead: cacheReadCost,
+            cacheWrite: cacheWriteCost,
+            output: outputCost,
+            total: totalCost,
+        }
+        : null;
+    return {
+        provider: args.provider,
+        model: args.model,
+        provider_key_source: args.providerKeySource,
+        role: args.role,
+        attempt: args.attempt,
+        outcome: args.outcome,
+        provider_request_id: providerRequestId(args.providerMessage),
+        provider_input_tokens: nonnegativeTokenCount(usage?.input),
+        provider_cache_read_tokens: nonnegativeTokenCount(usage?.cacheRead),
+        provider_cache_write_tokens: nonnegativeTokenCount(usage?.cacheWrite),
+        provider_output_tokens: nonnegativeTokenCount(usage?.output),
+        provider_input_cost_usd: costs?.input ?? null,
+        provider_cache_read_cost_usd: costs?.cacheRead ?? null,
+        provider_cache_write_cost_usd: costs?.cacheWrite ?? null,
+        provider_output_cost_usd: costs?.output ?? null,
+        provider_cost_usd: costs?.total ?? null,
+        provider_pricing_known: providerPricingKnown,
+        usage_estimated: usage !== null && usage.estimated === true,
+    };
+}
+function providerRequestId(message) {
+    return message !== null &&
+        typeof message.responseId === "string" &&
+        message.responseId.length > 0
+        ? message.responseId
+        : null;
+}
+function nonnegativeMoney(value) {
+    const number = finiteNumber(value);
+    return number === null || number < 0 ? null : String(number);
+}
+function nonnegativeTokenCount(value) {
+    const count = tokenCount(value);
+    return count === null || count < 0 ? null : count;
+}

package/dist/telemetry/ingest_values.d.ts

@@ -0,0 +1,4 @@
+export declare function tokenCount(value: unknown): number | null;
+export declare function finiteNumber(value: unknown): number | null;
+export declare function costString(value: unknown): string | null;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/telemetry/ingest_values.js

@@ -0,0 +1,12 @@
+export function tokenCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : null;
+}
+export function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+export function costString(value) {
+    return typeof value === "number" && Number.isFinite(value) ? String(value) : null;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/telemetry/model_cost.d.ts

@@ -0,0 +1,3 @@
+import type { RoutingBillingProviderAttemptFacts } from "./billing_finalization.js";
+/** Model reference cost only, including retries; unknown/estimated usage is never free. */
+export declare function modelCost(attempts: readonly RoutingBillingProviderAttemptFacts[]): number | null;

package/dist/telemetry/model_cost.js

@@ -0,0 +1,15 @@
+/** Model reference cost only, including retries; unknown/estimated usage is never free. */
+export function modelCost(attempts) {
+    if (attempts.length === 0)
+        return null;
+    let total = 0;
+    for (const attempt of attempts) {
+        if (!attempt.provider_pricing_known || attempt.usage_estimated || attempt.provider_cost_usd === null)
+            return null;
+        const cost = Number(attempt.provider_cost_usd);
+        if (!Number.isFinite(cost) || cost < 0)
+            return null;
+        total += cost;
+    }
+    return Number.isFinite(total) ? total : null;
+}

package/dist/telemetry/prefix_state.d.ts

@@ -0,0 +1,47 @@
+import { type ReasoningEffort, type RouterPrefixHit, type RoutingDecision } from "@mupt-ai/dari-router/policy-engine";
+import type { InteractionOutput, InteractionRequest, InteractionUsage, ProviderIdentity } from "../interaction/types.js";
+import { type PrefixStateWrite } from "../platform/platform.js";
+export type CompletedPrefixHit = Omit<RouterPrefixHit, "updated_at"> & {
+    lease_depth: number;
+};
+export declare function buildCompletedPrefixHit(args: {
+    request: InteractionRequest;
+    output: InteractionOutput;
+    model: string;
+    nextModel: string | null;
+    nextReasoningEffort: ReasoningEffort | null;
+    reasoningBucket: ReasoningEffort | null;
+    leaseTurnsRemaining: number | null;
+    reason: string | null;
+    chain: string[];
+    looseChain: readonly string[];
+    target: ProviderIdentity;
+    conversationId: string;
+    leaseDepth: number;
+    providerBlockDepth: number;
+    fingerprints: {
+        tool_choice_fp: string;
+        response_format_fp: string;
+    };
+    usage: InteractionUsage;
+    benchmarkReplayDepth: number;
+}): CompletedPrefixHit | null;
+export declare function leaseCountdownForPrefix(args: {
+    served: RoutingDecision | null;
+    next: RoutingDecision | null;
+    fallbackServed?: boolean;
+}): number | null;
+export declare function reportPendingLease(args: {
+    routerId: string;
+    conversationId: string;
+    decidedAtDepth: number;
+    lease: {
+        model: string;
+        reasoningEffort: string;
+        turns: number;
+        reason: string;
+        outputText: string | null;
+    } | null;
+}): Promise<void>;
+export declare function prefixEntryForIngest(hit: CompletedPrefixHit): Record<string, unknown>;
+export declare function reportPrefixState(write: PrefixStateWrite): Promise<void>;

package/dist/telemetry/prefix_state.js

@@ -0,0 +1,116 @@
+import { extendInteractionChain, extendInteractionLooseChain, } from "../context/interaction_fingerprint.js";
+import { gatewayPlatform } from "../platform/platform.js";
+import { tokenCount } from "./ingest_values.js";
+export function buildCompletedPrefixHit(args) {
+    if (args.chain.length === 0)
+        return null;
+    const outputExtension = extendOutputPrefix({
+        request: args.request,
+        output: args.output,
+        chain: args.chain,
+        target: args.target,
+    });
+    const hash = outputExtension.at(-1);
+    if (hash === undefined)
+        return null;
+    const inputTokens = tokenCount(args.usage?.input) ?? 0;
+    const cacheReadTokens = tokenCount(args.usage?.cacheRead) ?? 0;
+    const cacheWriteTokens = tokenCount(args.usage?.cacheWrite) ?? 0;
+    return {
+        hash,
+        loose_hash: looseOutputHash(args.looseChain, args.output, args.request.sourceProtocol),
+        conversation_id: args.conversationId,
+        model: args.model,
+        provider: args.target.provider,
+        next_model: args.nextModel,
+        next_reasoning_effort: args.nextReasoningEffort,
+        message_depth: args.chain.length + outputExtension.length,
+        lease_depth: args.leaseDepth,
+        provider_block_depth: args.providerBlockDepth,
+        prompt_anchor_depth: args.chain.length,
+        input_tokens: inputTokens,
+        cache_read_tokens: cacheReadTokens,
+        cache_write_tokens: cacheWriteTokens,
+        prompt_tokens: inputTokens + cacheReadTokens + cacheWriteTokens,
+        benchmark_replay_depth: args.benchmarkReplayDepth,
+        tool_choice_fp: args.fingerprints.tool_choice_fp,
+        response_format_fp: args.fingerprints.response_format_fp,
+        reasoning_bucket: args.reasoningBucket,
+        lease_turns_remaining: args.leaseTurnsRemaining,
+        reason: args.reason,
+    };
+}
+export function leaseCountdownForPrefix(args) {
+    const granted = args.fallbackServed === true ? args.served : args.next ?? args.served;
+    const remaining = granted?.leaseTurnsRemaining;
+    if (remaining === undefined || remaining === null)
+        return null;
+    if (args.fallbackServed === true)
+        return remaining;
+    const servedGrantedPair = args.next === null ||
+        (args.served !== null &&
+            args.served.selectedModel === args.next.selectedModel &&
+            args.served.reasoningEffort === args.next.reasoningEffort);
+    return servedGrantedPair ? remaining : remaining + 1;
+}
+export async function reportPendingLease(args) {
+    try {
+        await gatewayPlatform().writePendingLease({
+            router_id: args.routerId,
+            conversation_id: args.conversationId,
+            decided_at_depth: args.decidedAtDepth,
+            pending_lease: args.lease === null
+                ? null
+                : {
+                    model: args.lease.model,
+                    reasoning_effort: args.lease.reasoningEffort,
+                    turns: args.lease.turns,
+                    reason: args.lease.reason,
+                    output_text: args.lease.outputText,
+                },
+        });
+    }
+    catch (error) {
+        console.error("pending-lease write failed", error);
+    }
+}
+export function prefixEntryForIngest(hit) {
+    const { hash, loose_hash, ...entry } = hit;
+    return { prefix_hash: hash, loose_prefix_hash: loose_hash ?? null, ...entry };
+}
+// Loose-tier hash for the entry: the request's loose chain extended with the
+// reply. Best-effort — a null loose hash only forfeits echo-mutation
+// tolerance for this one turn, never the entry itself.
+function looseOutputHash(looseChain, output, sourceProtocol) {
+    const lastHash = looseChain[looseChain.length - 1];
+    if (lastHash === undefined)
+        return null;
+    try {
+        return extendInteractionLooseChain(lastHash, output, sourceProtocol).at(-1) ?? null;
+    }
+    catch (error) {
+        console.error("loose prefix extension failed", error);
+        return null;
+    }
+}
+function extendOutputPrefix(args) {
+    const lastHash = args.chain[args.chain.length - 1];
+    return extendInteractionChain(lastHash, args.output, args.target, {
+        includeItemIds: carriesItemIds(args.request),
+        sourceProtocol: args.request.sourceProtocol,
+    });
+}
+// Codex strips provider-returned item ids from stateless HTTP requests unless
+// its ItemIds feature is active. Existing input ids are the only request-side
+// evidence that newly returned ids will be carried into the next turn.
+function carriesItemIds(request) {
+    return request.items.some((item) => "id" in item && typeof item.id === "string" && item.id.length > 0);
+}
+export async function reportPrefixState(write) {
+    try {
+        await gatewayPlatform().writePrefixState(write);
+    }
+    catch (error) {
+        console.error("routing prefix-state write failed", error);
+    }
+}

package/dist/telemetry/report.d.ts

@@ -0,0 +1,88 @@
+import { type CandidateCostEstimate, type CandidatePruningAudit, type ChainHits, type PrefixHit, type PricingLookup, type RoutingDecision, type RoutingStrategy } from "@mupt-ai/dari-router/policy-engine";
+import type { ImageCapabilityPrunedModel } from "../context/routing_context.js";
+import { type InteractionRequest, type ProviderIdentity } from "../interaction/types.js";
+import { type RequestTags } from "../platform/platform.js";
+import type { ProviderAttemptRecord, FrozenProviderTerminal, ReportableProviderOutcome } from "../runtime/runtime_reporter.js";
+import { type SelectorRun } from "../strategies/routing.js";
+import type { ResolvedRouter } from "../types.js";
+import type { HarnessConversationIdentity } from "../runtime/harness_identity/index.js";
+import { type RoutingBillingFinalization } from "./billing_finalization.js";
+export type ReportedCandidatePruning = (CandidatePruningAudit & {
+    capability_pruned_models?: ImageCapabilityPrunedModel[];
+}) | {
+    capability_pruned_models: ImageCapabilityPrunedModel[];
+};
+export declare class RequestReporter {
+    private readonly args;
+    private selectorRun;
+    private selectorTrace;
+    private adoptedSelectorOutput;
+    private selectorOutputAccepted;
+    private decision;
+    private nextDecision;
+    private fallbackDecision;
+    private providerAttempts;
+    private billingProviderAttempts;
+    private decisionDetails;
+    private reported;
+    private terminal;
+    private prefixStatePromise;
+    constructor(args: {
+        requestId: string;
+        clientRequestId: string | null;
+        tags: RequestTags;
+        credentials: ResolvedRouter;
+        routerId: string;
+        interaction: InteractionRequest;
+        harnessConversationIdentity?: HarnessConversationIdentity;
+        leaseDepth: number;
+        providerBlockDepthFor: (model: string) => number;
+        zdr: boolean;
+        strategy: RoutingStrategy;
+        receivedAt: Date;
+        startedMs: number;
+        conversationId: string;
+        isNewConversation: boolean;
+        agentSessionId?: string;
+        identityMatchDepth: number | null;
+        identityHit?: PrefixHit;
+        hits: ChainHits;
+        costEstimates: CandidateCostEstimate[];
+        pruning: ReportedCandidatePruning | null;
+        pricing: PricingLookup | null;
+        chainByModel: ReadonlyMap<string, string[]>;
+        looseChain: readonly string[];
+        targetsByModel: ReadonlyMap<string, ProviderIdentity>;
+        fingerprints: {
+            tool_choice_fp: string;
+            response_format_fp: string;
+        };
+        billingFinalization: RoutingBillingFinalization;
+    });
+    attachSelectorRun(run: SelectorRun): void;
+    attachSpeculativeSelectorRun(run: SelectorRun, servingDecision: RoutingDecision): void;
+    attachDecision(decision: RoutingDecision): void;
+    attachFallbackDecision(decision: RoutingDecision | undefined): void;
+    attachServingDecision(decision: RoutingDecision): void;
+    recordProviderAttempt(attempt: ProviderAttemptRecord): void;
+    modelCost(attempt?: ProviderAttemptRecord): number | null;
+    private billingFacts;
+    attachAdoptedSelectorOutput(adopted: {
+        outputText: string | null;
+        reason: string;
+        candidates: readonly {
+            model: string;
+            reasoningEffort: string;
+        }[];
+    }): void;
+    attachDecisionDetails(details: Record<string, unknown>): void;
+    waitForPrefixEntryWrite(): Promise<void>;
+    freezeProviderTerminal(args: ReportableProviderOutcome): FrozenProviderTerminal;
+    reportSelectorFailure(error: unknown): void;
+    freezeFailure(error: unknown): FrozenProviderTerminal;
+    private attachFailedSelectorTrace;
+    private pricingKnown;
+    private freezeTerminal;
+    private registerBilling;
+    private send;
+}