@elisym/sdk 0.12.4 → 0.13.0

package/dist/skills.d.cts

@@ -16,12 +16,42 @@ interface SkillOutput {
     data: string;
     outputMime?: string;
 }
+/**
+ * Optional per-skill LLM override declared in SKILL.md frontmatter.
+ *
+ * Parse-time invariant (enforced by `validateLlmOverride` in the loader):
+ * `provider` is set iff `model` is set. `maxTokens` is independent. So
+ * downstream code may rely on: when `provider !== undefined`, `model` is
+ * also defined.
+ */
+interface SkillLlmOverride {
+    provider?: 'anthropic' | 'openai';
+    model?: string;
+    maxTokens?: number;
+}
 interface SkillContext {
+    /** Agent-default LLM client. May be undefined when every LLM skill overrides. */
     llm?: LlmClient;
+    /**
+     * Resolve the LLM client for a skill. The runtime caches clients by
+     * resolved (provider, model, maxTokens) triple. Callers pass their
+     * `llmOverride` (or undefined for the agent default).
+     */
+    getLlm?: (override?: SkillLlmOverride) => LlmClient | undefined;
     agentName: string;
     agentDescription: string;
     signal?: AbortSignal;
 }
+/**
+ * How the runtime produces a result for a job:
+ * - `llm`: feed input through Anthropic/OpenAI with the skill's system prompt (default).
+ * - `static-file`: return the contents of a fixed file. No input required.
+ * - `static-script`: spawn a script with no stdin. No input required.
+ * - `dynamic-script`: spawn a script and pipe the user's input to stdin.
+ *
+ * Static modes set `card.static = true` so the webapp hides its input box.
+ */
+type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script';
 interface ToolDef {
     name: string;
     description: string;
@@ -61,6 +91,14 @@ interface Skill {
     priceSubunits: bigint;
     /** Asset the price is denominated in (NATIVE_SOL or USDC_SOLANA_DEVNET, etc.). */
     asset: Asset;
+    /** Execution mode. Default 'llm' for back-compat. */
+    mode: SkillMode;
+    /**
+     * Optional per-skill LLM config override (only set when mode === 'llm').
+     * Carried through from SKILL.md frontmatter so the runtime can route this
+     * skill to a non-default model/provider/max_tokens.
+     */
+    llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
@@ -77,6 +115,8 @@ declare function createAnthropicClient(config: Omit<LlmClientConfig, 'provider'>
 declare function createOpenAIClient(config: Omit<LlmClientConfig, 'provider'>): LlmClient;
 declare function createLlmClient(config: LlmClientConfig): LlmClient;
 
+declare const MAX_SCRIPT_OUTPUT = 1000000;
+declare const DEFAULT_SCRIPT_TIMEOUT_MS = 60000;
 interface SkillToolDef {
     name: string;
     description: string;
@@ -90,6 +130,35 @@ interface SkillToolDef {
 interface ScriptSkillLogger {
     debug?(obj: Record<string, unknown>, msg?: string): void;
 }
+interface RunScriptOptions {
+    cwd: string;
+    /**
+     * UTF-8 string written to the child's stdin, then stdin closed.
+     * When undefined, stdin is closed immediately (EOF) so that children
+     * which read stdin do not block until `timeoutMs`.
+     */
+    stdin?: string;
+    /** Cancel the spawn. SIGKILL is sent on abort. */
+    signal?: AbortSignal;
+    /** Hard timeout in ms. Default `DEFAULT_SCRIPT_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /** Cap on stdout/stderr capture. Default `MAX_SCRIPT_OUTPUT`. */
+    maxOutput?: number;
+}
+interface RunScriptResult {
+    stdout: string;
+    stderr: string;
+    /** Null when the process was killed by signal before exiting. */
+    code: number | null;
+    /** Set when spawn itself failed (ENOENT, EACCES, etc.). */
+    spawnError?: Error;
+}
+/**
+ * Spawn `cmd` with `args` and capture stdout/stderr. Never uses `shell: true`,
+ * so shell metacharacters in arguments are safe. Caller is responsible for
+ * checking `code === 0` / interpreting `spawnError`.
+ */
+declare function runScript(cmd: string, args: string[], opts: RunScriptOptions): Promise<RunScriptResult>;
 interface ScriptSkillParams {
     name: string;
     description: string;
@@ -100,6 +169,8 @@ interface ScriptSkillParams {
     systemPrompt: string;
     tools: SkillToolDef[];
     maxToolRounds: number;
+    /** Optional per-skill LLM override (provider/model pair and/or maxTokens). */
+    llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
     logger?: ScriptSkillLogger;
@@ -117,6 +188,8 @@ declare class ScriptSkill implements Skill {
     capabilities: string[];
     priceSubunits: bigint;
     asset: Asset;
+    mode: SkillMode;
+    readonly llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
     private skillDir;
@@ -126,9 +199,137 @@ declare class ScriptSkill implements Skill {
     private logger;
     constructor(params: ScriptSkillParams);
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
+    /**
+     * Resolve the LLM client for this skill from the runtime context.
+     *
+     * Contract:
+     * - When `llmOverride` is set, `ctx.getLlm` MUST be wired. Falling back to
+     *   `ctx.llm` (the agent default) would silently use the wrong configuration
+     *   for max-tokens-only overrides.
+     * - When no override is set, prefer `ctx.getLlm()` (returns the agent
+     *   default), then fall back to `ctx.llm` for legacy callers that wire only
+     *   a single client.
+     */
+    private resolveLlmClient;
     private runTool;
 }
 
+/** Hard ceiling on result size for static-file skills. NIP-90 result events
+ *  travel through relays that may reject very large payloads; cap at 256 KB
+ *  of UTF-8. Larger files should use a script that streams to an external host. */
+declare const MAX_STATIC_FILE_SIZE: number;
+interface StaticFileSkillParams {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    /** Absolute path to the file whose contents are returned on each job. */
+    outputFilePath: string;
+    image?: string;
+    imageFile?: string;
+}
+/**
+ * Returns the contents of a fixed file as the job result. Reads on every
+ * `execute()` so authors can edit the file without restarting the agent.
+ */
+declare class StaticFileSkill implements Skill {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    mode: SkillMode;
+    image?: string;
+    imageFile?: string;
+    private outputFilePath;
+    constructor(params: StaticFileSkillParams);
+    execute(_input: SkillInput, _ctx: SkillContext): Promise<SkillOutput>;
+}
+
+interface StaticScriptSkillParams {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    /** Absolute path to the script. */
+    scriptPath: string;
+    /** Extra args appended after the script path. */
+    scriptArgs: string[];
+    /** Optional override of the default 60s timeout. */
+    scriptTimeoutMs?: number;
+    image?: string;
+    imageFile?: string;
+}
+/**
+ * Spawns a configured script with no stdin and returns its trimmed stdout.
+ * Throws on non-zero exit so the runtime surfaces a sanitized error.
+ * The script runs with cwd set to its containing directory so relative
+ * paths inside the script behave intuitively.
+ */
+declare class StaticScriptSkill implements Skill {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    mode: SkillMode;
+    image?: string;
+    imageFile?: string;
+    private scriptPath;
+    private scriptArgs;
+    private scriptTimeoutMs?;
+    constructor(params: StaticScriptSkillParams);
+    execute(_input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
+}
+
+interface DynamicScriptSkillParams {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    /** Absolute path to the script. */
+    scriptPath: string;
+    /** Extra args appended after the script path. */
+    scriptArgs: string[];
+    /** Optional override of the default 60s timeout. */
+    scriptTimeoutMs?: number;
+    image?: string;
+    imageFile?: string;
+}
+/**
+ * Pipes the user's job input to the script's stdin and returns its
+ * trimmed stdout. Enables script-backed capabilities (proxies to
+ * external models, classical NLP, custom workers) without an LLM key
+ * on the elisym side.
+ */
+declare class DynamicScriptSkill implements Skill {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    mode: SkillMode;
+    image?: string;
+    imageFile?: string;
+    private scriptPath;
+    private scriptArgs;
+    private scriptTimeoutMs?;
+    constructor(params: DynamicScriptSkillParams);
+    execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
+}
+
+/**
+ * Resolve `value` relative to `rootDir` and reject anything that escapes
+ * the root (`..` segments, absolute paths outside it, or the root itself).
+ *
+ * Returns the absolute path on success, or null on rejection so callers
+ * can surface a precise error message.
+ */
+declare function resolveInsidePath(rootDir: string, value: string): string | null;
+
 declare const DEFAULT_MAX_TOOL_ROUNDS = 10;
 interface SkillFrontmatter {
     name?: unknown;
@@ -143,6 +344,22 @@ interface SkillFrontmatter {
     image_file?: unknown;
     tools?: unknown;
     max_tool_rounds?: unknown;
+    /** Optional per-skill LLM provider override ('anthropic' | 'openai'). Pairs with `model`. */
+    provider?: unknown;
+    /** Optional per-skill LLM model override. Pairs with `provider`. */
+    model?: unknown;
+    /** Optional per-skill max_tokens override. Independent of provider/model. */
+    max_tokens?: unknown;
+    /** Execution mode. Default 'llm'. */
+    mode?: unknown;
+    /** Required when mode === 'static-file'. Path relative to skill dir. */
+    output_file?: unknown;
+    /** Required when mode === 'static-script' | 'dynamic-script'. Path relative to skill dir. */
+    script?: unknown;
+    /** Optional positional args appended after the script. */
+    script_args?: unknown;
+    /** Optional override of `DEFAULT_SCRIPT_TIMEOUT_MS`. */
+    script_timeout_ms?: unknown;
 }
 interface ParsedSkill {
     name: string;
@@ -151,11 +368,26 @@ interface ParsedSkill {
     /** Price in subunits of `asset`. */
     priceSubunits: bigint;
     asset: Asset;
+    mode: SkillMode;
     systemPrompt: string;
     tools: SkillToolDef[];
     maxToolRounds: number;
+    /**
+     * Per-skill LLM override (only present when mode === 'llm' and the SKILL.md
+     * declared at least one of `provider`/`model`/`max_tokens`). Parse-time
+     * invariant: `provider` set iff `model` set.
+     */
+    llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
+    /** Set when mode === 'static-file'. */
+    outputFile?: string;
+    /** Set when mode is a script mode. */
+    script?: string;
+    /** Empty when no script. */
+    scriptArgs: string[];
+    /** Undefined => caller uses `DEFAULT_SCRIPT_TIMEOUT_MS`. */
+    scriptTimeoutMs?: number;
 }
 interface LoaderLogger {
     debug?(obj: Record<string, unknown>, msg?: string): void;
@@ -177,9 +409,9 @@ declare function parseSkillMd(content: string): {
 declare function validateSkillFrontmatter(frontmatter: SkillFrontmatter, systemPrompt: string, options?: LoadSkillsOptions): ParsedSkill;
 /**
  * Walk `skillsDir`, load each immediate subdirectory's SKILL.md, and
- * return constructed `ScriptSkill` instances. Malformed directories are
- * skipped with a `warn` log.
+ * return constructed `Skill` instances (LLM or non-LLM depending on
+ * frontmatter `mode`). Malformed directories are skipped with a `warn` log.
  */
 declare function loadSkillsFromDir(skillsDir: string, options?: LoadSkillsOptions): Skill[];
 
-export { type CompletionResult, DEFAULT_MAX_TOOL_ROUNDS, type LlmClient, type LlmClientConfig, type LlmProvider, type LoadSkillsOptions, type LoaderLogger, type ParsedSkill, ScriptSkill, type ScriptSkillLogger, type ScriptSkillParams, type Skill, type SkillContext, type SkillFrontmatter, type SkillInput, type SkillOutput, type SkillToolDef, type ToolCall, type ToolDef, type ToolResult, createAnthropicClient, createLlmClient, createOpenAIClient, loadSkillsFromDir, parseSkillMd, validateSkillFrontmatter };
+export { type CompletionResult, DEFAULT_MAX_TOOL_ROUNDS, DEFAULT_SCRIPT_TIMEOUT_MS, DynamicScriptSkill, type DynamicScriptSkillParams, type LlmClient, type LlmClientConfig, type LlmProvider, type LoadSkillsOptions, type LoaderLogger, MAX_SCRIPT_OUTPUT, MAX_STATIC_FILE_SIZE, type ParsedSkill, type RunScriptOptions, type RunScriptResult, ScriptSkill, type ScriptSkillLogger, type ScriptSkillParams, type Skill, type SkillContext, type SkillFrontmatter, type SkillInput, type SkillLlmOverride, type SkillMode, type SkillOutput, type SkillToolDef, StaticFileSkill, type StaticFileSkillParams, StaticScriptSkill, type StaticScriptSkillParams, type ToolCall, type ToolDef, type ToolResult, createAnthropicClient, createLlmClient, createOpenAIClient, loadSkillsFromDir, parseSkillMd, resolveInsidePath, runScript, validateSkillFrontmatter };

package/dist/skills.d.ts

@@ -16,12 +16,42 @@ interface SkillOutput {
     data: string;
     outputMime?: string;
 }
+/**
+ * Optional per-skill LLM override declared in SKILL.md frontmatter.
+ *
+ * Parse-time invariant (enforced by `validateLlmOverride` in the loader):
+ * `provider` is set iff `model` is set. `maxTokens` is independent. So
+ * downstream code may rely on: when `provider !== undefined`, `model` is
+ * also defined.
+ */
+interface SkillLlmOverride {
+    provider?: 'anthropic' | 'openai';
+    model?: string;
+    maxTokens?: number;
+}
 interface SkillContext {
+    /** Agent-default LLM client. May be undefined when every LLM skill overrides. */
     llm?: LlmClient;
+    /**
+     * Resolve the LLM client for a skill. The runtime caches clients by
+     * resolved (provider, model, maxTokens) triple. Callers pass their
+     * `llmOverride` (or undefined for the agent default).
+     */
+    getLlm?: (override?: SkillLlmOverride) => LlmClient | undefined;
     agentName: string;
     agentDescription: string;
     signal?: AbortSignal;
 }
+/**
+ * How the runtime produces a result for a job:
+ * - `llm`: feed input through Anthropic/OpenAI with the skill's system prompt (default).
+ * - `static-file`: return the contents of a fixed file. No input required.
+ * - `static-script`: spawn a script with no stdin. No input required.
+ * - `dynamic-script`: spawn a script and pipe the user's input to stdin.
+ *
+ * Static modes set `card.static = true` so the webapp hides its input box.
+ */
+type SkillMode = 'llm' | 'static-file' | 'static-script' | 'dynamic-script';
 interface ToolDef {
     name: string;
     description: string;
@@ -61,6 +91,14 @@ interface Skill {
     priceSubunits: bigint;
     /** Asset the price is denominated in (NATIVE_SOL or USDC_SOLANA_DEVNET, etc.). */
     asset: Asset;
+    /** Execution mode. Default 'llm' for back-compat. */
+    mode: SkillMode;
+    /**
+     * Optional per-skill LLM config override (only set when mode === 'llm').
+     * Carried through from SKILL.md frontmatter so the runtime can route this
+     * skill to a non-default model/provider/max_tokens.
+     */
+    llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
@@ -77,6 +115,8 @@ declare function createAnthropicClient(config: Omit<LlmClientConfig, 'provider'>
 declare function createOpenAIClient(config: Omit<LlmClientConfig, 'provider'>): LlmClient;
 declare function createLlmClient(config: LlmClientConfig): LlmClient;
 
+declare const MAX_SCRIPT_OUTPUT = 1000000;
+declare const DEFAULT_SCRIPT_TIMEOUT_MS = 60000;
 interface SkillToolDef {
     name: string;
     description: string;
@@ -90,6 +130,35 @@ interface SkillToolDef {
 interface ScriptSkillLogger {
     debug?(obj: Record<string, unknown>, msg?: string): void;
 }
+interface RunScriptOptions {
+    cwd: string;
+    /**
+     * UTF-8 string written to the child's stdin, then stdin closed.
+     * When undefined, stdin is closed immediately (EOF) so that children
+     * which read stdin do not block until `timeoutMs`.
+     */
+    stdin?: string;
+    /** Cancel the spawn. SIGKILL is sent on abort. */
+    signal?: AbortSignal;
+    /** Hard timeout in ms. Default `DEFAULT_SCRIPT_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /** Cap on stdout/stderr capture. Default `MAX_SCRIPT_OUTPUT`. */
+    maxOutput?: number;
+}
+interface RunScriptResult {
+    stdout: string;
+    stderr: string;
+    /** Null when the process was killed by signal before exiting. */
+    code: number | null;
+    /** Set when spawn itself failed (ENOENT, EACCES, etc.). */
+    spawnError?: Error;
+}
+/**
+ * Spawn `cmd` with `args` and capture stdout/stderr. Never uses `shell: true`,
+ * so shell metacharacters in arguments are safe. Caller is responsible for
+ * checking `code === 0` / interpreting `spawnError`.
+ */
+declare function runScript(cmd: string, args: string[], opts: RunScriptOptions): Promise<RunScriptResult>;
 interface ScriptSkillParams {
     name: string;
     description: string;
@@ -100,6 +169,8 @@ interface ScriptSkillParams {
     systemPrompt: string;
     tools: SkillToolDef[];
     maxToolRounds: number;
+    /** Optional per-skill LLM override (provider/model pair and/or maxTokens). */
+    llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
     logger?: ScriptSkillLogger;
@@ -117,6 +188,8 @@ declare class ScriptSkill implements Skill {
     capabilities: string[];
     priceSubunits: bigint;
     asset: Asset;
+    mode: SkillMode;
+    readonly llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
     private skillDir;
@@ -126,9 +199,137 @@ declare class ScriptSkill implements Skill {
     private logger;
     constructor(params: ScriptSkillParams);
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
+    /**
+     * Resolve the LLM client for this skill from the runtime context.
+     *
+     * Contract:
+     * - When `llmOverride` is set, `ctx.getLlm` MUST be wired. Falling back to
+     *   `ctx.llm` (the agent default) would silently use the wrong configuration
+     *   for max-tokens-only overrides.
+     * - When no override is set, prefer `ctx.getLlm()` (returns the agent
+     *   default), then fall back to `ctx.llm` for legacy callers that wire only
+     *   a single client.
+     */
+    private resolveLlmClient;
     private runTool;
 }
 
+/** Hard ceiling on result size for static-file skills. NIP-90 result events
+ *  travel through relays that may reject very large payloads; cap at 256 KB
+ *  of UTF-8. Larger files should use a script that streams to an external host. */
+declare const MAX_STATIC_FILE_SIZE: number;
+interface StaticFileSkillParams {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    /** Absolute path to the file whose contents are returned on each job. */
+    outputFilePath: string;
+    image?: string;
+    imageFile?: string;
+}
+/**
+ * Returns the contents of a fixed file as the job result. Reads on every
+ * `execute()` so authors can edit the file without restarting the agent.
+ */
+declare class StaticFileSkill implements Skill {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    mode: SkillMode;
+    image?: string;
+    imageFile?: string;
+    private outputFilePath;
+    constructor(params: StaticFileSkillParams);
+    execute(_input: SkillInput, _ctx: SkillContext): Promise<SkillOutput>;
+}
+
+interface StaticScriptSkillParams {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    /** Absolute path to the script. */
+    scriptPath: string;
+    /** Extra args appended after the script path. */
+    scriptArgs: string[];
+    /** Optional override of the default 60s timeout. */
+    scriptTimeoutMs?: number;
+    image?: string;
+    imageFile?: string;
+}
+/**
+ * Spawns a configured script with no stdin and returns its trimmed stdout.
+ * Throws on non-zero exit so the runtime surfaces a sanitized error.
+ * The script runs with cwd set to its containing directory so relative
+ * paths inside the script behave intuitively.
+ */
+declare class StaticScriptSkill implements Skill {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    mode: SkillMode;
+    image?: string;
+    imageFile?: string;
+    private scriptPath;
+    private scriptArgs;
+    private scriptTimeoutMs?;
+    constructor(params: StaticScriptSkillParams);
+    execute(_input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
+}
+
+interface DynamicScriptSkillParams {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    /** Absolute path to the script. */
+    scriptPath: string;
+    /** Extra args appended after the script path. */
+    scriptArgs: string[];
+    /** Optional override of the default 60s timeout. */
+    scriptTimeoutMs?: number;
+    image?: string;
+    imageFile?: string;
+}
+/**
+ * Pipes the user's job input to the script's stdin and returns its
+ * trimmed stdout. Enables script-backed capabilities (proxies to
+ * external models, classical NLP, custom workers) without an LLM key
+ * on the elisym side.
+ */
+declare class DynamicScriptSkill implements Skill {
+    name: string;
+    description: string;
+    capabilities: string[];
+    priceSubunits: bigint;
+    asset: Asset;
+    mode: SkillMode;
+    image?: string;
+    imageFile?: string;
+    private scriptPath;
+    private scriptArgs;
+    private scriptTimeoutMs?;
+    constructor(params: DynamicScriptSkillParams);
+    execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
+}
+
+/**
+ * Resolve `value` relative to `rootDir` and reject anything that escapes
+ * the root (`..` segments, absolute paths outside it, or the root itself).
+ *
+ * Returns the absolute path on success, or null on rejection so callers
+ * can surface a precise error message.
+ */
+declare function resolveInsidePath(rootDir: string, value: string): string | null;
+
 declare const DEFAULT_MAX_TOOL_ROUNDS = 10;
 interface SkillFrontmatter {
     name?: unknown;
@@ -143,6 +344,22 @@ interface SkillFrontmatter {
     image_file?: unknown;
     tools?: unknown;
     max_tool_rounds?: unknown;
+    /** Optional per-skill LLM provider override ('anthropic' | 'openai'). Pairs with `model`. */
+    provider?: unknown;
+    /** Optional per-skill LLM model override. Pairs with `provider`. */
+    model?: unknown;
+    /** Optional per-skill max_tokens override. Independent of provider/model. */
+    max_tokens?: unknown;
+    /** Execution mode. Default 'llm'. */
+    mode?: unknown;
+    /** Required when mode === 'static-file'. Path relative to skill dir. */
+    output_file?: unknown;
+    /** Required when mode === 'static-script' | 'dynamic-script'. Path relative to skill dir. */
+    script?: unknown;
+    /** Optional positional args appended after the script. */
+    script_args?: unknown;
+    /** Optional override of `DEFAULT_SCRIPT_TIMEOUT_MS`. */
+    script_timeout_ms?: unknown;
 }
 interface ParsedSkill {
     name: string;
@@ -151,11 +368,26 @@ interface ParsedSkill {
     /** Price in subunits of `asset`. */
     priceSubunits: bigint;
     asset: Asset;
+    mode: SkillMode;
     systemPrompt: string;
     tools: SkillToolDef[];
     maxToolRounds: number;
+    /**
+     * Per-skill LLM override (only present when mode === 'llm' and the SKILL.md
+     * declared at least one of `provider`/`model`/`max_tokens`). Parse-time
+     * invariant: `provider` set iff `model` set.
+     */
+    llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
+    /** Set when mode === 'static-file'. */
+    outputFile?: string;
+    /** Set when mode is a script mode. */
+    script?: string;
+    /** Empty when no script. */
+    scriptArgs: string[];
+    /** Undefined => caller uses `DEFAULT_SCRIPT_TIMEOUT_MS`. */
+    scriptTimeoutMs?: number;
 }
 interface LoaderLogger {
     debug?(obj: Record<string, unknown>, msg?: string): void;
@@ -177,9 +409,9 @@ declare function parseSkillMd(content: string): {
 declare function validateSkillFrontmatter(frontmatter: SkillFrontmatter, systemPrompt: string, options?: LoadSkillsOptions): ParsedSkill;
 /**
  * Walk `skillsDir`, load each immediate subdirectory's SKILL.md, and
- * return constructed `ScriptSkill` instances. Malformed directories are
- * skipped with a `warn` log.
+ * return constructed `Skill` instances (LLM or non-LLM depending on
+ * frontmatter `mode`). Malformed directories are skipped with a `warn` log.
  */
 declare function loadSkillsFromDir(skillsDir: string, options?: LoadSkillsOptions): Skill[];
 
-export { type CompletionResult, DEFAULT_MAX_TOOL_ROUNDS, type LlmClient, type LlmClientConfig, type LlmProvider, type LoadSkillsOptions, type LoaderLogger, type ParsedSkill, ScriptSkill, type ScriptSkillLogger, type ScriptSkillParams, type Skill, type SkillContext, type SkillFrontmatter, type SkillInput, type SkillOutput, type SkillToolDef, type ToolCall, type ToolDef, type ToolResult, createAnthropicClient, createLlmClient, createOpenAIClient, loadSkillsFromDir, parseSkillMd, validateSkillFrontmatter };
+export { type CompletionResult, DEFAULT_MAX_TOOL_ROUNDS, DEFAULT_SCRIPT_TIMEOUT_MS, DynamicScriptSkill, type DynamicScriptSkillParams, type LlmClient, type LlmClientConfig, type LlmProvider, type LoadSkillsOptions, type LoaderLogger, MAX_SCRIPT_OUTPUT, MAX_STATIC_FILE_SIZE, type ParsedSkill, type RunScriptOptions, type RunScriptResult, ScriptSkill, type ScriptSkillLogger, type ScriptSkillParams, type Skill, type SkillContext, type SkillFrontmatter, type SkillInput, type SkillLlmOverride, type SkillMode, type SkillOutput, type SkillToolDef, StaticFileSkill, type StaticFileSkillParams, StaticScriptSkill, type StaticScriptSkillParams, type ToolCall, type ToolDef, type ToolResult, createAnthropicClient, createLlmClient, createOpenAIClient, loadSkillsFromDir, parseSkillMd, resolveInsidePath, runScript, validateSkillFrontmatter };