@treeseed/sdk 0.12.62 → 0.13.0-rc.10

package/dist/capacity.d.ts

@@ -1,483 +0,0 @@
-import type { AttentionEstimate, AttentionPolicy, CapacityEstimateConfidence, CapacityGrant, CapacityPlan, CapacityProvider, CapacityProviderLane, CapacityReservation, CreditConversionProfile, CreateCapacityReservationRequest, CreateCapacityRoutingDecisionRequest, DerivedCapacityAvailability, DerivedCapacityInput, ExecutionProfile, HybridExecutionPlan, NativeUsageObservation, PlannedTaskNode, PlanningAdmissionResult, PlanningPolicy, PredictiveReservePolicy, ProjectEnvironmentName, RecordCapacityUsageRequest, ReservePrediction, TaskAdmissionDecision, TaskAdmissionPolicy, TaskClassification, TaskEstimateProfile, TaskPlanProposal, TaskMutationScope, TaskUsageActual, UtilityEstimate, UtilityPolicy, WorkdayBudgetEnvelope } from './sdk-types.js';
-import type { AgentProviderProfile } from './types/agents.js';
-export declare const ACTUAL_CREDIT_FORMULA_VERSION = "treeseed.actual-credits.v1";
-export interface ActualCreditCalculationInput {
-    nativeUsage?: NativeUsageObservation | Record<string, unknown> | null;
-    conversionProfile?: CreditConversionProfile | null;
-    legacyActualCredits?: number | null;
-    actualCreditsOverride?: boolean | null;
-    reservedCredits?: number | null;
-    actualUsd?: number | null;
-    inputTokens?: number | null;
-    outputTokens?: number | null;
-    cachedInputTokens?: number | null;
-    quotaMinutes?: number | null;
-    wallMinutes?: number | null;
-    filesOpened?: number | null;
-    filesChanged?: number | null;
-    diffLinesAdded?: number | null;
-    diffLinesRemoved?: number | null;
-    testRuns?: number | null;
-    retryCount?: number | null;
-    source?: string | null;
-}
-export interface ActualCreditCalculation {
-    actualCredits: number;
-    formulaVersion: string;
-    source: 'central_calculator' | 'conversion_profile' | 'blended_conversion_profile' | 'legacy_override' | 'legacy_fallback' | 'reserved_fallback' | 'zero_fallback';
-    nativeUsage: NativeUsageObservation;
-    components: Record<string, number>;
-    partial: boolean;
-    interrupted: boolean;
-    conversionProfileId?: string | null;
-    conversionConfidence?: string | null;
-}
-export declare function nativeUsageUnit(input: NativeUsageObservation | Record<string, unknown> | null | undefined): string | null;
-export declare function nativeUsageAmount(input: NativeUsageObservation | Record<string, unknown> | null | undefined, nativeUnit?: string | null): number | null;
-export declare function selectCreditConversionProfile(input: {
-    profiles?: CreditConversionProfile[] | null;
-    taskSignature?: string | null;
-    executionProfileId?: string | null;
-    executionProviderKind?: string | null;
-    nativeUnit?: string | null;
-}): CreditConversionProfile | null;
-export declare function buildCreditConversionProfileFromActuals(input: {
-    taskSignature: string;
-    executionProfileId?: string | null;
-    executionProviderKind: string;
-    nativeUnit: string;
-    actuals: TaskUsageActual[];
-    formulaVersion?: string | null;
-    now?: Date | string | null;
-    id?: string | null;
-}): CreditConversionProfile;
-export declare function deriveAvailableCredits(input: DerivedCapacityInput): DerivedCapacityAvailability;
-export declare function calculateActualCredits(input: ActualCreditCalculationInput): ActualCreditCalculation;
-export interface CapacityEstimateInput {
-    taskSignature?: string | null;
-    taskKind?: string | null;
-    confidence?: CapacityEstimateConfidence | null;
-    estimatedCreditsP50?: number | null;
-    estimatedCreditsP90?: number | null;
-    profile?: TaskEstimateProfile | null;
-    profiles?: TaskEstimateProfile[] | null;
-    defaultCredits?: number | null;
-    executionProfile?: ExecutionProfile | null;
-    executionProfileId?: string | null;
-    costMultiplier?: number | null;
-}
-export interface CapacityLaneCandidate {
-    lane: CapacityProviderLane;
-    grant?: CapacityGrant | null;
-    remainingCredits?: number | null;
-    agentProfile?: AgentProviderProfile | null;
-    taskKind?: string | null;
-    requiredCapabilities?: string[];
-    modelClass?: string | null;
-    region?: string | null;
-}
-export interface CapacityLaneScore {
-    laneId: string;
-    capacityProviderId: string;
-    score: number;
-    agentFit: number;
-    scarcityPenalty: number;
-    fairnessScore: number;
-    costPenalty: number;
-    qualityFit?: number;
-    latencyPenalty?: number;
-    quotaPressure?: number;
-    congestionPenalty?: number;
-    attentionPenalty?: number;
-    contextPenalty?: number;
-    nativePressurePenalty?: number;
-    utilityScore?: number;
-    utilityPerCredit?: number;
-    predictedReserveImpact?: number;
-    trustScore?: number | null;
-    successProbability?: number | null;
-    executionProfileId?: string | null;
-    reservedCredits?: number | null;
-    attentionEstimate?: AttentionEstimate | null;
-    utilityEstimate?: UtilityEstimate | null;
-    reservePrediction?: ReservePrediction | null;
-    spilloverReason?: string | null;
-    trustScore?: number | null;
-    successProbability?: number | null;
-    reasons: string[];
-}
-export interface CapacityTaskEstimate {
-    taskSignature: string;
-    confidence: CapacityEstimateConfidence;
-    estimatedCreditsP50: number;
-    estimatedCreditsP90: number;
-    reservedCredits: number;
-    baseReservedCredits?: number;
-    executionProfileId?: string | null;
-    costMultiplier?: number | null;
-}
-export interface AdmissionEstimateInput extends CapacityEstimateInput {
-    classification?: TaskClassification | null;
-}
-export interface WorkdayBudgetEnvelopeInput {
-    dailyCreditBudget: number;
-    usedCredits?: number | null;
-    queuedCredits?: number | null;
-    reserveBufferPercent?: number | null;
-    recoveryBudgetCredits?: number | null;
-}
-export interface TaskAdmissionInput {
-    classification: TaskClassification;
-    estimate: CapacityTaskEstimate;
-    budget: WorkdayBudgetEnvelopeInput;
-    policy?: Partial<TaskAdmissionPolicy> | null;
-    source?: string | null;
-    metadata?: Record<string, unknown>;
-}
-export interface CapacityInterruptionInput {
-    reservedCredits?: number | null;
-    consumedCredits?: number | null;
-    estimatedRemainingCreditsP50?: number | null;
-    estimatedRemainingCreditsP90?: number | null;
-    reservationUsedPercentThreshold?: number | null;
-    recoveryBudgetRemainingCredits?: number | null;
-    recoveryBudgetMinimumCredits?: number | null;
-    providerAvailable?: boolean | null;
-}
-export interface TeamCapacitySummary {
-    teamId: string;
-    monthlyCredits: number | null;
-    monthlyUsedCredits: number;
-    monthlyRemainingCredits: number | null;
-    dailyCredits: number | null;
-    dailyUsedCredits: number;
-    dailyReservedCredits: number;
-    dailyRemainingCredits: number | null;
-    providerCount: number;
-    activeProviderCount: number;
-    degradedProviderCount: number;
-    grantCount: number;
-    blockedTaskCount: number;
-    approvalRequiredCount: number;
-}
-export interface ProjectCapacitySummary extends TeamCapacitySummary {
-    projectId: string;
-    environment: ProjectEnvironmentName | 'local';
-    readiness: 'ready' | 'waiting_for_budget' | 'waiting_for_provider' | 'paused_by_policy' | 'needs_approval';
-    reasons: string[];
-}
-export interface RouteAndReserveInput {
-    plan: CapacityPlan;
-    estimate: CapacityTaskEstimate;
-    classification?: TaskClassification | null;
-    taskId?: string | null;
-    workDayId?: string | null;
-    taskKind?: string | null;
-    requiredCapabilities?: string[];
-    modelClass?: string | null;
-    priorityClass?: string | null;
-    allowDegradedProviders?: boolean;
-    repositoryMutation?: boolean;
-    production?: boolean;
-    selectedModel?: string | null;
-    executionProfile?: ExecutionProfile | string | null;
-    executionProfiles?: Array<ExecutionProfile | string> | null;
-    estimateProfiles?: TaskEstimateProfile[] | null;
-    minimumQualityWeight?: number | null;
-    requiredContextTokens?: number | null;
-    estimatedContextTokens?: number | null;
-    attentionWeight?: number | null;
-    coordinationWeight?: number | null;
-    minimumAttentionAvailable?: number | null;
-    attentionPolicy?: Partial<AttentionPolicy> | null;
-    attentionEstimate?: AttentionEstimate | null;
-    utilityPolicy?: Partial<UtilityPolicy> | null;
-    utilityEstimate?: UtilityEstimate | null;
-    utilityValue?: number | null;
-    maintenanceValue?: number | null;
-    deadlineAt?: string | null;
-    successProbability?: number | null;
-    trustRequirement?: number | null;
-    cooperativeRouting?: boolean | null;
-    predictiveReservePolicy?: Partial<PredictiveReservePolicy> | null;
-    hybridExecutionPlan?: HybridExecutionPlan | Record<string, unknown> | null;
-    preferredExecutionProfiles?: string[] | null;
-    disallowedExecutionProfiles?: string[] | null;
-    source?: string;
-    metadata?: Record<string, unknown>;
-}
-export type RouteAndReserveBlockCode = 'no_capacity_provider' | 'no_capacity_grant' | 'no_eligible_lane' | 'insufficient_budget' | 'approval_required';
-export interface RouteAndReserveCandidate {
-    providerId: string;
-    laneId: string;
-    grantId: string;
-    executionProviderId?: string | null;
-    executionProfileId?: string | null;
-    nativeUnit?: string | null;
-    remainingCredits: number | null;
-    staticRemainingCredits?: number | null;
-    derivedAvailableCredits?: number | null;
-    reservedNativeAmount?: number | null;
-    derivedCapacity?: DerivedCapacityAvailability | null;
-    derivedCapacityMode?: 'static' | 'hybrid' | 'derived';
-    score: CapacityLaneScore;
-    eligible: boolean;
-    reasons: string[];
-    estimate?: CapacityTaskEstimate;
-    pressure?: CapacityRoutePressure;
-    nativePressure?: CapacityRouteNativePressure | null;
-    qualityFit?: number;
-    attentionEstimate?: AttentionEstimate;
-    utilityEstimate?: UtilityEstimate;
-    reservePrediction?: ReservePrediction | null;
-    trustScore?: number | null;
-    successProbability?: number | null;
-    spilloverReason?: string | null;
-}
-export interface CapacityRouteNativePressure {
-    executionProviderId: string;
-    nativeUnit: string;
-    availableNativeAmount: number;
-    activeReservedNativeAmount: number;
-    reserveBufferNativeAmount: number;
-    reservedNativeAmount: number | null;
-    pressureRatio: number | null;
-    confidence: string;
-    reasons: string[];
-}
-export interface CapacityRoutePressure {
-    activeReservations: number;
-    maxActiveReservations: number | null;
-    congestionRatio: number;
-    quotaRemainingPercent: number | null;
-    sessionRemainingMinutes: number | null;
-    subscriptionSaturationPercent: number | null;
-    providerUnavailable: boolean;
-    activeAttentionLoad: number;
-    maxAttentionLoad: number | null;
-    attentionSaturationPercent: number | null;
-    activeContextTokens: number;
-    maxContextTokens: number | null;
-    contextSaturationPercent: number | null;
-}
-export type RouteAndReserveResult = {
-    ok: true;
-    provider: CapacityProvider;
-    lane: CapacityProviderLane;
-    grant: CapacityGrant;
-    estimate: CapacityTaskEstimate;
-    remainingCreditsBefore: number | null;
-    reservation: CreateCapacityReservationRequest;
-    routingDecision: CreateCapacityRoutingDecisionRequest;
-    ledgerEntry: RecordCapacityUsageRequest;
-    capacityMetadata: {
-        providerId: string;
-        laneId: string;
-        grantId: string;
-        reservationId: string | null;
-        routingDecisionId: string | null;
-        estimatedCreditsP50: number;
-        estimatedCreditsP90: number;
-        reservedCredits: number;
-        executionProviderId?: string | null;
-        nativeUnit?: string | null;
-        reservedNativeAmount?: number | null;
-        derivedAvailableCredits?: number | null;
-        derivedCapacityMode?: 'static' | 'hybrid' | 'derived';
-        nativePressure?: CapacityRouteNativePressure | null;
-        executionProfileId?: string | null;
-        costMultiplier?: number | null;
-        score?: number | null;
-        attentionEstimate?: AttentionEstimate | null;
-        utilityEstimate?: UtilityEstimate | null;
-        reservePrediction?: ReservePrediction | null;
-        hybridExecutionPlan?: HybridExecutionPlan | null;
-        candidates?: Record<string, unknown>[];
-    };
-    candidates: RouteAndReserveCandidate[];
-} | {
-    ok: false;
-    code: RouteAndReserveBlockCode;
-    reason: string;
-    estimate: CapacityTaskEstimate;
-    candidates: RouteAndReserveCandidate[];
-};
-export interface CapacitySettlementInput {
-    reservation: CapacityReservation;
-    actualCredits: number;
-    actualProviderUnits?: number | null;
-    actualUsd?: number | null;
-    teamId?: string | null;
-    projectId?: string | null;
-    workDayId?: string | null;
-    taskId?: string | null;
-    source?: string;
-    metadata?: Record<string, unknown>;
-}
-export interface CapacitySettlement {
-    reservationId: string;
-    state: 'consumed' | 'overran_pending_approval';
-    consumeEntry: RecordCapacityUsageRequest;
-    releaseEntry: RecordCapacityUsageRequest | null;
-    overrunEntry: RecordCapacityUsageRequest | null;
-    consumedCredits: number;
-    releasedCredits: number;
-    overrunCredits: number;
-}
-export declare const DEFAULT_EXECUTION_PROFILE_ID = "standard-code-model";
-export declare function estimateLearningPercentile(values: Array<number | null | undefined>, percentile: number): number | null;
-export declare function estimateLearningVariance(values: Array<number | null | undefined>): number;
-export declare function isInterruptedUsageActual(actual: Pick<TaskUsageActual, 'metadata'> | {
-    metadata?: Record<string, unknown> | null;
-}): boolean;
-export declare function estimateProfileConfidenceScore(input: {
-    sampleCount?: number | null;
-    creditsVariance?: number | null;
-    creditsP50?: number | null;
-    lastSampleAt?: string | null;
-    now?: Date | string | null;
-}): number;
-export declare function estimateConfidenceFromProfile(profile: TaskEstimateProfile | null | undefined, now?: Date | string | null): CapacityEstimateConfidence;
-export declare function selectTaskEstimateProfile(input: {
-    profiles?: TaskEstimateProfile[] | null;
-    taskSignature?: string | null;
-    executionProfile?: ExecutionProfile | string | null;
-    executionProfileId?: string | null;
-}): TaskEstimateProfile | null;
-export declare function buildTaskEstimateProfileFromActuals(input: {
-    taskSignature: string;
-    executionProfileId?: string | null;
-    actuals: TaskUsageActual[];
-    now?: Date | string | null;
-}): TaskEstimateProfile;
-export declare const DEFAULT_EXECUTION_PROFILES: Record<string, ExecutionProfile>;
-export declare const DEFAULT_TASK_ADMISSION_POLICY: TaskAdmissionPolicy;
-export declare function normalizeExecutionProfile(input?: ExecutionProfile | string | null): ExecutionProfile;
-export declare function normalizeTaskAdmissionPolicy(input?: Partial<TaskAdmissionPolicy> | null | undefined): {
-    planningThresholdCredits: number;
-    approvalThresholdCredits: number;
-    reserveBufferPercent: number;
-    recoveryBudgetCredits: number;
-    maxDownstreamTasks: number;
-    maxPlanningDepth: number;
-    maxAdmittedPlanTasksPerCycle: number;
-    planningTaskSignature: string;
-    allowBackfill: boolean | undefined;
-    maxAttentionLoad: number | null | undefined;
-    reserveAttentionPercent: number;
-    maxContextTokens: number | null | undefined;
-    maxContextSaturationPercent: number;
-    coordinationOverheadFactor: number;
-    predictiveReservePolicy?: Partial<PredictiveReservePolicy> | null;
-    utilityPolicy?: Partial<UtilityPolicy> | null;
-};
-export declare function normalizeAttentionPolicy(input?: Partial<AttentionPolicy | TaskAdmissionPolicy> | null | undefined): AttentionPolicy;
-export declare function normalizeUtilityPolicy(input?: Partial<UtilityPolicy> | null | undefined): UtilityPolicy;
-export declare function normalizePredictiveReservePolicy(input?: Partial<PredictiveReservePolicy> | null | undefined): PredictiveReservePolicy;
-export declare function estimateUtilityForTask(input: {
-    classification?: TaskClassification | null;
-    executionProfile?: ExecutionProfile | string | null;
-    estimate?: Pick<CapacityTaskEstimate, 'reservedCredits'> | null;
-    utilityPolicy?: Partial<UtilityPolicy> | null;
-    utilityValue?: number | null;
-    maintenanceValue?: number | null;
-    priority?: number | null;
-    deadlineAt?: string | null;
-    successProbability?: number | null;
-    metadata?: Record<string, unknown> | null;
-    source?: string | null;
-    now?: Date | string | null;
-}): UtilityEstimate;
-export declare function predictReserveForCapacityPlan(input: {
-    plan?: CapacityPlan | null;
-    policy?: Partial<PredictiveReservePolicy> | null;
-    dailyCreditBudget?: number | null;
-    remainingCredits?: number | null;
-    metadata?: Record<string, unknown> | null;
-}): ReservePrediction;
-export declare function normalizeHybridExecutionPlan(input: HybridExecutionPlan | Record<string, unknown> | null | undefined): HybridExecutionPlan | null;
-export declare function normalizePlanningPolicy(input?: Partial<PlanningPolicy | TaskAdmissionPolicy> | null | undefined): PlanningPolicy;
-export declare function synthesizePlanEstimate(tasks: PlannedTaskNode[]): {
-    totalEstimatedCreditsP50: number;
-    totalEstimatedCreditsP90: number;
-};
-export declare function rankPlannedTaskNodes(tasks: PlannedTaskNode[]): PlannedTaskNode[];
-export declare function normalizeTaskPlanProposal(input: unknown, policyInput?: Partial<PlanningPolicy | TaskAdmissionPolicy> | null): TaskPlanProposal;
-export declare function validateTaskPlanProposal(input: TaskPlanProposal, policyInput?: Partial<PlanningPolicy | TaskAdmissionPolicy> | null): {
-    ok: boolean;
-    reasons: string[];
-    rejected: {
-        node: PlannedTaskNode;
-        reasons: string[];
-    }[];
-};
-export declare function progressivelyAdmitPlanProposal(input: {
-    proposal: TaskPlanProposal;
-    policy?: Partial<PlanningPolicy | TaskAdmissionPolicy> | null;
-    availableCredits?: number | null;
-    remainingQueuedCredits?: number | null;
-    remainingQueuedSlots?: number | null;
-}): PlanningAdmissionResult;
-export declare function computeWorkdayBudgetEnvelope(input: WorkdayBudgetEnvelopeInput): WorkdayBudgetEnvelope;
-export declare function mutationRequiresRepositoryClaim(scope: TaskMutationScope | null | undefined): scope is "repository_write" | "production";
-export declare function reserveCreditsForEstimate(input: CapacityEstimateInput): {
-    taskSignature: string;
-    confidence: CapacityEstimateConfidence;
-    estimatedCreditsP50: number;
-    estimatedCreditsP90: number;
-    reservedCredits: number;
-    baseReservedCredits: number;
-    executionProfileId: string | null;
-    costMultiplier: number;
-};
-export declare function estimateForClassification(input: AdmissionEstimateInput): CapacityTaskEstimate;
-export declare function decideTaskAdmission(input: TaskAdmissionInput): TaskAdmissionDecision;
-export declare function shouldInterruptForCapacity(input: CapacityInterruptionInput): {
-    interrupt: boolean;
-    reasons: string[];
-    usedPercent: number;
-    estimatedRemainingP50: number;
-    estimatedRemainingP90: number;
-    remainingReservationCredits: number;
-};
-export declare function summarizeCapacityPlan(plan: CapacityPlan): {
-    grantedDailyCredits: number;
-    reservedCredits: number;
-    consumedCredits: number;
-    remainingDailyCredits: number | null;
-    providerCount: number;
-    laneCount: number;
-    grantCount: number;
-};
-export declare function summarizeTeamCapacityPlan(plan: CapacityPlan): TeamCapacitySummary;
-export declare function summarizeProjectCapacityPlan(plan: CapacityPlan, options?: {
-    workPolicyEnabled?: boolean | null;
-    approvalRequiredCount?: number;
-    blockedTaskCount?: number;
-}): ProjectCapacitySummary;
-export declare function scoreCapacityLane(input: CapacityLaneCandidate): CapacityLaneScore;
-export declare function selectBestCapacityLane(candidates: CapacityLaneCandidate[]): {
-    selected: CapacityLaneScore;
-    scores: CapacityLaneScore[];
-};
-export declare function reservationHasCapacity(reservation: CapacityReservation): boolean;
-export declare function createReservationReleaseEntry(input: {
-    reservation: CapacityReservation;
-    credits?: number | null;
-    source?: string;
-    metadata?: Record<string, unknown>;
-}): RecordCapacityUsageRequest;
-export declare function settleCapacityActuals(input: CapacitySettlementInput): CapacitySettlement;
-export declare function estimateAttentionForTask(input: {
-    classification?: TaskClassification | null;
-    executionProfile?: ExecutionProfile | string | null;
-    attentionPolicy?: Partial<AttentionPolicy | TaskAdmissionPolicy> | null;
-    attentionWeight?: number | null;
-    coordinationWeight?: number | null;
-    estimatedContextTokens?: number | null;
-    requiredContextTokens?: number | null;
-    source?: string | null;
-    metadata?: Record<string, unknown>;
-}): AttentionEstimate;
-export declare function capacityRoutePressure(plan: CapacityPlan, provider: CapacityProvider, lane: CapacityProviderLane): CapacityRoutePressure;
-export declare function routeAndReserveCapacity(input: RouteAndReserveInput): RouteAndReserveResult;