oricore 1.5.0 → 1.5.2

package/dist/index.d.cts

@@ -944,18 +944,179 @@ type Plugin = {
     }) => Promise<void> | void;
 };
 
+/**
+ * Bundled skill definition for TypeScript-encoded skills.
+ * This allows skills to be defined programmatically with dynamic behavior.
+ */
+interface BundledSkillDefinition {
+    /** Unique skill name */
+    name: string;
+    /** Skill description */
+    description: string;
+    /**
+     * Tools that this skill is allowed to use.
+     * If specified, only these tools will be available when the skill executes.
+     */
+    allowedTools?: string[];
+    /**
+     * Execution context for the skill.
+     * - 'inline': Skill content is injected into current conversation (default)
+     * - 'fork': Skill runs in an isolated sub-agent
+     */
+    context?: 'inline' | 'fork';
+    /**
+     * Agent type to use when context is 'fork'.
+     * If not specified, defaults to 'general-purpose'.
+     */
+    agent?: string;
+    /**
+     * Whether this skill can be invoked by users via slash commands.
+     * @default true
+     */
+    userInvocable?: boolean;
+    /**
+     * Whether this skill can be invoked by the model via SkillTool.
+     * @default true
+     */
+    modelInvocable?: boolean;
+    /**
+     * Aliases for the skill name.
+     * Allows the skill to be invoked by alternative names.
+     */
+    aliases?: string[];
+    /**
+     * When to use this skill.
+     * Provides guidance to the model about when to invoke this skill.
+     */
+    whenToUse?: string;
+    /**
+     * Hint for arguments that can be passed to the skill.
+     * Example: '[file_path] [issue_description]'
+     */
+    argumentHint?: string;
+    /**
+     * Function to determine if this skill is enabled in the current context.
+     * Can be a boolean or a function that receives the context.
+     */
+    isEnabled?: boolean | ((context: Context) => boolean);
+    /**
+     * Embedded reference files that will be extracted when the skill runs.
+     * Key is the filename, value is the file content.
+     */
+    files?: Record<string, string>;
+    /**
+     * Generate the skill prompt content.
+     * This function is called when the skill is invoked.
+     * @param args Arguments passed to the skill
+     * @param context The execution context
+     * @returns Promise resolving to the skill prompt content
+     */
+    getPrompt: (args: string, context: Context) => Promise<string> | string;
+}
+/**
+ * Registry for bundled skills.
+ * Skills registered here are built into the engine binary.
+ */
+declare class BundledSkillRegistry {
+    private skills;
+    private aliases;
+    /**
+     * Register a bundled skill.
+     * @param definition The skill definition
+     */
+    register(definition: BundledSkillDefinition): void;
+    /**
+     * Get a bundled skill by name or alias.
+     * @param name Skill name or alias
+     * @returns The skill definition or undefined if not found
+     */
+    get(name: string): BundledSkillDefinition | undefined;
+    /**
+     * Get all registered bundled skills.
+     * @param context Optional context to filter by isEnabled
+     * @returns Array of skill definitions
+     */
+    getAll(context?: Context): BundledSkillDefinition[];
+    /**
+     * Check if a skill is registered.
+     * @param name Skill name or alias
+     */
+    has(name: string): boolean;
+    /**
+     * Unregister a skill.
+     * @param name Skill name
+     */
+    unregister(name: string): void;
+    /**
+     * Clear all registered skills.
+     */
+    clear(): void;
+}
+declare const bundledSkillRegistry: BundledSkillRegistry;
+/**
+ * Convert a bundled skill definition to SkillMetadata format.
+ * This is used internally when loading bundled skills into the SkillManager.
+ */
+declare function bundledSkillToMetadata(definition: BundledSkillDefinition, source?: SkillSource): SkillMetadata;
+/**
+ * Helper function to create a simple bundled skill.
+ */
+declare function createBundledSkill(config: Omit<BundledSkillDefinition, 'getPrompt'> & {
+    prompt: string | ((args: string, context: Context) => Promise<string> | string);
+}): BundledSkillDefinition;
+/**
+ * Register a bundled skill using a simplified configuration.
+ */
+declare function registerBundledSkill(config: Omit<BundledSkillDefinition, 'getPrompt'> & {
+    prompt: string | ((args: string, context: Context) => Promise<string> | string);
+}): void;
+
 declare enum SkillSource {
     Plugin = "plugin",
     GlobalClaude = "global-claude",
     Global = "global",
     ProjectClaude = "project-claude",
-    Project = "project"
+    Project = "project",
+    Builtin = "builtin"
 }
+type SkillContext = 'inline' | 'fork';
 interface SkillMetadata {
     name: string;
     description: string;
     path: string;
     source: SkillSource;
+    /**
+     * Tools that this skill is allowed to use.
+     * If specified, only these tools will be available when the skill executes.
+     * Example: ['Read', 'Grep', 'Bash']
+     */
+    allowedTools?: string[];
+    /**
+     * Execution context for the skill.
+     * - 'inline': Skill content is injected into current conversation (default)
+     * - 'fork': Skill runs in an isolated sub-agent
+     */
+    context?: SkillContext;
+    /**
+     * Agent type to use when context is 'fork'.
+     * If not specified, defaults to a general-purpose agent.
+     */
+    agent?: string;
+    /**
+     * File path patterns that trigger this skill's availability.
+     * Example: ['src/asterisk/asterisk.ts', '*.test.js']
+     */
+    paths?: string[];
+    /**
+     * Whether this skill can be invoked by users via slash commands.
+     * @default true
+     */
+    userInvocable?: boolean;
+    /**
+     * Whether this skill can be invoked by the model via SkillTool.
+     * @default true
+     */
+    modelInvocable?: boolean;
 }
 interface SkillError {
     path: string;
@@ -999,15 +1160,90 @@ declare class SkillManager {
     private errors;
     private paths;
     private context;
+    /**
+     * Tracks which skills are currently "active" based on file operations.
+     * Skills with `paths` frontmatter are activated when matching files are accessed.
+     */
+    private activeSkillNames;
+    /**
+     * Maps alias names to original skill names for bundled skills.
+     */
+    private aliasMap;
     constructor(opts: SkillManagerOpts);
-    getSkills(): SkillMetadata[];
+    /**
+     * Get all loaded skills.
+     * @param options Filter options
+     * @returns Array of skill metadata
+     */
+    getSkills(options?: {
+        /** Only return skills that are user-invocable */
+        userInvocable?: boolean;
+        /** Only return skills that are model-invocable */
+        modelInvocable?: boolean;
+        /** Only return active skills (those with matching paths) */
+        activeOnly?: boolean;
+    }): SkillMetadata[];
+    /**
+     * Get a specific skill by name.
+     * Automatically resolves aliases to the original skill.
+     * @param name Skill name or alias
+     * @returns Skill metadata or undefined if not found
+     */
     getSkill(name: string): SkillMetadata | undefined;
+    /**
+     * Check if a skill is active (has matching paths for current context).
+     * @param name Skill name
+     */
+    isSkillActive(name: string): boolean;
+    /**
+     * Activate skills based on file paths.
+     * Skills with `paths` frontmatter that match the given paths will be activated.
+     * @param filePaths Array of file paths to check
+     * @returns Array of newly activated skill names
+     */
+    activateSkillsForPaths(filePaths: string[]): string[];
+    /**
+     * Clear all active skill activations.
+     * Useful when switching contexts or projects.
+     */
+    clearActiveSkills(): void;
+    /**
+     * Get all skills that have path-based conditional activation.
+     * @returns Array of skills with paths defined
+     */
+    getConditionalSkills(): SkillMetadata[];
     getErrors(): SkillError[];
-    readSkillBody(skill: SkillMetadata): Promise<string>;
+    /**
+     * Read the body content of a skill.
+     * For file-based skills, reads from disk.
+     * For bundled skills, generates content via getPrompt.
+     */
+    readSkillBody(skill: SkillMetadata, args?: string): Promise<string>;
+    /**
+     * Get a bundled skill definition by name.
+     * @param name Bundled skill name
+     * @returns Bundled skill definition or undefined if not found
+     */
+    getBundledSkill(name: string): BundledSkillDefinition | undefined;
+    /**
+     * Register a bundled skill programmatically.
+     * @param definition Bundled skill definition
+     */
+    registerBundledSkill(definition: BundledSkillDefinition): void;
     loadSkills(): Promise<void>;
+    /**
+     * Load builtin/bundled skills from the registry.
+     */
+    private loadBuiltinSkills;
     private loadSkillsFromDirectory;
     private loadSkillFile;
     private parseSkillFile;
+    /**
+     * Parse a field that can be either a comma-separated string or an array of strings.
+     * @param value The value to parse
+     * @returns Array of strings or undefined if empty
+     */
+    private parseStringArrayField;
     addSkill(source: string, options?: AddSkillOptions): Promise<AddSkillResult>;
     private normalizeSource;
     private extractFolderName;
@@ -1561,4 +1797,4 @@ declare function randomUUID(): string;
 
 declare const ENGINE_VERSION = "1.0.0";
 
-export { type AddSkillOptions, type AddSkillResult, type BaseMessage, Compression, type CompressionConfig, type ConnectionState, DirectTransport, ENGINE_VERSION, Engine, type EngineConfig, type EngineOptions, type EventHandler, type EventMessage, type ExecOptions, type ExecResult, GlobalData, History, JsonlLogger, type LoopResult, type Message, MessageBus, type MessageHandler, type MessageId, type MessageTransport, type Mode, type ModeConfig, ModeRegistryImpl as ModeRegistry, type ModeType, NodePlatform, Paths, type PlatformAdapter, type PreviewSkillsResult, type PruneResult, type RequestMessage, type ResponseMessage, type SendMessageOptions, Session, type SessionConfig, SessionConfigManager, type SessionId, type SessionOptions, type SkillError, type SkillLoadOutcome, SkillManager, type SkillManagerOpts, type SkillMetadata, type SkillPreview, SkillSource, type Stats, Usage, brainstormMode, builtinModes, createEngine, debugMode, defaultMode, getGlobalDataPath, isOverflow, loadSessionMessages, modeRegistry, nodePlatform, planMode, randomUUID, registerBuiltinModes, reviewMode };
+export { type AddSkillOptions, type AddSkillResult, type BaseMessage, type BundledSkillDefinition, Compression, type CompressionConfig, type ConnectionState, DirectTransport, ENGINE_VERSION, Engine, type EngineConfig, type EngineOptions, type EventHandler, type EventMessage, type ExecOptions, type ExecResult, GlobalData, History, JsonlLogger, type LoopResult, type Message, MessageBus, type MessageHandler, type MessageId, type MessageTransport, type Mode, type ModeConfig, ModeRegistryImpl as ModeRegistry, type ModeType, NodePlatform, Paths, type PlatformAdapter, type PreviewSkillsResult, type PruneResult, type RequestMessage, type ResponseMessage, type SendMessageOptions, Session, type SessionConfig, SessionConfigManager, type SessionId, type SessionOptions, type SkillContext, type SkillError, type SkillLoadOutcome, SkillManager, type SkillManagerOpts, type SkillMetadata, type SkillPreview, SkillSource, type Stats, Usage, brainstormMode, builtinModes, bundledSkillRegistry, bundledSkillToMetadata, createBundledSkill, createEngine, debugMode, defaultMode, getGlobalDataPath, isOverflow, loadSessionMessages, modeRegistry, nodePlatform, planMode, randomUUID, registerBuiltinModes, registerBundledSkill, reviewMode };

package/dist/index.d.ts

@@ -944,18 +944,179 @@ type Plugin = {
     }) => Promise<void> | void;
 };
 
+/**
+ * Bundled skill definition for TypeScript-encoded skills.
+ * This allows skills to be defined programmatically with dynamic behavior.
+ */
+interface BundledSkillDefinition {
+    /** Unique skill name */
+    name: string;
+    /** Skill description */
+    description: string;
+    /**
+     * Tools that this skill is allowed to use.
+     * If specified, only these tools will be available when the skill executes.
+     */
+    allowedTools?: string[];
+    /**
+     * Execution context for the skill.
+     * - 'inline': Skill content is injected into current conversation (default)
+     * - 'fork': Skill runs in an isolated sub-agent
+     */
+    context?: 'inline' | 'fork';
+    /**
+     * Agent type to use when context is 'fork'.
+     * If not specified, defaults to 'general-purpose'.
+     */
+    agent?: string;
+    /**
+     * Whether this skill can be invoked by users via slash commands.
+     * @default true
+     */
+    userInvocable?: boolean;
+    /**
+     * Whether this skill can be invoked by the model via SkillTool.
+     * @default true
+     */
+    modelInvocable?: boolean;
+    /**
+     * Aliases for the skill name.
+     * Allows the skill to be invoked by alternative names.
+     */
+    aliases?: string[];
+    /**
+     * When to use this skill.
+     * Provides guidance to the model about when to invoke this skill.
+     */
+    whenToUse?: string;
+    /**
+     * Hint for arguments that can be passed to the skill.
+     * Example: '[file_path] [issue_description]'
+     */
+    argumentHint?: string;
+    /**
+     * Function to determine if this skill is enabled in the current context.
+     * Can be a boolean or a function that receives the context.
+     */
+    isEnabled?: boolean | ((context: Context) => boolean);
+    /**
+     * Embedded reference files that will be extracted when the skill runs.
+     * Key is the filename, value is the file content.
+     */
+    files?: Record<string, string>;
+    /**
+     * Generate the skill prompt content.
+     * This function is called when the skill is invoked.
+     * @param args Arguments passed to the skill
+     * @param context The execution context
+     * @returns Promise resolving to the skill prompt content
+     */
+    getPrompt: (args: string, context: Context) => Promise<string> | string;
+}
+/**
+ * Registry for bundled skills.
+ * Skills registered here are built into the engine binary.
+ */
+declare class BundledSkillRegistry {
+    private skills;
+    private aliases;
+    /**
+     * Register a bundled skill.
+     * @param definition The skill definition
+     */
+    register(definition: BundledSkillDefinition): void;
+    /**
+     * Get a bundled skill by name or alias.
+     * @param name Skill name or alias
+     * @returns The skill definition or undefined if not found
+     */
+    get(name: string): BundledSkillDefinition | undefined;
+    /**
+     * Get all registered bundled skills.
+     * @param context Optional context to filter by isEnabled
+     * @returns Array of skill definitions
+     */
+    getAll(context?: Context): BundledSkillDefinition[];
+    /**
+     * Check if a skill is registered.
+     * @param name Skill name or alias
+     */
+    has(name: string): boolean;
+    /**
+     * Unregister a skill.
+     * @param name Skill name
+     */
+    unregister(name: string): void;
+    /**
+     * Clear all registered skills.
+     */
+    clear(): void;
+}
+declare const bundledSkillRegistry: BundledSkillRegistry;
+/**
+ * Convert a bundled skill definition to SkillMetadata format.
+ * This is used internally when loading bundled skills into the SkillManager.
+ */
+declare function bundledSkillToMetadata(definition: BundledSkillDefinition, source?: SkillSource): SkillMetadata;
+/**
+ * Helper function to create a simple bundled skill.
+ */
+declare function createBundledSkill(config: Omit<BundledSkillDefinition, 'getPrompt'> & {
+    prompt: string | ((args: string, context: Context) => Promise<string> | string);
+}): BundledSkillDefinition;
+/**
+ * Register a bundled skill using a simplified configuration.
+ */
+declare function registerBundledSkill(config: Omit<BundledSkillDefinition, 'getPrompt'> & {
+    prompt: string | ((args: string, context: Context) => Promise<string> | string);
+}): void;
+
 declare enum SkillSource {
     Plugin = "plugin",
     GlobalClaude = "global-claude",
     Global = "global",
     ProjectClaude = "project-claude",
-    Project = "project"
+    Project = "project",
+    Builtin = "builtin"
 }
+type SkillContext = 'inline' | 'fork';
 interface SkillMetadata {
     name: string;
     description: string;
     path: string;
     source: SkillSource;
+    /**
+     * Tools that this skill is allowed to use.
+     * If specified, only these tools will be available when the skill executes.
+     * Example: ['Read', 'Grep', 'Bash']
+     */
+    allowedTools?: string[];
+    /**
+     * Execution context for the skill.
+     * - 'inline': Skill content is injected into current conversation (default)
+     * - 'fork': Skill runs in an isolated sub-agent
+     */
+    context?: SkillContext;
+    /**
+     * Agent type to use when context is 'fork'.
+     * If not specified, defaults to a general-purpose agent.
+     */
+    agent?: string;
+    /**
+     * File path patterns that trigger this skill's availability.
+     * Example: ['src/asterisk/asterisk.ts', '*.test.js']
+     */
+    paths?: string[];
+    /**
+     * Whether this skill can be invoked by users via slash commands.
+     * @default true
+     */
+    userInvocable?: boolean;
+    /**
+     * Whether this skill can be invoked by the model via SkillTool.
+     * @default true
+     */
+    modelInvocable?: boolean;
 }
 interface SkillError {
     path: string;
@@ -999,15 +1160,90 @@ declare class SkillManager {
     private errors;
     private paths;
     private context;
+    /**
+     * Tracks which skills are currently "active" based on file operations.
+     * Skills with `paths` frontmatter are activated when matching files are accessed.
+     */
+    private activeSkillNames;
+    /**
+     * Maps alias names to original skill names for bundled skills.
+     */
+    private aliasMap;
     constructor(opts: SkillManagerOpts);
-    getSkills(): SkillMetadata[];
+    /**
+     * Get all loaded skills.
+     * @param options Filter options
+     * @returns Array of skill metadata
+     */
+    getSkills(options?: {
+        /** Only return skills that are user-invocable */
+        userInvocable?: boolean;
+        /** Only return skills that are model-invocable */
+        modelInvocable?: boolean;
+        /** Only return active skills (those with matching paths) */
+        activeOnly?: boolean;
+    }): SkillMetadata[];
+    /**
+     * Get a specific skill by name.
+     * Automatically resolves aliases to the original skill.
+     * @param name Skill name or alias
+     * @returns Skill metadata or undefined if not found
+     */
     getSkill(name: string): SkillMetadata | undefined;
+    /**
+     * Check if a skill is active (has matching paths for current context).
+     * @param name Skill name
+     */
+    isSkillActive(name: string): boolean;
+    /**
+     * Activate skills based on file paths.
+     * Skills with `paths` frontmatter that match the given paths will be activated.
+     * @param filePaths Array of file paths to check
+     * @returns Array of newly activated skill names
+     */
+    activateSkillsForPaths(filePaths: string[]): string[];
+    /**
+     * Clear all active skill activations.
+     * Useful when switching contexts or projects.
+     */
+    clearActiveSkills(): void;
+    /**
+     * Get all skills that have path-based conditional activation.
+     * @returns Array of skills with paths defined
+     */
+    getConditionalSkills(): SkillMetadata[];
     getErrors(): SkillError[];
-    readSkillBody(skill: SkillMetadata): Promise<string>;
+    /**
+     * Read the body content of a skill.
+     * For file-based skills, reads from disk.
+     * For bundled skills, generates content via getPrompt.
+     */
+    readSkillBody(skill: SkillMetadata, args?: string): Promise<string>;
+    /**
+     * Get a bundled skill definition by name.
+     * @param name Bundled skill name
+     * @returns Bundled skill definition or undefined if not found
+     */
+    getBundledSkill(name: string): BundledSkillDefinition | undefined;
+    /**
+     * Register a bundled skill programmatically.
+     * @param definition Bundled skill definition
+     */
+    registerBundledSkill(definition: BundledSkillDefinition): void;
     loadSkills(): Promise<void>;
+    /**
+     * Load builtin/bundled skills from the registry.
+     */
+    private loadBuiltinSkills;
     private loadSkillsFromDirectory;
     private loadSkillFile;
     private parseSkillFile;
+    /**
+     * Parse a field that can be either a comma-separated string or an array of strings.
+     * @param value The value to parse
+     * @returns Array of strings or undefined if empty
+     */
+    private parseStringArrayField;
     addSkill(source: string, options?: AddSkillOptions): Promise<AddSkillResult>;
     private normalizeSource;
     private extractFolderName;
@@ -1561,4 +1797,4 @@ declare function randomUUID(): string;
 
 declare const ENGINE_VERSION = "1.0.0";
 
-export { type AddSkillOptions, type AddSkillResult, type BaseMessage, Compression, type CompressionConfig, type ConnectionState, DirectTransport, ENGINE_VERSION, Engine, type EngineConfig, type EngineOptions, type EventHandler, type EventMessage, type ExecOptions, type ExecResult, GlobalData, History, JsonlLogger, type LoopResult, type Message, MessageBus, type MessageHandler, type MessageId, type MessageTransport, type Mode, type ModeConfig, ModeRegistryImpl as ModeRegistry, type ModeType, NodePlatform, Paths, type PlatformAdapter, type PreviewSkillsResult, type PruneResult, type RequestMessage, type ResponseMessage, type SendMessageOptions, Session, type SessionConfig, SessionConfigManager, type SessionId, type SessionOptions, type SkillError, type SkillLoadOutcome, SkillManager, type SkillManagerOpts, type SkillMetadata, type SkillPreview, SkillSource, type Stats, Usage, brainstormMode, builtinModes, createEngine, debugMode, defaultMode, getGlobalDataPath, isOverflow, loadSessionMessages, modeRegistry, nodePlatform, planMode, randomUUID, registerBuiltinModes, reviewMode };
+export { type AddSkillOptions, type AddSkillResult, type BaseMessage, type BundledSkillDefinition, Compression, type CompressionConfig, type ConnectionState, DirectTransport, ENGINE_VERSION, Engine, type EngineConfig, type EngineOptions, type EventHandler, type EventMessage, type ExecOptions, type ExecResult, GlobalData, History, JsonlLogger, type LoopResult, type Message, MessageBus, type MessageHandler, type MessageId, type MessageTransport, type Mode, type ModeConfig, ModeRegistryImpl as ModeRegistry, type ModeType, NodePlatform, Paths, type PlatformAdapter, type PreviewSkillsResult, type PruneResult, type RequestMessage, type ResponseMessage, type SendMessageOptions, Session, type SessionConfig, SessionConfigManager, type SessionId, type SessionOptions, type SkillContext, type SkillError, type SkillLoadOutcome, SkillManager, type SkillManagerOpts, type SkillMetadata, type SkillPreview, SkillSource, type Stats, Usage, brainstormMode, builtinModes, bundledSkillRegistry, bundledSkillToMetadata, createBundledSkill, createEngine, debugMode, defaultMode, getGlobalDataPath, isOverflow, loadSessionMessages, modeRegistry, nodePlatform, planMode, randomUUID, registerBuiltinModes, registerBundledSkill, reviewMode };