@elisym/sdk 0.15.2 → 0.16.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-8vJ1I2KQ.cjs';
+import { S as SkillRateLimit } from './types-COvV499T.cjs';
 
 /**
  * Shared SKILL.md runtime types. A skill is a markdown document whose
@@ -103,9 +103,13 @@ interface Skill {
     /** 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.
+     * Optional per-skill LLM config / dependency.
+     *
+     * For mode 'llm', this overrides the agent default model/provider/max_tokens.
+     * For script modes, the (provider, model) pair declares which LLM API key
+     * the script depends on so the agent runtime can health-monitor it
+     * (startup probe + reactive markUnhealthy + lazy recovery). `max_tokens`
+     * is forbidden in script modes (the script controls its own limits).
      */
     llmOverride?: SkillLlmOverride;
     image?: string;
@@ -232,6 +236,13 @@ interface StaticFileSkillParams {
     outputFilePath: string;
     image?: string;
     imageFile?: string;
+    /**
+     * Declared LLM dependency. The skill itself never calls an LLM, but if
+     * the file is produced by an external pipeline that depends on a key,
+     * operators can declare the (provider, model) pair so the runtime can
+     * health-monitor it. Carried through from SKILL.md as-is.
+     */
+    llmOverride?: SkillLlmOverride;
 }
 /**
  * Returns the contents of a fixed file as the job result. Reads on every
@@ -246,6 +257,7 @@ declare class StaticFileSkill implements Skill {
     mode: SkillMode;
     image?: string;
     imageFile?: string;
+    llmOverride?: SkillLlmOverride;
     private outputFilePath;
     constructor(params: StaticFileSkillParams);
     execute(_input: SkillInput, _ctx: SkillContext): Promise<SkillOutput>;
@@ -271,6 +283,13 @@ interface StaticScriptSkillParams {
     scriptEnv?: NodeJS.ProcessEnv;
     image?: string;
     imageFile?: string;
+    /**
+     * Declared LLM dependency. The (provider, model) pair tells the runtime
+     * which API key the script reaches under the hood so it can be
+     * health-monitored. Carried through from SKILL.md as-is; the script
+     * itself reads the key from its environment.
+     */
+    llmOverride?: SkillLlmOverride;
 }
 /**
  * Spawns a configured script with no stdin and returns its trimmed stdout.
@@ -287,6 +306,7 @@ declare class StaticScriptSkill implements Skill {
     mode: SkillMode;
     image?: string;
     imageFile?: string;
+    llmOverride?: SkillLlmOverride;
     private scriptPath;
     private scriptArgs;
     private scriptTimeoutMs?;
@@ -315,6 +335,13 @@ interface DynamicScriptSkillParams {
     scriptEnv?: NodeJS.ProcessEnv;
     image?: string;
     imageFile?: string;
+    /**
+     * Declared LLM dependency. The (provider, model) pair tells the runtime
+     * which API key the script reaches under the hood so it can be
+     * health-monitored. Carried through from SKILL.md as-is; the script
+     * itself reads the key from its environment.
+     */
+    llmOverride?: SkillLlmOverride;
 }
 /**
  * Pipes the user's job input to the script's stdin and returns its
@@ -331,6 +358,7 @@ declare class DynamicScriptSkill implements Skill {
     mode: SkillMode;
     image?: string;
     imageFile?: string;
+    llmOverride?: SkillLlmOverride;
     private scriptPath;
     private scriptArgs;
     private scriptTimeoutMs?;
@@ -362,11 +390,16 @@ interface SkillFrontmatter {
     image_file?: unknown;
     tools?: unknown;
     max_tool_rounds?: unknown;
-    /** Optional per-skill LLM provider override (e.g. 'anthropic', 'openai'). Pairs with `model`. */
+    /**
+     * LLM provider id. For `mode: 'llm'` this overrides the agent default for
+     * runtime LLM execution. For script modes, it declares the LLM the script
+     * depends on so the agent can health-monitor the API key (startup probe +
+     * reactive markUnhealthy + lazy recovery). Pairs with `model`.
+     */
     provider?: unknown;
-    /** Optional per-skill LLM model override. Pairs with `provider`. */
+    /** LLM model id. Same semantics as `provider`. Must be set together with `provider`. */
     model?: unknown;
-    /** Optional per-skill max_tokens override. Independent of provider/model. */
+    /** Per-skill max_tokens override. Only valid for `mode: 'llm'`. */
     max_tokens?: unknown;
     /** Execution mode. Default 'llm'. */
     mode?: unknown;
@@ -397,9 +430,13 @@ interface ParsedSkill {
     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.
+     * Per-skill LLM override / dependency. Present when SKILL.md declared at
+     * least one of `provider`/`model`/`max_tokens`. Parse-time invariant:
+     * `provider` set iff `model` set; `max_tokens` only when mode === 'llm'.
+     *
+     * For mode 'llm': the runtime uses these to construct the LLM client.
+     * For script modes: the (provider, model) pair declares the API key the
+     * script depends on so the agent can health-monitor it.
      */
     llmOverride?: SkillLlmOverride;
     image?: string;

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 import { A as Asset } from './assets-C-nzSYD4.js';
-import { S as SkillRateLimit } from './types-8vJ1I2KQ.js';
+import { S as SkillRateLimit } from './types-COvV499T.js';
 
 /**
  * Shared SKILL.md runtime types. A skill is a markdown document whose
@@ -103,9 +103,13 @@ interface Skill {
     /** 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.
+     * Optional per-skill LLM config / dependency.
+     *
+     * For mode 'llm', this overrides the agent default model/provider/max_tokens.
+     * For script modes, the (provider, model) pair declares which LLM API key
+     * the script depends on so the agent runtime can health-monitor it
+     * (startup probe + reactive markUnhealthy + lazy recovery). `max_tokens`
+     * is forbidden in script modes (the script controls its own limits).
      */
     llmOverride?: SkillLlmOverride;
     image?: string;
@@ -232,6 +236,13 @@ interface StaticFileSkillParams {
     outputFilePath: string;
     image?: string;
     imageFile?: string;
+    /**
+     * Declared LLM dependency. The skill itself never calls an LLM, but if
+     * the file is produced by an external pipeline that depends on a key,
+     * operators can declare the (provider, model) pair so the runtime can
+     * health-monitor it. Carried through from SKILL.md as-is.
+     */
+    llmOverride?: SkillLlmOverride;
 }
 /**
  * Returns the contents of a fixed file as the job result. Reads on every
@@ -246,6 +257,7 @@ declare class StaticFileSkill implements Skill {
     mode: SkillMode;
     image?: string;
     imageFile?: string;
+    llmOverride?: SkillLlmOverride;
     private outputFilePath;
     constructor(params: StaticFileSkillParams);
     execute(_input: SkillInput, _ctx: SkillContext): Promise<SkillOutput>;
@@ -271,6 +283,13 @@ interface StaticScriptSkillParams {
     scriptEnv?: NodeJS.ProcessEnv;
     image?: string;
     imageFile?: string;
+    /**
+     * Declared LLM dependency. The (provider, model) pair tells the runtime
+     * which API key the script reaches under the hood so it can be
+     * health-monitored. Carried through from SKILL.md as-is; the script
+     * itself reads the key from its environment.
+     */
+    llmOverride?: SkillLlmOverride;
 }
 /**
  * Spawns a configured script with no stdin and returns its trimmed stdout.
@@ -287,6 +306,7 @@ declare class StaticScriptSkill implements Skill {
     mode: SkillMode;
     image?: string;
     imageFile?: string;
+    llmOverride?: SkillLlmOverride;
     private scriptPath;
     private scriptArgs;
     private scriptTimeoutMs?;
@@ -315,6 +335,13 @@ interface DynamicScriptSkillParams {
     scriptEnv?: NodeJS.ProcessEnv;
     image?: string;
     imageFile?: string;
+    /**
+     * Declared LLM dependency. The (provider, model) pair tells the runtime
+     * which API key the script reaches under the hood so it can be
+     * health-monitored. Carried through from SKILL.md as-is; the script
+     * itself reads the key from its environment.
+     */
+    llmOverride?: SkillLlmOverride;
 }
 /**
  * Pipes the user's job input to the script's stdin and returns its
@@ -331,6 +358,7 @@ declare class DynamicScriptSkill implements Skill {
     mode: SkillMode;
     image?: string;
     imageFile?: string;
+    llmOverride?: SkillLlmOverride;
     private scriptPath;
     private scriptArgs;
     private scriptTimeoutMs?;
@@ -362,11 +390,16 @@ interface SkillFrontmatter {
     image_file?: unknown;
     tools?: unknown;
     max_tool_rounds?: unknown;
-    /** Optional per-skill LLM provider override (e.g. 'anthropic', 'openai'). Pairs with `model`. */
+    /**
+     * LLM provider id. For `mode: 'llm'` this overrides the agent default for
+     * runtime LLM execution. For script modes, it declares the LLM the script
+     * depends on so the agent can health-monitor the API key (startup probe +
+     * reactive markUnhealthy + lazy recovery). Pairs with `model`.
+     */
     provider?: unknown;
-    /** Optional per-skill LLM model override. Pairs with `provider`. */
+    /** LLM model id. Same semantics as `provider`. Must be set together with `provider`. */
     model?: unknown;
-    /** Optional per-skill max_tokens override. Independent of provider/model. */
+    /** Per-skill max_tokens override. Only valid for `mode: 'llm'`. */
     max_tokens?: unknown;
     /** Execution mode. Default 'llm'. */
     mode?: unknown;
@@ -397,9 +430,13 @@ interface ParsedSkill {
     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.
+     * Per-skill LLM override / dependency. Present when SKILL.md declared at
+     * least one of `provider`/`model`/`max_tokens`. Parse-time invariant:
+     * `provider` set iff `model` set; `max_tokens` only when mode === 'llm'.
+     *
+     * For mode 'llm': the runtime uses these to construct the LLM client.
+     * For script modes: the (provider, model) pair declares the API key the
+     * script depends on so the agent can health-monitor it.
      */
     llmOverride?: SkillLlmOverride;
     image?: string;

package/dist/skills.js

@@ -207,6 +207,7 @@ var StaticFileSkill = class {
   mode = "static-file";
   image;
   imageFile;
+  llmOverride;
   outputFilePath;
   constructor(params) {
     this.name = params.name;
@@ -216,6 +217,7 @@ var StaticFileSkill = class {
     this.asset = params.asset;
     this.image = params.image;
     this.imageFile = params.imageFile;
+    this.llmOverride = params.llmOverride;
     this.outputFilePath = params.outputFilePath;
   }
   async execute(_input, _ctx) {
@@ -228,6 +230,24 @@ var StaticFileSkill = class {
     return { data: buffer.toString("utf-8") };
   }
 };
+var SCRIPT_EXIT_BILLING_EXHAUSTED = 42;
+
+// src/llm-health/types.ts
+var ScriptBillingExhaustedError = class extends Error {
+  exitCode;
+  stderr;
+  stdout;
+  constructor(exitCode, stdout, stderr) {
+    const detail = stderr.trim() || stdout.trim() || "(no output)";
+    super(`script exited with billing-exhausted code ${exitCode}: ${detail}`);
+    this.name = "ScriptBillingExhaustedError";
+    this.exitCode = exitCode;
+    this.stdout = stdout;
+    this.stderr = stderr;
+  }
+};
+
+// src/skills/staticScriptSkill.ts
 var StaticScriptSkill = class {
   name;
   description;
@@ -237,6 +257,7 @@ var StaticScriptSkill = class {
   mode = "static-script";
   image;
   imageFile;
+  llmOverride;
   scriptPath;
   scriptArgs;
   scriptTimeoutMs;
@@ -249,6 +270,7 @@ var StaticScriptSkill = class {
     this.asset = params.asset;
     this.image = params.image;
     this.imageFile = params.imageFile;
+    this.llmOverride = params.llmOverride;
     this.scriptPath = params.scriptPath;
     this.scriptArgs = params.scriptArgs;
     this.scriptTimeoutMs = params.scriptTimeoutMs;
@@ -264,6 +286,9 @@ var StaticScriptSkill = class {
     if (result.spawnError) {
       throw new Error(`script spawn failed: ${result.spawnError.message}`);
     }
+    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}`);
@@ -280,6 +305,7 @@ var DynamicScriptSkill = class {
   mode = "dynamic-script";
   image;
   imageFile;
+  llmOverride;
   scriptPath;
   scriptArgs;
   scriptTimeoutMs;
@@ -292,6 +318,7 @@ var DynamicScriptSkill = class {
     this.asset = params.asset;
     this.image = params.image;
     this.imageFile = params.imageFile;
+    this.llmOverride = params.llmOverride;
     this.scriptPath = params.scriptPath;
     this.scriptArgs = params.scriptArgs;
     this.scriptTimeoutMs = params.scriptTimeoutMs;
@@ -308,6 +335,9 @@ var DynamicScriptSkill = class {
     if (result.spawnError) {
       throw new Error(`script spawn failed: ${result.spawnError.message}`);
     }
+    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}`);
@@ -551,9 +581,9 @@ function validateLlmOverride(skillName, frontmatter, mode) {
   if (!hasProvider && !hasModel && !hasMaxTokens) {
     return void 0;
   }
-  if (mode !== "llm") {
+  if (hasMaxTokens && mode !== "llm") {
     throw new Error(
-      `SKILL.md "${skillName}": "provider"/"model"/"max_tokens" are only valid in mode 'llm' (got '${mode}')`
+      `SKILL.md "${skillName}": "max_tokens" is only valid in mode 'llm' (got '${mode}'). For script modes, control token limits inside the script.`
     );
   }
   if (hasProvider !== hasModel) {
@@ -810,7 +840,8 @@ function buildSkillFromParsed(parsed, skillDir, logger) {
         asset: parsed.asset,
         outputFilePath,
         image: parsed.image,
-        imageFile: parsed.imageFile
+        imageFile: parsed.imageFile,
+        llmOverride: parsed.llmOverride
       });
     }
     case "static-script":
@@ -835,7 +866,8 @@ function buildSkillFromParsed(parsed, skillDir, logger) {
         scriptArgs: parsed.scriptArgs,
         scriptTimeoutMs: parsed.scriptTimeoutMs ?? DEFAULT_SCRIPT_TIMEOUT_MS,
         image: parsed.image,
-        imageFile: parsed.imageFile
+        imageFile: parsed.imageFile,
+        llmOverride: parsed.llmOverride
       });
     }
   }