@elisym/sdk 0.5.0 → 0.7.0

package/dist/skills.cjs

@@ -0,0 +1,673 @@
+'use strict';
+
+var child_process = require('child_process');
+var string_decoder = require('string_decoder');
+var fs = require('fs');
+var path = require('path');
+var YAML = require('yaml');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var YAML__default = /*#__PURE__*/_interopDefault(YAML);
+
+// src/skills/llmClient.ts
+var LLM_TIMEOUT_MS = 12e4;
+var MAX_RETRIES = 2;
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var DEFAULT_MAX_TOKENS = 4096;
+var DEFAULT_ANTHROPIC_MODEL = "claude-haiku-4-5-20251001";
+var DEFAULT_OPENAI_MODEL = "gpt-4o-mini";
+function createAbortError() {
+  const err = new Error("The operation was aborted");
+  err.name = "AbortError";
+  return err;
+}
+function sleepWithSignal(ms, signal) {
+  if (signal?.aborted) {
+    return Promise.reject(createAbortError());
+  }
+  if (!signal) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      reject(createAbortError());
+    };
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function fetchWithTimeout(url, init, signal) {
+  if (signal?.aborted) {
+    throw createAbortError();
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), LLM_TIMEOUT_MS);
+  const onAbort = () => controller.abort();
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+  }
+}
+async function fetchWithRetry(url, init, signal) {
+  for (let attempt = 0; ; attempt++) {
+    let response;
+    try {
+      response = await fetchWithTimeout(url, init, signal);
+    } catch (error) {
+      const name = error instanceof Error ? error.name : "";
+      if (attempt >= MAX_RETRIES || name === "AbortError") {
+        throw error;
+      }
+      await sleepWithSignal(Math.min(1e3 * 2 ** attempt, 8e3), signal);
+      continue;
+    }
+    if (response.ok || attempt >= MAX_RETRIES || !RETRYABLE_STATUSES.has(response.status)) {
+      return response;
+    }
+    const retryAfter = response.headers.get("retry-after");
+    const delay = retryAfter ? Math.min(parseInt(retryAfter, 10) * 1e3 || 1e3 * 2 ** attempt, 3e4) : Math.min(1e3 * 2 ** attempt, 8e3);
+    await response.body?.cancel().catch(() => void 0);
+    await sleepWithSignal(delay, signal);
+  }
+}
+var AnthropicClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  async complete(systemPrompt, userInput, signal) {
+    const response = await fetchWithRetry(
+      "https://api.anthropic.com/v1/messages",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.config.apiKey,
+          "anthropic-version": "2023-06-01"
+        },
+        body: JSON.stringify({
+          model: this.config.model,
+          max_tokens: this.config.maxTokens,
+          system: systemPrompt,
+          messages: [{ role: "user", content: userInput }]
+        })
+      },
+      signal
+    );
+    if (!response.ok) {
+      throw new Error(`Anthropic API error: ${response.status} ${await response.text()}`);
+    }
+    const data = await response.json();
+    const textBlock = data.content?.find((block) => block.type === "text");
+    return textBlock?.text ?? "";
+  }
+  async completeWithTools(systemPrompt, messages, tools, signal) {
+    const anthropicTools = tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      input_schema: {
+        type: "object",
+        properties: Object.fromEntries(
+          tool.parameters.map((param) => [
+            param.name,
+            { type: "string", description: param.description }
+          ])
+        ),
+        required: tool.parameters.filter((param) => param.required).map((param) => param.name)
+      }
+    }));
+    const response = await fetchWithRetry(
+      "https://api.anthropic.com/v1/messages",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.config.apiKey,
+          "anthropic-version": "2023-06-01"
+        },
+        body: JSON.stringify({
+          model: this.config.model,
+          max_tokens: this.config.maxTokens,
+          system: systemPrompt,
+          messages,
+          tools: anthropicTools
+        })
+      },
+      signal
+    );
+    if (!response.ok) {
+      throw new Error(`Anthropic API error: ${response.status} ${await response.text()}`);
+    }
+    const data = await response.json();
+    const content = data.content ?? [];
+    const toolUses = content.filter((block) => block.type === "tool_use");
+    if (toolUses.length > 0) {
+      const calls = toolUses.map((block) => ({
+        id: block.id ?? "",
+        name: block.name ?? "",
+        arguments: block.input ?? {}
+      }));
+      return {
+        type: "tool_use",
+        calls,
+        assistantMessage: { role: "assistant", content }
+      };
+    }
+    const textBlock = content.find((block) => block.type === "text");
+    return { type: "text", text: textBlock?.text ?? "" };
+  }
+  formatToolResultMessages(results) {
+    return [
+      {
+        role: "user",
+        content: results.map((result) => ({
+          type: "tool_result",
+          tool_use_id: result.callId,
+          content: result.content
+        }))
+      }
+    ];
+  }
+};
+var OpenAIClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  isReasoningModel() {
+    return /^o\d/.test(this.config.model);
+  }
+  async complete(systemPrompt, userInput, signal) {
+    const reasoning = this.isReasoningModel();
+    const response = await fetchWithRetry(
+      "https://api.openai.com/v1/chat/completions",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify({
+          model: this.config.model,
+          ...reasoning ? { max_completion_tokens: this.config.maxTokens } : { max_tokens: this.config.maxTokens },
+          messages: [
+            { role: reasoning ? "developer" : "system", content: systemPrompt },
+            { role: "user", content: userInput }
+          ]
+        })
+      },
+      signal
+    );
+    if (!response.ok) {
+      throw new Error(`OpenAI API error: ${response.status} ${await response.text()}`);
+    }
+    const data = await response.json();
+    return data.choices?.[0]?.message?.content ?? "";
+  }
+  async completeWithTools(systemPrompt, messages, tools, signal) {
+    const openaiTools = tools.map((tool) => ({
+      type: "function",
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: {
+          type: "object",
+          properties: Object.fromEntries(
+            tool.parameters.map((param) => [
+              param.name,
+              { type: "string", description: param.description }
+            ])
+          ),
+          required: tool.parameters.filter((param) => param.required).map((param) => param.name)
+        }
+      }
+    }));
+    const reasoning = this.isReasoningModel();
+    const response = await fetchWithRetry(
+      "https://api.openai.com/v1/chat/completions",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify({
+          model: this.config.model,
+          ...reasoning ? { max_completion_tokens: this.config.maxTokens } : { max_tokens: this.config.maxTokens },
+          messages: [
+            { role: reasoning ? "developer" : "system", content: systemPrompt },
+            ...messages
+          ],
+          tools: openaiTools
+        })
+      },
+      signal
+    );
+    if (!response.ok) {
+      throw new Error(`OpenAI API error: ${response.status} ${await response.text()}`);
+    }
+    const data = await response.json();
+    const message = data.choices?.[0]?.message;
+    const toolCalls = message?.tool_calls ?? [];
+    if (toolCalls.length > 0) {
+      const calls = toolCalls.map((call) => {
+        let args;
+        try {
+          args = JSON.parse(call.function?.arguments ?? "{}");
+        } catch {
+          args = {};
+        }
+        return { id: call.id ?? "", name: call.function?.name ?? "", arguments: args };
+      });
+      return { type: "tool_use", calls, assistantMessage: message };
+    }
+    return { type: "text", text: message?.content ?? "" };
+  }
+  formatToolResultMessages(results) {
+    return results.map((result) => ({
+      role: "tool",
+      tool_call_id: result.callId,
+      content: result.content
+    }));
+  }
+};
+function createAnthropicClient(config) {
+  if (!config.apiKey) {
+    throw new Error("ANTHROPIC_API_KEY is required for skill runtime");
+  }
+  return new AnthropicClient({
+    apiKey: config.apiKey,
+    model: config.model ?? DEFAULT_ANTHROPIC_MODEL,
+    maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS
+  });
+}
+function createOpenAIClient(config) {
+  if (!config.apiKey) {
+    throw new Error("OPENAI_API_KEY is required for skill runtime");
+  }
+  return new OpenAIClient({
+    apiKey: config.apiKey,
+    model: config.model ?? DEFAULT_OPENAI_MODEL,
+    maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS
+  });
+}
+function createLlmClient(config) {
+  if (config.provider === "openai") {
+    return createOpenAIClient(config);
+  }
+  return createAnthropicClient(config);
+}
+var MAX_TOOL_OUTPUT = 1e6;
+var TOOL_TIMEOUT_MS = 6e4;
+var ScriptSkill = class {
+  name;
+  description;
+  capabilities;
+  priceLamports;
+  image;
+  imageFile;
+  skillDir;
+  systemPrompt;
+  tools;
+  maxToolRounds;
+  logger;
+  constructor(params) {
+    this.name = params.name;
+    this.description = params.description;
+    this.capabilities = params.capabilities;
+    this.priceLamports = params.priceLamports;
+    this.image = params.image;
+    this.imageFile = params.imageFile;
+    this.skillDir = params.skillDir;
+    this.systemPrompt = params.systemPrompt;
+    this.tools = params.tools;
+    this.maxToolRounds = params.maxToolRounds;
+    this.logger = params.logger ?? {};
+  }
+  async execute(input, ctx) {
+    if (!ctx.llm) {
+      throw new Error("LLM client not configured for skill runtime");
+    }
+    if (this.tools.length === 0) {
+      const result = await ctx.llm.complete(this.systemPrompt, input.data, ctx.signal);
+      return { data: result };
+    }
+    const toolDefs = this.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: (tool.parameters ?? []).map((param) => ({
+        name: param.name,
+        description: param.description,
+        required: param.required ?? true
+      }))
+    }));
+    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");
+      }
+      const result = await llm.completeWithTools(
+        this.systemPrompt,
+        messages,
+        toolDefs,
+        ctx.signal
+      );
+      if (result.type === "text") {
+        return { data: result.text };
+      }
+      messages.push(result.assistantMessage);
+      const toolResults = [];
+      for (const call of result.calls) {
+        const toolDef = this.tools.find((tool) => tool.name === call.name);
+        if (!toolDef) {
+          toolResults.push({
+            callId: call.id,
+            content: `Error: unknown tool "${call.name}"`
+          });
+          continue;
+        }
+        const output = await this.runTool(toolDef, call, ctx.signal);
+        toolResults.push({ callId: call.id, content: output });
+      }
+      messages.push(...llm.formatToolResultMessages(toolResults));
+    }
+    throw new Error(`Max tool rounds (${this.maxToolRounds}) exceeded`);
+  }
+  runTool(toolDef, call, signal) {
+    return new Promise((resolve) => {
+      const args = [...toolDef.command];
+      const cmd = args.shift();
+      if (!cmd) {
+        resolve(`Error: tool "${toolDef.name}" has an empty command`);
+        return;
+      }
+      const params = toolDef.parameters ?? [];
+      for (let index = 0; index < params.length; index++) {
+        const param = params[index];
+        if (!param) {
+          continue;
+        }
+        const value = call.arguments[param.name];
+        if (value === void 0) {
+          continue;
+        }
+        if (param.required && index === 0) {
+          args.push(String(value));
+        } else {
+          args.push(`--${param.name}`, String(value));
+        }
+      }
+      const child = child_process.spawn(cmd, args, {
+        cwd: this.skillDir,
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: TOOL_TIMEOUT_MS,
+        killSignal: "SIGKILL",
+        signal
+      });
+      let stdout = "";
+      let stderr = "";
+      const stdoutDecoder = new string_decoder.StringDecoder("utf8");
+      const stderrDecoder = new string_decoder.StringDecoder("utf8");
+      child.stdout?.on("data", (data) => {
+        if (stdout.length < MAX_TOOL_OUTPUT) {
+          stdout += stdoutDecoder.write(data);
+          if (stdout.length > MAX_TOOL_OUTPUT) {
+            stdout = stdout.slice(0, MAX_TOOL_OUTPUT);
+          }
+        }
+      });
+      child.stderr?.on("data", (data) => {
+        if (stderr.length < MAX_TOOL_OUTPUT) {
+          stderr += stderrDecoder.write(data);
+          if (stderr.length > MAX_TOOL_OUTPUT) {
+            stderr = stderr.slice(0, MAX_TOOL_OUTPUT);
+          }
+        }
+      });
+      child.on("close", (code) => {
+        stdout += stdoutDecoder.end();
+        stderr += stderrDecoder.end();
+        if (code === 0) {
+          resolve(stdout.trim());
+          return;
+        }
+        this.logger.debug?.(
+          { tool: toolDef.name, code, stderrLen: stderr.length },
+          "skill tool exited non-zero"
+        );
+        resolve(`Error (exit ${code}): ${stderr.trim() || stdout.trim()}`);
+      });
+      child.on("error", (err) => {
+        resolve(`Error: ${err.message}`);
+      });
+    });
+  }
+};
+var LAMPORTS_PER_SOL = 1e9;
+
+// src/skills/loader.ts
+var DEFAULT_MAX_TOOL_ROUNDS = 10;
+function solToLamports(sol) {
+  const asNumber = typeof sol === "string" ? Number(sol) : sol;
+  if (!Number.isFinite(asNumber) || asNumber < 0) {
+    throw new Error(`Invalid SOL amount: ${sol}`);
+  }
+  return BigInt(Math.round(asNumber * LAMPORTS_PER_SOL));
+}
+function parseSkillMd(content) {
+  const lines = content.split("\n");
+  let start = -1;
+  let end = -1;
+  for (let index = 0; index < lines.length; index++) {
+    if (lines[index]?.trim() === "---") {
+      if (start === -1) {
+        start = index;
+      } else {
+        end = index;
+        break;
+      }
+    }
+  }
+  if (start === -1 || end === -1) {
+    throw new Error("SKILL.md must have YAML frontmatter between --- delimiters");
+  }
+  const yamlStr = lines.slice(start + 1, end).join("\n");
+  const frontmatter = YAML__default.default.parse(yamlStr);
+  const systemPrompt = lines.slice(end + 1).join("\n").trim();
+  return { frontmatter, systemPrompt };
+}
+function validateTool(raw, skillName, index) {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error(`skill "${skillName}" tool[${index}] must be an object`);
+  }
+  const tool = raw;
+  if (typeof tool.name !== "string" || tool.name.length === 0) {
+    throw new Error(`skill "${skillName}" tool[${index}] missing name`);
+  }
+  if (typeof tool.description !== "string" || tool.description.length === 0) {
+    throw new Error(`skill "${skillName}" tool "${tool.name}" missing description`);
+  }
+  if (!Array.isArray(tool.command) || tool.command.length === 0) {
+    throw new Error(`skill "${skillName}" tool "${tool.name}" missing command[] array`);
+  }
+  for (const part of tool.command) {
+    if (typeof part !== "string") {
+      throw new Error(`skill "${skillName}" tool "${tool.name}" command[] must be strings`);
+    }
+  }
+  const parameters = [];
+  if (tool.parameters !== void 0) {
+    if (!Array.isArray(tool.parameters)) {
+      throw new Error(`skill "${skillName}" tool "${tool.name}" parameters must be an array`);
+    }
+    for (let paramIndex = 0; paramIndex < tool.parameters.length; paramIndex++) {
+      const param = tool.parameters[paramIndex];
+      if (typeof param !== "object" || param === null) {
+        throw new Error(
+          `skill "${skillName}" tool "${tool.name}" parameter[${paramIndex}] must be an object`
+        );
+      }
+      const record = param;
+      if (typeof record.name !== "string" || record.name.length === 0) {
+        throw new Error(
+          `skill "${skillName}" tool "${tool.name}" parameter[${paramIndex}] missing name`
+        );
+      }
+      if (typeof record.description !== "string") {
+        throw new Error(
+          `skill "${skillName}" tool "${tool.name}" parameter "${record.name}" missing description`
+        );
+      }
+      parameters.push({
+        name: record.name,
+        description: record.description,
+        required: record.required === void 0 ? void 0 : Boolean(record.required)
+      });
+    }
+  }
+  return {
+    name: tool.name,
+    description: tool.description,
+    command: tool.command,
+    parameters
+  };
+}
+function validateSkillFrontmatter(frontmatter, systemPrompt, options = {}) {
+  if (typeof frontmatter.name !== "string" || frontmatter.name.length === 0) {
+    throw new Error('SKILL.md: missing or invalid "name" field');
+  }
+  if (typeof frontmatter.description !== "string" || frontmatter.description.length === 0) {
+    throw new Error('SKILL.md: missing or invalid "description" field');
+  }
+  if (!Array.isArray(frontmatter.capabilities) || frontmatter.capabilities.length === 0) {
+    throw new Error('SKILL.md: "capabilities" must be a non-empty array');
+  }
+  const capabilities = [];
+  for (const capability of frontmatter.capabilities) {
+    if (typeof capability !== "string" || capability.length === 0) {
+      throw new Error(
+        `SKILL.md "${frontmatter.name}": capability entries must be non-empty strings`
+      );
+    }
+    capabilities.push(capability);
+  }
+  let priceLamports;
+  if (frontmatter.price === void 0 || frontmatter.price === null) {
+    if (!options.allowFreeSkills) {
+      throw new Error(
+        `SKILL.md "${frontmatter.name}": "price" is required (SOL; e.g. 0.002). Free skills are not supported on the protocol yet.`
+      );
+    }
+    priceLamports = 0n;
+  } else {
+    const priceRaw = frontmatter.price;
+    if (typeof priceRaw !== "number" && typeof priceRaw !== "string") {
+      throw new Error(`SKILL.md "${frontmatter.name}": "price" must be a number or numeric string`);
+    }
+    priceLamports = solToLamports(priceRaw);
+    if (priceLamports <= 0n && !options.allowFreeSkills) {
+      throw new Error(
+        `SKILL.md "${frontmatter.name}": price must be > 0 SOL (got ${priceRaw}); free skills are not yet supported`
+      );
+    }
+  }
+  const tools = [];
+  if (frontmatter.tools !== void 0) {
+    if (!Array.isArray(frontmatter.tools)) {
+      throw new Error(`SKILL.md "${frontmatter.name}": "tools" must be an array`);
+    }
+    for (let index = 0; index < frontmatter.tools.length; index++) {
+      tools.push(validateTool(frontmatter.tools[index], frontmatter.name, index));
+    }
+  }
+  let maxToolRounds = DEFAULT_MAX_TOOL_ROUNDS;
+  if (frontmatter.max_tool_rounds !== void 0) {
+    if (typeof frontmatter.max_tool_rounds !== "number" || !Number.isInteger(frontmatter.max_tool_rounds) || frontmatter.max_tool_rounds <= 0) {
+      throw new Error(
+        `SKILL.md "${frontmatter.name}": "max_tool_rounds" must be a positive integer`
+      );
+    }
+    maxToolRounds = frontmatter.max_tool_rounds;
+  }
+  const image = typeof frontmatter.image === "string" ? frontmatter.image : void 0;
+  const imageFile = typeof frontmatter.image_file === "string" ? frontmatter.image_file : void 0;
+  return {
+    name: frontmatter.name,
+    description: frontmatter.description,
+    capabilities,
+    priceLamports,
+    systemPrompt,
+    tools,
+    maxToolRounds,
+    image,
+    imageFile
+  };
+}
+function loadSkillsFromDir(skillsDir, options = {}) {
+  const logger = options.logger ?? {};
+  const skills = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(skillsDir);
+  } catch (error) {
+    logger.debug?.({ err: error, skillsDir }, "skills directory not readable; no skills loaded");
+    return skills;
+  }
+  for (const entry of entries) {
+    const entryPath = path.join(skillsDir, entry);
+    try {
+      if (!fs.statSync(entryPath).isDirectory()) {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    const skillMdPath = path.join(entryPath, "SKILL.md");
+    try {
+      const content = fs.readFileSync(skillMdPath, "utf-8");
+      const { frontmatter, systemPrompt } = parseSkillMd(content);
+      const parsed = validateSkillFrontmatter(frontmatter, systemPrompt, options);
+      skills.push(
+        new ScriptSkill({
+          name: parsed.name,
+          description: parsed.description,
+          capabilities: parsed.capabilities,
+          priceLamports: parsed.priceLamports,
+          skillDir: entryPath,
+          systemPrompt: parsed.systemPrompt,
+          tools: parsed.tools,
+          maxToolRounds: parsed.maxToolRounds,
+          image: parsed.image,
+          imageFile: parsed.imageFile,
+          logger
+        })
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn?.({ dir: entry, err: message }, "skipping malformed skill directory");
+    }
+  }
+  return skills;
+}
+
+exports.DEFAULT_MAX_TOOL_ROUNDS = DEFAULT_MAX_TOOL_ROUNDS;
+exports.ScriptSkill = ScriptSkill;
+exports.createAnthropicClient = createAnthropicClient;
+exports.createLlmClient = createLlmClient;
+exports.createOpenAIClient = createOpenAIClient;
+exports.loadSkillsFromDir = loadSkillsFromDir;
+exports.parseSkillMd = parseSkillMd;
+exports.validateSkillFrontmatter = validateSkillFrontmatter;
+//# sourceMappingURL=skills.cjs.map
+//# sourceMappingURL=skills.cjs.map