@treeseed/sdk 0.8.7 → 0.8.8

package/dist/capacity.d.ts

@@ -1,4 +1,4 @@
-import type { CapacityEstimateConfidence, CapacityGrant, CapacityPlan, CapacityProviderLane, CapacityReservation, TaskEstimateProfile } from './sdk-types.ts';
+import type { CapacityEstimateConfidence, CapacityGrant, CapacityPlan, CapacityProvider, CapacityProviderLane, CapacityReservation, CreateCapacityReservationRequest, CreateCapacityRoutingDecisionRequest, RecordCapacityUsageRequest, TaskEstimateProfile } from './sdk-types.ts';
 import type { AgentProviderProfile } from './types/agents.ts';
 export type ProcessingEnvironment = 'local' | 'staging' | 'prod';
 export interface CapacityProviderRegistration {
@@ -62,6 +62,111 @@ export interface CapacityLaneScore {
     costPenalty: number;
     reasons: string[];
 }
+export interface CapacityTaskEstimate {
+    taskSignature: string;
+    confidence: CapacityEstimateConfidence;
+    estimatedCreditsP50: number;
+    estimatedCreditsP90: number;
+    reservedCredits: number;
+}
+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: ProcessingEnvironment;
+    readiness: 'ready' | 'waiting_for_budget' | 'waiting_for_provider' | 'paused_by_policy' | 'needs_approval';
+    reasons: string[];
+}
+export interface RouteAndReserveInput {
+    plan: CapacityPlan;
+    estimate: CapacityTaskEstimate;
+    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;
+    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;
+    remainingCredits: number | null;
+    score: CapacityLaneScore;
+    eligible: boolean;
+    reasons: string[];
+}
+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;
+    };
+    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 function reserveCreditsForEstimate(input: CapacityEstimateInput): {
     taskSignature: string;
     confidence: CapacityEstimateConfidence;
@@ -78,9 +183,23 @@ export declare function summarizeCapacityPlan(plan: CapacityPlan): {
     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 routeAndReserveCapacity(input: RouteAndReserveInput): RouteAndReserveResult;

package/dist/capacity.js

@@ -6,6 +6,97 @@ function scarcityPenalty(level) {
   if (level === "medium") return 15;
   return 0;
 }
+function metadataStatus(value) {
+  const status = value?.status;
+  return typeof status === "string" ? status : null;
+}
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function booleanValue(value) {
+  return typeof value === "boolean" ? value : null;
+}
+function numberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function reservationDebit(reservation) {
+  if (reservation.state === "released" || reservation.state === "expired" || reservation.state === "cancelled") {
+    return 0;
+  }
+  if (reservation.state === "consumed" || reservation.state === "failed") {
+    return Math.max(0, reservation.consumedCredits);
+  }
+  return Math.max(reservation.reservedCredits, reservation.consumedCredits, 0);
+}
+function activeReservationDebit(reservation) {
+  if (reservation.state === "reserved" || reservation.state === "consuming") {
+    return Math.max(reservation.reservedCredits, reservation.consumedCredits, 0);
+  }
+  if (reservation.state === "consumed" || reservation.state === "failed") {
+    return Math.max(reservation.consumedCredits, 0);
+  }
+  return 0;
+}
+function grantMatchesReservation(grant, reservation) {
+  if (grant.teamId !== reservation.teamId) return false;
+  if (grant.capacityProviderId !== reservation.capacityProviderId) return false;
+  if (grant.laneId && grant.laneId !== reservation.laneId) return false;
+  if (grant.projectId && grant.projectId !== reservation.projectId) return false;
+  return true;
+}
+function grantRemainingCredits(plan, grant) {
+  const limit = grant.dailyCreditLimit ?? grant.monthlyCreditLimit;
+  if (limit === null || limit === void 0) return null;
+  const debits = plan.activeReservations.filter((reservation) => grantMatchesReservation(grant, reservation)).reduce((total, reservation) => total + reservationDebit(reservation), 0);
+  return Math.max(0, Number(limit) - debits);
+}
+function providerIsEligible(provider, input) {
+  if (provider.status === "active") return true;
+  if (provider.status === "degraded" && input.allowDegradedProviders) return true;
+  return false;
+}
+function grantIsEligible(grant, input) {
+  if (grant.state !== "active") return false;
+  if (grant.teamId !== input.plan.teamId) return false;
+  if (grant.environment && grant.environment !== input.plan.environment) return false;
+  if (grant.projectId && grant.projectId !== input.plan.projectId) return false;
+  return true;
+}
+function lanePolicyReasons(lane, input) {
+  const reasons = [];
+  const laneStatus = metadataStatus(lane.metadata);
+  if (laneStatus && laneStatus !== "active") reasons.push(`lane_status:${laneStatus}`);
+  const policy = lane.routingPolicy ?? {};
+  const taskKinds = stringArray(policy.taskKinds);
+  const taskKind = input.taskKind ?? input.estimate.taskSignature;
+  if (taskKinds.length > 0 && !taskKinds.includes(taskKind)) reasons.push("task_kind_mismatch");
+  const requiredCapabilities = stringArray(policy.requiredCapabilities);
+  const missingCapabilities = (input.requiredCapabilities ?? []).filter((capability) => !requiredCapabilities.includes(capability));
+  if (requiredCapabilities.length > 0 && missingCapabilities.length > 0) {
+    reasons.push("capability_mismatch");
+  }
+  const allowedEnvironments = stringArray(policy.allowedEnvironments);
+  if (allowedEnvironments.length > 0 && !allowedEnvironments.includes(input.plan.environment)) {
+    reasons.push("environment_mismatch");
+  }
+  const maxCreditsPerTask = numberValue(policy.maxCreditsPerTask);
+  if (maxCreditsPerTask !== null && input.estimate.reservedCredits > maxCreditsPerTask) {
+    reasons.push("task_credit_limit_exceeded");
+  }
+  const approvalThreshold = numberValue(policy.requiresApprovalAboveCredits);
+  if (approvalThreshold !== null && input.estimate.reservedCredits > approvalThreshold) {
+    reasons.push("approval_required");
+  }
+  const repositoryMutationAllowed = booleanValue(policy.repositoryMutationAllowed);
+  if (input.repositoryMutation && repositoryMutationAllowed === false) {
+    reasons.push("repository_mutation_not_allowed");
+  }
+  const productionAllowed = booleanValue(policy.productionAllowed);
+  if (input.production && productionAllowed === false) {
+    reasons.push("production_not_allowed");
+  }
+  return reasons;
+}
 function reserveCreditsForEstimate(input) {
   const profileP50 = finiteNumber(input.profile?.creditsP50);
   const profileP90 = finiteNumber(input.profile?.creditsP90);
@@ -26,7 +117,7 @@ function reserveCreditsForEstimate(input) {
   };
 }
 function summarizeCapacityPlan(plan) {
-  const reservedCredits = plan.activeReservations.filter((reservation) => reservation.state === "reserved").reduce((total, reservation) => total + reservation.reservedCredits, 0);
+  const reservedCredits = plan.activeReservations.filter((reservation) => reservation.state === "reserved" || reservation.state === "consuming").reduce((total, reservation) => total + reservation.reservedCredits, 0);
   const consumedCredits = plan.activeReservations.reduce((total, reservation) => total + reservation.consumedCredits, 0);
   const grantedDailyCredits = plan.grants.filter((grant) => grant.state === "active").reduce((total, grant) => total + (grant.dailyCreditLimit ?? 0), 0);
   return {
@@ -39,6 +130,55 @@ function summarizeCapacityPlan(plan) {
     grantCount: plan.grants.length
   };
 }
+function summarizeTeamCapacityPlan(plan) {
+  const dailyCredits = plan.grants.filter((grant) => grant.state === "active").reduce((total, grant) => total + (grant.dailyCreditLimit ?? 0), 0);
+  const monthlyCredits = plan.grants.filter((grant) => grant.state === "active").reduce((total, grant) => total + (grant.monthlyCreditLimit ?? 0), 0);
+  const dailyReservedCredits = plan.activeReservations.reduce((total, reservation) => total + activeReservationDebit(reservation), 0);
+  const dailyUsedCredits = plan.activeReservations.reduce((total, reservation) => total + Math.max(0, reservation.consumedCredits), 0);
+  return {
+    teamId: plan.teamId,
+    monthlyCredits: monthlyCredits > 0 ? monthlyCredits : null,
+    monthlyUsedCredits: dailyUsedCredits,
+    monthlyRemainingCredits: monthlyCredits > 0 ? Math.max(0, monthlyCredits - dailyUsedCredits) : null,
+    dailyCredits: dailyCredits > 0 ? dailyCredits : null,
+    dailyUsedCredits,
+    dailyReservedCredits,
+    dailyRemainingCredits: dailyCredits > 0 ? Math.max(0, dailyCredits - dailyReservedCredits - dailyUsedCredits) : null,
+    providerCount: plan.providers.length,
+    activeProviderCount: plan.providers.filter((provider) => provider.status === "active").length,
+    degradedProviderCount: plan.providers.filter((provider) => provider.status === "degraded").length,
+    grantCount: plan.grants.length,
+    blockedTaskCount: 0,
+    approvalRequiredCount: 0
+  };
+}
+function summarizeProjectCapacityPlan(plan, options = {}) {
+  const summary = summarizeTeamCapacityPlan(plan);
+  const reasons = [];
+  let readiness = "ready";
+  if (options.workPolicyEnabled === false) {
+    readiness = "paused_by_policy";
+    reasons.push("work_policy_disabled");
+  } else if (summary.activeProviderCount <= 0) {
+    readiness = "waiting_for_provider";
+    reasons.push("no_active_provider");
+  } else if (summary.dailyRemainingCredits !== null && summary.dailyRemainingCredits <= 0) {
+    readiness = "waiting_for_budget";
+    reasons.push("daily_budget_exhausted");
+  } else if ((options.approvalRequiredCount ?? 0) > 0) {
+    readiness = "needs_approval";
+    reasons.push("approval_required");
+  }
+  return {
+    ...summary,
+    projectId: plan.projectId,
+    environment: plan.environment,
+    readiness,
+    reasons,
+    blockedTaskCount: options.blockedTaskCount ?? summary.blockedTaskCount,
+    approvalRequiredCount: options.approvalRequiredCount ?? summary.approvalRequiredCount
+  };
+}
 function scoreCapacityLane(input) {
   const reasons = [];
   let agentFit = 0;
@@ -91,10 +231,239 @@ function selectBestCapacityLane(candidates) {
 function reservationHasCapacity(reservation) {
   return reservation.state === "reserved" && reservation.reservedCredits > reservation.consumedCredits;
 }
+function createReservationReleaseEntry(input) {
+  const credits = Math.max(0, Number(input.credits ?? input.reservation.reservedCredits - input.reservation.consumedCredits));
+  return {
+    capacityProviderId: input.reservation.capacityProviderId,
+    laneId: input.reservation.laneId,
+    reservationId: input.reservation.id,
+    teamId: input.reservation.teamId,
+    projectId: input.reservation.projectId,
+    workDayId: input.reservation.workDayId,
+    taskId: input.reservation.taskId,
+    phase: "reservation_released",
+    credits: -credits,
+    source: input.source ?? "capacity_coordinator",
+    metadata: input.metadata ?? {}
+  };
+}
+function settleCapacityActuals(input) {
+  const consumedCredits = Math.max(0, Number(input.actualCredits ?? 0));
+  const releasedCredits = Math.max(0, input.reservation.reservedCredits - consumedCredits);
+  const overrunCredits = Math.max(0, consumedCredits - input.reservation.reservedCredits);
+  const base = {
+    capacityProviderId: input.reservation.capacityProviderId,
+    laneId: input.reservation.laneId,
+    reservationId: input.reservation.id,
+    teamId: input.teamId ?? input.reservation.teamId,
+    projectId: input.projectId ?? input.reservation.projectId,
+    workDayId: input.workDayId ?? input.reservation.workDayId,
+    taskId: input.taskId ?? input.reservation.taskId,
+    source: input.source ?? "capacity_coordinator",
+    metadata: input.metadata ?? {}
+  };
+  const consumeEntry = {
+    ...base,
+    phase: "task_completed_actual_settlement",
+    credits: consumedCredits,
+    providerUnits: input.actualProviderUnits ?? null,
+    usd: input.actualUsd ?? null
+  };
+  const releaseEntry = releasedCredits > 0 ? {
+    ...base,
+    phase: "reservation_released",
+    credits: -releasedCredits
+  } : null;
+  const overrunEntry = overrunCredits > 0 ? {
+    ...base,
+    phase: "overrun_hold",
+    credits: overrunCredits
+  } : null;
+  return {
+    reservationId: input.reservation.id,
+    state: overrunCredits > 0 ? "overran_pending_approval" : "consumed",
+    consumeEntry,
+    releaseEntry,
+    overrunEntry,
+    consumedCredits,
+    releasedCredits,
+    overrunCredits
+  };
+}
+function routeAndReserveCapacity(input) {
+  const providers = input.plan.providers.filter((provider2) => providerIsEligible(provider2, input));
+  const grants = input.plan.grants.filter((grant2) => grantIsEligible(grant2, input));
+  const candidates = [];
+  for (const grant2 of grants) {
+    const provider2 = providers.find((candidate) => candidate.id === grant2.capacityProviderId);
+    if (!provider2) continue;
+    const lanes = input.plan.lanes.filter(
+      (lane2) => lane2.capacityProviderId === provider2.id && (!grant2.laneId || grant2.laneId === lane2.id)
+    );
+    for (const lane2 of lanes) {
+      const reasons = lanePolicyReasons(lane2, input);
+      const remainingCredits = grantRemainingCredits(input.plan, grant2);
+      if (remainingCredits !== null && remainingCredits < input.estimate.reservedCredits && (grant2.overflowPolicy === "deny" || grant2.overflowPolicy === "hard_grant")) {
+        reasons.push("insufficient_budget");
+      }
+      if (remainingCredits !== null && remainingCredits < input.estimate.reservedCredits && grant2.overflowPolicy === "approval_required") {
+        reasons.push("approval_required");
+      }
+      const score = scoreCapacityLane({
+        lane: lane2,
+        grant: grant2,
+        remainingCredits,
+        taskKind: input.taskKind ?? input.estimate.taskSignature,
+        requiredCapabilities: input.requiredCapabilities,
+        modelClass: input.modelClass ?? null
+      });
+      candidates.push({
+        providerId: provider2.id,
+        laneId: lane2.id,
+        grantId: grant2.id,
+        remainingCredits,
+        score,
+        eligible: reasons.length === 0,
+        reasons
+      });
+    }
+  }
+  if (input.plan.providers.length === 0 || providers.length === 0) {
+    return {
+      ok: false,
+      code: "no_capacity_provider",
+      reason: "No active helper capacity provider is available.",
+      estimate: input.estimate,
+      candidates
+    };
+  }
+  if (grants.length === 0) {
+    return {
+      ok: false,
+      code: "no_capacity_grant",
+      reason: "No active capacity grant is available for this team, project, and environment.",
+      estimate: input.estimate,
+      candidates
+    };
+  }
+  const eligible = candidates.filter((candidate) => candidate.eligible).sort((left, right) => right.score.score - left.score.score || left.laneId.localeCompare(right.laneId));
+  const selected = eligible[0] ?? null;
+  if (!selected) {
+    const hasApprovalBlock = candidates.some((candidate) => candidate.reasons.includes("approval_required"));
+    const hasBudgetBlock = candidates.some((candidate) => candidate.reasons.includes("insufficient_budget"));
+    return {
+      ok: false,
+      code: hasApprovalBlock ? "approval_required" : hasBudgetBlock ? "insufficient_budget" : "no_eligible_lane",
+      reason: hasApprovalBlock ? "The requested helper task needs approval before capacity can be reserved." : hasBudgetBlock ? "The requested helper task is above the remaining approved budget." : "No provider lane matches the task policy and capability requirements.",
+      estimate: input.estimate,
+      candidates
+    };
+  }
+  const provider = providers.find((candidate) => candidate.id === selected.providerId);
+  const lane = input.plan.lanes.find((candidate) => candidate.id === selected.laneId);
+  const grant = grants.find((candidate) => candidate.id === selected.grantId);
+  if (!provider || !lane || !grant) {
+    return {
+      ok: false,
+      code: "no_eligible_lane",
+      reason: "The selected capacity lane could not be resolved.",
+      estimate: input.estimate,
+      candidates
+    };
+  }
+  const candidatePayload = candidates.map((candidate) => ({
+    providerId: candidate.providerId,
+    laneId: candidate.laneId,
+    grantId: candidate.grantId,
+    remainingCredits: candidate.remainingCredits,
+    eligible: candidate.eligible,
+    reasons: candidate.reasons,
+    score: candidate.score.score
+  }));
+  const scorePayload = Object.fromEntries(candidates.map((candidate) => [candidate.laneId, candidate.score]));
+  const reservation = {
+    capacityProviderId: provider.id,
+    laneId: lane.id,
+    teamId: input.plan.teamId,
+    projectId: input.plan.projectId,
+    workDayId: input.workDayId ?? null,
+    taskId: input.taskId ?? null,
+    state: "reserved",
+    reservedCredits: input.estimate.reservedCredits,
+    metadata: {
+      ...input.metadata ?? {},
+      grantId: grant.id,
+      taskSignature: input.estimate.taskSignature,
+      estimatedCreditsP50: input.estimate.estimatedCreditsP50,
+      estimatedCreditsP90: input.estimate.estimatedCreditsP90
+    }
+  };
+  const routingDecision = {
+    taskId: input.taskId ?? null,
+    workDayId: input.workDayId ?? null,
+    projectId: input.plan.projectId,
+    selectedProviderId: provider.id,
+    selectedLaneId: lane.id,
+    selectedModel: input.selectedModel ?? null,
+    decision: "selected",
+    reason: selected.score.reasons.length > 0 ? selected.score.reasons.join(",") : "best_eligible_lane",
+    candidates: candidatePayload,
+    scores: scorePayload,
+    metadata: {
+      ...input.metadata ?? {},
+      grantId: grant.id,
+      remainingCreditsBefore: selected.remainingCredits,
+      reservedCredits: input.estimate.reservedCredits
+    }
+  };
+  const ledgerEntry = {
+    capacityProviderId: provider.id,
+    laneId: lane.id,
+    teamId: input.plan.teamId,
+    projectId: input.plan.projectId,
+    workDayId: input.workDayId ?? null,
+    taskId: input.taskId ?? null,
+    phase: "reservation_created",
+    credits: input.estimate.reservedCredits,
+    source: input.source ?? "capacity_coordinator",
+    metadata: {
+      ...input.metadata ?? {},
+      grantId: grant.id,
+      taskSignature: input.estimate.taskSignature
+    }
+  };
+  return {
+    ok: true,
+    provider,
+    lane,
+    grant,
+    estimate: input.estimate,
+    remainingCreditsBefore: selected.remainingCredits,
+    reservation,
+    routingDecision,
+    ledgerEntry,
+    capacityMetadata: {
+      providerId: provider.id,
+      laneId: lane.id,
+      grantId: grant.id,
+      reservationId: reservation.id ?? null,
+      routingDecisionId: routingDecision.id ?? null,
+      estimatedCreditsP50: input.estimate.estimatedCreditsP50,
+      estimatedCreditsP90: input.estimate.estimatedCreditsP90,
+      reservedCredits: input.estimate.reservedCredits
+    },
+    candidates
+  };
+}
 export {
+  createReservationReleaseEntry,
   reservationHasCapacity,
   reserveCreditsForEstimate,
+  routeAndReserveCapacity,
   scoreCapacityLane,
   selectBestCapacityLane,
-  summarizeCapacityPlan
+  settleCapacityActuals,
+  summarizeCapacityPlan,
+  summarizeProjectCapacityPlan,
+  summarizeTeamCapacityPlan
 };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { ContentGraphRuntime } from './graph.ts';
 export { projectConnectionModeFromHosting } from './sdk-types.ts';
 export { createControlPlaneReporter } from './control-plane.ts';
 export { ControlPlaneClient } from './control-plane-client.ts';
-export { reservationHasCapacity, reserveCreditsForEstimate, scoreCapacityLane, selectBestCapacityLane, summarizeCapacityPlan, } from './capacity.ts';
+export { reservationHasCapacity, reserveCreditsForEstimate, routeAndReserveCapacity, scoreCapacityLane, selectBestCapacityLane, settleCapacityActuals, createReservationReleaseEntry, summarizeCapacityPlan, summarizeProjectCapacityPlan, summarizeTeamCapacityPlan, } from './capacity.ts';
 export { executeKnowledgeHubProviderLaunch, validateKnowledgeHubProviderLaunchPrerequisites, } from './operations/services/hub-provider-launch.ts';
 export { createKnowledgeHubRepositories, defaultHubContentResolutionPolicy, executeKnowledgeHubLaunch, normalizeKnowledgeHubLaunchIntent, planKnowledgeHubLaunch, planKnowledgeHubRepositories, validateRepositoryHost, type HubContentResolutionPolicy, type KnowledgeHubLaunchIntent, type KnowledgeHubLaunchPhase, type KnowledgeHubLaunchPlan, type KnowledgeHubLaunchResult, type KnowledgeHubRepositoryPlan, type RepositoryHost, } from './operations/services/hub-launch.ts';
 export { ensureRailwayEnvironment, ensureRailwayProject, ensureRailwayService, getRailwayAuthProfile, listRailwayEnvironments, listRailwayProjects, listRailwayServices, listRailwayVariables, railwayGraphqlRequest, resolveRailwayApiToken, resolveRailwayApiUrl, resolveRailwayWorkspace, resolveRailwayWorkspaceContext, upsertRailwayVariables, } from './operations/services/railway-api.ts';

package/dist/index.js

@@ -6,9 +6,14 @@ import { ControlPlaneClient } from "./control-plane-client.js";
 import {
   reservationHasCapacity,
   reserveCreditsForEstimate,
+  routeAndReserveCapacity,
   scoreCapacityLane,
   selectBestCapacityLane,
-  summarizeCapacityPlan
+  settleCapacityActuals,
+  createReservationReleaseEntry,
+  summarizeCapacityPlan,
+  summarizeProjectCapacityPlan,
+  summarizeTeamCapacityPlan
 } from "./capacity.js";
 import {
   executeKnowledgeHubProviderLaunch,
@@ -250,6 +255,7 @@ export {
   createFilesystemContentSource,
   createKnowledgeHubRepositories,
   createPublishedContentPipeline,
+  createReservationReleaseEntry,
   createTeamScopedR2OverlayContentPublishProvider,
   createTeamScopedR2OverlayContentRuntimeProvider,
   createTreeseedManagedToolEnv,
@@ -336,14 +342,18 @@ export {
   resolveTreeseedTenantRoot,
   resolveTreeseedToolBinary,
   resolveTreeseedToolCommand,
+  routeAndReserveCapacity,
   runTreeseedCopilotTask,
   runTreeseedVerifyDriver,
   scoreCapacityLane,
   selectBestCapacityLane,
   setActiveMarketProfile,
   setMarketSession,
+  settleCapacityActuals,
   signEditorialPreviewToken,
   summarizeCapacityPlan,
+  summarizeProjectCapacityPlan,
+  summarizeTeamCapacityPlan,
   tenantFeatureEnabled,
   tenantModelRendered,
   upsertRailwayVariables,

package/dist/market-client.d.ts

@@ -165,6 +165,38 @@ export declare class MarketClient {
             environments: ProjectEnvironmentAccess[];
         };
     }>;
+    teamCapacity(teamId: string): Promise<{
+        ok: true;
+        payload: Record<string, unknown>;
+    }>;
+    launchManagedCapacityProvider(teamId: string, body?: Record<string, unknown>): Promise<{
+        ok: true;
+        payload: Record<string, unknown>;
+    }>;
+    capacityProvider(providerId: string): Promise<{
+        ok: true;
+        payload: Record<string, unknown>;
+    }>;
+    resetCapacityProviderApiKey(providerId: string, body?: Record<string, unknown>): Promise<{
+        ok: true;
+        payload: Record<string, unknown>;
+    }>;
+    revokeCapacityProviderApiKey(providerId: string, keyId: string): Promise<{
+        ok: true;
+        payload: Record<string, unknown>;
+    }>;
+    capacityGrants(teamId: string): Promise<{
+        ok: true;
+        payload: unknown[];
+    }>;
+    createCapacityGrant(teamId: string, body: Record<string, unknown>): Promise<{
+        ok: true;
+        payload: Record<string, unknown>;
+    }>;
+    enqueueAgentTask(projectId: string, body: Record<string, unknown>): Promise<{
+        ok: true;
+        payload: Record<string, unknown>;
+    }>;
     catalog(kind?: string | null): Promise<{
         ok: true;
         payload: unknown[];

package/dist/market-client.js

@@ -315,6 +315,54 @@ class MarketClient {
       { requireAuth: true }
     );
   }
+  teamCapacity(teamId) {
+    return this.request(
+      `/v1/teams/${encodeURIComponent(teamId)}/capacity`,
+      { requireAuth: true }
+    );
+  }
+  launchManagedCapacityProvider(teamId, body = {}) {
+    return this.request(
+      `/v1/teams/${encodeURIComponent(teamId)}/capacity/providers/managed`,
+      { method: "POST", body, requireAuth: true }
+    );
+  }
+  capacityProvider(providerId) {
+    return this.request(
+      `/v1/capacity/providers/${encodeURIComponent(providerId)}`,
+      { requireAuth: true }
+    );
+  }
+  resetCapacityProviderApiKey(providerId, body = {}) {
+    return this.request(
+      `/v1/capacity/providers/${encodeURIComponent(providerId)}/api-keys/reset`,
+      { method: "POST", body, requireAuth: true }
+    );
+  }
+  revokeCapacityProviderApiKey(providerId, keyId) {
+    return this.request(
+      `/v1/capacity/providers/${encodeURIComponent(providerId)}/api-keys/${encodeURIComponent(keyId)}/revoke`,
+      { method: "POST", requireAuth: true }
+    );
+  }
+  capacityGrants(teamId) {
+    return this.request(
+      `/v1/teams/${encodeURIComponent(teamId)}/capacity-grants`,
+      { requireAuth: true }
+    );
+  }
+  createCapacityGrant(teamId, body) {
+    return this.request(
+      `/v1/teams/${encodeURIComponent(teamId)}/capacity-grants`,
+      { method: "POST", body, requireAuth: true }
+    );
+  }
+  enqueueAgentTask(projectId, body) {
+    return this.request(
+      `/v1/projects/${encodeURIComponent(projectId)}/agent-tasks`,
+      { method: "POST", body, requireAuth: true }
+    );
+  }
   catalog(kind) {
     const query = kind ? `?kind=${encodeURIComponent(kind)}` : "";
     return this.request(`/v1/catalog${query}`, { requireAuth: Boolean(this.accessToken) });

package/dist/operations/services/config-runtime.js

@@ -1851,30 +1851,53 @@ function checkGitHubConnection({ tenantRoot, env }) {
   if (!gh) {
     return providerConnectionResult("github", false, "GitHub CLI `gh` is not installed.");
   }
-  const repository = maybeResolveGitHubRepositorySlug(tenantRoot);
-  const args = repository ? ["repo", "view", repository, "--json", "nameWithOwner", "--jq", ".nameWithOwner"] : ["api", "user", "--jq", ".login"];
+  const identityMode = env.TREESEED_GITHUB_IDENTITY_MODE === "account" ? "account" : "repository";
+  const repository = identityMode === "repository" ? maybeResolveGitHubRepositorySlug(tenantRoot) : null;
+  const owner = typeof env.TREESEED_HOSTED_HUBS_GITHUB_OWNER === "string" ? env.TREESEED_HOSTED_HUBS_GITHUB_OWNER.trim() : "";
+  const commandCandidates = repository ? [{
+    args: ["repo", "view", repository, "--json", "nameWithOwner", "--jq", ".nameWithOwner"],
+    successMessage: (resolved) => `GitHub token can access ${resolved || repository}.`
+  }] : owner ? [
+    {
+      args: ["api", `orgs/${owner}`, "--jq", ".login"],
+      successMessage: (resolved) => `GitHub token can access organization ${resolved || owner}.`,
+      optional: true
+    },
+    {
+      args: ["api", `users/${owner}`, "--jq", ".login"],
+      successMessage: (resolved) => `GitHub token can access user ${resolved || owner}.`,
+      optional: true
+    }
+  ] : [
+    {
+      args: ["api", "user", "--jq", ".login"],
+      successMessage: (resolved) => resolved ? `Authenticated as ${resolved}.` : "GitHub API check succeeded."
+    }
+  ];
+  let lastDetail = "";
   for (let attempt = 0; attempt < 3; attempt += 1) {
-    const result = spawnSync(gh, args, {
-      cwd: tenantRoot,
-      stdio: "pipe",
-      encoding: "utf8",
-      env: createTreeseedManagedToolEnv({ ...process.env, ...env }),
-      timeout: CLI_CHECK_TIMEOUT_MS
-    });
-    if (result.status === 0) {
-      const resolved = result.stdout.trim();
-      return providerConnectionResult(
-        "github",
-        true,
-        repository ? `GitHub token can access ${resolved || repository}.` : resolved ? `Authenticated as ${resolved}.` : "GitHub API check succeeded."
-      );
+    for (const candidate of commandCandidates) {
+      const result = spawnSync(gh, candidate.args, {
+        cwd: tenantRoot,
+        stdio: "pipe",
+        encoding: "utf8",
+        env: createTreeseedManagedToolEnv({ ...process.env, ...env }),
+        timeout: CLI_CHECK_TIMEOUT_MS
+      });
+      if (result.status === 0) {
+        return providerConnectionResult("github", true, candidate.successMessage(result.stdout.trim()));
+      }
+      lastDetail = formatCheckOutput(result) || "GitHub API check failed.";
+      if (candidate.optional && !isTransientProviderConnectionError(lastDetail)) {
+        continue;
+      }
+      break;
     }
-    const detail = formatCheckOutput(result) || "GitHub API check failed.";
-    if (attempt >= 2 || !isTransientProviderConnectionError(detail)) {
-      return providerConnectionResult("github", false, detail);
+    if (attempt >= 2 || !isTransientProviderConnectionError(lastDetail)) {
+      return providerConnectionResult("github", false, lastDetail || "GitHub API check failed.");
     }
   }
-  return providerConnectionResult("github", false, "GitHub API check failed.");
+  return providerConnectionResult("github", false, lastDetail || "GitHub API check failed.");
 }
 function checkCloudflareConnection({ tenantRoot, env }) {
   if (!env.CLOUDFLARE_API_TOKEN) {
@@ -1964,8 +1987,22 @@ async function checkRailwayConnection({ tenantRoot, env }) {
 }
 async function checkTreeseedProviderConnections({ tenantRoot, scope = "prod", env = process.env, valuesOverlay = {} } = {}) {
   const values = collectTreeseedConfigSeedValues(tenantRoot, scope, env, valuesOverlay);
+  const passthroughValue = (key) => {
+    const overlayValue = valuesOverlay?.[key];
+    if (typeof overlayValue === "string" && overlayValue.trim()) {
+      return overlayValue.trim();
+    }
+    const envValue = env?.[key];
+    if (typeof envValue === "string" && envValue.trim()) {
+      return envValue.trim();
+    }
+    const resolvedValue = values?.[key];
+    return typeof resolvedValue === "string" && resolvedValue.trim() ? resolvedValue.trim() : void 0;
+  };
   const rawCommandEnv = {
     GH_TOKEN: values.GH_TOKEN,
+    TREESEED_GITHUB_IDENTITY_MODE: passthroughValue("TREESEED_GITHUB_IDENTITY_MODE"),
+    TREESEED_HOSTED_HUBS_GITHUB_OWNER: passthroughValue("TREESEED_HOSTED_HUBS_GITHUB_OWNER"),
     CLOUDFLARE_API_TOKEN: values.CLOUDFLARE_API_TOKEN,
     CLOUDFLARE_ACCOUNT_ID: values.CLOUDFLARE_ACCOUNT_ID,
     RAILWAY_API_TOKEN: values.RAILWAY_API_TOKEN,

package/dist/operations/services/hosting-audit.js

@@ -514,8 +514,14 @@ async function runTreeseedHostingAudit({
   const connectionReport = await checkTreeseedProviderConnections({
     tenantRoot,
     scope: resolved.scope,
-    env: values,
-    valuesOverlay: values
+    env: {
+      ...values,
+      TREESEED_GITHUB_IDENTITY_MODE: "account"
+    },
+    valuesOverlay: {
+      ...values,
+      TREESEED_GITHUB_IDENTITY_MODE: "account"
+    }
   });
   checks.push(...providerConnectionChecks(connectionReport, hostKinds));
   if (hostKinds.includes("email")) {

package/dist/reconcile/builtin-adapters.js

@@ -48,6 +48,8 @@ import {
   resolveRailwayWorkspaceContext,
   upsertRailwayVariables
 } from "../operations/services/railway-api.js";
+import { loadTreeseedReconcileState } from "./state.js";
+import { createTreeseedReconcileUnitId } from "./units.js";
 function toDeployTarget(target) {
   return target.kind === "persistent" ? createPersistentDeployTarget(target.scope) : createBranchPreviewDeployTarget(target.branchName);
 }
@@ -289,6 +291,28 @@ function storeCustomDomainState(input, provider, domain, value) {
 function getCustomDomainState(input, provider, domain) {
   return input.context.session.get(customDomainStateKey(provider, domain));
 }
+function getPersistedCustomDomainState(input, provider, domain) {
+  if (!domain) {
+    return null;
+  }
+  if (provider === "railway") {
+    try {
+      const state = loadTreeseedReconcileState(input.context.tenantRoot, input.context.target);
+      const unitId = createTreeseedReconcileUnitId("custom-domain:api", domain);
+      const unit = state.units[unitId];
+      const reconciled = unit?.lastReconciledState;
+      if (reconciled && typeof reconciled === "object" && reconciled.domain === domain) {
+        return reconciled;
+      }
+      const observed = unit?.lastObservedState;
+      if (observed && typeof observed === "object" && observed.domain === domain) {
+        return observed;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
 function listCloudflareDnsRecords(env, zoneId, recordName) {
   const query = recordName ? `?name=${encodeURIComponent(recordName)}` : "";
   const payload = cloudflareApiRequest(`/zones/${encodeURIComponent(zoneId)}/dns_records${query}`, {
@@ -402,22 +426,70 @@ function normalizeRailwayDomainDnsRecord(value) {
     status: typeof record.status === "string" ? record.status.trim().toUpperCase() : ""
   };
 }
+function firstRailwayDomainString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+function firstRailwayDomainArray(...values) {
+  for (const value of values) {
+    if (Array.isArray(value)) {
+      return value;
+    }
+  }
+  return [];
+}
 function normalizeRailwayDomainPayload(value) {
   if (!value || typeof value !== "object") {
     return null;
   }
   const record = value;
+  const status = record.status && typeof record.status === "object" ? record.status : {};
   const domain = typeof record.domain === "string" ? record.domain.trim() : typeof record.name === "string" ? record.name.trim() : "";
-  const dnsRecordCandidates = Array.isArray(record.dnsRecords) ? record.dnsRecords : Array.isArray(record.status?.dnsRecords) ? record.status.dnsRecords : [];
+  const serviceDomain = firstRailwayDomainString(
+    record.serviceDomain,
+    record.target,
+    record.targetDomain,
+    record.cnameTarget,
+    record.cname,
+    record.dnsTarget,
+    status.serviceDomain,
+    status.target,
+    status.targetDomain,
+    status.cnameTarget,
+    status.cname,
+    status.dnsTarget
+  );
+  const dnsRecordCandidates = firstRailwayDomainArray(
+    record.dnsRecords,
+    record.requiredDnsRecords,
+    record.requiredRecords,
+    record.records,
+    record.dns,
+    status.dnsRecords,
+    status.requiredDnsRecords,
+    status.requiredRecords,
+    status.records,
+    status.dns
+  );
   const dnsRecords = dnsRecordCandidates.map((entry) => normalizeRailwayDomainDnsRecord(entry)).filter(Boolean);
+  const effectiveDnsRecords = dnsRecords.length > 0 || !domain || !serviceDomain || serviceDomain === domain ? dnsRecords : [{
+    type: "CNAME",
+    name: domain,
+    content: serviceDomain,
+    status: ""
+  }];
   return {
     id: typeof record.id === "string" ? record.id.trim() : null,
     domain,
-    serviceDomain: typeof record.serviceDomain === "string" ? record.serviceDomain.trim() : typeof record.target === "string" ? record.target.trim() : null,
-    certificateStatus: typeof record.status?.certificateStatus === "string" ? String(record.status.certificateStatus).trim().toUpperCase() : null,
-    verificationDnsHost: typeof record.verificationDnsHost === "string" ? record.verificationDnsHost.trim() : typeof record.status?.verificationDnsHost === "string" ? String(record.status.verificationDnsHost).trim() : null,
-    verificationToken: typeof record.verificationToken === "string" ? record.verificationToken.trim() : typeof record.status?.verificationToken === "string" ? String(record.status.verificationToken).trim() : null,
-    dnsRecords
+    serviceDomain,
+    certificateStatus: typeof status.certificateStatus === "string" ? String(status.certificateStatus).trim().toUpperCase() : null,
+    verificationDnsHost: typeof record.verificationDnsHost === "string" ? record.verificationDnsHost.trim() : typeof status.verificationDnsHost === "string" ? String(status.verificationDnsHost).trim() : null,
+    verificationToken: typeof record.verificationToken === "string" ? record.verificationToken.trim() : typeof status.verificationToken === "string" ? String(status.verificationToken).trim() : null,
+    dnsRecords: effectiveDnsRecords
   };
 }
 async function ensureRailwayCustomDomain(input, service, domain, env, identifiers) {
@@ -1581,8 +1653,16 @@ function resolveDesiredDnsRecords(input) {
   if (!domain) {
     return [];
   }
-  const railwayState = getCustomDomainState(input, "railway", domain) ?? input.persistedState?.lastObservedState ?? input.persistedState?.lastReconciledState;
+  const railwayState = getCustomDomainState(input, "railway", domain) ?? getPersistedCustomDomainState(input, "railway", domain) ?? input.persistedState?.lastObservedState ?? input.persistedState?.lastReconciledState;
   const records = Array.isArray(railwayState?.dnsRecords) ? railwayState.dnsRecords.map((entry) => normalizeRailwayDomainDnsRecord(entry)).filter(Boolean) : [];
+  if (records.length === 0 && typeof railwayState?.serviceDomain === "string" && railwayState.serviceDomain.trim() && railwayState.serviceDomain.trim() !== domain) {
+    records.push({
+      type: "CNAME",
+      name: domain,
+      content: railwayState.serviceDomain.trim(),
+      status: ""
+    });
+  }
   const desiredRecords = records.map((record) => ({
     ...record,
     proxied: false
@@ -1685,8 +1765,9 @@ function verifyCustomDomainUnit(input) {
     }
     case "custom-domain:api": {
       const domain = String(input.unit.spec.domain ?? "").trim();
-      const live = getCustomDomainState(input, "railway", domain) ?? input.persistedState?.lastObservedState ?? input.persistedState?.lastReconciledState ?? null;
+      const live = getCustomDomainState(input, "railway", domain) ?? getPersistedCustomDomainState(input, "railway", domain) ?? input.persistedState?.lastObservedState ?? input.persistedState?.lastReconciledState ?? null;
       const dnsRecords = Array.isArray(live?.dnsRecords) ? live.dnsRecords : [];
+      const hasDnsRequirements = dnsRecords.length > 0 || typeof live?.serviceDomain === "string" && live.serviceDomain.trim().length > 0 || typeof live?.verificationDnsHost === "string" && live.verificationDnsHost.trim().length > 0 && typeof live?.verificationToken === "string" && live.verificationToken.trim().length > 0;
       return summarizeVerification(input.unit.unitId, [
         verificationCheck("custom-domain.exists", "Railway custom domain attachment exists", "cli", {
           exists: Boolean(live?.domain),
@@ -1695,10 +1776,13 @@ function verifyCustomDomainUnit(input) {
           issues: live?.domain ? [] : [`Railway custom domain ${domain || "(unset)"} is missing.`]
         }),
         verificationCheck("custom-domain.dns-requirements", "Railway custom domain exposes DNS requirements", "api", {
-          exists: dnsRecords.length > 0,
+          exists: hasDnsRequirements,
           expected: true,
-          observed: dnsRecords.length,
-          issues: dnsRecords.length > 0 ? [] : [`Railway custom domain ${domain || "(unset)"} did not expose DNS requirements.`]
+          observed: dnsRecords.length > 0 ? dnsRecords.length : {
+            serviceDomain: typeof live?.serviceDomain === "string" ? live.serviceDomain : null,
+            verificationDnsHost: typeof live?.verificationDnsHost === "string" ? live.verificationDnsHost : null
+          },
+          issues: hasDnsRequirements ? [] : [`Railway custom domain ${domain || "(unset)"} did not expose DNS requirements.`]
         })
       ]);
     }

package/dist/sdk-types.d.ts

@@ -394,21 +394,21 @@ export interface TaskCreditLedgerEntry {
     projectId: string;
     workDayId: string;
     taskId: string | null;
-    phase: 'seed' | 'settle' | 'refund' | 'grant' | 'reserve' | 'consume' | 'release' | 'adjustment';
+    phase: 'seed' | 'settle' | 'refund' | 'grant' | 'reserve' | 'consume' | 'release' | 'adjustment' | 'grant_created' | 'reservation_created' | 'reservation_released' | 'task_started' | 'task_completed_estimate_settlement' | 'task_completed_actual_settlement' | 'task_failed_refund' | 'manual_adjustment' | 'monthly_rollover' | 'overrun_hold';
     credits: number;
     metadata?: Record<string, unknown>;
     createdAt: string;
 }
 export type CapacityProviderKind = 'treeseed_managed' | 'team_owned' | 'external' | 'hybrid';
-export type CapacityProviderStatus = 'pending' | 'active' | 'paused' | 'configuration_required' | 'disabled';
+export type CapacityProviderStatus = 'pending' | 'credential_required' | 'registering' | 'active' | 'degraded' | 'draining' | 'paused' | 'configuration_required' | 'disabled' | 'failed';
 export type CapacityProviderBillingScope = 'treeseed' | 'team' | 'external';
 export type CapacityBusinessModel = 'subscription_quota' | 'token_metered' | 'hybrid_usage_based' | 'infrastructure_runtime' | 'custom';
 export type CapacityLaneUnit = 'treeseed_credit' | 'quota_minute' | 'token_usd' | 'github_ai_credit' | 'worker_second' | 'request' | 'custom';
 export type CapacityScarcityLevel = 'low' | 'medium' | 'high';
 export type CapacityGrantScope = 'team' | 'project' | 'workday' | 'overflow_pool';
 export type CapacityGrantState = 'active' | 'paused' | 'expired' | 'disabled';
-export type CapacityOverflowPolicy = 'hard_grant' | 'soft_grant' | 'weighted_fair_share' | 'approval_required';
-export type CapacityReservationState = 'reserved' | 'consumed' | 'released' | 'expired' | 'cancelled';
+export type CapacityOverflowPolicy = 'deny' | 'hard_grant' | 'soft_grant' | 'weighted_fair_share' | 'approval_required' | 'fallback_lane' | 'platform_subsidy';
+export type CapacityReservationState = 'reserved' | 'consuming' | 'consumed' | 'released' | 'expired' | 'cancelled' | 'failed' | 'overran_pending_approval';
 export type CapacityEstimatePhase = 'intent' | 'discovery' | 'plan' | 'execution' | 'actual';
 export type CapacityEstimateConfidence = 'low' | 'medium' | 'high';
 export type CapacityApprovalState = 'pending' | 'approved' | 'rejected' | 'expired' | 'superseded';
@@ -1667,6 +1667,7 @@ export interface RecordCapacityUsageRequest {
     usd?: number | null;
     source?: string;
     metadata?: Record<string, unknown> | null;
+    usageActual?: Record<string, unknown> | null;
 }
 export interface CreateCapacityRoutingDecisionRequest {
     id?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/sdk",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Shared Treeseed SDK for content-backed and D1-backed object models.",
   "license": "AGPL-3.0-only",
   "repository": {