@elisym/sdk 0.23.0 → 0.24.1

package/dist/skills.d.cts

@@ -1,5 +1,5 @@
 import { A as Asset } from './assets-C-nzSYD4.cjs';
-import { S as SkillRateLimit } from './types-Cdscy9kY.cjs';
+import { S as SkillRateLimit } from './types-CqN9kFTn.cjs';
 
 /**
  * Shared SKILL.md runtime types. A skill is a markdown document whose
@@ -12,10 +12,29 @@ interface SkillInput {
     inputType: string;
     tags: string[];
     jobId: string;
+    /**
+     * Local path to a file input fetched out-of-band (P2P via iroh), when the job
+     * carried a file attachment. The runtime fetches it after payment and removes
+     * it after execution; the skill reads from disk rather than from `data`.
+     */
+    filePath?: string;
 }
 interface SkillOutput {
     data: string;
     outputMime?: string;
+    /**
+     * Local path to a file result. When set, the runtime seeds the file via iroh
+     * and the customer fetches it out-of-band; `data` carries any text note (or '').
+     * `outputMime` is reused as the attachment's mime.
+     */
+    filePath?: string;
+    /**
+     * Releases the resources backing `filePath` (e.g. a temp dir). The runtime
+     * calls it once it has seeded the file - or failed to - since seeding happens
+     * after `execute()` returns and the producer cannot release the file itself.
+     * Mirrors the input-side cleanup callback in the runtime's `resolveInputFile`.
+     */
+    cleanup?: () => Promise<void>;
 }
 /**
  * Optional per-skill LLM override declared in SKILL.md frontmatter.
@@ -342,6 +361,12 @@ interface DynamicScriptSkillParams {
      * itself reads the key from its environment.
      */
     llmOverride?: SkillLlmOverride;
+    /**
+     * MIME type the script declares for a file result (SKILL.md `output_mime`).
+     * Used only when the script writes a file to `ELISYM_OUTPUT_FILE`; becomes the
+     * iroh attachment's mime. Defaults to `application/octet-stream`.
+     */
+    outputMime?: string;
 }
 /**
  * Pipes the user's job input to the script's stdin and returns its
@@ -363,6 +388,7 @@ declare class DynamicScriptSkill implements Skill {
     private scriptArgs;
     private scriptTimeoutMs?;
     private scriptEnv?;
+    private outputMime?;
     constructor(params: DynamicScriptSkillParams);
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
 }
@@ -411,6 +437,20 @@ interface SkillFrontmatter {
     script_args?: unknown;
     /** Optional override of `DEFAULT_SCRIPT_TIMEOUT_MS`. */
     script_timeout_ms?: unknown;
+    /**
+     * MIME type for a file result. Only valid in mode 'dynamic-script' (the only
+     * mode that can emit a file via `ELISYM_OUTPUT_FILE`). Becomes the iroh
+     * attachment's mime; defaults to `application/octet-stream` when omitted.
+     */
+    output_mime?: unknown;
+    /**
+     * MIME the skill expects as a file input. Only valid in mode 'dynamic-script'
+     * (the only mode that receives a file via `ELISYM_INPUT_FILE`). Discovery hint
+     * only - the runtime still content-sniffs the actual file and does not enforce
+     * this. Convention: `*` = any file, `image/*` = any image, `image/png` =
+     * exact. Its presence signals "this capability needs a file input".
+     */
+    input_mime?: unknown;
     /**
      * Optional per-skill rate limit. Applies to any skill mode. Snake-case
      * keys here match the YAML frontmatter convention; parsed into camelCase
@@ -455,6 +495,14 @@ interface ParsedSkill {
     scriptArgs: string[];
     /** Undefined => caller uses `DEFAULT_SCRIPT_TIMEOUT_MS`. */
     scriptTimeoutMs?: number;
+    /** MIME for a file result (mode 'dynamic-script' only). */
+    outputMime?: string;
+    /**
+     * MIME the skill expects as a file input (mode 'dynamic-script' only).
+     * Discovery hint only; not enforced at runtime. Presence signals the
+     * capability needs a file input (clients gate file-only flows on it).
+     */
+    inputMime?: string;
     /** Optional per-skill rate limit (any mode). */
     rateLimit?: SkillRateLimit;
     /**

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 import { A as Asset } from './assets-C-nzSYD4.js';
-import { S as SkillRateLimit } from './types-Cdscy9kY.js';
+import { S as SkillRateLimit } from './types-CqN9kFTn.js';
 
 /**
  * Shared SKILL.md runtime types. A skill is a markdown document whose
@@ -12,10 +12,29 @@ interface SkillInput {
     inputType: string;
     tags: string[];
     jobId: string;
+    /**
+     * Local path to a file input fetched out-of-band (P2P via iroh), when the job
+     * carried a file attachment. The runtime fetches it after payment and removes
+     * it after execution; the skill reads from disk rather than from `data`.
+     */
+    filePath?: string;
 }
 interface SkillOutput {
     data: string;
     outputMime?: string;
+    /**
+     * Local path to a file result. When set, the runtime seeds the file via iroh
+     * and the customer fetches it out-of-band; `data` carries any text note (or '').
+     * `outputMime` is reused as the attachment's mime.
+     */
+    filePath?: string;
+    /**
+     * Releases the resources backing `filePath` (e.g. a temp dir). The runtime
+     * calls it once it has seeded the file - or failed to - since seeding happens
+     * after `execute()` returns and the producer cannot release the file itself.
+     * Mirrors the input-side cleanup callback in the runtime's `resolveInputFile`.
+     */
+    cleanup?: () => Promise<void>;
 }
 /**
  * Optional per-skill LLM override declared in SKILL.md frontmatter.
@@ -342,6 +361,12 @@ interface DynamicScriptSkillParams {
      * itself reads the key from its environment.
      */
     llmOverride?: SkillLlmOverride;
+    /**
+     * MIME type the script declares for a file result (SKILL.md `output_mime`).
+     * Used only when the script writes a file to `ELISYM_OUTPUT_FILE`; becomes the
+     * iroh attachment's mime. Defaults to `application/octet-stream`.
+     */
+    outputMime?: string;
 }
 /**
  * Pipes the user's job input to the script's stdin and returns its
@@ -363,6 +388,7 @@ declare class DynamicScriptSkill implements Skill {
     private scriptArgs;
     private scriptTimeoutMs?;
     private scriptEnv?;
+    private outputMime?;
     constructor(params: DynamicScriptSkillParams);
     execute(input: SkillInput, ctx: SkillContext): Promise<SkillOutput>;
 }
@@ -411,6 +437,20 @@ interface SkillFrontmatter {
     script_args?: unknown;
     /** Optional override of `DEFAULT_SCRIPT_TIMEOUT_MS`. */
     script_timeout_ms?: unknown;
+    /**
+     * MIME type for a file result. Only valid in mode 'dynamic-script' (the only
+     * mode that can emit a file via `ELISYM_OUTPUT_FILE`). Becomes the iroh
+     * attachment's mime; defaults to `application/octet-stream` when omitted.
+     */
+    output_mime?: unknown;
+    /**
+     * MIME the skill expects as a file input. Only valid in mode 'dynamic-script'
+     * (the only mode that receives a file via `ELISYM_INPUT_FILE`). Discovery hint
+     * only - the runtime still content-sniffs the actual file and does not enforce
+     * this. Convention: `*` = any file, `image/*` = any image, `image/png` =
+     * exact. Its presence signals "this capability needs a file input".
+     */
+    input_mime?: unknown;
     /**
      * Optional per-skill rate limit. Applies to any skill mode. Snake-case
      * keys here match the YAML frontmatter convention; parsed into camelCase
@@ -455,6 +495,14 @@ interface ParsedSkill {
     scriptArgs: string[];
     /** Undefined => caller uses `DEFAULT_SCRIPT_TIMEOUT_MS`. */
     scriptTimeoutMs?: number;
+    /** MIME for a file result (mode 'dynamic-script' only). */
+    outputMime?: string;
+    /**
+     * MIME the skill expects as a file input (mode 'dynamic-script' only).
+     * Discovery hint only; not enforced at runtime. Presence signals the
+     * capability needs a file input (clients gate file-only flows on it).
+     */
+    inputMime?: string;
     /** Optional per-skill rate limit (any mode). */
     rateLimit?: SkillRateLimit;
     /**

package/dist/skills.js

@@ -1,7 +1,8 @@
 import { spawn } from 'node:child_process';
 import { StringDecoder } from 'node:string_decoder';
-import { readFile } from 'node:fs/promises';
-import { dirname, resolve, relative, sep, join } from 'node:path';
+import { readFile, mkdtemp, stat, rm } from 'node:fs/promises';
+import { dirname, join, resolve, relative, sep } from 'node:path';
+import { tmpdir } from 'node:os';
 import { readdirSync, statSync, readFileSync } from 'node:fs';
 import YAML from 'yaml';
 import Decimal from 'decimal.js-light';
@@ -345,6 +346,7 @@ var DynamicScriptSkill = class {
   scriptArgs;
   scriptTimeoutMs;
   scriptEnv;
+  outputMime;
   constructor(params) {
     this.name = params.name;
     this.description = params.description;
@@ -358,35 +360,65 @@ var DynamicScriptSkill = class {
     this.scriptArgs = params.scriptArgs;
     this.scriptTimeoutMs = params.scriptTimeoutMs;
     this.scriptEnv = params.scriptEnv;
+    this.outputMime = params.outputMime;
   }
   async execute(input, ctx) {
-    const result = await runScript(this.scriptPath, this.scriptArgs, {
-      cwd: dirname(this.scriptPath),
-      stdin: input.data,
-      signal: ctx.signal,
-      timeoutMs: this.scriptTimeoutMs,
-      env: this.scriptEnv
-    });
-    if (result.spawnError) {
-      throw new ScriptExecutionError(
-        null,
-        result.spawnError.message,
-        "script could not be started"
-      );
-    }
-    if (result.code === SCRIPT_EXIT_BILLING_EXHAUSTED) {
-      throw new ScriptBillingExhaustedError(result.code, result.stdout, result.stderr);
-    }
-    if (result.code !== 0) {
-      const detail = result.stderr.trim() || result.stdout.trim() || "(no output)";
-      throw new ScriptExecutionError(result.code, detail);
+    const outDir = await mkdtemp(join(tmpdir(), "elisym-skill-out-"));
+    const outputFile = join(outDir, "output");
+    const env = {
+      ...this.scriptEnv ?? process.env,
+      ELISYM_OUTPUT_FILE: outputFile
+    };
+    if (input.filePath !== void 0) {
+      env.ELISYM_INPUT_FILE = input.filePath;
     }
-    const output = result.stdout.trim();
-    if (output === "") {
-      const detail = result.stderr.trim() || "(no stderr)";
-      throw new ScriptExecutionError(result.code, detail, "script produced empty output");
+    let keepOutDir = false;
+    try {
+      const result = await runScript(this.scriptPath, this.scriptArgs, {
+        cwd: dirname(this.scriptPath),
+        stdin: input.data,
+        signal: ctx.signal,
+        timeoutMs: this.scriptTimeoutMs,
+        env
+      });
+      if (result.spawnError) {
+        throw new ScriptExecutionError(
+          null,
+          result.spawnError.message,
+          "script could not be started"
+        );
+      }
+      if (result.code === SCRIPT_EXIT_BILLING_EXHAUSTED) {
+        throw new ScriptBillingExhaustedError(result.code, result.stdout, result.stderr);
+      }
+      if (result.code !== 0) {
+        const detail = result.stderr.trim() || result.stdout.trim() || "(no output)";
+        throw new ScriptExecutionError(result.code, detail);
+      }
+      const outputStat = await stat(outputFile).catch(() => null);
+      if (outputStat !== null && outputStat.isFile() && outputStat.size > 0) {
+        keepOutDir = true;
+        return {
+          data: result.stdout.trim(),
+          filePath: outputFile,
+          outputMime: this.outputMime ?? "application/octet-stream",
+          cleanup: async () => {
+            await rm(outDir, { recursive: true, force: true });
+          }
+        };
+      }
+      const output = result.stdout.trim();
+      if (output === "") {
+        const detail = result.stderr.trim() || "(no stderr)";
+        throw new ScriptExecutionError(result.code, detail, "script produced empty output");
+      }
+      return { data: output };
+    } finally {
+      if (!keepOutDir) {
+        await rm(outDir, { recursive: true, force: true }).catch(() => {
+        });
+      }
     }
-    return { data: output };
   }
 };
 function resolveInsidePath(rootDir, value) {
@@ -404,6 +436,7 @@ var LIMITS = {
   // hours, so this exists only to keep `secs * 1000` within Node's setTimeout limit
   // (2_147_483_647 ms) - a larger value overflows and fires the timer immediately.
   MAX_EXECUTION_SECS: 2147483};
+new TextEncoder();
 var NATIVE_SOL = {
   chain: "solana",
   token: "sol",
@@ -701,6 +734,34 @@ function validateScriptTimeoutMs(skillName, raw) {
   }
   return raw;
 }
+function validateOutputMime(skillName, raw) {
+  if (raw === void 0 || raw === null) {
+    return void 0;
+  }
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(
+      `SKILL.md "${skillName}": "output_mime" must be a non-empty string (e.g. "image/png")`
+    );
+  }
+  if (raw.length > 255) {
+    throw new Error(`SKILL.md "${skillName}": "output_mime" too long (max 255 chars)`);
+  }
+  return raw;
+}
+function validateInputMime(skillName, raw) {
+  if (raw === void 0 || raw === null) {
+    return void 0;
+  }
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(
+      `SKILL.md "${skillName}": "input_mime" must be a non-empty string (e.g. "image/png" or "*")`
+    );
+  }
+  if (raw.length > 255) {
+    throw new Error(`SKILL.md "${skillName}": "input_mime" too long (max 255 chars)`);
+  }
+  return raw;
+}
 function validateMaxExecutionSecs(skillName, raw) {
   if (raw === void 0 || raw === null) {
     return void 0;
@@ -801,6 +862,8 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
   let script;
   let scriptArgs = [];
   let scriptTimeoutMs;
+  let outputMime;
+  let inputMime;
   if (mode === "static-file") {
     if (typeof frontmatter.output_file !== "string" || frontmatter.output_file.length === 0) {
       throw new Error(
@@ -812,6 +875,16 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
         `SKILL.md "${frontmatter.name}": "script" is not valid in mode 'static-file'`
       );
     }
+    if (frontmatter.output_mime !== void 0) {
+      throw new Error(
+        `SKILL.md "${frontmatter.name}": "output_mime" is only valid in mode 'dynamic-script'`
+      );
+    }
+    if (frontmatter.input_mime !== void 0) {
+      throw new Error(
+        `SKILL.md "${frontmatter.name}": "input_mime" is only valid in mode 'dynamic-script'`
+      );
+    }
     outputFile = frontmatter.output_file;
   } else if (mode === "static-script" || mode === "dynamic-script") {
     if (typeof frontmatter.script !== "string" || frontmatter.script.length === 0) {
@@ -825,6 +898,21 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
     script = frontmatter.script;
     scriptArgs = validateScriptArgs(frontmatter.name, frontmatter.script_args);
     scriptTimeoutMs = validateScriptTimeoutMs(frontmatter.name, frontmatter.script_timeout_ms);
+    if (mode === "dynamic-script") {
+      outputMime = validateOutputMime(frontmatter.name, frontmatter.output_mime);
+      inputMime = validateInputMime(frontmatter.name, frontmatter.input_mime);
+    } else {
+      if (frontmatter.output_mime !== void 0) {
+        throw new Error(
+          `SKILL.md "${frontmatter.name}": "output_mime" is only valid in mode 'dynamic-script'`
+        );
+      }
+      if (frontmatter.input_mime !== void 0) {
+        throw new Error(
+          `SKILL.md "${frontmatter.name}": "input_mime" is only valid in mode 'dynamic-script'`
+        );
+      }
+    }
   } else {
     if (frontmatter.output_file !== void 0) {
       throw new Error(
@@ -846,6 +934,16 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
         `SKILL.md "${frontmatter.name}": "script_timeout_ms" is only valid in script modes`
       );
     }
+    if (frontmatter.output_mime !== void 0) {
+      throw new Error(
+        `SKILL.md "${frontmatter.name}": "output_mime" is only valid in mode 'dynamic-script'`
+      );
+    }
+    if (frontmatter.input_mime !== void 0) {
+      throw new Error(
+        `SKILL.md "${frontmatter.name}": "input_mime" is only valid in mode 'dynamic-script'`
+      );
+    }
   }
   const image = typeof frontmatter.image === "string" ? frontmatter.image : void 0;
   const imageFile = typeof frontmatter.image_file === "string" ? frontmatter.image_file : void 0;
@@ -872,6 +970,8 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
     script,
     scriptArgs,
     scriptTimeoutMs,
+    outputMime,
+    inputMime,
     rateLimit,
     executionTimeoutSecs
   };
@@ -937,8 +1037,7 @@ function buildSkillFromParsed(parsed, skillDir, logger) {
       if (!scriptPath) {
         throw new Error(`SKILL.md "${parsed.name}": "script" must stay inside the skill directory`);
       }
-      const Ctor = parsed.mode === "static-script" ? StaticScriptSkill : DynamicScriptSkill;
-      return new Ctor({
+      const scriptParams = {
         name: parsed.name,
         description: parsed.description,
         capabilities: parsed.capabilities,
@@ -950,7 +1049,8 @@ function buildSkillFromParsed(parsed, skillDir, logger) {
         image: parsed.image,
         imageFile,
         llmOverride: parsed.llmOverride
-      });
+      };
+      return parsed.mode === "dynamic-script" ? new DynamicScriptSkill({ ...scriptParams, outputMime: parsed.outputMime }) : new StaticScriptSkill(scriptParams);
     }
   }
 }