@elisym/sdk 0.22.0 → 0.24.0

package/dist/skills.d.cts

@@ -1,5 +1,5 @@
 import { A as Asset } from './assets-C-nzSYD4.cjs';
-import { S as SkillRateLimit } from './types-COvV499T.cjs';
+import { S as SkillRateLimit } from './types-Cdscy9kY.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-COvV499T.js';
+import { S as SkillRateLimit } from './types-Cdscy9kY.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';
@@ -56,6 +57,14 @@ function runScript(cmd, args, opts) {
     }
   });
 }
+var SECRET_ENV_VARS = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
+function scopedToolEnv() {
+  const env = { ...process.env };
+  for (const key of SECRET_ENV_VARS) {
+    delete env[key];
+  }
+  return env;
+}
 var ScriptSkill = class {
   name;
   description;
@@ -177,13 +186,21 @@ var ScriptSkill = class {
       if (value === void 0) {
         continue;
       }
+      const stringValue = String(value);
+      if (stringValue.startsWith("-")) {
+        return `Error: tool "${toolDef.name}" argument "${param.name}" must not begin with "-".`;
+      }
       if (param.required && index === 0) {
-        args.push(String(value));
+        args.push(stringValue);
       } else {
-        args.push(`--${param.name}`, String(value));
+        args.push(`--${param.name}`, stringValue);
       }
     }
-    const result = await runScript(cmd, args, { cwd: this.skillDir, signal });
+    const result = await runScript(cmd, args, {
+      cwd: this.skillDir,
+      signal,
+      env: scopedToolEnv()
+    });
     if (result.spawnError) {
       return `Error: ${result.spawnError.message}`;
     }
@@ -246,6 +263,16 @@ var ScriptBillingExhaustedError = class extends Error {
     this.stderr = stderr;
   }
 };
+var ScriptExecutionError = class extends Error {
+  exitCode;
+  detail;
+  constructor(exitCode, detail, summary) {
+    super(summary ?? `script failed (exit ${exitCode ?? "unknown"})`);
+    this.name = "ScriptExecutionError";
+    this.exitCode = exitCode;
+    this.detail = detail;
+  }
+};
 
 // src/skills/staticScriptSkill.ts
 var StaticScriptSkill = class {
@@ -284,19 +311,23 @@ var StaticScriptSkill = class {
       env: this.scriptEnv
     });
     if (result.spawnError) {
-      throw new Error(`script spawn failed: ${result.spawnError.message}`);
+      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 Error(`script failed (exit ${result.code}): ${detail}`);
+      throw new ScriptExecutionError(result.code, detail);
     }
     const output = result.stdout.trim();
     if (output === "") {
       const detail = result.stderr.trim() || "(no stderr)";
-      throw new Error(`script exited 0 but produced empty output: ${detail}`);
+      throw new ScriptExecutionError(result.code, detail, "script produced empty output");
     }
     return { data: output };
   }
@@ -315,6 +346,7 @@ var DynamicScriptSkill = class {
   scriptArgs;
   scriptTimeoutMs;
   scriptEnv;
+  outputMime;
   constructor(params) {
     this.name = params.name;
     this.description = params.description;
@@ -328,31 +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 Error(`script spawn failed: ${result.spawnError.message}`);
+    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;
     }
-    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 Error(`script failed (exit ${result.code}): ${detail}`);
-    }
-    const output = result.stdout.trim();
-    if (output === "") {
-      const detail = result.stderr.trim() || "(no stderr)";
-      throw new Error(`script exited 0 but produced empty output: ${detail}`);
+    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) {
@@ -364,13 +430,13 @@ function resolveInsidePath(rootDir, value) {
   }
   return candidate;
 }
-var LAMPORTS_PER_SOL = 1e9;
 var LIMITS = {
   // Upper bound for execution budgets (`max_execution_secs` / `execution_timeout_secs`).
   // Distinct from MAX_TIMEOUT_SECS (the result-wait cap): execution budgets may be
   // 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",
@@ -447,11 +513,15 @@ var VALID_MODES = [
   "dynamic-script"
 ];
 function solToLamports(sol) {
-  const asNumber = typeof sol === "string" ? Number(sol) : sol;
-  if (!Number.isFinite(asNumber) || asNumber < 0) {
+  const asString = (typeof sol === "string" ? sol : String(sol)).trim();
+  if (/^0+(?:\.0+)?$/.test(asString)) {
+    return 0n;
+  }
+  try {
+    return parseAssetAmount(NATIVE_SOL, asString);
+  } catch {
     throw new Error(`Invalid SOL amount: ${sol}`);
   }
-  return BigInt(Math.round(asNumber * LAMPORTS_PER_SOL));
 }
 function resolveSkillAsset(skillName, token, mint) {
   if (token === void 0 || token === null) {
@@ -664,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;
@@ -715,7 +813,7 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
     }
     const priceString = typeof priceRaw === "number" ? String(priceRaw) : priceRaw;
     if (asset === NATIVE_SOL) {
-      priceSubunits = solToLamports(priceRaw);
+      priceSubunits = solToLamports(priceString);
     } else {
       try {
         priceSubunits = parseAssetAmount(asset, priceString);
@@ -764,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(
@@ -775,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) {
@@ -788,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(
@@ -809,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;
@@ -835,11 +970,21 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
     script,
     scriptArgs,
     scriptTimeoutMs,
+    outputMime,
+    inputMime,
     rateLimit,
     executionTimeoutSecs
   };
 }
 function buildSkillFromParsed(parsed, skillDir, logger) {
+  let imageFile = parsed.imageFile;
+  if (imageFile !== void 0 && resolveInsidePath(skillDir, imageFile) === null) {
+    logger.warn?.(
+      { skill: parsed.name, imageFile },
+      'SKILL.md "image_file" escapes the skill directory; ignoring it'
+    );
+    imageFile = void 0;
+  }
   switch (parsed.mode) {
     case "llm":
       return new ScriptSkill({
@@ -854,7 +999,7 @@ function buildSkillFromParsed(parsed, skillDir, logger) {
         maxToolRounds: parsed.maxToolRounds,
         llmOverride: parsed.llmOverride,
         image: parsed.image,
-        imageFile: parsed.imageFile,
+        imageFile,
         logger
       });
     case "static-file": {
@@ -877,7 +1022,7 @@ function buildSkillFromParsed(parsed, skillDir, logger) {
         asset: parsed.asset,
         outputFilePath,
         image: parsed.image,
-        imageFile: parsed.imageFile,
+        imageFile,
         llmOverride: parsed.llmOverride
       });
     }
@@ -892,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,
@@ -903,9 +1047,10 @@ function buildSkillFromParsed(parsed, skillDir, logger) {
         scriptArgs: parsed.scriptArgs,
         scriptTimeoutMs: parsed.scriptTimeoutMs ?? DEFAULT_SCRIPT_TIMEOUT_MS,
         image: parsed.image,
-        imageFile: parsed.imageFile,
+        imageFile,
         llmOverride: parsed.llmOverride
-      });
+      };
+      return parsed.mode === "dynamic-script" ? new DynamicScriptSkill({ ...scriptParams, outputMime: parsed.outputMime }) : new StaticScriptSkill(scriptParams);
     }
   }
 }