@kodax-ai/kodax 0.7.57 → 0.7.59

package/dist/sdk-skills.d.ts

@@ -1,232 +1,5 @@
-/**
- * Agent Skills Standard Type Definitions
- * Compliant with https://agentskills.io/ specification
- *
- * 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; still invokable by explicit slash forms. */
-    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.
- *
- * 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
- * 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;
-}>;
+import { l as SkillSource, S as Skill, e as SkillFile, i as SkillMetadata, f as SkillFrontmatter, j as SkillPathsConfig, a as IVariableResolver, c as SkillContext, I as ISkillRegistry, k as SkillResult } from './types-chunks/types.d-vJExiRje.js';
+export { b as SkillArtifact, d as SkillDynamicContextExecutor, g as SkillHook, h as SkillHooks, m as getDefaultSkillPaths, n as getSkillPathsFlat } from './types-chunks/types.d-vJExiRje.js';
 
 declare function registerPluginSkillPath(skillPath: string): () => void;
 declare function unregisterPluginSkillPath(skillPath: string): boolean;
@@ -556,5 +329,5 @@ declare function expandSkillForLLM(skill: Skill, args: string, context: SkillCon
  */
 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 };
+export { ISkillRegistry, IVariableResolver, Skill, SkillContext, SkillExecutor, SkillFile, SkillFrontmatter, SkillMetadata, SkillPathsConfig, SkillRegistry, SkillResult, SkillSource, VariableResolver, clearPluginSkillPaths, createExecutor, createResolver, discoverSkills, discoverSkillsWithMonorepo, executeSkill, expandSkillForLLM, formatSkillActivationMessage, getNestedSkillPaths, getSkillRegistry, initializeSkillRegistry, listPluginSkillPaths, loadFullSkill, loadSkillFileContent, loadSkillMetadata, parseArguments, parseSkillMarkdown, registerPluginSkillPath, resetSkillRegistry, resolveSkillContent, unregisterPluginSkillPath };
+export type { DiscoveryResult, ExecutionMode, ExecutionOptions, SkillExpansionResult };

package/dist/sdk-skills.js

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{Cc as k,Dc as r,Ec as S,Fc as s,Gc as n,Hc as g,Ic as u,Jc as c,Kc as x,Lc as d,Mc as P,Nc as R,Oc as h,Pc as p,Qc as v,Rc as y,Sc as M,Tc as f,Uc as m,Vc as E,tc as l,uc as e,vc as i,wc as t,xc as a,yc as o}from"./chunks/chunk-N2N2W3AQ.js";import"./chunks/chunk-V4WSBIXB.js";export{y as SkillExecutor,R as SkillRegistry,x as VariableResolver,t as clearPluginSkillPaths,M as createExecutor,d as createResolver,n as discoverSkills,u as discoverSkillsWithMonorepo,f as executeSkill,m as expandSkillForLLM,E as formatSkillActivationMessage,a as getDefaultSkillPaths,g as getNestedSkillPaths,o as getSkillPathsFlat,h as getSkillRegistry,p as initializeSkillRegistry,i as listPluginSkillPaths,S as loadFullSkill,s as loadSkillFileContent,r as loadSkillMetadata,c as parseArguments,k as parseSkillMarkdown,l as registerPluginSkillPath,v as resetSkillRegistry,P as resolveSkillContent,e as unregisterPluginSkillPath};
+import{Ac as o,Ec as k,Fc as r,Gc as S,Hc as s,Ic as n,Jc as g,Kc as u,Lc as c,Mc as x,Nc as d,Oc as P,Pc as R,Qc as h,Rc as p,Sc as v,Tc as y,Uc as M,Vc as f,Wc as m,Xc as E,vc as l,wc as e,xc as i,yc as t,zc as a}from"./chunks/chunk-PRIBJN5E.js";import"./chunks/chunk-BEXLPFFB.js";import"./chunks/chunk-V4WSBIXB.js";export{y as SkillExecutor,R as SkillRegistry,x as VariableResolver,t as clearPluginSkillPaths,M as createExecutor,d as createResolver,n as discoverSkills,u as discoverSkillsWithMonorepo,f as executeSkill,m as expandSkillForLLM,E as formatSkillActivationMessage,a as getDefaultSkillPaths,g as getNestedSkillPaths,o as getSkillPathsFlat,h as getSkillRegistry,p as initializeSkillRegistry,i as listPluginSkillPaths,S as loadFullSkill,s as loadSkillFileContent,r as loadSkillMetadata,c as parseArguments,k as parseSkillMarkdown,l as registerPluginSkillPath,v as resetSkillRegistry,P as resolveSkillContent,e as unregisterPluginSkillPath};

package/dist/types-chunks/{base.d-BnjQrSVf.d.ts → base.d-BA9Doaj_.d.ts}

@@ -1,9 +1,9 @@
-import { p as KodaXProviderConfig, j as KodaXMessage, _ as KodaXToolDefinition, G as KodaXReasoningRequest, x as KodaXProviderStreamOptions, M as KodaXStreamResult, a4 as KodaXVerifyCredentialResult, k as KodaXModelDescriptor, o as KodaXProviderCapabilityProfile, A as KodaXReasoningCapability, F as KodaXReasoningProfile, m as KodaXNormalizedReasoningRequest, a6 as KodaXWireReasoningEffort } from './types.d-6VOXvF88.js';
+import { p as KodaXProviderConfig, j as KodaXMessage, _ as KodaXToolDefinition, G as KodaXReasoningRequest, x as KodaXProviderStreamOptions, M as KodaXStreamResult, a4 as KodaXVerifyCredentialResult, k as KodaXModelDescriptor, o as KodaXProviderCapabilityProfile, A as KodaXReasoningCapability, F as KodaXReasoningProfile, m as KodaXNormalizedReasoningRequest, a6 as KodaXWireReasoningEffort } from './types.d-Ci5YPFEh.js';
 
 /**
  * Retry-After header parsing — FEATURE_130 (v0.7.36).
  *
- * Handles the four forms KodaX's 12 provider adapters encounter when a
+ * Handles the four forms KodaX's built-in provider adapters encounter when a
  * model returns 429 (rate limit) or 503/529 (overloaded):
  *
  *   1. `Retry-After: 120`               — integer seconds (HTTP 7231 standard)
@@ -277,7 +277,7 @@ declare abstract class KodaXBaseProvider {
      * Returns milliseconds, or undefined when no usable header is present.
      *
      * FEATURE_130 (v0.7.36): now delegates to the shared `parseRetryAfter`
-     * helper so all 12 provider adapters get 4-form coverage without each
+     * helper so all built-in provider adapters get 4-form coverage without each
      * adapter rolling its own parser. The 4 forms supported are:
      *   - `Retry-After: <integer-seconds>`
      *   - `Retry-After: <HTTP-date>`