@elisym/cli 0.27.0 → 0.29.0

package/dist/index.js

@@ -9,7 +9,7 @@ import { generateSecretKey, getPublicKey, nip19, verifyEvent } from 'nostr-tools
 import YAML2 from 'yaml';
 import { Command } from 'commander';
 import { mkdir, writeFile, readFile, mkdtemp, rm, rename, stat } from 'node:fs/promises';
-import { parseSkillMd, validateSkillFrontmatter, DEFAULT_X402_MAX_INPUT_BYTES, resolveInsidePathReal, DEFAULT_SCRIPT_TIMEOUT_MS, DynamicScriptSkill as DynamicScriptSkill$1, StaticScriptSkill as StaticScriptSkill$1, StaticFileSkill as StaticFileSkill$1, ScriptSkill as ScriptSkill$1 } from '@elisym/sdk/skills';
+import { parseSkillMd, validateSkillFrontmatter, DEFAULT_X402_MAX_INPUT_BYTES, resolveInsidePathReal, DEFAULT_SCRIPT_TIMEOUT_MS, OnchainCallSkill, DynamicScriptSkill as DynamicScriptSkill$1, StaticScriptSkill as StaticScriptSkill$1, StaticFileSkill as StaticFileSkill$1, ScriptSkill as ScriptSkill$1 } from '@elisym/sdk/skills';
 import chalk from 'chalk';
 import Decimal from 'decimal.js-light';
 import { decodePaymentRequiredHeader } from '@x402/core/http';
@@ -5318,7 +5318,15 @@ var AgentRuntime = class {
           return;
         }
         this.ledger.recordDeliveredContent(job.jobId, deliveredContent);
+        delegatedPull.chargedSubunits = this.resolveMeteredCharge(
+          job,
+          matched,
+          delegatedPull.priceSubunits,
+          output.chargeSubunits,
+          log
+        );
         const outcome = await this.executeDelegatedPull(job, delegatedPull, log);
+        netAmount = Number(delegatedPull.chargedSubunits ?? delegatedPull.priceSubunits);
         if (outcome === "dead") {
           this.ledger.markFailed(job.jobId);
           await this.transport.sendFeedback(job, {
@@ -5353,6 +5361,59 @@ var AgentRuntime = class {
       }
     }
   }
+  /**
+   * Decide what a delegated pull should move, for a skill that opted into
+   * metered pricing.
+   *
+   * The skill reports a figure through `ELISYM_CHARGE_FILE`; we clamp it into
+   * the range the CARD published, so the buyer can never be billed above the
+   * `price` they approved nor below the `min` they were quoted. A skill that is
+   * not metered, or one that reported nothing usable, charges the ceiling -
+   * that is exactly today's behaviour and exactly what the buyer consented to,
+   * so a provider-side bug costs the provider nothing and surprises no one.
+   * The "reported nothing" case is logged loudly because on a metered skill it
+   * means the script is broken, not that the job was cheap.
+   *
+   * Returns `undefined` to mean "charge the ceiling", which is what every
+   * caller already falls back to.
+   */
+  resolveMeteredCharge(job, skill, ceiling, reported, log) {
+    const floor = skill?.meteredMinSubunits;
+    if (floor === void 0) {
+      return void 0;
+    }
+    if (typeof floor !== "bigint" || floor <= 0n) {
+      log(
+        `[${job.jobId.slice(0, 8)}] Metered skill has an unusable floor (${String(floor)}) - billing the ${ceiling} ceiling.`
+      );
+      return void 0;
+    }
+    if (reported !== void 0 && typeof reported !== "bigint") {
+      log(
+        `[${job.jobId.slice(0, 8)}] Metered skill reported a non-bigint charge - billing the ${ceiling} ceiling.`
+      );
+      return void 0;
+    }
+    if (reported === void 0) {
+      log(
+        `[${job.jobId.slice(0, 8)}] Metered skill reported no charge - billing the ${ceiling} ceiling. The script should write its cost in subunits to ELISYM_CHARGE_FILE.`
+      );
+      return void 0;
+    }
+    let charged = reported;
+    if (charged < floor) {
+      charged = floor;
+    }
+    if (charged > ceiling) {
+      charged = ceiling;
+    }
+    if (charged !== reported) {
+      log(
+        `[${job.jobId.slice(0, 8)}] Metered charge ${reported} clamped to ${charged} (published range ${floor}..${ceiling}).`
+      );
+    }
+    return charged;
+  }
   reserveDelegation(owner, amount) {
     this.delegationInFlight.set(owner, (this.delegationInFlight.get(owner) ?? 0n) + amount);
   }
@@ -5484,13 +5545,13 @@ var AgentRuntime = class {
         "the delegation account balance is below this skill price."
       );
     }
-    this.reserveDelegation(request.owner, priceSubunits);
     log(
       `[${job.jobId.slice(0, 8)}] Delegated pre-check ok: ${formatAssetAmount(
         delegationAsset,
         priceSubunits
       )} from ${request.owner.slice(0, 8)}... (pull after work)`
     );
+    this.reserveDelegation(request.owner, priceSubunits);
     return { request, delegateSigner, ownerAta, priceSubunits, rpc, network };
   }
   /**
@@ -5504,11 +5565,12 @@ var AgentRuntime = class {
       throw new Error("Solana address not configured");
     }
     const destinationAta = await deriveOwnerDelegationAta(this.config.solanaAddress, ctx.network);
+    const amount = ctx.chargedSubunits ?? ctx.priceSubunits;
     const instructions = await buildDelegatedTransfer({
       delegate: ctx.delegateSigner,
       source: ctx.ownerAta,
       destination: destinationAta,
-      amount: ctx.priceSubunits,
+      amount,
       network: ctx.network,
       // Idempotent create (delegate-paid rent) so a fresh provider wallet's
       // first delegated job does not dead-letter on a missing ATA.
@@ -5521,11 +5583,13 @@ var AgentRuntime = class {
       job.jobId,
       pull.signature,
       Number(pull.lastValidBlockHeight),
-      Number(ctx.priceSubunits)
+      Number(amount)
     );
     ctx.pullSignature = pull.signature;
     const outcome = await sendConfirmToTerminal(ctx.rpc, pull, {});
-    log(`[${job.jobId.slice(0, 8)}] Delegated pull ${outcome}: ${pull.signature.slice(0, 16)}...`);
+    log(
+      `[${job.jobId.slice(0, 8)}] Delegated pull ${outcome}: ${amount} subunits, ${pull.signature.slice(0, 16)}...`
+    );
     return outcome;
   }
   /**
@@ -6704,6 +6768,51 @@ var DynamicScriptSkill = class {
     return this.inner.execute(input, ctx);
   }
 };
+var OnchainSkill = class {
+  name;
+  description;
+  capabilities;
+  priceSubunits;
+  asset;
+  mode = "onchain";
+  image;
+  imageFile;
+  dir;
+  llmOverride;
+  onchain;
+  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.llmOverride = params.llmOverride;
+    this.onchain = params.onchain;
+    this.inner = new OnchainCallSkill({
+      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,
+      scriptEnv: params.scriptEnv,
+      image: params.image,
+      imageFile: params.imageFile,
+      llmOverride: params.llmOverride,
+      onchain: params.onchain,
+      network: params.network
+    });
+  }
+  async execute(input, ctx) {
+    return this.inner.execute(input, ctx);
+  }
+};
 var ScriptSkill = class {
   name;
   description;
@@ -6836,7 +6945,7 @@ function scopeLlmKeys(scriptEnv, declaredProvider) {
   }
   return env;
 }
-function buildCliSkill(parsed, entryPath, scriptEnv) {
+function buildCliSkill(parsed, entryPath, scriptEnv, network) {
   let safeImageFile = parsed.imageFile;
   if (safeImageFile !== void 0 && resolveInsidePathReal(entryPath, safeImageFile) === null) {
     console.warn(
@@ -6924,6 +7033,35 @@ function buildCliSkill(parsed, entryPath, scriptEnv) {
       }) : new StaticScriptSkill(scriptParams);
       break;
     }
+    case "onchain": {
+      if (parsed.script === void 0 || parsed.onchain === void 0) {
+        throw new Error(
+          `SKILL.md "${parsed.name}": internal error - script or onchain block missing for mode 'onchain'`
+        );
+      }
+      const scriptPath = resolveInsidePathReal(entryPath, parsed.script);
+      if (!scriptPath) {
+        throw new Error(`SKILL.md "${parsed.name}": "script" must stay inside the skill directory`);
+      }
+      skill = new OnchainSkill({
+        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,
+        scriptEnv: scopeLlmKeys(scriptEnv, parsed.llmOverride?.provider),
+        image: parsed.image,
+        imageFile: safeImageFile,
+        dir: entryPath,
+        llmOverride: parsed.llmOverride,
+        onchain: parsed.onchain,
+        network
+      });
+      break;
+    }
     case "x402": {
       if (parsed.x402 === void 0) {
         throw new Error(
@@ -6951,6 +7089,9 @@ function buildCliSkill(parsed, entryPath, scriptEnv) {
   if (parsed.executionTimeoutSecs !== void 0) {
     skill.executionTimeoutSecs = parsed.executionTimeoutSecs;
   }
+  if (parsed.meteredMinSubunits !== void 0) {
+    skill.meteredMinSubunits = parsed.meteredMinSubunits;
+  }
   if (parsed.delegation) {
     skill.delegation = parsed.delegation;
   }
@@ -6989,7 +7130,7 @@ function loadSkillsFromDir(skillsDir, options) {
           warn: (_obj, msg) => console.warn(`  ! ${msg ?? ""}`)
         }
       });
-      skills.push(buildCliSkill(parsed, entryPath, options.scriptEnv));
+      skills.push(buildCliSkill(parsed, entryPath, options.scriptEnv, options.network));
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
       console.warn(`  ! Skipping skill "${entry}": ${message}`);
@@ -8368,6 +8509,12 @@ async function cmdStart(nameArg, options = {}) {
     agentName,
     agentDescription: loaded.yaml.description ?? ""
   };
+  const onchainSkillCount = allSkills.filter((skill) => skill.onchain !== void 0).length;
+  if (solanaAddress === void 0 && onchainSkillCount > 0) {
+    console.warn(
+      `  ! ${onchainSkillCount} onchain capability(ies) declare a block but this agent has no Solana payment address, so the network their cards would promise is a guess. Add a payments entry to elisym.yaml.`
+    );
+  }
   const x402Skills = allSkills.filter((skill) => skill.mode === "x402");
   let x402InvariantBroken;
   if (x402Skills.length > 0) {
@@ -8377,9 +8524,13 @@ async function cmdStart(nameArg, options = {}) {
     } else if (!solanaAddress) {
       x402InvariantBroken = "no payments[] entry in elisym.yaml";
     } else {
-      const bridgeSigner = await signerFromSecretKeyBase58(solanaSecretKey);
-      if (bridgeSigner.address !== solanaAddress) {
-        x402InvariantBroken = `payments[].address (${solanaAddress}) differs from the solana_secret_key address (${bridgeSigner.address})`;
+      try {
+        const bridgeSigner = await signerFromSecretKeyBase58(solanaSecretKey);
+        if (bridgeSigner.address !== solanaAddress) {
+          x402InvariantBroken = `payments[].address (${solanaAddress}) differs from the solana_secret_key address (${bridgeSigner.address})`;
+        }
+      } catch (error) {
+        x402InvariantBroken = `solana_secret_key is present but unreadable - ${error instanceof Error ? error.message : String(error)}`;
       }
     }
     for (const skill of x402Skills) {
@@ -8655,6 +8806,16 @@ async function cmdStart(nameArg, options = {}) {
       );
       continue;
     }
+    if (withholdsOnchainCard(skill, solanaAddress)) {
+      console.warn(
+        `  ! Not republishing "${skill.name}" - no Solana payments entry. An earlier card for it, if any, stays on the relays until it expires.`
+      );
+      logger.warn(
+        { event: "publish_skipped_onchain_no_wallet", kind: 31990, skill: skill.name },
+        "capability not advertised - onchain block with no Solana payment address"
+      );
+      continue;
+    }
     try {
       await client.discovery.publishCapability(identity2, buildCard(skill), kinds);
       cardsPublished += 1;
@@ -8832,6 +8993,26 @@ function buildCapabilityCard(skill, inputs) {
     // exists (delegatePubkey resolved). The pubkey is injected here, never
     // taken from the SKILL.md - the operator declares only the cap/mechanism.
     ...skill.delegation && delegatePubkey ? { delegation: { ...skill.delegation, delegate_pubkey: delegatePubkey } } : {},
+    // Metered descriptor. The gate is COMPOUND on purpose and both halves
+    // matter: `delegatePubkey` is agent-wide (hoisted when ANY skill declares
+    // delegation), while `skill.delegation` is per-skill. Stamping on the agent
+    // half alone would advertise pay-per-use on a card that ships no delegation
+    // block - the buyer would be told "you pay for what you use" while the only
+    // rail they can reach charges the ceiling. The loader already refuses
+    // `metered` without `delegation`, so this is defence in depth.
+    // `solanaAddress` is in the gate too: without it the `payment` block below
+    // is omitted, and a metered descriptor with no price to clamp against is
+    // incoherent by construction - the write-side mirror would then reject the
+    // card with a misleading "malformed metered descriptor" instead of the real
+    // reason, which is that the agent has no payment address.
+    ...skill.meteredMinSubunits !== void 0 && skill.delegation && delegatePubkey && solanaAddress ? { metered: { min_subunits: skill.meteredMinSubunits.toString() } } : {},
+    // On-chain promise (`mode: onchain`): the network is stamped from the
+    // agent's wallet here, never from SKILL.md, so a capability copied between
+    // a devnet and a mainnet agent cannot advertise the wrong chain.
+    // Only stamped when the agent actually has a Solana payment entry: without
+    // one `walletNetwork` is a default, and a card must never promise a chain
+    // the operator never chose. `cmdStart` warns for such a skill at step 7a.
+    ...skill.onchain && solanaAddress ? { onchain: { ...skill.onchain, network: walletNetwork } } : {},
     payment: solanaAddress ? {
       chain: "solana",
       network: walletNetwork,
@@ -8844,6 +9025,9 @@ function buildCapabilityCard(skill, inputs) {
     } : void 0
   };
 }
+function withholdsOnchainCard(skill, solanaAddress) {
+  return skill.onchain !== void 0 && solanaAddress === void 0;
+}
 function buildScriptEnv(secrets) {
   const scriptEnv = { ...process.env };
   delete scriptEnv.ELISYM_PASSPHRASE;