Bridge SDK — API Reference

function createNitySession(config?: NityBridgeConfig): Promise<NitySessionHandle>

function dispatchTask(
  taskType: NityTaskType,
  prompt: string,
  context?: NityContext,
  options?: { role?: NityRole; maxPromptTokens?: number }
): string

function getToolName(taskType: NityTaskType): string

function isValidTaskType(taskType: string): taskType is NityTaskType

function validatePrompt(prompt: string): { valid: boolean; errors: string[] }

function optimizePrompt(prompt: string, maxTokens?: number): string

function selectRole(taskType: NityTaskType, explicitRole?: NityRole): NityRole

function resolveConfig(userConfig?: NityBridgeConfig): Required<NityBridgeConfig>

function getTierDefinition(tier: CostTier): TierDefinition

function getTierModels(tier: CostTier): TierModelConfig

function getAllTiers(): Record<CostTier, TierModelConfig>

function isValidCostTier(tier: string): tier is CostTier

function getCostIndicator(tier: CostTier): 'free' | 'low' | 'medium' | 'high'

function getModelCapabilities(model: string): ModelCapabilities | null

function modelHasCapability(model: string, capability: keyof ModelCapabilities): boolean

function matchModel(requiredCapabilities: string[], preferredTier: CostTier): string

function getFallbackChain(tier: CostTier): string[]

function getNextFallback(tier: CostTier, currentModel: string): string | null

function categorizeEvent(event: PiAgentEvent): EventCategory

function extractProgress(event: PiAgentEvent): NityProgress | null

function extractQualityGates(event: PiAgentEvent): { passed: boolean; details: string } | null

function extractReflection(event: PiAgentEvent): { lessons: string[]; followUps: string[] } | null

function extractEpisodeRefs(event: PiAgentEvent): string[]

function validateResult(result: NityResult): { valid: boolean; warnings: string[] }

function buildResult(
  taskType: NityTaskType,
  events: PiAgentEvent[],
  duration: number,
  error?: string
): NityResult

function createEventTransformer(
  taskType: NityTaskType
): (event: PiAgentEvent) => NityEvent | null

function createProgressThrottler(
  emit: (progress: NityProgress) => void,
  minIntervalMs?: number
): { push: (progress: NityProgress) => void; cancel: () => void; flush: () => void }

class NitySessionRegistry {
  register(clientId: string, session: NitySessionHandle): void
  unregister(sessionId: string): Promise<void>
  cleanupClient(clientId: string): Promise<number>
  getClientSessions(clientId: string): NitySessionHandle[]
  getSession(sessionId: string): NitySessionHandle | undefined
  getStats(): NitySessionRegistryStats
  cleanupStale(): Promise<number>
}

class CostTracker {
  constructor(options?: { budgetLimit?: number; budgetAlertThreshold?: number })
 
  recordTask(tier: CostTier, inputTokens: number, outputTokens: number): number
  recordSession(): void
  estimateCost(tier: CostTier, estimatedInputTokens: number, estimatedOutputTokens: number): NityCostEstimate
  isBudgetExceeded(): boolean
  onBudgetAlert(callback: (spent: number, limit: number) => void): void
  getReport(): NityCostReport
  getOptimizationSuggestions(): string[]
  reset(): void
}

class ProgressStore {
  record(taskId: string, progress: NityProgress): void
  getHistory(taskId: string): NityProgress[]
  getLatest(taskId: string): NityProgress | null
  clear(taskId: string): void
  clearAll(): void
}

interface NitySessionHandle {
  id: string;
  state: NitySessionState;
  sendTask(
    type: NityTaskType,
    prompt: string,
    context?: NityContext,
    options?: NityTaskOptions
  ): Promise<NityResult>;
  cancelTask(): void;
  isRunning(): boolean;
  subscribe(callback: (event: NityEvent) => void): () => void;
  close(): Promise<void>;
  getHealth(): {
    state: NitySessionState;
    errorCount: number;
    lastActivity: number;
    isTimedOut: boolean;
    uptime: number;
  };
}

interface NityBridgeConfig {
  costTier?: CostTier;                    // Model tier (default: 'free')
  orchestratorModel?: string;             // Override orchestrator model
  executorModel?: string;                 // Override executor model
  timeout?: number;                       // Session timeout in ms (default: 300000)
  maxRetries?: number;                    // Max retries on transient errors (default: 2)
  enableQualityGates?: boolean;           // Quality gate checks (default: true)
  enableReflection?: boolean;             // Post-task reflection (default: true)
  workingDirectory?: string;              // Working directory for execution
  enableFallback?: boolean;               // Fallback to standalone on Nity failure (default: true)
  contextProvider?: () => Promise<NityContext | undefined>;  // Auto-inject context
  budgetLimit?: number;                   // USD budget per session (0 = unlimited)
  budgetAlertThreshold?: number;          // Alert threshold in USD (0 = disabled)
  requiredCapabilities?: string[];        // Required model capabilities
  maxPromptTokens?: number;               // Token budget for prompt optimization (0 = unlimited)
}

interface NityResult {
  taskType: NityTaskType;
  success: boolean;
  output: string;
  duration: number;
  qualityReport?: QualityGateReport;
  reflection?: ReflectionRecord;
  episodeId?: string;
  error?: string;
  qualityGatePassed?: boolean;
}

interface NityContext {
  episodes?: Array<{ id: string; summary: string; outcome: string }>;
  memory?: {
    goal?: string;
    discoveries?: string[];
    workingSet?: string[];
  };
  skillHints?: Array<{ name: string; successRate: number }>;
  metadata?: Record<string, string>;
}

interface NityTaskOptions {
  signal?: AbortSignal;         // Cancellation signal
  priority?: NityTaskPriority;  // 'low' | 'normal' | 'high' | 'critical'
  role?: NityRole;              // Force a specific role
  cacheKey?: string;            // Enable result caching
  cacheMaxAge?: number;         // Cache TTL in ms (default: 300000)
}

type NityTaskType = 'analyze' | 'execute' | 'validate' | 'reflect' | 'skills';

type NityRole = 'pm' | 'coder' | 'auto';

type NityTaskPriority = 'low' | 'normal' | 'high' | 'critical';

type NitySessionState = 'idle' | 'active' | 'completed' | 'error';

type CostTier = 'free' | 'hybrid' | 'premium';

type NityEventType = 'session_start' | 'task_start' | 'task_progress' | 'task_complete' | 'task_error' | 'session_close';

interface NityEvent {
  type: NityEventType;
  timestamp: number;
  payload: Record<string, unknown>;
}

interface NityProgress {
  phase: string;
  percentage: number;
  delta?: string;
}

interface NityCostEstimate {
  estimatedCost: number;
  orchestratorModel: string;
  executorModel: string;
  tier: CostTier;
}

interface NityCostReport {
  totalSessions: number;
  totalTasks: number;
  totalCost: number;
  byTier: Record<CostTier, { tasks: number; cost: number }>;
  avgCostPerTask: number;
}