pi-harness-runtime 0.10.14 → 0.10.16

package/RFC/0052_SKILL_REGISTRY.md

@@ -1,167 +0,0 @@
-# RFC-0052 — Skill Registry
-
-Status: Draft  
-Target package: `packages/skill-registry`  
-Depends on: RFC-0051 Capability Registry
-
-## 1. Problem
-
-Agents need to discover and invoke skills dynamically. Currently skills are loaded statically. The Skill Registry provides a centralized system for discovering, loading, and invoking skills at runtime.
-
-## 2. Skill Contract
-
-```ts
-export interface Skill {
-  id: string;
-  name: string;
-  description: string;
-  version: string;
-  trigger: SkillTrigger;
-  handler: SkillHandler;
-  metadata: SkillMetadata;
-}
-
-export interface SkillTrigger {
-  type: "keyword" | "pattern" | "intent" | "tool_request";
-  value: string | RegExp | string[];
-  confidence?: number;
-}
-
-export interface SkillHandler {
-  (context: SkillContext): Promise<SkillResult>;
-}
-
-export interface SkillContext {
-  messages: CompactableMessage[];
-  task?: CompiledTask;
-  requirement?: CompiledRequirement;
-  tools: AvailableTool[];
-  metadata: Record<string, unknown>;
-}
-
-export interface SkillResult {
-  success: boolean;
-  output?: string;
-  toolCalls?: ToolCall[];
-  error?: string;
-  metadata?: Record<string, unknown>;
-}
-
-export interface SkillMetadata {
-  author?: string;
-  tags: string[];
-  examples?: string[];
-  requiresCapabilities?: Capability[];
-  deprecated?: boolean;
-}
-```
-
-## 3. Registry Interface
-
-```ts
-export interface SkillRegistry {
-  register(skill: Skill): void;
-  unregister(skillId: string): void;
-  get(skillId: string): Skill | undefined;
-  list(): Skill[];
-  find(trigger: SkillTrigger): Skill[];
-  invoke(skillId: string, context: SkillContext): Promise<SkillResult>;
-  invokeBestMatch(trigger: SkillTrigger, context: SkillContext): Promise<SkillResult>;
-}
-
-export interface SkillTrigger {
-  type: "keyword" | "pattern" | "intent" | "tool_request";
-  value: string | string[];
-  confidence?: number;
-}
-```
-
-## 4. Trigger Matching
-
-```ts
-export function matchTrigger(skill: Skill, input: string): number {
-  switch (skill.trigger.type) {
-    case "keyword":
-      return skill.trigger.value
-        .split(" ")
-        .filter(k => input.toLowerCase().includes(k.toLowerCase())).length;
-    
-    case "pattern":
-      const regex = new RegExp(skill.trigger.value);
-      return regex.test(input) ? 1 : 0;
-    
-    case "intent":
-      const intents = Array.isArray(skill.trigger.value) 
-        ? skill.trigger.value 
-        : [skill.trigger.value];
-      return intents.some(i => input.toLowerCase().includes(i.toLowerCase())) ? 1 : 0;
-    
-    case "tool_request":
-      return input.toLowerCase().includes("tool") ? 1 : 0;
-    
-    default:
-      return 0;
-  }
-}
-
-export function findBestMatch(
-  skills: Skill[], 
-  input: string,
-  minConfidence = 0.5,
-): Skill | undefined {
-  const matches = skills
-    .map(s => ({ skill: s, score: matchTrigger(s, input) }))
-    .filter(m => m.score >= (s.trigger.confidence ?? 0.5))
-    .sort((a, b) => b.score - a.score);
-  
-  return matches[0]?.skill;
-}
-```
-
-## 5. Default Skills
-
-```ts
-export const DEFAULT_SKILLS: Skill[] = [
-  {
-    id: "skill-registry-introspect",
-    name: "Introspect Skill Registry",
-    description: "Lists all registered skills and their triggers",
-    version: "1.0.0",
-    trigger: { type: "keyword", value: "list skills", confidence: 0.8 },
-    handler: async (ctx) => {
-      const skills = ctx.metadata.registry.list();
-      return {
-        success: true,
-        output: JSON.stringify(skills, null, 2),
-      };
-    },
-    metadata: { tags: ["meta", "debug"], examples: ["list skills"] },
-  },
-];
-```
-
-## 6. Events
-
-```ts
-type SkillRegistryEvent =
-  | { type: "skill.registered"; skillId: string; name: string }
-  | { type: "skill.unregistered"; skillId: string }
-  | { type: "skill.invoked"; skillId: string; success: boolean; duration: number }
-  | { type: "skill.error"; skillId: string; error: string };
-```
-
-## 7. Integration Points
-
-- Agent Worker uses Skill Registry to find relevant skills
-- Context Compiler can inject skill results into prompts
-- Task Compiler may reference skills for specialized tasks
-
-## 8. Acceptance Criteria
-
-- Skills can be registered and unregistered at runtime
-- Trigger matching works for keywords, patterns, and intents
-- Best match returns highest-scoring skill
-- Skill handler receives full context
-- Default skills are loaded on initialization
-- Events are emitted for all operations
-- Unit tests cover all matching scenarios

package/RFC/0053_MODEL_REGISTRY.md

@@ -1,214 +0,0 @@
-# RFC-0053 — Model Registry
-
-Status: Draft  
-Target package: `packages/model-registry`  
-Depends on: RFC-0051 Capability Registry
-
-## 1. Problem
-
-The runtime needs a centralized registry of available AI models with their properties (pricing, limits, capabilities). Currently model info is scattered. The Model Registry provides a single source of truth for model metadata.
-
-## 2. Model Definition
-
-```ts
-export interface ModelInfo {
-  id: string;
-  providerId: string;
-  name: string;
-  version?: string;
-  contextWindow: number;
-  maxOutputTokens: number;
-  pricing: Pricing;
-  capabilities: string[]; // references to Capability IDs
-  aliases: string[];
-  status: "active" | "deprecated" | "disabled";
-  releasedAt?: string;
-  deprecatedAt?: string;
-}
-
-export interface Pricing {
-  currency: "USD" | "THB";
-  inputPer1M: number;  // cost per 1M input tokens
-  outputPer1M: number; // cost per 1M output tokens
-  batchInputPer1M?: number;
-  cacheReadPer1M?: number;
-  cacheWritePer1M?: number;
-}
-```
-
-## 3. Registry Interface
-
-```ts
-export interface ModelRegistry {
-  register(model: ModelInfo): void;
-  unregister(providerId: string, modelId: string): void;
-  get(providerId: string, modelId: string): ModelInfo | undefined;
-  getByAlias(alias: string): ModelInfo | undefined;
-  list(providerId?: string): ModelInfo[];
-  listActive(): ModelInfo[];
-  find(filters: ModelFilters): ModelInfo[];
-  updateStatus(providerId: string, modelId: string, status: ModelInfo["status"]): void;
-}
-
-export interface ModelFilters {
-  providerId?: string;
-  minContextWindow?: number;
-  maxCostPer1M?: number;
-  capabilities?: string[];
-  status?: ModelInfo["status"];
-}
-```
-
-## 4. Default Models
-
-```ts
-export const DEFAULT_MODELS: ModelInfo[] = [
-  {
-    id: "gpt-4o",
-    providerId: "openai",
-    name: "GPT-4o",
-    contextWindow: 128000,
-    maxOutputTokens: 16384,
-    pricing: { currency: "USD", inputPer1M: 5, outputPer1M: 15 },
-    capabilities: ["code_generation", "code_review", "vision", "function_calling"],
-    aliases: ["gpt4o", "gpt-4o"],
-    status: "active",
-  },
-  {
-    id: "claude-sonnet-4",
-    providerId: "anthropic",
-    name: "Claude Sonnet 4",
-    contextWindow: 200000,
-    maxOutputTokens: 8192,
-    pricing: { currency: "USD", inputPer1M: 3, outputPer1M: 15 },
-    capabilities: ["code_generation", "code_review", "planning", "vision"],
-    aliases: ["sonnet", "claude-sonnet"],
-    status: "active",
-  },
-  {
-    id: "claude-opus-4",
-    providerId: "anthropic",
-    name: "Claude Opus 4",
-    contextWindow: 200000,
-    maxOutputTokens: 8192,
-    pricing: { currency: "USD", inputPer1M: 15, outputPer1M: 75 },
-    capabilities: ["code_generation", "planning", "analysis"],
-    aliases: ["opus", "claude-opus"],
-    status: "active",
-  },
-  {
-    id: "MiniMax-Text-01",
-    providerId: "minimax",
-    name: "MiniMax Text 01",
-    contextWindow: 1000000,
-    maxOutputTokens: 8192,
-    pricing: { 
-      currency: "USD", 
-      inputPer1M: 0.1, 
-      outputPer1M: 0.5,
-      batchInputPer1M: 0.01,
-    },
-    capabilities: ["code_generation", "function_calling"],
-    aliases: ["minimax", "minimax-text"],
-    status: "active",
-  },
-];
-```
-
-## 5. Query Algorithm
-
-```ts
-export function findModels(
-  registry: ModelRegistry,
-  filters: ModelFilters,
-): ModelInfo[] {
-  let models = registry.listActive();
-  
-  if (filters.providerId) {
-    models = models.filter(m => m.providerId === filters.providerId);
-  }
-  
-  if (filters.minContextWindow) {
-    models = models.filter(m => m.contextWindow >= filters.minContextWindow!);
-  }
-  
-  if (filters.maxCostPer1M !== undefined) {
-    models = models.filter(m => 
-      (m.pricing.inputPer1M + m.pricing.outputPer1M) <= filters.maxCostPer1M!
-    );
-  }
-  
-  if (filters.capabilities?.length) {
-    models = models.filter(m =>
-      filters.capabilities!.every(c => m.capabilities.includes(c))
-    );
-  }
-  
-  if (filters.status) {
-    models = models.filter(m => m.status === filters.status);
-  }
-  
-  return models.sort((a, b) => {
-    const costA = a.pricing.inputPer1M + a.pricing.outputPer1M;
-    const costB = b.pricing.inputPer1M + b.pricing.outputPer1M;
-    return costA - costB;
-  });
-}
-```
-
-## 6. Cost Calculation
-
-```ts
-export function calculateCost(
-  model: ModelInfo,
-  inputTokens: number,
-  outputTokens: number,
-  options?: {
-    useBatch?: boolean;
-    cacheReadTokens?: number;
-    cacheWriteTokens?: number;
-  },
-): number {
-  const base = (inputTokens / 1_000_000) * model.pricing.inputPer1M
-    + (outputTokens / 1_000_000) * model.pricing.outputPer1M;
-  
-  let total = base;
-  
-  if (options?.useBatch && model.pricing.batchInputPer1M) {
-    const batchSavings = (inputTokens / 1_000_000) 
-      * (model.pricing.inputPer1M - model.pricing.batchInputPer1M);
-    total -= batchSavings;
-  }
-  
-  if (options?.cacheReadTokens && model.pricing.cacheReadPer1M) {
-    total += (options.cacheReadTokens / 1_000_000) * model.pricing.cacheReadPer1M;
-  }
-  
-  if (options?.cacheWriteTokens && model.pricing.cacheWritePer1M) {
-    total += (options.cacheWriteTokens / 1_000_000) * model.pricing.cacheWritePer1M;
-  }
-  
-  return Math.round(total * 100) / 100; // round to cents
-}
-```
-
-## 7. Events
-
-```ts
-type ModelRegistryEvent =
-  | { type: "model.registered"; providerId: string; modelId: string }
-  | { type: "model.unregistered"; providerId: string; modelId: string }
-  | { type: "model.status_changed"; providerId: string; modelId: string; status: string }
-  | { type: "model.queried"; filters: ModelFilters; results: number };
-```
-
-## 8. Acceptance Criteria
-
-- Models can be registered and unregistered
-- Alias lookup works correctly
-- Filters return correctly filtered and sorted results
-- Cost calculation handles all pricing components
-- Default models are loaded on initialization
-- Status changes are tracked
-- Events are emitted for all operations
-- Unit tests cover all query scenarios

package/RFC/0054_PROVIDER_ROUTER.md

@@ -1,239 +0,0 @@
-# RFC-0054 — Provider Router
-
-Status: Draft  
-Target package: `packages/provider-router`  
-Depends on: RFC-0051 Capability Registry, RFC-0053 Model Registry
-
-## 1. Problem
-
-The SimpleProviderRouter exists but lacks:
-
-- Capability-based filtering
-- Cost-aware routing
-- Quota-aware selection
-- Multi-criteria optimization
-
-The Enhanced Provider Router provides intelligent routing based on task requirements, model capabilities, cost constraints, and provider availability.
-
-## 2. Router Interface
-
-```ts
-export interface ProviderRouter {
-  selectProvider(
-    task: RuntimeTask,
-    context: RoutingContext,
-    options?: RoutingOptions,
-  ): Promise<RoutingDecision>;
-  
-  selectProviders(
-    task: RuntimeTask,
-    context: RoutingContext,
-    count: number,
-  ): Promise<RoutingDecision[]>;
-  
-  getRoutingPolicy(): RoutingPolicy;
-  setRoutingPolicy(policy: RoutingPolicy): void;
-}
-
-export interface RoutingContext {
-  task: RuntimeTask;
-  requirement: CompiledRequirement;
-  providerStates: Record<string, ProviderState>;
-  quotaStates: Record<string, QuotaState>;
-  costBudget?: CostBudget;
-}
-
-export interface RoutingOptions {
-  preferCheapest?: boolean;
-  preferFastest?: boolean;
-  preferHighestQuality?: boolean;
-  maxCostPerTask?: number;
-  requiredCapabilities?: Capability[];
-  preferProviders?: string[];
-  avoidProviders?: string[];
-}
-
-export interface RoutingDecision {
-  providerId: string;
-  modelId: string;
-  reason: string;
-  estimatedCost?: number;
-  estimatedLatency?: "fast" | "medium" | "slow";
-  confidence: number;
-}
-```
-
-## 3. Routing Policy
-
-```ts
-export interface RoutingPolicy {
-  defaultStrategy: RoutingStrategy;
-  costWeight: number;      // 0-100
-  qualityWeight: number;   // 0-100
-  latencyWeight: number;   // 0-100
-  quotaWeight: number;      // 0-100
-  fallbackProviders: string[];
-  taskTypeOverrides: Record<string, RoutingStrategy>;
-  providerPreferences: Record<string, number>;
-}
-
-export type RoutingStrategy =
-  | "cheapest"
-  | "fastest"
-  | "best_quality"
-  | "balanced"
-  | "quota_aware";
-```
-
-## 4. Selection Algorithm
-
-```ts
-export async function selectProvider(
-  router: ProviderRouter,
-  task: RuntimeTask,
-  context: RoutingContext,
-  options?: RoutingOptions,
-): Promise<RoutingDecision> {
-  const policy = router.getRoutingPolicy();
-  const strategy = policy.taskTypeOverrides[task.type] ?? policy.defaultStrategy;
-  
-  // Get all candidates
-  let candidates = await getEligibleCandidates(task, context, options);
-  
-  // Filter by capabilities
-  if (options?.requiredCapabilities?.length) {
-    candidates = candidates.filter(c => 
-      options.requiredCapabilities!.every(cap => 
-        c.capabilities.includes(cap)
-      )
-    );
-  }
-  
-  // Filter by cost
-  if (options?.maxCostPerTask) {
-    candidates = candidates.filter(c => 
-      (c.estimatedCost ?? Infinity) <= options.maxCostPerTask!
-    );
-  }
-  
-  // Filter by quota
-  candidates = candidates.filter(c => {
-    const quota = context.quotaStates[c.providerId];
-    return !quota || !quota.exhausted;
-  });
-  
-  if (candidates.length === 0) {
-    throw new Error(`No eligible providers for task ${task.id}`);
-  }
-  
-  // Apply strategy
-  return applyStrategy(candidates, strategy, policy, options);
-}
-
-function applyStrategy(
-  candidates: ProviderCandidate[],
-  strategy: RoutingStrategy,
-  policy: RoutingPolicy,
-  options?: RoutingOptions,
-): RoutingDecision {
-  switch (strategy) {
-    case "cheapest":
-      return candidates
-        .sort((a, b) => (a.estimatedCost ?? 0) - (b.estimatedCost ?? 0))[0];
-    
-    case "fastest":
-      return candidates
-        .sort((a, b) => LATENCY_RANK[a.estimatedLatency] - LATENCY_RANK[b.estimatedLatency])[0];
-    
-    case "best_quality":
-      return candidates
-        .sort((a, b) => (b.qualityScore ?? 0) - (a.qualityScore ?? 0))[0];
-    
-    case "balanced":
-      return candidates
-        .sort((a, b) => {
-          const scoreA = calculateWeightedScore(a, policy);
-          const scoreB = calculateWeightedScore(b, policy);
-          return scoreB - scoreA;
-        })[0];
-    
-    case "quota_aware":
-      return candidates
-        .sort((a, b) => {
-          const quotaA = a.remainingQuotaPct ?? 1;
-          const quotaB = b.remainingQuotaPct ?? 1;
-          const costA = a.estimatedCost ?? Infinity;
-          const costB = b.estimatedCost ?? Infinity;
-          return (quotaA / costA) - (quotaB / costB);
-        })[0];
-  }
-}
-
-function calculateWeightedScore(
-  candidate: ProviderCandidate,
-  policy: RoutingPolicy,
-): number {
-  const costScore = 100 - Math.min(candidate.estimatedCost ?? 0, 100);
-  const qualityScore = candidate.qualityScore ?? 50;
-  const latencyScore = 100 - (LATENCY_RANK[candidate.estimatedLatency] * 33);
-  const quotaScore = (candidate.remainingQuotaPct ?? 1) * 100;
-  
-  return (
-    (costScore * policy.costWeight +
-      qualityScore * policy.qualityWeight +
-      latencyScore * policy.latencyWeight +
-      quotaScore * policy.quotaWeight) /
-    (policy.costWeight + policy.qualityWeight + policy.latencyWeight + policy.quotaWeight)
-  );
-}
-```
-
-## 5. Default Policy
-
-```ts
-export const DEFAULT_ROUTING_POLICY: RoutingPolicy = {
-  defaultStrategy: "balanced",
-  costWeight: 30,
-  qualityWeight: 40,
-  latencyWeight: 20,
-  quotaWeight: 10,
-  fallbackProviders: ["anthropic", "openai"],
-  taskTypeOverrides: {
-    "planning": "best_quality",
-    "code_generation": "balanced",
-    "code_review": "best_quality",
-    "test_generation": "fastest",
-    "e2e_testing": "quota_aware",
-    "analysis": "best_quality",
-    "refactoring": "balanced",
-    "debugging": "fastest",
-    "documentation": "cheapest",
-  },
-  providerPreferences: {
-    "minimax": 20,   // prefer cheaper options
-    "openai": 0,
-    "anthropic": 10,
-  },
-};
-```
-
-## 6. Events
-
-```ts
-type ProviderRouterEvent =
-  | { type: "router.provider_selected"; taskId: string; providerId: string; reason: string }
-  | { type: "router.no_candidates"; taskId: string; reason: string }
-  | { type: "router.policy_updated"; oldPolicy: RoutingPolicy; newPolicy: RoutingPolicy }
-  | { type: "router.fallback_triggered"; taskId: string; originalProvider: string; fallbackProvider: string };
-```
-
-## 7. Acceptance Criteria
-
-- Routing respects task type and capabilities
-- Strategy selection works for all strategies
-- Cost and quota filters are applied correctly
-- Weighted scoring produces reasonable results
-- Fallback providers are used when needed
-- Events are emitted for all routing decisions
-- Unit tests cover all strategies and scenarios
-- Integration with Capability Registry and Model Registry works