@treeseed/sdk 0.8.11 → 0.8.12

package/README.md

@@ -23,6 +23,7 @@ If you are unsure, use `AgentSdk`.
 - generic model reads and mutations across content-backed and D1-backed models
 - 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
 - graph-first context retrieval through `parseGraphDsl()`, `resolveSeeds()`, `queryGraph()`, and `buildContextPack()`
 - agent scoping through `scopeForAgent()`
 
@@ -102,6 +103,12 @@ ctx <target>
 
 The old `key=value` graph DSL is no longer supported.
 
+## Capacity Scheduling Contracts
+
+The SDK owns the provider-neutral capacity runtime helpers used by the agent manager, workers, and market control plane. These helpers keep work estimation separate from provider cost by normalizing `taskSignature + executionProfileId` estimates, then routing against grants, provider lanes, quality requirements, quota/congestion pressure, attention/context saturation, utility, predictive reserve, and hybrid phase metadata.
+
+Capacity records remain metadata-compatible: advanced scheduling data lives in task payload JSON, routing decision candidates/scores, reservation metadata, capacity plan metadata, checkpoint artifacts, and usage actual metadata. Missing metadata is neutral, so older callers continue to use the credit-only behavior.
+
 ## Shared Fixture Support
 
 SDK also owns the shared fixture support model used across the Treeseed workspace.

package/dist/capacity.d.ts

@@ -1,4 +1,4 @@
-import type { CapacityEstimateConfidence, CapacityGrant, CapacityPlan, CapacityProvider, CapacityProviderLane, CapacityReservation, CreateCapacityReservationRequest, CreateCapacityRoutingDecisionRequest, RecordCapacityUsageRequest, TaskEstimateProfile } from './sdk-types.ts';
+import type { AttentionEstimate, AttentionPolicy, CapacityEstimateConfidence, CapacityGrant, CapacityPlan, CapacityProvider, CapacityProviderLane, CapacityReservation, CreateCapacityReservationRequest, CreateCapacityRoutingDecisionRequest, ExecutionProfile, HybridExecutionPlan, PlannedTaskNode, PlanningAdmissionResult, PlanningPolicy, PredictiveReservePolicy, RecordCapacityUsageRequest, ReservePrediction, TaskAdmissionDecision, TaskAdmissionPolicy, TaskClassification, TaskEstimateProfile, TaskPlanProposal, TaskMutationScope, TaskUsageActual, UtilityEstimate, UtilityPolicy, WorkdayBudgetEnvelope } from './sdk-types.ts';
 import type { AgentProviderProfile } from './types/agents.ts';
 export type ProcessingEnvironment = 'local' | 'staging' | 'prod';
 export interface CapacityProviderRegistration {
@@ -40,7 +40,11 @@ export interface CapacityEstimateInput {
     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;
@@ -60,6 +64,25 @@ export interface CapacityLaneScore {
     scarcityPenalty: number;
     fairnessScore: number;
     costPenalty: number;
+    qualityFit?: number;
+    latencyPenalty?: number;
+    quotaPressure?: number;
+    congestionPenalty?: number;
+    attentionPenalty?: number;
+    contextPenalty?: 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 {
@@ -68,6 +91,37 @@ export interface CapacityTaskEstimate {
     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;
@@ -94,6 +148,7 @@ export interface ProjectCapacitySummary extends TeamCapacitySummary {
 export interface RouteAndReserveInput {
     plan: CapacityPlan;
     estimate: CapacityTaskEstimate;
+    classification?: TaskClassification | null;
     taskId?: string | null;
     workDayId?: string | null;
     taskKind?: string | null;
@@ -104,6 +159,29 @@ export interface RouteAndReserveInput {
     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>;
 }
@@ -112,10 +190,35 @@ export interface RouteAndReserveCandidate {
     providerId: string;
     laneId: string;
     grantId: string;
+    executionProfileId?: string | null;
     remainingCredits: number | null;
     score: CapacityLaneScore;
     eligible: boolean;
     reasons: string[];
+    estimate?: CapacityTaskEstimate;
+    pressure?: CapacityRoutePressure;
+    qualityFit?: number;
+    attentionEstimate?: AttentionEstimate;
+    utilityEstimate?: UtilityEstimate;
+    reservePrediction?: ReservePrediction | null;
+    trustScore?: number | null;
+    successProbability?: number | null;
+    spilloverReason?: string | null;
+}
+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;
@@ -136,6 +239,14 @@ export type RouteAndReserveResult = {
         estimatedCreditsP50: number;
         estimatedCreditsP90: number;
         reservedCredits: number;
+        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[];
 } | {
@@ -167,12 +278,121 @@ export interface CapacitySettlement {
     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;
@@ -202,4 +422,16 @@ export declare function createReservationReleaseEntry(input: {
     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;