@elisym/sdk 0.12.4 → 0.12.5

package/dist/skills.d.cts

@@ -17,11 +17,22 @@ interface SkillOutput {
     outputMime?: string;
 }
 interface SkillContext {
+    /** Required only when the routed skill has `mode === 'llm'`. */
     llm?: LlmClient;
     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 +72,8 @@ 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;
     image?: string;
     imageFile?: string;
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
@@ -77,6 +90,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 +105,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;
@@ -117,6 +161,7 @@ declare class ScriptSkill implements Skill {
     capabilities: string[];
     priceSubunits: bigint;
     asset: Asset;
+    mode: SkillMode;
     image?: string;
     imageFile?: string;
     private skillDir;
@@ -129,6 +174,122 @@ declare class ScriptSkill implements Skill {
     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 +304,16 @@ interface SkillFrontmatter {
     image_file?: unknown;
     tools?: unknown;
     max_tool_rounds?: 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 +322,20 @@ interface ParsedSkill {
     /** Price in subunits of `asset`. */
     priceSubunits: bigint;
     asset: Asset;
+    mode: SkillMode;
     systemPrompt: string;
     tools: SkillToolDef[];
     maxToolRounds: number;
     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 +357,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 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

@@ -17,11 +17,22 @@ interface SkillOutput {
     outputMime?: string;
 }
 interface SkillContext {
+    /** Required only when the routed skill has `mode === 'llm'`. */
     llm?: LlmClient;
     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 +72,8 @@ 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;
     image?: string;
     imageFile?: string;
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
@@ -77,6 +90,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 +105,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;
@@ -117,6 +161,7 @@ declare class ScriptSkill implements Skill {
     capabilities: string[];
     priceSubunits: bigint;
     asset: Asset;
+    mode: SkillMode;
     image?: string;
     imageFile?: string;
     private skillDir;
@@ -129,6 +174,122 @@ declare class ScriptSkill implements Skill {
     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 +304,16 @@ interface SkillFrontmatter {
     image_file?: unknown;
     tools?: unknown;
     max_tool_rounds?: 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 +322,20 @@ interface ParsedSkill {
     /** Price in subunits of `asset`. */
     priceSubunits: bigint;
     asset: Asset;
+    mode: SkillMode;
     systemPrompt: string;
     tools: SkillToolDef[];
     maxToolRounds: number;
     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 +357,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 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 };