@treeseed/sdk 0.12.62 → 0.13.0-rc.10

package/dist/agent-capacity/contracts/support/time-capacity.d.ts

@@ -0,0 +1,163 @@
+export declare const CAPACITY_BUDGET_SCHEMA: "treeseed.capacity-budget/v2";
+export interface CapacityTimeDimensions {
+    requestedSeconds: number;
+    /** Productive provider execution time. Preparation and closeout are separate. */
+    executionSeconds?: number;
+    preparationSeconds?: number;
+    closeoutSeconds?: number;
+    reservedSeconds: number;
+    activeSeconds: number;
+    elapsedSeconds: number;
+    releasedSeconds: number;
+    overrunSeconds: number;
+    hardDeadlineAt?: string | null;
+    authorityDeadlineAt?: string | null;
+    preparationStartedAt?: string | null;
+    preparationDeadlineAt?: string | null;
+    executionStartedAt?: string | null;
+    executionDeadlineAt?: string | null;
+    closeoutStartedAt?: string | null;
+    closeoutDeadlineAt?: string | null;
+    remainingSeconds?: number | null;
+    closeoutWarningSeconds?: number | null;
+}
+export type AssignmentTimePhase = 'preparation' | 'working' | 'closeout' | 'expired';
+export declare function assignmentTimeWindow(time: Partial<CapacityTimeDimensions>, nowMs?: number): {
+    phase: AssignmentTimePhase;
+    deadlineAt: string | null;
+    preparationRemainingSeconds: number | null;
+    executionRemainingSeconds: number | null;
+    closeoutRemainingSeconds: number | null;
+    shouldCloseOut: boolean;
+};
+export interface CapacityTokenDimensions {
+    inputTokens: number;
+    cachedInputTokens: number;
+    reasoningTokens: number;
+    outputTokens: number;
+    warningTokens?: number | null;
+    hardLimitTokens?: number | null;
+    hardLimitEnforceable: boolean;
+}
+export interface CapacityCostDimensions {
+    amount: number;
+    currency: string;
+    warningAmount?: number | null;
+    hardLimitAmount?: number | null;
+    hardLimitEnforceable: boolean;
+}
+export interface CapacityNativeDimensions {
+    unit: string;
+    observed: number;
+    cap?: number | null;
+    capEnforceable: boolean;
+}
+export interface CapacityBudgetV2 {
+    schemaVersion: typeof CAPACITY_BUDGET_SCHEMA;
+    time: CapacityTimeDimensions;
+    tokens: CapacityTokenDimensions;
+    cost?: CapacityCostDimensions | null;
+    native?: CapacityNativeDimensions[];
+    maxAttempts: number;
+    maxConcurrency?: number | null;
+    deadline: string;
+    pricingGeneration?: string | null;
+    enforcementConfidence?: 'exact' | 'bounded' | 'estimated' | 'opaque';
+    legacyAccounting?: Record<string, unknown> | null;
+}
+export declare const ASSIGNMENT_TERMINAL_DISPOSITIONS: readonly ["completed", "completed_early", "deadline_exhausted", "budget_exhausted", "blocked", "cancelled", "failed"];
+export type AssignmentTerminalDisposition = (typeof ASSIGNMENT_TERMINAL_DISPOSITIONS)[number];
+export interface AssignmentCompletionEvidence {
+    disposition: AssignmentTerminalDisposition;
+    acceptanceChecks: Array<{
+        id: string;
+        passed: boolean;
+        evidenceRefs?: string[];
+    }>;
+    durableArtifactRefs: string[];
+    remainingBudget: Partial<CapacityBudgetV2>;
+    completionReason: string;
+    noUsefulScopedWorkRemaining: boolean;
+}
+export declare const ASSIGNMENT_PERFORMANCE_SCHEMA: "treeseed.assignment-performance/v2";
+export interface AssignmentConfigurationAttribution {
+    planningGraphRevision: string | null;
+    agentDefinitionRevision: string | null;
+    agentClassRevision: string | null;
+    activityProfileRevision: string | null;
+    handlerRevision: string | null;
+    groupMembershipRevision: string | null;
+    executionProviderConfigurationRevision: string | null;
+}
+export interface AssignmentDownstreamOutcome {
+    kind: 'validation' | 'revision' | 'rejection' | 'review' | 'signal' | 'integration' | 'deployment';
+    status: string;
+    evidenceRefs: string[];
+    artifactMutationReceiptIds: string[];
+    proposalId?: string | null;
+    proposalVersion?: number | null;
+    occurredAt: string;
+}
+export interface AssignmentPerformanceSummary {
+    schemaVersion: typeof ASSIGNMENT_PERFORMANCE_SCHEMA;
+    assignmentId: string;
+    workdayId: string | null;
+    teamId: string;
+    projectId: string;
+    agentId: string | null;
+    agentClassId: string;
+    activityProfile: string;
+    handlerId: string | null;
+    capacityProviderId: string;
+    executionProviderId: string | null;
+    model: string | null;
+    groupIds: string[];
+    configuration: AssignmentConfigurationAttribution;
+    taskSignature: string;
+    disposition: AssignmentTerminalDisposition;
+    reason: string;
+    acceptanceChecks: AssignmentCompletionEvidence['acceptanceChecks'];
+    completedScope: string[];
+    remainingScope: string[];
+    artifactRefs: string[];
+    budget: CapacityBudgetV2;
+    actual: {
+        preparationSeconds: number;
+        executionSeconds: number;
+        closeoutSeconds: number;
+        custodySeconds: number;
+        activeSeconds: number;
+        elapsedSeconds: number;
+        inputTokens: number;
+        cachedInputTokens: number;
+        reasoningTokens: number;
+        outputTokens: number;
+        costAmount: number | null;
+        costCurrency: string | null;
+        native: CapacityNativeDimensions[];
+        attempts: number;
+    };
+    noUsefulScopedWorkRemaining: boolean;
+    agentAssessment: Record<string, unknown> | null;
+    systemAssessment: {
+        generatedBy: 'agent-runner' | 'api-recovery';
+        measuredAt: string;
+        enforcementConfidence: CapacityBudgetV2['enforcementConfidence'];
+    };
+    downstreamOutcomes: AssignmentDownstreamOutcome[];
+}
+export interface WorkdayTimePolicy {
+    cooperativePlanningPercent: number;
+    governedExecutionPercent: number;
+    reservePercent: number;
+}
+export declare function validateWorkdayTimePolicy(policy: WorkdayTimePolicy): {
+    ok: boolean;
+    diagnostics: Array<{
+        code: string;
+        path: string;
+        message: string;
+    }>;
+    value?: WorkdayTimePolicy;
+};
+export declare function emptyCapacityBudget(deadline: string, requestedSeconds: number): CapacityBudgetV2;

package/dist/agent-capacity/contracts/support/time-capacity.js

@@ -0,0 +1,63 @@
+const CAPACITY_BUDGET_SCHEMA = "treeseed.capacity-budget/v2";
+function assignmentTimeWindow(time, nowMs = Date.now()) {
+  const timestamp = (value) => typeof value === "string" && Number.isFinite(Date.parse(value)) ? Date.parse(value) : null;
+  const phased = time.preparationDeadlineAt !== void 0 || time.executionStartedAt !== void 0 || time.executionDeadlineAt !== void 0 || time.closeoutDeadlineAt !== void 0;
+  if (!phased) {
+    const deadline = timestamp(time.hardDeadlineAt);
+    const remaining2 = deadline === null ? null : Math.max(0, Math.floor((deadline - nowMs) / 1e3));
+    const warning = Number(time.closeoutWarningSeconds ?? 0);
+    const phase2 = remaining2 === 0 ? "expired" : remaining2 !== null && remaining2 <= warning ? "closeout" : "working";
+    return { phase: phase2, deadlineAt: typeof time.hardDeadlineAt === "string" ? time.hardDeadlineAt : null, preparationRemainingSeconds: 0, executionRemainingSeconds: phase2 === "working" ? remaining2 : 0, closeoutRemainingSeconds: phase2 === "closeout" ? remaining2 : 0, shouldCloseOut: phase2 === "closeout" || phase2 === "expired" };
+  }
+  const preparationDeadlineMs = timestamp(time.preparationDeadlineAt);
+  const executionStartedMs = timestamp(time.executionStartedAt);
+  const executionDeadlineMs = timestamp(time.executionDeadlineAt);
+  const closeoutDeadlineMs = timestamp(time.closeoutDeadlineAt ?? time.hardDeadlineAt);
+  let phase;
+  if (closeoutDeadlineMs !== null && nowMs >= closeoutDeadlineMs) phase = "expired";
+  else if (executionStartedMs === null) phase = preparationDeadlineMs !== null && nowMs >= preparationDeadlineMs ? "closeout" : "preparation";
+  else if (executionDeadlineMs !== null && nowMs >= executionDeadlineMs) phase = "closeout";
+  else phase = "working";
+  const remaining = (deadline) => deadline === null ? null : Math.max(0, Math.floor((deadline - nowMs) / 1e3));
+  return {
+    phase,
+    deadlineAt: phase === "preparation" ? time.preparationDeadlineAt ?? null : phase === "working" ? time.executionDeadlineAt ?? null : time.closeoutDeadlineAt ?? time.hardDeadlineAt ?? null,
+    preparationRemainingSeconds: phase === "preparation" ? remaining(preparationDeadlineMs) : 0,
+    executionRemainingSeconds: phase === "working" ? remaining(executionDeadlineMs) : phase === "preparation" ? Number(time.executionSeconds ?? time.requestedSeconds) : 0,
+    closeoutRemainingSeconds: phase === "closeout" ? remaining(closeoutDeadlineMs) : phase === "expired" ? 0 : Number(time.closeoutSeconds ?? time.closeoutWarningSeconds ?? 0),
+    shouldCloseOut: phase === "closeout" || phase === "expired"
+  };
+}
+const ASSIGNMENT_TERMINAL_DISPOSITIONS = [
+  "completed",
+  "completed_early",
+  "deadline_exhausted",
+  "budget_exhausted",
+  "blocked",
+  "cancelled",
+  "failed"
+];
+const ASSIGNMENT_PERFORMANCE_SCHEMA = "treeseed.assignment-performance/v2";
+function validateWorkdayTimePolicy(policy) {
+  const values = [policy.cooperativePlanningPercent, policy.governedExecutionPercent, policy.reservePercent];
+  if (values.some((value) => !Number.isFinite(value) || value < 0 || value > 100)) return { ok: false, diagnostics: [{ code: "workday_time_percent_invalid", path: "timePolicy", message: "Workday time percentages must be finite values from 0 through 100." }] };
+  if (Math.abs(values.reduce((sum, value) => sum + value, 0) - 100) >= 1e-6) return { ok: false, diagnostics: [{ code: "workday_time_total_invalid", path: "timePolicy", message: "Workday time percentages must total exactly 100%." }] };
+  return { ok: true, diagnostics: [], value: policy };
+}
+function emptyCapacityBudget(deadline, requestedSeconds) {
+  return {
+    schemaVersion: CAPACITY_BUDGET_SCHEMA,
+    time: { requestedSeconds, reservedSeconds: 0, activeSeconds: 0, elapsedSeconds: 0, releasedSeconds: 0, overrunSeconds: 0 },
+    tokens: { inputTokens: 0, cachedInputTokens: 0, reasoningTokens: 0, outputTokens: 0, hardLimitEnforceable: false },
+    maxAttempts: 1,
+    deadline
+  };
+}
+export {
+  ASSIGNMENT_PERFORMANCE_SCHEMA,
+  ASSIGNMENT_TERMINAL_DISPOSITIONS,
+  CAPACITY_BUDGET_SCHEMA,
+  assignmentTimeWindow,
+  emptyCapacityBudget,
+  validateWorkdayTimePolicy
+};

package/dist/agent-capacity/policy/capacity/allocations/allocation-hierarchy.d.ts

@@ -0,0 +1,29 @@
+import type { CapacityAdmissionCounterClaim, CapacityAdmissionReasonCode, CapacityAllocationSetV2 } from '../../../allocation.js';
+interface AllocationHierarchyInput {
+    allocation: CapacityAllocationSetV2;
+    workdayId: string;
+    totalSeconds: number;
+    requestedSeconds: number;
+    selectedSliceIds: string[];
+    committedBySlice: Record<string, number>;
+    committedBorrowedByRule?: Record<string, number>;
+    reserveCommittedSeconds?: number;
+    approvedBorrowingRuleIds?: string[];
+}
+export interface AllocationHierarchyDecision {
+    reasons: CapacityAdmissionReasonCode[];
+    explanation: Array<{
+        gate: string;
+        allowed: boolean;
+        remaining?: number;
+        detail?: string;
+    }>;
+    counterClaims: CapacityAdmissionCounterClaim[];
+    maxReservableSeconds: number;
+    requiresApproval: boolean;
+    calculations: Record<string, unknown>;
+    priorityBand: 'minimum' | 'target' | 'normal' | 'overflow';
+    priorityScore: number;
+}
+export declare function evaluateAllocationHierarchy(input: AllocationHierarchyInput): AllocationHierarchyDecision;
+export {};

package/dist/agent-capacity/policy/capacity/allocations/allocation-hierarchy.js

@@ -0,0 +1,110 @@
+function sliceLimits(allocation, totalSeconds, slice, cache = /* @__PURE__ */ new Map()) {
+  const cached = cache.get(slice.id);
+  if (cached) return cached;
+  const parent = slice.parentSliceId ? allocation.slices.find((candidate) => candidate.id === slice.parentSliceId) : null;
+  const basis = parent ? sliceLimits(allocation, totalSeconds, parent, cache).target : totalSeconds;
+  const limits = {
+    min: basis * slice.policy.minPercent / 100,
+    target: basis * slice.policy.targetPercent / 100,
+    max: basis * slice.policy.maxPercent / 100,
+    hard: basis * slice.policy.hardCapPercent / 100
+  };
+  cache.set(slice.id, limits);
+  return limits;
+}
+function claim(id, scope, scopeId, periodKey, hardLimit, amount) {
+  return amount > 0 ? { id, scope, scopeId, periodKey, hardLimit, amount, release: "settlement-difference" } : null;
+}
+function evaluateAllocationHierarchy(input) {
+  const reasons = [];
+  const explanation = [];
+  const counterClaims = [];
+  const calculations = {};
+  const approved = new Set(input.approvedBorrowingRuleIds ?? []);
+  const cache = /* @__PURE__ */ new Map();
+  let remaining = Number.POSITIVE_INFINITY;
+  let requiresApproval = false;
+  let priorityScore = 4;
+  for (const sliceId of input.selectedSliceIds) {
+    const slice = input.allocation.slices.find((candidate) => candidate.id === sliceId);
+    if (!slice) {
+      reasons.push("allocation_slice_missing");
+      explanation.push({ gate: `allocation:${sliceId}`, allowed: false, detail: "selected slice does not exist" });
+      continue;
+    }
+    const limits = sliceLimits(input.allocation, input.totalSeconds, slice, cache);
+    const committed = input.committedBySlice[sliceId] ?? 0;
+    const normalAvailable = Math.max(0, limits.max - committed);
+    const overflowAvailable = Math.max(0, limits.hard - Math.max(committed, limits.max));
+    let available = normalAvailable;
+    let overflowSource = "none";
+    let overflowRuleId = null;
+    let overflowSourceAvailable = 0;
+    if (overflowAvailable > 0) {
+      const rule = input.allocation.borrowingRules.find((candidate) => candidate.toSliceId === sliceId);
+      if (rule) {
+        const donor = input.allocation.slices.find((candidate) => candidate.id === rule.fromSliceId);
+        if (donor) {
+          const donorLimits = sliceLimits(input.allocation, input.totalSeconds, donor, cache);
+          const donorCommitted = input.committedBySlice[donor.id] ?? 0;
+          const donorAvailable = Math.max(0, donorLimits.target - Math.max(donorCommitted, donorLimits.min));
+          const ruleLimit = donorLimits.target * rule.maxPercent / 100;
+          const ruleAvailable = Math.max(0, ruleLimit - (input.committedBorrowedByRule?.[rule.id] ?? 0));
+          overflowSource = "borrowing-rule";
+          overflowRuleId = rule.id;
+          overflowSourceAvailable = Math.min(donorAvailable, ruleAvailable);
+        }
+      } else if (!slice.parentSliceId) {
+        overflowSource = "reserve";
+        overflowSourceAvailable = Math.max(0, input.totalSeconds * input.allocation.reservePolicy.percent / 100 - (input.reserveCommittedSeconds ?? 0));
+      }
+    }
+    const usableOverflow = Math.min(overflowAvailable, overflowSourceAvailable);
+    if (input.allocation.reservePolicy.overflow === "borrow") available += usableOverflow;
+    else if (input.requestedSeconds > normalAvailable && input.allocation.reservePolicy.overflow === "approval-required") {
+      requiresApproval = true;
+      reasons.push("allocation_borrowing_approval_required");
+    }
+    if (overflowRuleId) {
+      const rule = input.allocation.borrowingRules.find((candidate) => candidate.id === overflowRuleId);
+      if (rule.requiresApproval && !approved.has(rule.id) && input.requestedSeconds > normalAvailable) {
+        requiresApproval = true;
+        reasons.push("allocation_borrowing_approval_required");
+        available = normalAvailable;
+      }
+    }
+    if (input.requestedSeconds > available && !reasons.includes("allocation_borrowing_approval_required")) {
+      reasons.push(input.allocation.reservePolicy.overflow === "deny" ? "allocation_borrowing_denied" : "allocation_hard_cap_exhausted");
+    }
+    remaining = Math.min(remaining, available);
+    const ownAmount = Math.min(input.requestedSeconds, normalAvailable);
+    const overflowAmount = Math.max(0, input.requestedSeconds - ownAmount);
+    const ownClaim = claim(`allocation-slice:${input.allocation.id}:${slice.id}:${input.workdayId}`, "allocation-slice", `${input.allocation.id}:${slice.id}`, input.workdayId, limits.max, ownAmount);
+    if (ownClaim) counterClaims.push(ownClaim);
+    if (overflowAmount > 0 && overflowAmount <= usableOverflow && input.allocation.reservePolicy.overflow === "borrow") {
+      const overflowClaim = claim(`allocation-overflow:${input.allocation.id}:${slice.id}:${input.workdayId}`, "allocation-overflow", `${input.allocation.id}:${slice.id}`, input.workdayId, Math.max(0, limits.hard - limits.max), overflowAmount);
+      if (overflowClaim) counterClaims.push(overflowClaim);
+      if (overflowSource === "reserve") {
+        const reserveClaim = claim(`allocation-reserve:${input.allocation.id}:${input.workdayId}`, "allocation-reserve", input.allocation.id, input.workdayId, input.totalSeconds * input.allocation.reservePolicy.percent / 100, overflowAmount);
+        if (reserveClaim) counterClaims.push(reserveClaim);
+      } else if (overflowRuleId) {
+        const rule = input.allocation.borrowingRules.find((candidate) => candidate.id === overflowRuleId);
+        const donor = input.allocation.slices.find((candidate) => candidate.id === rule.fromSliceId);
+        const donorLimits = sliceLimits(input.allocation, input.totalSeconds, donor, cache);
+        const donorClaim = claim(`allocation-slice:${input.allocation.id}:${donor.id}:${input.workdayId}`, "allocation-slice", `${input.allocation.id}:${donor.id}`, input.workdayId, donorLimits.target, overflowAmount);
+        const ruleClaim = claim(`allocation-borrow:${input.allocation.id}:${rule.id}:${input.workdayId}`, "allocation-borrow", `${input.allocation.id}:${rule.id}`, input.workdayId, donorLimits.target * rule.maxPercent / 100, overflowAmount);
+        if (donorClaim) counterClaims.push(donorClaim);
+        if (ruleClaim) counterClaims.push(ruleClaim);
+      }
+    }
+    const position = committed < limits.min ? "below-minimum" : committed < limits.target ? "below-target" : committed < limits.max ? "above-target" : "overflow";
+    priorityScore = Math.min(priorityScore, position === "below-minimum" ? 4 : position === "below-target" ? 3 : position === "above-target" ? 2 : 1);
+    calculations[sliceId] = { committed, ...limits, normalAvailable, overflowAvailable, overflowSource, overflowSourceAvailable, usableOverflow, position };
+    explanation.push({ gate: `allocation:${sliceId}`, allowed: input.requestedSeconds <= available, remaining: available, detail: JSON.stringify(calculations[sliceId]) });
+  }
+  const priorityBand = priorityScore === 4 ? "minimum" : priorityScore === 3 ? "target" : priorityScore === 2 ? "normal" : "overflow";
+  return { reasons: [...new Set(reasons)], explanation, counterClaims, maxReservableSeconds: Number.isFinite(remaining) ? Math.max(0, remaining) : 0, requiresApproval, calculations, priorityBand, priorityScore };
+}
+export {
+  evaluateAllocationHierarchy
+};

package/dist/agent-capacity/validation/activity-profile.d.ts

@@ -0,0 +1,12 @@
+import { type AgentActivityProfile, type AgentActivityType } from '../../types/agents.js';
+export interface AgentActivityProfileDiagnostic {
+    code: string;
+    path: string;
+    message: string;
+}
+export interface AgentActivityProfileValidation {
+    ok: boolean;
+    diagnostics: AgentActivityProfileDiagnostic[];
+}
+export declare function validateAgentActivityProfilesConfiguration(value: unknown): AgentActivityProfileValidation;
+export type ValidAgentActivityProfilesConfiguration = Partial<Record<AgentActivityType, AgentActivityProfile>>;