@kodax-ai/kodax 0.7.40 → 0.7.42

package/dist/sdk-skills.d.ts

@@ -1,16 +1,560 @@
 /**
- * SDK subpath entry — `@kodax-ai/kodax/skills`
+ * Agent Skills Standard Type Definitions
+ * Compliant with https://agentskills.io/ specification
  *
- * Re-exports the entire `@kodax-ai/skills` public API — skill loader,
- * resolver, registry, frontmatter parser, etc. The `@kodax-ai/skills`
- * package has zero external dependencies, making it the cheapest
- * subpath for SDK consumers to pull in.
+ * Also supports Claude Code extension fields for compatibility
+ */
+/**
+ * Skill frontmatter as defined in SKILL.md YAML header
+ */
+interface SkillFrontmatter {
+    /** Skill name in kebab-case, max 64 characters */
+    name: string;
+    /** Skill description, max 1024 characters, should include trigger conditions */
+    description: string;
+    /** Whether to disable automatic model invocation (default: false) */
+    disableModelInvocation?: boolean;
+    /** Whether skill appears in / menu (default: true) */
+    userInvocable?: boolean;
+    /** Tool restrictions, e.g., "Read, Grep, Bash(python:*)" */
+    allowedTools?: string;
+    /** Execution context - 'fork' for sub-agent execution */
+    context?: 'fork';
+    /** Sub-agent type: Explore, Plan, general-purpose, etc. */
+    agent?: string;
+    /** Argument hint for UI, e.g., "[file] [format]" */
+    argumentHint?: string;
+    /** Model preference: haiku, sonnet, opus, or a provider-specific model id */
+    model?: string;
+    /** Hooks scoped to this skill's lifecycle */
+    hooks?: SkillHooks;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SkillHook {
+    matcher?: string;
+    command: string;
+}
+interface SkillHooks {
+    SessionStart?: SkillHook[];
+    UserPromptSubmit?: SkillHook[];
+    PreToolUse?: SkillHook[];
+    PostToolUse?: SkillHook[];
+    Stop?: SkillHook[];
+    SubagentStop?: SkillHook[];
+    Notification?: SkillHook[];
+}
+/**
+ * Lightweight skill metadata for system prompt injection
+ * Loaded at startup for progressive disclosure
+ */
+interface SkillMetadata {
+    name: string;
+    description: string;
+    userInvocable: boolean;
+    argumentHint?: string;
+    path: string;
+    source: SkillSource;
+    /** If true, exclude from system prompt (only invokable via /skill:name) */
+    disableModelInvocation: boolean;
+}
+/**
+ * Complete skill definition with all content loaded
+ */
+interface Skill extends SkillFrontmatter {
+    /** Skill directory absolute path */
+    path: string;
+    /** SKILL.md absolute path */
+    skillFilePath: string;
+    /** Markdown content (with variables resolved) */
+    content: string;
+    /** Raw markdown content (before variable resolution) */
+    rawContent: string;
+    /** Support files */
+    scripts?: SkillFile[];
+    references?: SkillFile[];
+    assets?: SkillFile[];
+    templates?: SkillFile[];
+    resources?: SkillFile[];
+    /** Runtime state */
+    loaded: boolean;
+    source: SkillSource;
+}
+/**
+ * File within a skill directory
+ */
+interface SkillFile {
+    name: string;
+    path: string;
+    relativePath: string;
+    content?: string;
+}
+type SkillSource = 'project' | 'user' | 'plugin' | 'builtin';
+/**
+ * Skill registry interface for managing discovered skills
+ */
+interface ISkillRegistry {
+    /** Read-only view of discovered skill metadata */
+    readonly skills: ReadonlyMap<string, SkillMetadata>;
+    /** Discover skills from all configured paths */
+    discover(): Promise<void>;
+    /** Get skill metadata by name */
+    get(name: string): SkillMetadata | undefined;
+    /** Load full skill content */
+    loadFull(name: string): Promise<Skill>;
+    /** Invoke a skill with arguments */
+    invoke(name: string, args: string, context: SkillContext): Promise<SkillResult>;
+    /** Reload skills from disk */
+    reload(): Promise<void>;
+    /** List all discovered skills */
+    list(): ReadonlyArray<SkillMetadata>;
+    /** List skills that can be invoked directly by users */
+    listUserInvocable(): ReadonlyArray<SkillMetadata>;
+    /** Check whether a skill exists */
+    has(name: string): boolean;
+    /** Number of discovered skills */
+    readonly size: number;
+}
+/**
+ * v0.7.42 — SDK-embedder hook for `!`cmd`` dynamic context resolution.
  *
- * Usage:
+ * Receives the literal command string and the working directory the resolver
+ * would have used. Must return the command's text output (which the resolver
+ * splices into the skill markdown in place of the `!`cmd`` token), or throw
+ * to deny.
+ *
+ * **Trust boundary**: when the KodaX SDK is embedded inside a host app
+ * (e.g. KodaX Space, IDE extensions), the host typically mediates shell
+ * execution through a permission broker so the end user can approve / deny
+ * each command. Without this hook, `VariableResolver` directly `execSync`s
+ * commands using its own built-in whitelist — bypassing the host's broker
+ * and producing OS side-effects the user never saw.
+ *
+ * Embedders should route here to:
+ *   - prompt the user via their own UI,
+ *   - log execution to their audit trail,
+ *   - apply policy (e.g. block network commands),
+ *   - or refuse outright (throw).
+ *
+ * @example
  * ```ts
- * import { loadSkill, SkillRegistry } from '@kodax-ai/kodax/skills';
+ * const context: SkillContext = {
+ *   workingDirectory: '/repo',
+ *   executeDynamicContext: async (cmd, cwd) => {
+ *     const approved = await brokerAskUser({ kind: 'skill-cmd', command: cmd, cwd });
+ *     if (!approved) throw new Error('user denied');
+ *     return await brokerExecute(cmd, cwd);
+ *   },
+ * };
  * ```
+ */
+type SkillDynamicContextExecutor = (command: string, cwd: string) => Promise<string>;
+interface SkillContext {
+    workingDirectory: string;
+    projectRoot?: string;
+    /**
+     * Optional. Used to substitute `${CLAUDE_SESSION_ID}` / `${KODAX_SESSION_ID}`
+     * template variables in skill markdown. Tool-invocation callers (e.g. the
+     * `skill` tool) may not have a session bound — in that case the resolver
+     * falls back to an empty replacement so the substitution doesn't leak the
+     * literal `${...}` to the LLM.
+     */
+    sessionId?: string;
+    environment?: Record<string, string>;
+    messages?: unknown[];
+    /**
+     * v0.7.42 — SDK-embedder hook for `!`cmd`` dynamic-context resolution.
+     * See {@link SkillDynamicContextExecutor} for the trust-boundary rationale.
+     * When present, completely replaces the built-in `execSync`-based path
+     * (whitelist + 5s timeout). When absent, the legacy whitelist path runs.
+     */
+    executeDynamicContext?: SkillDynamicContextExecutor;
+    /**
+     * v0.7.42 — hard-disable `!`cmd`` resolution.
+     * When `true`, encountering a `!`cmd`` token throws
+     * `[Dynamic context disabled by host]` regardless of any hook. Useful for
+     * embedders that want a single-flag kill switch without writing a hook.
+     * `executeDynamicContext` is ignored when this is `true`.
+     */
+    disableDynamicContext?: boolean;
+}
+interface SkillResult {
+    success: boolean;
+    /** Processed prompt content */
+    content: string;
+    /** Generated artifacts */
+    artifacts?: SkillArtifact[];
+    error?: string;
+}
+interface SkillArtifact {
+    type: 'file' | 'code' | 'text';
+    name: string;
+    content: string;
+    path?: string;
+}
+interface IVariableResolver {
+    /** Resolve all variables in content */
+    resolve(content: string, args: string, context: SkillContext): Promise<string>;
+}
+interface SkillPathsConfig {
+    projectPaths: string[];
+    userPaths: string[];
+    pluginPaths: string[];
+    builtinPath: string;
+}
+/**
+ * Get default skill discovery paths
+ *
+ * Priority order (highest first):
+ * 1. Project - <projectRoot>/.kodax/skills/
+ * 2. User - ~/.kodax/skills/
+ * 3. User - ~/.agents/skills/ (AgentSkills standard)
+ * 4. Plugin - (dynamic)
+ * 5. Builtin - packages/skills/src/builtin/
+ */
+declare function getDefaultSkillPaths(projectRoot?: string): SkillPathsConfig;
+/**
+ * All skill paths in priority order (highest to lowest)
+ *
+ * Priority: Project > User > Plugin > Builtin
+ * - Project: Project-specific skills override everything else
+ * - User: User preferences (~/.kodax/ and ~/.agents/)
+ * - Plugin: Third-party plugins
+ * - Builtin: Default skills shipped with KodaX
+ */
+declare function getSkillPathsFlat(config: SkillPathsConfig): Array<{
+    path: string;
+    source: SkillSource;
+}>;
+
+declare function registerPluginSkillPath(skillPath: string): () => void;
+declare function unregisterPluginSkillPath(skillPath: string): boolean;
+declare function listPluginSkillPaths(): string[];
+declare function clearPluginSkillPaths(): void;
+
+/**
+ * Skill Loader - YAML Frontmatter Parsing and Skill Loading
+ *
+ * Parses SKILL.md files with YAML frontmatter and loads skill content.
+ * Implements fallback sanitization for non-standard YAML formats.
+ */
+
+/**
+ * Parse SKILL.md file with YAML frontmatter
+ */
+declare function parseSkillMarkdown(content: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+};
+/**
+ * Load skill metadata from SKILL.md file
+ */
+declare function loadSkillMetadata(skillDir: string, source: SkillSource): Promise<SkillMetadata | null>;
+/**
+ * Load full skill content
+ */
+declare function loadFullSkill(skillDir: string, source: SkillSource): Promise<Skill | null>;
+/**
+ * Load a specific support file's content
+ */
+declare function loadSkillFileContent(file: SkillFile): Promise<string>;
+
+/**
+ * Skill Discovery - Multi-path skill scanning
+ *
+ * Discovers skills from multiple paths with priority handling.
+ * Supports nested directory discovery for monorepos.
+ */
+
+/**
+ * Result of skill discovery
+ */
+interface DiscoveryResult {
+    skills: Map<string, SkillMetadata>;
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/**
+ * Discover all skills from configured paths
+ */
+declare function discoverSkills(projectRoot?: string, customPaths?: Partial<SkillPathsConfig>): Promise<DiscoveryResult>;
+/**
+ * Get nested skill paths for monorepo support
+ * When in a subdirectory, also check parent directories for skills
+ */
+declare function getNestedSkillPaths(currentDir: string, projectRoot: string): string[];
+/**
+ * Discover skills with monorepo support
+ */
+declare function discoverSkillsWithMonorepo(currentDir: string, projectRoot: string): Promise<DiscoveryResult>;
+
+/**
+ * Skill Resolver - Variable Replacement System
  *
- * See docs/ADR.md ADR-024 for the SDK formalization decision.
+ * Handles variable replacement in skill content:
+ * - $ARGUMENTS - All arguments
+ * - $0, $1, $2... - Positional arguments
+ * - ${VAR_NAME} - Environment variables
+ * - !`command` - Dynamic context injection
+ */
+
+/**
+ * Split arguments string into positional arguments
+ * Handles quoted strings correctly
+ */
+declare function parseArguments(args: string): string[];
+/**
+ * Variable resolver implementation
+ */
+declare class VariableResolver implements IVariableResolver {
+    private context;
+    constructor(context: SkillContext);
+    /**
+     * Resolve all variables in content
+     */
+    resolve(content: string, args: string): Promise<string>;
+    /**
+     * Replace $0, $1, $2... with positional arguments
+     */
+    private resolvePositionalArgs;
+    /**
+     * Replace $ARGUMENTS with all arguments
+     */
+    private resolveArguments;
+    /**
+     * Replace ${VAR_NAME} with environment variables
+     */
+    private resolveEnvVars;
+    /**
+     * Replace !`command` with command output (dynamic context).
+     *
+     * Three-tier dispatch (v0.7.42):
+     *   1. `context.disableDynamicContext === true` → throw immediately,
+     *      surfaced to the LLM as `[Error: …]`. Host-level kill switch.
+     *   2. `context.executeDynamicContext` provided → route there. Embedder
+     *      mediates shell execution (broker, audit, deny).
+     *   3. else → legacy built-in path (`isSafeDynamicContextCommand`
+     *      whitelist + `execSync` with 5s timeout).
+     *
+     * The resolver inlines an `[Error: …]` placeholder for any thrown
+     * exception so a single bad token doesn't poison the whole skill load.
+     */
+    private resolveDynamicContext;
+    /**
+     * Execute a dynamic context command via the appropriate dispatch tier.
+     * See `resolveDynamicContext` JSDoc for the 3-tier ordering rationale.
+     */
+    private executeDynamicCommand;
+}
+/**
+ * Create a variable resolver for a given context
+ */
+declare function createResolver(context: SkillContext): IVariableResolver;
+/**
+ * Resolve skill content with arguments and context
+ */
+declare function resolveSkillContent(content: string, args: string, context: SkillContext): Promise<string>;
+
+/**
+ * Skill Registry - Progressive Disclosure and Skill Management
+ *
+ * Manages skill discovery, loading, and invocation with progressive disclosure:
+ * - Level 1: Metadata preloaded at startup (name, description)
+ * - Level 2: Full content loaded on invoke
+ * - Level 3: Support files loaded on demand
+ */
+
+/**
+ * Skill Registry implementation
+ */
+declare class SkillRegistry implements ISkillRegistry {
+    private readonly skillsByName;
+    private readonly fullSkillsByName;
+    private readonly projectRoot?;
+    private readonly customPaths?;
+    constructor(projectRoot?: string, customPaths?: Partial<SkillPathsConfig>);
+    /**
+     * Discover skills from all configured paths
+     */
+    discover(): Promise<void>;
+    /**
+     * Get skill metadata by name
+     */
+    get skills(): ReadonlyMap<string, SkillMetadata>;
+    /**
+     * Get skill metadata by name
+     */
+    get(name: string): SkillMetadata | undefined;
+    /**
+     * Load full skill content
+     */
+    loadFull(name: string): Promise<Skill>;
+    /**
+     * Invoke a skill with arguments
+     */
+    invoke(name: string, args: string, context: SkillContext): Promise<SkillResult>;
+    /**
+     * Reload skills from disk
+     */
+    reload(): Promise<void>;
+    /**
+     * List all available skills
+     */
+    list(): SkillMetadata[];
+    /**
+     * List user-invocable skills (for / menu)
+     */
+    listUserInvocable(): SkillMetadata[];
+    /**
+     * Get skills formatted for system prompt injection.
+     *
+     * FEATURE_143 (v0.7.36): manifest wording hardened toward Claude
+     * Code-style strong constraints. The previous wording ("when a user
+     * request matches a skill description, use read to load the skill")
+     * was too soft — the LLM treated skill invocation as one option among
+     * many and frequently authored its own answer instead of loading the
+     * SKILL.md instructions. Aligns with the
+     * `c:/Works/claudecode/src/tools/SkillTool/prompt.ts` ruleset:
+     * BLOCKING REQUIREMENT to load the relevant skill BEFORE generating
+     * any other response when a skill matches.
+     *
+     * Filters out skills with disableModelInvocation=true (Issue 056).
+     */
+    getSystemPromptSnippet(): string;
+    /**
+     * Check if a name is a valid skill
+     */
+    has(name: string): boolean;
+    /**
+     * Get the count of discovered skills
+     */
+    get size(): number;
+}
+/**
+ * Get the global skill registry instance
+ *
+ * IMPORTANT: If projectRoot is undefined, returns existing instance without reset.
+ * This prevents accidental singleton reset when called without arguments.
+ */
+declare function getSkillRegistry(projectRoot?: string, customPaths?: Partial<SkillPathsConfig>): SkillRegistry;
+/**
+ * Initialize the skill registry and discover skills
+ */
+declare function initializeSkillRegistry(projectRoot?: string, customPaths?: Partial<SkillPathsConfig>): Promise<SkillRegistry>;
+/**
+ * Reset the global registry (for testing or hot reload)
+ */
+declare function resetSkillRegistry(): void;
+
+/**
+ * Skill Executor - Execution Engine
+ *
+ * Handles skill execution with support for:
+ * - Inline execution (default)
+ * - Fork execution (sub-agent)
+ * - Tool restrictions
+ */
+
+/**
+ * Execution mode
+ */
+type ExecutionMode = 'inline' | 'fork';
+/**
+ * Execution options
+ */
+interface ExecutionOptions {
+    /** Force a specific execution mode */
+    mode?: ExecutionMode;
+    /** Override model */
+    model?: string;
+    /** Override agent type (for fork mode) */
+    agent?: string;
+    /** Override allowed tools */
+    allowedTools?: string[];
+    /** Callback for inline execution */
+    onExecute?: (content: string, skill: Skill) => Promise<string>;
+}
+/**
+ * Skill executor class
+ */
+declare class SkillExecutor {
+    private context;
+    constructor(context: SkillContext);
+    /**
+     * Execute a skill
+     */
+    execute(skillName: string, args: string, options?: ExecutionOptions): Promise<SkillResult>;
+    /**
+     * Execute skill inline (in current context)
+     */
+    private executeInline;
+    /**
+     * Execute skill in fork mode (sub-agent)
+     */
+    private executeFork;
+    /**
+     * Build the execution prompt
+     */
+    private buildPrompt;
+    /**
+     * Parse allowed tools string into array
+     */
+    private parseAllowedTools;
+}
+/**
+ * Create a skill executor
+ */
+declare function createExecutor(context: SkillContext): SkillExecutor;
+/**
+ * Execute a skill with default context
+ */
+declare function executeSkill(skillName: string, args: string, context: SkillContext, options?: ExecutionOptions): Promise<SkillResult>;
+
+/**
+ * Skill Expander - Expand skill commands for LLM context injection
+ *
+ * Takes a skill invocation and produces content that can be injected
+ * into the user message for LLM execution.
+ *
+ * Design based on pi-mono's _expandSkillCommand:
+ * - Wraps content in XML blocks for clear context
+ * - Includes skill metadata (name, location)
+ * - Resolves all variables ($ARGUMENTS, $0, etc.)
+ * - Handles dynamic context (!`command`)
+ */
+
+/**
+ * Result of skill expansion
+ */
+interface SkillExpansionResult {
+    /** The expanded skill content ready for LLM injection */
+    content: string;
+    /** Whether the skill has model invocation disabled */
+    disableModelInvocation: boolean;
+    /** Original skill metadata */
+    skill: Skill;
+}
+/**
+ * Expand a skill into LLM-ready content
+ *
+ * This function:
+ * 1. Resolves all variables in the skill content ($ARGUMENTS, $0, $1, etc.)
+ * 2. Executes dynamic context commands (!`command`)
+ * 3. Wraps the content in an XML block for clear context boundaries
+ *
+ * @param skill - The full skill object with content
+ * @param args - Raw arguments string from user input
+ * @param context - Execution context (working directory, session ID, etc.)
+ * @returns Expansion result with content ready for LLM injection
+ */
+declare function expandSkillForLLM(skill: Skill, args: string, context: SkillContext): Promise<SkillExpansionResult>;
+/**
+ * Format skill activation message for user display
  */
-export * from '@kodax-ai/skills';
+declare function formatSkillActivationMessage(skillName: string, args: string): string;
+
+export { SkillExecutor, SkillRegistry, VariableResolver, clearPluginSkillPaths, createExecutor, createResolver, discoverSkills, discoverSkillsWithMonorepo, executeSkill, expandSkillForLLM, formatSkillActivationMessage, getDefaultSkillPaths, getNestedSkillPaths, getSkillPathsFlat, getSkillRegistry, initializeSkillRegistry, listPluginSkillPaths, loadFullSkill, loadSkillFileContent, loadSkillMetadata, parseArguments, parseSkillMarkdown, registerPluginSkillPath, resetSkillRegistry, resolveSkillContent, unregisterPluginSkillPath };
+export type { DiscoveryResult, ExecutionMode, ExecutionOptions, ISkillRegistry, IVariableResolver, Skill, SkillArtifact, SkillContext, SkillDynamicContextExecutor, SkillExpansionResult, SkillFile, SkillFrontmatter, SkillHook, SkillHooks, SkillMetadata, SkillPathsConfig, SkillResult, SkillSource };

package/dist/sdk-skills.js

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{A as w,B as y,C as z,a as o,b as r,c as e,d as f,e as m,f as p,j as t,k as x,l as a,m as b,n as c,o as d,p as g,q as h,r as i,s as j,t as k,u as l,v as n,w as q,x as s,y as u,z as v}from"./chunks/chunk-EQ5DGS2W.js";import"./chunks/chunk-V4WSBIXB.js";export{u as SkillExecutor,l as SkillRegistry,i as VariableResolver,f as clearPluginSkillPaths,v as createExecutor,j as createResolver,c as discoverSkills,g as discoverSkillsWithMonorepo,w as executeSkill,y as expandSkillForLLM,z as formatSkillActivationMessage,m as getDefaultSkillPaths,d as getNestedSkillPaths,p as getSkillPathsFlat,n as getSkillRegistry,q as initializeSkillRegistry,e as listPluginSkillPaths,a as loadFullSkill,b as loadSkillFileContent,x as loadSkillMetadata,h as parseArguments,t as parseSkillMarkdown,o as registerPluginSkillPath,s as resetSkillRegistry,k as resolveSkillContent,r as unregisterPluginSkillPath};
+import{A as w,B as y,C as z,a as o,b as r,c as e,d as f,e as m,f as p,j as t,k as x,l as a,m as b,n as c,o as d,p as g,q as h,r as i,s as j,t as k,u as l,v as n,w as q,x as s,y as u,z as v}from"./chunks/chunk-OWSKU55I.js";import"./chunks/chunk-V4WSBIXB.js";export{u as SkillExecutor,l as SkillRegistry,i as VariableResolver,f as clearPluginSkillPaths,v as createExecutor,j as createResolver,c as discoverSkills,g as discoverSkillsWithMonorepo,w as executeSkill,y as expandSkillForLLM,z as formatSkillActivationMessage,m as getDefaultSkillPaths,d as getNestedSkillPaths,p as getSkillPathsFlat,n as getSkillRegistry,q as initializeSkillRegistry,e as listPluginSkillPaths,a as loadFullSkill,b as loadSkillFileContent,x as loadSkillMetadata,h as parseArguments,t as parseSkillMarkdown,o as registerPluginSkillPath,s as resetSkillRegistry,k as resolveSkillContent,r as unregisterPluginSkillPath};