@treeseed/sdk 0.10.10 → 0.10.12

package/README.md

@@ -20,7 +20,7 @@ If you are unsure, use `AgentSdk`.
 
 `AgentSdk` covers five main areas:
 
-- generic model reads and mutations across content-backed and D1-backed models
+- generic model reads and mutations across content-backed models and the static-hub D1 form store
 - operational runtime state such as messages, runs, cursors, and leases
 - control-plane orchestration for work days, tasks, task events, graph runs, and reports
 - provider-neutral capacity scheduling contracts for task classification, admission, execution profiles, routing, estimates, planning proposals, attention load, utility, predictive reserve, hybrid execution, checkpoints, and usage actuals
@@ -49,7 +49,7 @@ const sdk = new AgentSdk({
 });
 ```
 
-Use `AgentSdk.createLocal()` when you want a local Wrangler-backed D1 database:
+Use `AgentSdk.createLocal()` when you want the local static-hub D1 form store:
 
 ```ts
 import { AgentSdk } from '@treeseed/sdk/sdk';

package/dist/capacity-provider.d.ts

@@ -1,3 +1,4 @@
+import type { NativeUsageObservation } from './sdk-types.ts';
 export declare const CAPACITY_PROVIDER_ENDPOINTS: {
     readonly register: "/v1/provider/register";
     readonly heartbeat: "/v1/provider/heartbeat";
@@ -35,11 +36,59 @@ export interface CapacityProviderCapability {
     verification: string[];
     metadata?: Record<string, unknown>;
 }
+export type NativeCapacityUnit = 'wall_minute' | 'quota_minute' | 'usd' | 'token' | 'request' | 'gpu_second' | 'human_minute' | 'custom' | string;
+export type NativeCapacityLimitScope = 'daily' | 'weekly' | 'monthly' | 'session' | 'rolling_window' | string;
+export type NativeCapacityConfidence = 'exact' | 'estimated' | 'opaque' | string;
+export type NativeCapacityLimitSource = 'configured' | 'observed' | 'learned' | 'manual_override' | string;
+export type ProviderQuotaVisibility = 'exact' | 'partial' | 'opaque' | string;
+export interface ExecutionProviderNativeLimitCapacity {
+    id?: string;
+    scope?: NativeCapacityLimitScope;
+    limitScope?: NativeCapacityLimitScope;
+    nativeUnit?: NativeCapacityUnit;
+    limitAmount: number;
+    reserveBufferPercent?: number | null;
+    resetCadence?: string | null;
+    resetAt?: string | null;
+    confidence?: NativeCapacityConfidence;
+    source?: NativeCapacityLimitSource;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionProviderObservationCapacity {
+    id?: string;
+    observedAt?: string;
+    health?: string;
+    activeWorkers?: number | null;
+    queuedTasks?: number | null;
+    throttleState?: string | null;
+    nativeRemaining?: Record<string, unknown>;
+    resetAt?: string | null;
+    confidence?: NativeCapacityConfidence;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionProviderNativeCapacity {
+    id?: string;
+    name: string;
+    kind: string;
+    status?: string;
+    nativeUnit: NativeCapacityUnit;
+    quotaVisibility?: ProviderQuotaVisibility;
+    maxConcurrentWorkers?: number | null;
+    resetCadence?: string | null;
+    config?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    nativeLimits?: ExecutionProviderNativeLimitCapacity[];
+    observation?: ExecutionProviderObservationCapacity;
+}
+export interface CapacityProviderNativeCapacity {
+    executionProviders: ExecutionProviderNativeCapacity[];
+}
 export interface CapacityProviderBudgetCapacity {
     dailyCreditBudget?: number | null;
     monthlyCreditBudget?: number | null;
     maxConcurrentWorkdays?: number | null;
     maxConcurrentRunners?: number | null;
+    nativeCapacity?: CapacityProviderNativeCapacity;
     [key: string]: unknown;
 }
 export interface CapacityProviderHealthState {
@@ -181,6 +230,7 @@ export interface ProviderUsageReport {
     projectId?: string | null;
     taskSignature?: string | null;
     executionProfileId?: string | null;
+    executionProviderId?: string | null;
     modelName?: string | null;
     inputTokens?: number | null;
     outputTokens?: number | null;
@@ -193,8 +243,10 @@ export interface ProviderUsageReport {
     diffLinesRemoved?: number | null;
     testRuns?: number | null;
     retryCount?: number | null;
-    actualCredits: number;
+    actualCredits?: number | null;
+    actualCreditsOverride?: boolean | null;
     actualUsd?: number | null;
+    nativeUsage?: NativeUsageObservation | Record<string, unknown> | null;
     metadata?: Record<string, unknown> | null;
 }
 export interface ProviderUsageReportResponse {

package/dist/capacity.d.ts

@@ -1,5 +1,58 @@
-import type { AttentionEstimate, AttentionPolicy, CapacityEstimateConfidence, CapacityGrant, CapacityPlan, CapacityProvider, CapacityProviderLane, CapacityReservation, CreateCapacityReservationRequest, CreateCapacityRoutingDecisionRequest, ExecutionProfile, HybridExecutionPlan, PlannedTaskNode, PlanningAdmissionResult, PlanningPolicy, PredictiveReservePolicy, ProjectEnvironmentName, RecordCapacityUsageRequest, ReservePrediction, TaskAdmissionDecision, TaskAdmissionPolicy, TaskClassification, TaskEstimateProfile, TaskPlanProposal, TaskMutationScope, TaskUsageActual, UtilityEstimate, UtilityPolicy, WorkdayBudgetEnvelope } from './sdk-types.ts';
+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.ts';
 import type { AgentProviderProfile } from './types/agents.ts';
+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;
@@ -37,6 +90,7 @@ export interface CapacityLaneScore {
     congestionPenalty?: number;
     attentionPenalty?: number;
     contextPenalty?: number;
+    nativePressurePenalty?: number;
     utilityScore?: number;
     utilityPerCredit?: number;
     predictedReserveImpact?: number;
@@ -157,13 +211,21 @@ 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;
@@ -172,6 +234,17 @@ export interface RouteAndReserveCandidate {
     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;
@@ -206,6 +279,12 @@ export type RouteAndReserveResult = {
         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;