@cuylabs/agent-core 0.4.0 → 0.5.0

package/dist/registry-CuRWWtcT.d.ts

@@ -0,0 +1,164 @@
+import { S as SkillDiscoveryResult, a as SkillMetadata, b as SkillContent, c as SkillResource, d as SkillConfig } from './tool-pFAnJc5Y.js';
+
+/**
+ * Skill Registry — in-memory store for discovered skills
+ *
+ * The registry is the central coordination point for the skill system.
+ * It holds discovered metadata (L1), handles on-demand content loading
+ * (L2/L3), provides the prompt summary for injection, and manages
+ * the lifecycle of skill state.
+ *
+ * ```
+ *   discoverSkills() → SkillRegistry → promptSummary (L1 → system prompt)
+ *                                     → loadSkill()   (L2 → tool response)
+ *                                     → loadResource  (L3 → tool response)
+ * ```
+ *
+ * The registry is designed to be created once per agent and shared
+ * across the agent's lifetime, including across forked sub-agents.
+ *
+ * @example
+ * ```typescript
+ * const registry = await createSkillRegistry("/path/to/project", {
+ *   externalDirs: [".agents", ".claude"],
+ * });
+ *
+ * // L1: summary goes into system prompt
+ * const summary = registry.formatSummary();
+ *
+ * // L2: agent calls skill tool → full content loaded
+ * const content = await registry.loadContent("testing");
+ *
+ * // L3: agent reads a bundled reference
+ * const ref = await registry.loadResource("testing", "references/patterns.md");
+ * ```
+ */
+
+/**
+ * In-memory registry of discovered skills with lazy content loading.
+ *
+ * Holds L1 metadata for all skills. Content (L2) and resources (L3)
+ * are loaded on demand and cached for the registry's lifetime.
+ */
+declare class SkillRegistry {
+    /** All discovered skill metadata indexed by name */
+    private readonly skills;
+    /** Cached full content for skills that have been loaded */
+    private readonly contentCache;
+    /** Discovery metadata */
+    readonly discoveryResult: SkillDiscoveryResult;
+    constructor(discoveryResult: SkillDiscoveryResult);
+    /** Get a skill's metadata by name. Returns undefined if not found. */
+    get(name: string): SkillMetadata | undefined;
+    /** Check if a skill exists by name. */
+    has(name: string): boolean;
+    /** Get all skill metadata entries. */
+    list(): SkillMetadata[];
+    /** Number of registered skills. */
+    get size(): number;
+    /** Skill names as an array. */
+    get names(): string[];
+    /**
+     * Load a skill's full content (L2: body + resource listing).
+     *
+     * Results are cached — subsequent calls return the cached content
+     * without re-reading the filesystem.
+     *
+     * @param name Skill name
+     * @returns Full skill content, or null if the skill doesn't exist
+     */
+    loadContent(name: string): Promise<SkillContent | null>;
+    /**
+     * Load a specific bundled resource from a skill (L3).
+     *
+     * The skill's content must be loaded first (via `loadContent`)
+     * so the resource listing is available.
+     *
+     * @param skillName  Skill name
+     * @param relativePath  Relative path to the resource within the skill dir
+     * @returns Resource file content as UTF-8 string
+     * @throws If the skill or resource doesn't exist
+     */
+    loadResource(skillName: string, relativePath: string): Promise<string>;
+    /**
+     * Get the list of resources for a loaded skill.
+     *
+     * @param name Skill name
+     * @returns Resource list, or empty array if skill isn't loaded yet
+     */
+    getResources(name: string): SkillResource[];
+    /**
+     * Format a summary of all available skills for injection into the system prompt.
+     *
+     * This is the L1 layer — the agent sees names and descriptions of all
+     * available skills, enabling it to decide which to activate via tool calls.
+     *
+     * The output format uses XML tags (consistent with the instruction format
+     * in `formatInstructions`) for clear delineation in the prompt.
+     *
+     * Returns empty string if no skills are available.
+     *
+     * @example Output:
+     * ```xml
+     * <available-skills>
+     *
+     * You have access to the following skills. To activate a skill and load its
+     * full instructions, call the `skill` tool with the skill's name.
+     *
+     * <skill name="testing" scope="project">
+     * Write comprehensive test suites with vitest, covering unit, integration,
+     * and snapshot testing patterns.
+     * </skill>
+     *
+     * <skill name="frontend-design" scope="user">
+     * Create distinctive, production-grade frontend interfaces with high design quality.
+     * </skill>
+     *
+     * </available-skills>
+     * ```
+     */
+    formatSummary(): string;
+    /**
+     * Format the full content of a loaded skill for a tool response.
+     *
+     * Wraps the skill body in XML with metadata, and lists bundled resources
+     * so the agent knows what's available at L3.
+     *
+     * @param content Previously loaded skill content
+     * @returns Formatted string for tool response
+     */
+    formatContent(content: SkillContent): string;
+    /** Clear the content cache, forcing reloads on next access. */
+    clearContentCache(): void;
+    /** Check if a skill's content has been loaded and cached. */
+    isContentLoaded(name: string): boolean;
+}
+/**
+ * Create a skill registry by discovering all available skills.
+ *
+ * This is the recommended way to initialize the skill system.
+ * It runs discovery, deduplicates by scope priority, and returns
+ * a ready-to-use registry.
+ *
+ * @param cwd     Current working directory
+ * @param config  Skill configuration
+ * @returns A populated SkillRegistry
+ *
+ * @example
+ * ```typescript
+ * const registry = await createSkillRegistry("/path/to/project", {
+ *   externalDirs: [".agents", ".claude"],
+ *   roots: ["./company-skills"],
+ * });
+ *
+ * console.log(`Found ${registry.size} skills`);
+ * console.log(registry.formatSummary());
+ * ```
+ */
+declare function createSkillRegistry(cwd: string, config?: SkillConfig): Promise<SkillRegistry>;
+/**
+ * Create an empty skill registry (for agents that don't use skills).
+ */
+declare function emptySkillRegistry(): SkillRegistry;
+
+export { SkillRegistry as S, createSkillRegistry as c, emptySkillRegistry as e };

package/dist/resolver-DOfZ-xuk.d.ts

@@ -0,0 +1,254 @@
+import { LanguageModel } from 'ai';
+
+/**
+ * Model Capability Types for @cuylabs/agent-core
+ *
+ * Defines the structure for model capabilities that can be sourced from
+ * static patterns, local cache, or remote APIs.
+ */
+/**
+ * Input modalities a model can accept
+ */
+type InputModality = "text" | "image" | "audio" | "video" | "pdf";
+/**
+ * Output modalities a model can produce
+ */
+type OutputModality = "text" | "image" | "audio" | "video";
+/**
+ * Comprehensive model capabilities
+ */
+interface ModelCapabilities {
+    /** Model supports extended reasoning/thinking */
+    reasoning: boolean;
+    /** Model supports function/tool calling */
+    toolCalling: boolean;
+    /** Model supports temperature adjustment */
+    temperature: boolean;
+    /** Model supports file attachments */
+    attachments: boolean;
+    /** Model supports streaming responses */
+    streaming: boolean;
+    /** Supported input modalities */
+    inputModalities: InputModality[];
+    /** Supported output modalities */
+    outputModalities: OutputModality[];
+    /** Maximum context window in tokens */
+    contextWindow?: number;
+    /** Maximum output tokens */
+    maxOutput?: number;
+}
+/**
+ * Provider-specific compatibility flags
+ * These handle quirks in different provider implementations
+ */
+interface ProviderCompatibility {
+    /** Supports OpenAI-style reasoning_effort parameter */
+    supportsReasoningEffort?: boolean;
+    /** Supports developer/system role distinction */
+    supportsDeveloperRole?: boolean;
+    /** Field name for max tokens (varies by provider) */
+    maxTokensField?: "max_tokens" | "max_completion_tokens";
+    /** Requires thinking as text tags vs structured */
+    requiresThinkingTags?: boolean;
+    /** Provider-specific thinking format */
+    thinkingFormat?: "openai" | "anthropic" | "google" | "zai";
+}
+/**
+ * Complete model entry with metadata
+ */
+interface ModelEntry {
+    /** Model identifier (e.g., "gpt-4o", "claude-sonnet-4") */
+    id: string;
+    /** Human-readable model name */
+    name: string;
+    /** Provider identifier (e.g., "openai", "anthropic") */
+    provider: string;
+    /** Model capabilities */
+    capabilities: ModelCapabilities;
+    /** Provider-specific compatibility settings */
+    compatibility?: ProviderCompatibility;
+    /** Cost per million tokens (input) */
+    costInput?: number;
+    /** Cost per million tokens (output) */
+    costOutput?: number;
+    /** When this entry was last updated */
+    updatedAt?: string;
+}
+/**
+ * Priority levels for capability sources
+ */
+declare enum SourcePriority {
+    /** User configuration overrides everything */
+    UserConfig = 0,
+    /** Local cache from previous fetch */
+    LocalCache = 1,
+    /** Bundled static data (build-time) */
+    BundledData = 2,
+    /** Pattern-based inference (fallback) */
+    PatternMatch = 3,
+    /** Remote API (if network available) */
+    RemoteAPI = 4
+}
+/**
+ * Result from a capability source lookup
+ */
+interface SourceResult {
+    /** The model entry if found */
+    entry?: ModelEntry;
+    /** Which source provided this result */
+    source: SourcePriority;
+    /** Whether this is a confident match */
+    confident: boolean;
+    /** Error message if lookup failed */
+    error?: string;
+}
+/**
+ * Capability source interface
+ */
+interface CapabilitySource {
+    /** Source priority (lower = higher priority) */
+    priority: SourcePriority;
+    /** Human-readable source name */
+    name: string;
+    /** Look up capabilities for a model */
+    lookup(modelId: string, provider?: string): Promise<SourceResult>;
+    /** Check if this source is available */
+    isAvailable(): Promise<boolean>;
+}
+/**
+ * Options for the capability resolver
+ */
+interface ResolverOptions {
+    /** Enable remote API fetching (default: false) */
+    enableRemoteFetch?: boolean;
+    /** Remote API URL (default: https://models.dev) */
+    remoteApiUrl?: string;
+    /** Cache directory path */
+    cachePath?: string;
+    /** Cache TTL in milliseconds (default: 1 hour) */
+    cacheTtlMs?: number;
+    /** Network timeout in milliseconds (default: 10 seconds) */
+    networkTimeoutMs?: number;
+    /** Custom user overrides for specific models */
+    modelOverrides?: Record<string, Partial<ModelCapabilities>>;
+}
+/**
+ * Default resolver options
+ */
+declare const DEFAULT_RESOLVER_OPTIONS: Required<ResolverOptions>;
+
+interface NetworkStatus {
+    online: boolean;
+    lastSuccess?: number;
+    lastError?: string;
+    failureCount: number;
+}
+
+/**
+ * Model Capability Resolver for @cuylabs/agent-core
+ *
+ * Main orchestrator that combines multiple capability sources:
+ * 1. User overrides (highest priority)
+ * 2. Local cache (fast, persisted)
+ * 3. Pattern matching (always available)
+ * 4. Remote API (optional, network-dependent)
+ *
+ * Designed for the Vercel AI SDK v6 ecosystem.
+ */
+
+/**
+ * Extract model ID from LanguageModel
+ */
+declare function extractModelId(model: LanguageModel): string;
+/**
+ * Extract provider from LanguageModel
+ */
+declare function extractProvider(model: LanguageModel): string | undefined;
+/**
+ * Resolution result with source information
+ */
+interface ResolutionResult {
+    /** The resolved model entry */
+    entry: ModelEntry;
+    /** Which source provided the primary result */
+    source: SourcePriority;
+    /** Whether this is a confident match */
+    confident: boolean;
+    /** Resolution timing in ms */
+    resolveTimeMs: number;
+}
+/**
+ * Model Capability Resolver
+ *
+ * Provides a unified API for querying model capabilities with
+ * automatic fallback through multiple sources.
+ */
+declare class ModelCapabilityResolver {
+    private options;
+    private cache;
+    private sources;
+    private initialized;
+    private initPromise;
+    constructor(options?: Partial<ResolverOptions>);
+    /**
+     * Initialize the resolver (load cache, optionally fetch remote)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Resolve capabilities for a model
+     */
+    resolve(model: LanguageModel): Promise<ResolutionResult>;
+    /**
+     * Quick check if a model supports reasoning
+     * Uses cache/patterns only for speed
+     */
+    supportsReasoning(model: LanguageModel): Promise<boolean>;
+    /**
+     * Get capabilities for a model
+     */
+    getCapabilities(model: LanguageModel): Promise<ModelCapabilities>;
+    /**
+     * Get provider compatibility settings
+     */
+    getCompatibility(model: LanguageModel): Promise<ProviderCompatibility | undefined>;
+    /**
+     * Force refresh from remote API
+     */
+    refreshRemote(): Promise<void>;
+    /**
+     * Get current network status
+     */
+    getNetworkStatus(): NetworkStatus;
+    /**
+     * Get resolver statistics
+     */
+    getStats(): {
+        cacheSize: number;
+        cacheLoaded: boolean;
+        remoteFetchEnabled: boolean;
+        networkOnline: boolean;
+    };
+    /**
+     * Clear all cached data
+     */
+    clearCache(): Promise<void>;
+    /**
+     * List all available models
+     * Fetches from remote if cache is empty and remote is enabled
+     */
+    listModels(): Promise<ModelEntry[]>;
+    /**
+     * List all available models grouped by provider
+     */
+    listModelsByProvider(): Promise<Record<string, ModelEntry[]>>;
+}
+/**
+ * Get the default resolver instance
+ */
+declare function getDefaultResolver(): ModelCapabilityResolver;
+/**
+ * Configure the default resolver with custom options
+ */
+declare function configureResolver(options: Partial<ResolverOptions>): void;
+
+export { type CapabilitySource as C, DEFAULT_RESOLVER_OPTIONS as D, type InputModality as I, type ModelEntry as M, type NetworkStatus as N, type OutputModality as O, type ProviderCompatibility as P, type ResolverOptions as R, SourcePriority as S, extractProvider as a, type SourceResult as b, type ModelCapabilities as c, ModelCapabilityResolver as d, extractModelId as e, type ResolutionResult as f, configureResolver as g, getDefaultResolver as h };