@elisym/sdk 0.12.5 → 0.13.0

package/dist/skills.d.ts

@@ -16,9 +16,28 @@ 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 {
-    /** Required only when the routed skill has `mode === 'llm'`. */
+    /** 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;
@@ -74,6 +93,12 @@ interface Skill {
     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>;
@@ -144,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;
@@ -162,6 +189,7 @@ declare class ScriptSkill implements Skill {
     priceSubunits: bigint;
     asset: Asset;
     mode: SkillMode;
+    readonly llmOverride?: SkillLlmOverride;
     image?: string;
     imageFile?: string;
     private skillDir;
@@ -171,6 +199,18 @@ 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;
 }
 
@@ -304,6 +344,12 @@ 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. */
@@ -326,6 +372,12 @@ interface ParsedSkill {
     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'. */
@@ -362,4 +414,4 @@ declare function validateSkillFrontmatter(frontmatter: SkillFrontmatter, systemP
  */
 declare function loadSkillsFromDir(skillsDir: string, options?: LoadSkillsOptions): Skill[];
 
-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 };
+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.js

@@ -358,6 +358,7 @@ var ScriptSkill = class {
   priceSubunits;
   asset;
   mode = "llm";
+  llmOverride;
   image;
   imageFile;
   skillDir;
@@ -371,6 +372,7 @@ var ScriptSkill = class {
     this.capabilities = params.capabilities;
     this.priceSubunits = params.priceSubunits;
     this.asset = params.asset;
+    this.llmOverride = params.llmOverride;
     this.image = params.image;
     this.imageFile = params.imageFile;
     this.skillDir = params.skillDir;
@@ -380,11 +382,9 @@ var ScriptSkill = class {
     this.logger = params.logger ?? {};
   }
   async execute(input, ctx) {
-    if (!ctx.llm) {
-      throw new Error("LLM client not configured for skill runtime");
-    }
+    const llm = this.resolveLlmClient(ctx);
     if (this.tools.length === 0) {
-      const result = await ctx.llm.complete(this.systemPrompt, input.data, ctx.signal);
+      const result = await llm.complete(this.systemPrompt, input.data, ctx.signal);
       return { data: result };
     }
     const toolDefs = this.tools.map((tool) => ({
@@ -397,7 +397,6 @@ var ScriptSkill = class {
       }))
     }));
     const messages = [{ role: "user", content: input.data }];
-    const llm = ctx.llm;
     for (let round = 0; round < this.maxToolRounds; round++) {
       if (ctx.signal?.aborted) {
         throw new Error("Job aborted");
@@ -429,6 +428,34 @@ var ScriptSkill = class {
     }
     throw new Error(`Max tool rounds (${this.maxToolRounds}) exceeded`);
   }
+  /**
+   * 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.
+   */
+  resolveLlmClient(ctx) {
+    let client;
+    if (this.llmOverride) {
+      client = ctx.getLlm?.(this.llmOverride);
+      if (!client) {
+        throw new Error(
+          `Skill "${this.name}" requires ctx.getLlm to be configured (llmOverride is set)`
+        );
+      }
+      return client;
+    }
+    client = ctx.getLlm?.() ?? ctx.llm;
+    if (!client) {
+      throw new Error("LLM client not configured for skill runtime");
+    }
+    return client;
+  }
   async runTool(toolDef, call, signal) {
     const args = [...toolDef.command];
     const cmd = args.shift();
@@ -654,6 +681,8 @@ function parseAssetAmount(asset, human) {
 Decimal.clone({ toExpNeg: -100, toExpPos: 100, precision: 50 });
 
 // src/skills/loader.ts
+var VALID_PROVIDERS = ["anthropic", "openai"];
+var MAX_TOKENS_LIMIT = 2e5;
 var DEFAULT_MAX_TOOL_ROUNDS = 10;
 var VALID_MODES = [
   "llm",
@@ -805,6 +834,49 @@ function validateScriptArgs(skillName, raw) {
   }
   return raw;
 }
+function validateLlmOverride(skillName, frontmatter, mode) {
+  const hasProvider = frontmatter.provider !== void 0 && frontmatter.provider !== null;
+  const hasModel = frontmatter.model !== void 0 && frontmatter.model !== null;
+  const hasMaxTokens = frontmatter.max_tokens !== void 0 && frontmatter.max_tokens !== null;
+  if (!hasProvider && !hasModel && !hasMaxTokens) {
+    return void 0;
+  }
+  if (mode !== "llm") {
+    throw new Error(
+      `SKILL.md "${skillName}": "provider"/"model"/"max_tokens" are only valid in mode 'llm' (got '${mode}')`
+    );
+  }
+  if (hasProvider !== hasModel) {
+    throw new Error(
+      `SKILL.md "${skillName}": "provider" and "model" must be set together (declare both, or neither)`
+    );
+  }
+  const override = {};
+  if (hasProvider && hasModel) {
+    if (typeof frontmatter.provider !== "string") {
+      throw new Error(`SKILL.md "${skillName}": "provider" must be a string`);
+    }
+    if (!VALID_PROVIDERS.includes(frontmatter.provider)) {
+      throw new Error(
+        `SKILL.md "${skillName}": invalid provider "${frontmatter.provider}". Allowed: ${VALID_PROVIDERS.join(", ")}`
+      );
+    }
+    if (typeof frontmatter.model !== "string" || frontmatter.model.length === 0) {
+      throw new Error(`SKILL.md "${skillName}": "model" must be a non-empty string`);
+    }
+    override.provider = frontmatter.provider;
+    override.model = frontmatter.model;
+  }
+  if (hasMaxTokens) {
+    if (typeof frontmatter.max_tokens !== "number" || !Number.isInteger(frontmatter.max_tokens) || frontmatter.max_tokens <= 0 || frontmatter.max_tokens > MAX_TOKENS_LIMIT) {
+      throw new Error(
+        `SKILL.md "${skillName}": "max_tokens" must be a positive integer <= ${MAX_TOKENS_LIMIT}`
+      );
+    }
+    override.maxTokens = frontmatter.max_tokens;
+  }
+  return override;
+}
 function validateScriptTimeoutMs(skillName, raw) {
   if (raw === void 0 || raw === null) {
     return void 0;
@@ -946,6 +1018,7 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
   }
   const image = typeof frontmatter.image === "string" ? frontmatter.image : void 0;
   const imageFile = typeof frontmatter.image_file === "string" ? frontmatter.image_file : void 0;
+  const llmOverride = validateLlmOverride(frontmatter.name, frontmatter, mode);
   return {
     name: frontmatter.name,
     description: frontmatter.description,
@@ -956,6 +1029,7 @@ function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
     systemPrompt,
     tools,
     maxToolRounds,
+    llmOverride,
     image,
     imageFile,
     outputFile,
@@ -977,6 +1051,7 @@ function buildSkillFromParsed(parsed, skillDir, logger) {
         systemPrompt: parsed.systemPrompt,
         tools: parsed.tools,
         maxToolRounds: parsed.maxToolRounds,
+        llmOverride: parsed.llmOverride,
         image: parsed.image,
         imageFile: parsed.imageFile,
         logger