@elisym/cli 0.14.0 → 0.16.0

package/README.md

@@ -21,7 +21,7 @@ npx @elisym/cli start    # Start provider mode
 
 ### Docker
 
-Each agent lives in its own directory: `elisym.yaml` (public config), `.secrets.json` (encrypted keys), `.media-cache.json` (uploaded image URLs), `.jobs.json` (ledger), and a `skills/` subfolder. Two locations are supported, and the CLI resolves by walking up from the current working directory:
+Each agent lives in its own directory: `elisym.yaml` (public config), `.secrets.json` (encrypted keys), `.media-cache.json` (uploaded image URLs), `.jobs.json` (ledger), a `skills/` subfolder, and an optional `policies/` subfolder. Two locations are supported, and the CLI resolves by walking up from the current working directory:
 
 - **Project-local**: `<project>/.elisym/<name>/` - shareable, committed to git (except the dotfiles, which the init command auto-gitignores).
 - **Home-global**: `~/.elisym/<name>/` - private, use for ad-hoc or MCP-created agents.
@@ -89,17 +89,17 @@ docker run --rm -it \
 
 ## Commands
 
-| Command                              | Description                                                                                                                                                                         |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `elisym init [name]`                 | Interactive wizard - create agent identity                                                                                                                                          |
-| `elisym init [name] --config <path>` | Non-interactive - load fields from an `elisym.yaml` template                                                                                                                        |
-| `elisym init [name] --defaults`      | Non-interactive - skip every prompt and use wizard defaults (description, default relays, no payments, no LLM, no encryption). Mutually exclusive with `--config`; implies `--yes`. |
-| `elisym init [name] --local`         | Create in project `.elisym/<name>/` (default: `~/.elisym/<name>/`)                                                                                                                  |
-| `elisym start [name]`                | Start agent in provider mode                                                                                                                                                        |
-| `elisym start [name] --verbose`      | Start with structured debug logs to stderr (publish acks, pool resets, config resolution). Also togglable via `ELISYM_DEBUG=1` or `LOG_LEVEL=debug`.                                |
-| `elisym list`                        | List all agents (project-local + home-global)                                                                                                                                       |
-| `elisym profile [name]`              | Edit agent profile, wallet, and LLM settings                                                                                                                                        |
-| `elisym wallet [name]`               | Show Solana wallet balance                                                                                                                                                          |
+| Command                                  | Description                                                                                                                                                                         |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `elisym init [name]`                     | Interactive wizard - create agent identity                                                                                                                                          |
+| `elisym init [name] --config <path>`     | Non-interactive - load fields from an `elisym.yaml` template                                                                                                                        |
+| `elisym init [name] --defaults`          | Non-interactive - skip every prompt and use wizard defaults (description, default relays, no payments, no LLM, no encryption). Mutually exclusive with `--config`; implies `--yes`. |
+| `elisym init [name] --local`             | Create in project `.elisym/<name>/` (default: `~/.elisym/<name>/`)                                                                                                                  |
+| `npx @elisym/cli start [name]`           | Start agent in provider mode                                                                                                                                                        |
+| `npx @elisym/cli start [name] --verbose` | Start with structured debug logs to stderr (publish acks, pool resets, config resolution). Also togglable via `ELISYM_DEBUG=1` or `LOG_LEVEL=debug`.                                |
+| `elisym list`                            | List all agents (project-local + home-global)                                                                                                                                       |
+| `elisym profile [name]`                  | Edit agent profile, wallet, and LLM settings                                                                                                                                        |
+| `elisym wallet [name]`                   | Show Solana wallet balance                                                                                                                                                          |
 
 Skills live inside each agent directory at `<agentDir>/skills/<skill-name>/SKILL.md`:
 
@@ -116,6 +116,9 @@ my-project/
           scripts/summarize.py
         general-assistant/
           SKILL.md
+      policies/         # optional - one *.md per legal/operational policy
+        tos.md
+        privacy.md
       .secrets.json     # encrypted Nostr/LLM keys (gitignored)
       .media-cache.json # sha256 -> uploaded URL cache (gitignored)
       .jobs.json        # crash-recovery ledger (gitignored)
@@ -164,7 +167,7 @@ then return a concise overview and key points.
 | `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.                 |
+| `image_file`        | no                                                            | string   | Local file path (relative to the skill directory). Uploaded on `npx @elisym/cli 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. |
@@ -316,9 +319,37 @@ See `skills-examples/` for working skills:
 
 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.
 
+## Policies
+
+Optional. Drop legal / operational policies (Terms of Service, Privacy, Refund, Acceptable Use, etc.) into `<agentDir>/policies/` and they'll be published as signed [NIP-23](https://github.com/nostr-protocol/nips/blob/master/23.md) long-form articles on `npx @elisym/cli start`. Each markdown file becomes one policy event - the filename without `.md` is the policy `type` slug.
+
+```
+<agentDir>/policies/
+  tos.md
+  privacy.md
+  refund.md
+```
+
+Minimal `tos.md`:
+
+```markdown
+---
+title: Terms of Service
+version: '1.0'
+---
+
+## Terms
+
+By submitting a job to this agent you agree to...
+```
+
+Policies show up in the elisym web app under the **Policies** tab on the agent page, and are readable via the `get_agent_policies` MCP tool.
+
+> Full reference for the policies workflow, frontmatter fields, type vocabulary, limits, update / removal flow, and reading paths lives in [`POLICIES.md`](./POLICIES.md).
+
 ## Troubleshooting
 
-If `elisym start` prints `* Running. Press Ctrl+C to stop.` but no jobs ever arrive (common on WSL and Windows when outbound relay connectivity is blocked by the firewall or NAT), run with `--verbose`:
+If `npx @elisym/cli start` prints `* Running. Press Ctrl+C to stop.` but no jobs ever arrive (common on WSL and Windows when outbound relay connectivity is blocked by the firewall or NAT), run with `--verbose`:
 
 ```
 npx @elisym/cli start <agent-name> --verbose
@@ -330,7 +361,7 @@ The debug firehose on stderr includes:
 - `publish_ack` / `publish_failed` - one per kind:0 profile event and per kind:31990 capability card. If every `publish_failed` row has `error: "Failed to publish to all N relays"`, outbound WebSocket to relays is being blocked.
 - `pool_reset` with `reason: probe_failed` or `self_ping_failed` - the watchdog rebuilt the relay pool; sustained resets mean connectivity is unstable.
 
-Optional deeper network diagnostics (DNS + TCP probe per relay host) are available via `ELISYM_NET_DIAG=1` (see `elisym start --help`).
+Optional deeper network diagnostics (DNS + TCP probe per relay host) are available via `ELISYM_NET_DIAG=1` (see `npx @elisym/cli start --help`).
 
 ## Commands
 

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env -S node --no-deprecation
-import { readFileSync, readdirSync, statSync, renameSync, mkdirSync, writeFileSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync, statSync, renameSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve, basename, relative, sep } from 'node:path';
-import { SolanaPaymentStrategy, validateAgentName, RELAYS, ElisymIdentity, formatSol, formatAssetAmount, USDC_SOLANA_DEVNET, ElisymClient, MediaService, jobRequestKind, DEFAULT_KIND_OFFSET, toDTag, DEFAULTS, makeCensor, DEFAULT_REDACT_PATHS, createSlidingWindowLimiter, getProtocolProgramId, getProtocolConfig, LIMITS, calculateProtocolFee, BoundedSet, KIND_JOB_FEEDBACK, NATIVE_SOL } from '@elisym/sdk';
-import { ElisymYamlSchema, resolveInHome, resolveInProject, createAgentDir, writeYamlInitial, writeExampleSkillTemplate, writeSecrets, listAgents, loadAgent, writeYaml, agentPaths, readMediaCache, lookupCachedUrl, newCacheEntry, writeMediaCache } from '@elisym/sdk/agent-store';
+import { SolanaPaymentStrategy, validateAgentName, RELAYS, ElisymIdentity, formatSol, formatAssetAmount, USDC_SOLANA_DEVNET, ElisymClient, MediaService, POLICY_D_TAG_PREFIX, KIND_LONG_FORM_ARTICLE, POLICY_T_TAG, jobRequestKind, DEFAULT_KIND_OFFSET, toDTag, DEFAULTS, makeCensor, DEFAULT_REDACT_PATHS, createSlidingWindowLimiter, getProtocolProgramId, getProtocolConfig, LIMITS, calculateProtocolFee, BoundedSet, KIND_JOB_FEEDBACK, NATIVE_SOL } from '@elisym/sdk';
+import { ElisymYamlSchema, resolveInHome, resolveInProject, createAgentDir, writeYamlInitial, writeExampleSkillTemplate, writeSecrets, listAgents, loadAgent, writeYaml, agentPaths, readMediaCache, loadPoliciesFromDir, lookupCachedUrl, newCacheEntry, writeMediaCache } from '@elisym/sdk/agent-store';
 import { isAddress, createSolanaRpc, address } from '@solana/kit';
 import { generateSecretKey, getPublicKey, nip19, verifyEvent } from 'nostr-tools';
 import YAML from 'yaml';
@@ -1970,6 +1970,22 @@ function resolveJobAsset(tags, skills) {
   return skill?.asset ?? NATIVE_SOL;
 }
 var BILLING_BODY_MARKERS3 = ["credit balance", "billing", "insufficient", "insufficient_quota"];
+var SCRIPT_BILLING_INVALID_MARKERS = [
+  "credit balance",
+  "billing",
+  "insufficient",
+  "insufficient_quota",
+  "x-api-key",
+  "invalid api key",
+  "invalid_api_key",
+  "authentication_error",
+  "unauthorized",
+  "unauthenticated"
+];
+function scriptMessageLooksLikeBillingOrInvalid(message) {
+  const lower = message.toLowerCase();
+  return SCRIPT_BILLING_INVALID_MARKERS.some((marker) => lower.includes(marker));
+}
 var AGENT_UNAVAILABLE_MESSAGE = "Agent temporarily unavailable";
 var AgentUnavailableError = class extends Error {
   constructor() {
@@ -2070,6 +2086,32 @@ var AgentRuntime = class {
    * Anything else is a transient/skill error and does NOT touch health
    * state - the recovery loop should not be poisoned by skill bugs.
    */
+  /**
+   * Build a "and N other model(s) for the same provider" suffix for
+   * cascade-narrating log lines. The SDK monitor cascades `invalid` /
+   * `billing` flips across every sibling pair sharing the same provider
+   * (shared API key); this helper just narrates that to the operator log
+   * so they can see why unrelated skills are now refusing jobs.
+   */
+  cascadeSuffix(provider, triggeringModel) {
+    if (!this.healthMonitor) {
+      return "";
+    }
+    let siblings = 0;
+    for (const entry of this.healthMonitor.snapshot()) {
+      if (entry.provider !== provider) {
+        continue;
+      }
+      if (entry.model === triggeringModel) {
+        continue;
+      }
+      siblings += 1;
+    }
+    if (siblings === 0) {
+      return "";
+    }
+    return ` (cascading to ${siblings} other model(s) for ${provider} sharing the same API key)`;
+  }
   markHealthFromExecuteError(skill, err, log, jobId) {
     if (!this.healthMonitor) {
       return false;
@@ -2085,7 +2127,7 @@ var AgentRuntime = class {
         return false;
       }
       log(
-        `${tag} Script signaled billing-exhausted (exit ${err.exitCode}). Marking ${provider}/${model} unhealthy; future jobs against this pair will be refused until recovery probe succeeds.`
+        `${tag} Script signaled billing-exhausted (exit ${err.exitCode}). Marking ${provider}/${model} unhealthy${this.cascadeSuffix(provider, model)}; future jobs against this pair will be refused until recovery probe succeeds.`
       );
       this.healthMonitor.markUnhealthyFromJob(provider, model, "billing", err.message);
       return true;
@@ -2109,11 +2151,32 @@ var AgentRuntime = class {
       const provider = skill.resolvedTriple.provider;
       const model = skill.resolvedTriple.model;
       log(
-        `${tag} LLM provider returned HTTP ${status} (${reason}). Marking ${provider}/${model} unhealthy; future jobs against this pair will be refused until recovery probe succeeds.`
+        `${tag} LLM provider returned HTTP ${status} (${reason}). Marking ${provider}/${model} unhealthy${this.cascadeSuffix(provider, model)}; future jobs against this pair will be refused until recovery probe succeeds.`
       );
       this.healthMonitor.markUnhealthyFromJob(provider, model, reason, body);
       return true;
     }
+    if (skill.mode !== "llm") {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!scriptMessageLooksLikeBillingOrInvalid(message)) {
+        return false;
+      }
+      const provider = skill.llmOverride?.provider;
+      const model = skill.llmOverride?.model;
+      if (!provider || !model) {
+        log(
+          `${tag} Script failure looks like billing/invalid ("${message.slice(0, 120)}") but skill "${skill.name}" did not declare provider/model in SKILL.md - cannot gate future jobs.`
+        );
+        return false;
+      }
+      const lower = message.toLowerCase();
+      const reason = lower.includes("credit balance") || lower.includes("billing") || lower.includes("insufficient") ? "billing" : "invalid";
+      log(
+        `${tag} Script failure carries ${reason} signal in stderr. Marking ${provider}/${model} unhealthy${this.cascadeSuffix(provider, model)}; future jobs against this pair will be refused until recovery probe succeeds.`
+      );
+      this.healthMonitor.markUnhealthyFromJob(provider, model, reason, message.slice(0, 200));
+      return true;
+    }
     return false;
   }
   /** Fetch on-chain protocol config (fee, treasury). Always fetches fresh to avoid stale treasury. */
@@ -3701,6 +3764,57 @@ async function cmdStart(nameArg, options = {}) {
     console.warn(`  ! Failed to publish profile: ${e.message}`);
     logger.warn({ event: "publish_failed", kind: 0, error: e.message }, "profile publish failed");
   }
+  const policies = existsSync(paths.policies) ? loadPoliciesFromDir(paths.policies) : [];
+  const localPolicyDTags = new Set(
+    policies.map((policy) => `${POLICY_D_TAG_PREFIX}${policy.type}`)
+  );
+  for (const policy of policies) {
+    try {
+      const { naddr } = await client.policies.publishPolicy(identity, policy);
+      console.log(`  * Policy: ${policy.type}@${policy.version} -> ${naddr}`);
+      logger.debug(
+        { event: "publish_ack", kind: KIND_LONG_FORM_ARTICLE, policy: policy.type, naddr },
+        "policy published"
+      );
+    } catch (e) {
+      console.warn(`  ! Failed to publish policy "${policy.type}": ${e.message}`);
+      logger.warn(
+        {
+          event: "publish_failed",
+          kind: KIND_LONG_FORM_ARTICLE,
+          policy: policy.type,
+          error: e.message
+        },
+        "policy publish failed"
+      );
+    }
+  }
+  try {
+    const existingPolicies = await client.pool.querySync({
+      kinds: [KIND_LONG_FORM_ARTICLE],
+      authors: [identity.publicKey],
+      "#t": [POLICY_T_TAG]
+    });
+    for (const event of existingPolicies) {
+      const dTag = event.tags.find((tag) => tag[0] === "d")?.[1];
+      if (!dTag || localPolicyDTags.has(dTag)) {
+        continue;
+      }
+      if (!event.content) {
+        continue;
+      }
+      const type = event.tags.find((tag) => tag[0] === "policy_type")?.[1];
+      if (!type) {
+        continue;
+      }
+      try {
+        await client.policies.deletePolicy(identity, type);
+        console.log(`  Removed stale policy: ${type}`);
+      } catch {
+      }
+    }
+  } catch {
+  }
   const kinds = [jobRequestKind(DEFAULT_KIND_OFFSET)];
   function buildCard(skill) {
     const isStatic = skill.mode === "static-file" || skill.mode === "static-script";