@elisym/cli 0.7.10 → 0.8.0

package/README.md

@@ -152,16 +152,23 @@ then return a concise overview and key points.
 
 ### Frontmatter fields
 
-| Field             | Required | Type     | Description                                                                                                                                                                |
-| ----------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`            | yes      | string   | Unique skill identifier. Shown in the marketplace and used internally.                                                                                                     |
-| `description`     | yes      | string   | Short one-line description. Used in discovery - customers match skills by this text, so be specific about the use case.                                                    |
-| `capabilities`    | yes      | string[] | Non-empty list of capability tags for NIP-89 discovery. Customers filter agents by these tags.                                                                             |
-| `price`           | no       | number   | Price per job in SOL (e.g. `0.01`). Converted to lamports internally. Omit or set `0` for a free skill.                                                                    |
-| `image`           | no       | string   | Hero image URL. Shown in the marketplace card. Takes priority over `image_file`.                                                                                           |
-| `image_file`      | no       | string   | Local file path (relative to the skill directory). Uploaded on `elisym start` and cached by sha256 in `<agentDir>/.media-cache.json`; the SKILL.md itself is not modified. |
-| `tools`           | no       | object[] | External scripts the LLM can call via tool-use. Omit if the skill is pure prompt + LLM.                                                                                    |
-| `max_tool_rounds` | no       | number   | Max LLM-tool interaction rounds per job. Default: `10`. Raise for multi-step flows (e.g. chunked transcripts).                                                             |
+| Field               | Required                                                      | Type     | Description                                                                                                                                                                                |
+| ------------------- | ------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`              | yes                                                           | string   | Unique skill identifier. Shown in the marketplace and used internally.                                                                                                                     |
+| `description`       | yes                                                           | string   | Short one-line description. Used in discovery - customers match skills by this text, so be specific about the use case.                                                                    |
+| `capabilities`      | yes                                                           | string[] | Non-empty list of capability tags for NIP-89 discovery. Customers filter agents by these tags.                                                                                             |
+| `price`             | no                                                            | number   | Price per job, denominated in `token` (e.g. `0.01` for 0.01 SOL or 0.01 USDC). Converted to subunits internally. Omit or set `0` for a free skill.                                         |
+| `token`             | no                                                            | string   | Payment asset on Solana: `sol` (default) or `usdc`. Buyer pays in this asset; the agent's wallet receives it.                                                                              |
+| `mint`              | no                                                            | string   | Override the SPL mint address (base58). Optional - resolved from `token` automatically; needed only for non-default mints.                                                                 |
+| `image`             | no                                                            | string   | Hero image URL. Shown in the marketplace card. Takes priority over `image_file`.                                                                                                           |
+| `image_file`        | no                                                            | string   | Local file path (relative to the skill directory). Uploaded on `elisym start` and cached by sha256 in `<agentDir>/.media-cache.json`; the SKILL.md itself is not modified.                 |
+| `mode`              | no                                                            | string   | Execution mode: `llm` (default), `static-file`, `static-script`, or `dynamic-script`. See [Skill modes](#skill-modes).                                                                     |
+| `output_file`       | required when `mode: static-file`                             | string   | Path (relative to the skill dir) of the file whose contents are returned as the job result. Read on every job, capped at 256 KB. Must stay inside the skill directory.                     |
+| `script`            | required when `mode: static-script` or `mode: dynamic-script` | string   | Path (relative to the skill dir) of the script to spawn. `child_process.spawn` runs it directly - list the interpreter in a shebang or use a binary. Must stay inside the skill directory. |
+| `script_args`       | no                                                            | string[] | Extra positional args appended after the script. Script modes only.                                                                                                                        |
+| `script_timeout_ms` | no                                                            | number   | Hard timeout for the script in ms (positive integer). Default: `60000`. Script modes only.                                                                                                 |
+| `tools`             | no                                                            | object[] | External scripts the LLM can call via tool-use. `mode: llm` only.                                                                                                                          |
+| `max_tool_rounds`   | no                                                            | number   | Max LLM-tool interaction rounds per job. Default: `10`. `mode: llm` only.                                                                                                                  |
 
 ### Tool definition
 
@@ -184,7 +191,57 @@ Each parameter has:
 
 ### Body (system prompt)
 
-Everything after the closing `---` becomes the LLM system prompt. Describe the agent's role, when to call each tool, and how to format the final answer. Keep it concrete - this is what drives the model's behavior for every job.
+Everything after the closing `---` becomes the LLM system prompt. Describe the agent's role, when to call each tool, and how to format the final answer. Keep it concrete - this is what drives the model's behavior for every job. The body is ignored when `mode` is anything other than `llm`.
+
+### Skill modes
+
+`mode` controls how the runtime turns a paid job into a result. Pick one per skill - the loader rejects fields that don't apply to the chosen mode (e.g. `tools` outside `mode: llm`, `script` outside script modes).
+
+| Mode             | What it does                                                                                                                   | Buyer UX                                                           | Required field |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | -------------- |
+| `llm` (default)  | Feeds the buyer's input through Anthropic / OpenAI with the body as the system prompt. Optional `tools` for tool-use scripts.  | Input box on the buyer side.                                       | -              |
+| `static-file`    | Returns the contents of a fixed file. Read on every job (capped at 256 KB UTF-8) so authors can edit without restarting.       | Buy-only, no input box (capability card publishes `static: true`). | `output_file`  |
+| `static-script`  | Spawns a script with no stdin and returns its trimmed stdout. Hard timeout via `script_timeout_ms` (default 60s).              | Buy-only, no input box (capability card publishes `static: true`). | `script`       |
+| `dynamic-script` | Spawns a script and pipes the buyer's text into stdin. Returns trimmed stdout. The skeleton for any crypto-paid HTTP/AI proxy. | Input box on the buyer side; the agent itself is not an LLM.       | `script`       |
+
+When **every** loaded skill is non-LLM, `npx @elisym/cli start` skips the LLM-key check - a fully non-AI provider can run with no `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` configured.
+
+Minimal non-LLM examples (drop `mode` to fall back to `llm`):
+
+```markdown
+---
+name: welcome-pack
+description: One-page onboarding doc.
+capabilities: [welcome-pack]
+price: 0.001
+mode: static-file
+output_file: ./welcome.md
+---
+```
+
+```markdown
+---
+name: utc-now
+description: Current UTC timestamp.
+capabilities: [utc-now]
+price: 0.0005
+mode: static-script
+script: ./scripts/now.sh
+---
+```
+
+```markdown
+---
+name: uppercase
+description: Uppercase any text. Skeleton for a paid model proxy.
+capabilities: [uppercase]
+price: 0.0005
+mode: dynamic-script
+script: ./scripts/upper.sh
+---
+```
+
+`output_file` and `script` are resolved relative to the skill directory and rejected if they escape it (`..` traversal, absolute paths outside the skill dir).
 
 ### How `command` is executed
 
@@ -240,7 +297,12 @@ If you cannot make a side effect idempotent, document the risk clearly in the sk
 
 ### More examples
 
-See `skills-examples/` for working skills: `youtube-summary`, `github-repo`, `stock-price`, `whois-lookup`, `site-status`, `trending`, `general-assistant`.
+See `skills-examples/` for working skills:
+
+- **LLM:** `general-assistant` (free), `usdc-summarize`, `site-status`, `whois-lookup`, `github-repo`, `stock-price`, `trending`, `youtube-summary` (multi-round tool-use).
+- **Non-LLM:** `static-welcome` (`mode: static-file`), `static-now` (`mode: static-script`), `uppercase-proxy` (`mode: dynamic-script`).
+
+Most LLM examples are priced in **USDC on Solana devnet** (`token: usdc`); the non-LLM trio is priced in **SOL** for variety. See [`skills-examples/README.md`](./skills-examples/README.md) for the full table and install commands.
 
 ## Troubleshooting
 

package/dist/index.js

@@ -13,7 +13,7 @@ import { lookup } from 'node:dns/promises';
 import { Socket } from 'node:net';
 import pino from 'pino';
 import pLimit from 'p-limit';
-import { parseSkillMd, validateSkillFrontmatter, ScriptSkill as ScriptSkill$1 } from '@elisym/sdk/skills';
+import { parseSkillMd, validateSkillFrontmatter, resolveInsidePath, DEFAULT_SCRIPT_TIMEOUT_MS, StaticScriptSkill as StaticScriptSkill$1, DynamicScriptSkill as DynamicScriptSkill$1, StaticFileSkill as StaticFileSkill$1, ScriptSkill as ScriptSkill$1 } from '@elisym/sdk/skills';
 import { fileURLToPath } from 'node:url';
 
 var __defProp = Object.defineProperty;
@@ -363,7 +363,7 @@ async function cmdProfile(name) {
   if (!name) {
     const agents = await listAgents(cwd);
     if (agents.length === 0) {
-      console.error("No agents found. Run `elisym init` first.");
+      console.error("No agents found. Run `npx @elisym/cli init` first.");
       process.exit(1);
     }
     const { selected } = await inquirer.prompt([
@@ -1660,12 +1660,122 @@ var SkillRegistry = class {
     return this.skills;
   }
 };
+var StaticFileSkill = class {
+  name;
+  description;
+  capabilities;
+  priceSubunits;
+  asset;
+  mode = "static-file";
+  image;
+  imageFile;
+  dir;
+  inner;
+  constructor(params) {
+    this.name = params.name;
+    this.description = params.description;
+    this.capabilities = params.capabilities;
+    this.priceSubunits = params.priceSubunits;
+    this.asset = params.asset;
+    this.image = params.image;
+    this.imageFile = params.imageFile;
+    this.dir = params.dir;
+    this.inner = new StaticFileSkill$1({
+      name: params.name,
+      description: params.description,
+      capabilities: params.capabilities,
+      priceSubunits: BigInt(Math.round(params.priceSubunits)),
+      asset: params.asset,
+      outputFilePath: params.outputFilePath,
+      image: params.image,
+      imageFile: params.imageFile
+    });
+  }
+  async execute(input, ctx) {
+    return this.inner.execute(input, ctx);
+  }
+};
+var StaticScriptSkill = class {
+  name;
+  description;
+  capabilities;
+  priceSubunits;
+  asset;
+  mode = "static-script";
+  image;
+  imageFile;
+  dir;
+  inner;
+  constructor(params) {
+    this.name = params.name;
+    this.description = params.description;
+    this.capabilities = params.capabilities;
+    this.priceSubunits = params.priceSubunits;
+    this.asset = params.asset;
+    this.image = params.image;
+    this.imageFile = params.imageFile;
+    this.dir = params.dir;
+    this.inner = new StaticScriptSkill$1({
+      name: params.name,
+      description: params.description,
+      capabilities: params.capabilities,
+      priceSubunits: BigInt(Math.round(params.priceSubunits)),
+      asset: params.asset,
+      scriptPath: params.scriptPath,
+      scriptArgs: params.scriptArgs,
+      scriptTimeoutMs: params.scriptTimeoutMs,
+      image: params.image,
+      imageFile: params.imageFile
+    });
+  }
+  async execute(input, ctx) {
+    return this.inner.execute(input, ctx);
+  }
+};
+var DynamicScriptSkill = class {
+  name;
+  description;
+  capabilities;
+  priceSubunits;
+  asset;
+  mode = "dynamic-script";
+  image;
+  imageFile;
+  dir;
+  inner;
+  constructor(params) {
+    this.name = params.name;
+    this.description = params.description;
+    this.capabilities = params.capabilities;
+    this.priceSubunits = params.priceSubunits;
+    this.asset = params.asset;
+    this.image = params.image;
+    this.imageFile = params.imageFile;
+    this.dir = params.dir;
+    this.inner = new DynamicScriptSkill$1({
+      name: params.name,
+      description: params.description,
+      capabilities: params.capabilities,
+      priceSubunits: BigInt(Math.round(params.priceSubunits)),
+      asset: params.asset,
+      scriptPath: params.scriptPath,
+      scriptArgs: params.scriptArgs,
+      scriptTimeoutMs: params.scriptTimeoutMs,
+      image: params.image,
+      imageFile: params.imageFile
+    });
+  }
+  async execute(input, ctx) {
+    return this.inner.execute(input, ctx);
+  }
+};
 var ScriptSkill = class {
   name;
   description;
   capabilities;
   priceSubunits;
   asset;
+  mode = "llm";
   image;
   imageFile;
   dir;
@@ -1723,6 +1833,74 @@ var ScriptSkill = class {
 };
 
 // src/skill/loader.ts
+function buildCliSkill(parsed, entryPath) {
+  switch (parsed.mode) {
+    case "llm":
+      return new ScriptSkill(
+        parsed.name,
+        parsed.description,
+        parsed.capabilities,
+        Number(parsed.priceSubunits),
+        parsed.asset,
+        parsed.image,
+        parsed.imageFile,
+        entryPath,
+        parsed.systemPrompt,
+        parsed.tools,
+        parsed.maxToolRounds
+      );
+    case "static-file": {
+      if (parsed.outputFile === void 0) {
+        throw new Error(
+          `SKILL.md "${parsed.name}": internal error - outputFile missing for mode 'static-file'`
+        );
+      }
+      const outputFilePath = resolveInsidePath(entryPath, parsed.outputFile);
+      if (!outputFilePath) {
+        throw new Error(
+          `SKILL.md "${parsed.name}": "output_file" must stay inside the skill directory`
+        );
+      }
+      return new StaticFileSkill({
+        name: parsed.name,
+        description: parsed.description,
+        capabilities: parsed.capabilities,
+        priceSubunits: Number(parsed.priceSubunits),
+        asset: parsed.asset,
+        outputFilePath,
+        image: parsed.image,
+        imageFile: parsed.imageFile,
+        dir: entryPath
+      });
+    }
+    case "static-script":
+    case "dynamic-script": {
+      if (parsed.script === void 0) {
+        throw new Error(
+          `SKILL.md "${parsed.name}": internal error - script missing for mode '${parsed.mode}'`
+        );
+      }
+      const scriptPath = resolveInsidePath(entryPath, parsed.script);
+      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({
+        name: parsed.name,
+        description: parsed.description,
+        capabilities: parsed.capabilities,
+        priceSubunits: Number(parsed.priceSubunits),
+        asset: parsed.asset,
+        scriptPath,
+        scriptArgs: parsed.scriptArgs,
+        scriptTimeoutMs: parsed.scriptTimeoutMs ?? DEFAULT_SCRIPT_TIMEOUT_MS,
+        image: parsed.image,
+        imageFile: parsed.imageFile,
+        dir: entryPath
+      });
+    }
+  }
+}
 function loadSkillsFromDir(skillsDir) {
   const skills = [];
   let entries;
@@ -1747,21 +1925,7 @@ function loadSkillsFromDir(skillsDir) {
       const parsed = validateSkillFrontmatter(frontmatter, systemPrompt, {
         allowFreeSkills: true
       });
-      skills.push(
-        new ScriptSkill(
-          parsed.name,
-          parsed.description,
-          parsed.capabilities,
-          Number(parsed.priceSubunits),
-          parsed.asset,
-          parsed.image,
-          parsed.imageFile,
-          entryPath,
-          parsed.systemPrompt,
-          parsed.tools,
-          parsed.maxToolRounds
-        )
-      );
+      skills.push(buildCliSkill(parsed, entryPath));
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
       console.warn(`  ! Skipping skill "${entry}": ${message}`);
@@ -2037,36 +2201,6 @@ async function cmdStart(nameArg, options = {}) {
 `);
     }
   }
-  if (!loaded.yaml.llm) {
-    console.error("  ! No LLM configured. Run `elisym init` to set up LLM.\n");
-    process.exit(1);
-  }
-  if (!loaded.secrets.llm_api_key) {
-    console.error(
-      `  ! No LLM API key. Set ${loaded.yaml.llm.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY"} env var or update the agent's secrets.
-`
-    );
-    process.exit(1);
-  }
-  const llmProvider = loaded.yaml.llm.provider;
-  const keyEnvVar = llmProvider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY";
-  process.stdout.write(`  Verifying ${llmProvider} API key... `);
-  const verification = await verifyLlmApiKey(llmProvider, loaded.secrets.llm_api_key);
-  if (verification.ok) {
-    console.log("ok");
-  } else if (verification.reason === "invalid") {
-    console.log("INVALID");
-    console.error(`  ! ${llmProvider} rejected the API key (HTTP ${verification.status}).`);
-    console.error(`    Update it via \`elisym profile\` or set ${keyEnvVar} to a valid key.
-`);
-    process.exit(1);
-  } else {
-    console.log("unavailable");
-    console.warn(
-      `  ! Could not verify ${llmProvider} API key (${verification.error}). Continuing - jobs will fail if the key is invalid.
-`
-    );
-  }
   const paths = agentPaths(loaded.dir);
   const skillsDir = paths.skills;
   const allSkills = loadSkillsFromDir(skillsDir);
@@ -2087,16 +2221,56 @@ async function cmdStart(nameArg, options = {}) {
   console.log();
   const hasPaid = allSkills.some((s) => s.priceSubunits > 0);
   if (hasPaid && !solanaAddress) {
-    console.error("  ! Paid skills require a Solana address. Run `elisym init` to configure.\n");
+    console.error(
+      "  ! Paid skills require a Solana address. Run `npx @elisym/cli init` to configure.\n"
+    );
     process.exit(1);
   }
-  const llm = createLlmClient({
-    provider: loaded.yaml.llm.provider,
-    apiKey: loaded.secrets.llm_api_key,
-    model: loaded.yaml.llm.model,
-    maxTokens: loaded.yaml.llm.max_tokens,
-    logUsage: true
-  });
+  const hasLlmSkill = allSkills.some((skill) => skill.mode === "llm");
+  let llm;
+  if (hasLlmSkill) {
+    if (!loaded.yaml.llm) {
+      console.error("  ! No LLM configured. Run `npx @elisym/cli init` to set up LLM.\n");
+      process.exit(1);
+    }
+    if (!loaded.secrets.llm_api_key) {
+      console.error(
+        `  ! No LLM API key. Set ${loaded.yaml.llm.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY"} env var or update the agent's secrets.
+`
+      );
+      process.exit(1);
+    }
+    const llmProvider = loaded.yaml.llm.provider;
+    const keyEnvVar = llmProvider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY";
+    process.stdout.write(`  Verifying ${llmProvider} API key... `);
+    const verification = await verifyLlmApiKey(llmProvider, loaded.secrets.llm_api_key);
+    if (verification.ok) {
+      console.log("ok");
+    } else if (verification.reason === "invalid") {
+      console.log("INVALID");
+      console.error(`  ! ${llmProvider} rejected the API key (HTTP ${verification.status}).`);
+      console.error(
+        `    Update it via \`npx @elisym/cli profile\` or set ${keyEnvVar} to a valid key.
+`
+      );
+      process.exit(1);
+    } else {
+      console.log("unavailable");
+      console.warn(
+        `  ! Could not verify ${llmProvider} API key (${verification.error}). Continuing - jobs will fail if the key is invalid.
+`
+      );
+    }
+    llm = createLlmClient({
+      provider: loaded.yaml.llm.provider,
+      apiKey: loaded.secrets.llm_api_key,
+      model: loaded.yaml.llm.model,
+      maxTokens: loaded.yaml.llm.max_tokens,
+      logUsage: true
+    });
+  } else {
+    console.log("  No LLM skills loaded; skipping LLM key check.\n");
+  }
   const skillCtx = {
     llm,
     agentName,
@@ -2177,11 +2351,13 @@ async function cmdStart(nameArg, options = {}) {
   }
   const kinds = [jobRequestKind(DEFAULT_KIND_OFFSET)];
   function buildCard(skill) {
+    const isStatic = skill.mode === "static-file" || skill.mode === "static-script";
     return {
       name: skill.name,
       description: skill.description,
       capabilities: skill.capabilities,
       image: skill.image,
+      ...isStatic ? { static: true } : {},
       payment: solanaAddress ? {
         chain: "solana",
         network: walletNetwork,
@@ -2370,7 +2546,7 @@ async function resolveStartAgentName(nameArg, cwd) {
   }
   const agents = await listAgents(cwd);
   if (agents.length === 0) {
-    console.log("No agents configured. Run `elisym init` first.");
+    console.log("No agents configured. Run `npx @elisym/cli init` first.");
     process.exit(1);
   }
   const { default: inquirer } = await import('inquirer');
@@ -2546,7 +2722,7 @@ program.command("list").description("List all agents (project-local and home-glo
     const cwd = process.cwd();
     const agents = await listAgents(cwd);
     if (agents.length === 0) {
-      console.log("No agents found. Run `elisym init` to create one.");
+      console.log("No agents found. Run `npx @elisym/cli init` to create one.");
       return;
     }
     console.log("\nAgents:");