@elisym/cli 0.4.0 → 0.5.1

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S node --no-deprecation
 import { readFileSync, readdirSync, statSync, renameSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve, basename, relative, sep } from 'node:path';
-import { SolanaPaymentStrategy, validateAgentName, RELAYS, ElisymIdentity, formatSol, ElisymClient, MediaService, jobRequestKind, DEFAULT_KIND_OFFSET, DEFAULTS, getProtocolProgramId, getProtocolConfig, LIMITS, calculateProtocolFee, BoundedSet } from '@elisym/sdk';
+import { SolanaPaymentStrategy, validateAgentName, RELAYS, ElisymIdentity, formatSol, ElisymClient, MediaService, jobRequestKind, DEFAULT_KIND_OFFSET, DEFAULTS, makeCensor, DEFAULT_REDACT_PATHS, createSlidingWindowLimiter, getProtocolProgramId, getProtocolConfig, LIMITS, calculateProtocolFee, BoundedSet } from '@elisym/sdk';
 import { ElisymYamlSchema, resolveInHome, resolveInProject, createAgentDir, writeYaml, writeSecrets, listAgents, loadAgent, agentPaths, readMediaCache, lookupCachedUrl, newCacheEntry, writeMediaCache } from '@elisym/sdk/agent-store';
 import { isAddress, createSolanaRpc, address } from '@solana/kit';
 import { generateSecretKey, getPublicKey, nip19 } from 'nostr-tools';
@@ -9,9 +9,11 @@ import YAML from 'yaml';
 import { Command } from 'commander';
 import { isEncrypted } from '@elisym/sdk/node';
 import { createHash } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import { Socket } from 'node:net';
+import pino from 'pino';
 import pLimit from 'p-limit';
-import { spawn } from 'node:child_process';
-import { StringDecoder } from 'node:string_decoder';
+import { parseSkillMd, validateSkillFrontmatter, ScriptSkill as ScriptSkill$1 } from '@elisym/sdk/skills';
 import { fileURLToPath } from 'node:url';
 
 var __defProp = Object.defineProperty;
@@ -512,6 +514,86 @@ function truncate(value, max = 40) {
   }
   return value.slice(0, max - 1) + "\u2026";
 }
+var TCP_PROBE_TIMEOUT_MS = 3e3;
+function parseRelayUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const isSecure = parsed.protocol === "wss:" || parsed.protocol === "https:";
+    const defaultPort = isSecure ? 443 : 80;
+    const port = parsed.port.length > 0 ? parseInt(parsed.port, 10) : defaultPort;
+    if (!Number.isFinite(port)) {
+      return null;
+    }
+    return { host: parsed.hostname, port };
+  } catch {
+    return null;
+  }
+}
+async function tcpProbe(host, port, timeoutMs) {
+  return new Promise((resolve3) => {
+    const started = Date.now();
+    const socket = new Socket();
+    let settled = false;
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.destroy();
+      resolve3(result);
+    };
+    const timer = setTimeout(() => finish({ error: "timeout" }), timeoutMs);
+    socket.once("connect", () => {
+      clearTimeout(timer);
+      finish({ openMs: Date.now() - started });
+    });
+    socket.once("error", (err) => {
+      clearTimeout(timer);
+      finish({ error: err.message });
+    });
+    socket.connect(port, host);
+  });
+}
+async function probeRelays(relays, logger, timeoutMs = TCP_PROBE_TIMEOUT_MS) {
+  const results = [];
+  for (const url of relays) {
+    const parsed = parseRelayUrl(url);
+    if (!parsed) {
+      logger.debug({ event: "net_diag_parse_failed", url }, "unparseable relay URL");
+      results.push({ url, host: "", port: 0, ips: [], error: "invalid URL" });
+      continue;
+    }
+    const { host, port } = parsed;
+    let ips = [];
+    try {
+      const resolved = await lookup(host, { all: true });
+      ips = resolved.map((entry) => entry.address);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.debug(
+        { event: "net_diag_dns_failed", url, host, error: message },
+        "DNS lookup failed"
+      );
+      results.push({ url, host, port, ips: [], error: `dns: ${message}` });
+      continue;
+    }
+    const probe = await tcpProbe(host, port, timeoutMs);
+    if ("openMs" in probe) {
+      logger.debug(
+        { event: "net_diag_tcp_open", url, host, port, ips, tcpOpenMs: probe.openMs },
+        "TCP open"
+      );
+      results.push({ url, host, port, ips, tcpOpenMs: probe.openMs });
+    } else {
+      logger.debug(
+        { event: "net_diag_tcp_failed", url, host, port, ips, error: probe.error },
+        "TCP probe failed"
+      );
+      results.push({ url, host, port, ips, error: `tcp: ${probe.error}` });
+    }
+  }
+  return results;
+}
 var HEARTBEAT_INTERVAL_MS = 10 * 60 * 1e3;
 var MAX_CONCURRENT_JOBS = 10;
 var RECOVERY_MAX_RETRIES = 5;
@@ -640,13 +722,29 @@ var JobLedger = class {
   }
   /** Remove old delivered/failed entries (default: 7 days). */
   gc(maxAgeSecs = 7 * 24 * 60 * 60) {
-    const cutoff = Math.floor(Date.now() / 1e3) - maxAgeSecs;
+    this.pruneOldEntries(maxAgeSecs * 1e3);
+  }
+  /**
+   * Drop terminal entries (`delivered` / `failed`) whose `created_at`
+   * predates `now - retentionMs`. Stuck non-terminal entries are never
+   * pruned - recovery keeps retrying them until the retry budget runs
+   * out, then they become terminal and are eligible on the next sweep.
+   *
+   * Returns the number of entries deleted, for observability.
+   */
+  pruneOldEntries(retentionMs) {
+    const cutoff = Math.floor(Date.now() / 1e3) - Math.floor(retentionMs / 1e3);
+    let deleted = 0;
     for (const [id, entry] of this.entries) {
       if ((entry.status === "delivered" || entry.status === "failed") && entry.created_at < cutoff) {
         this.entries.delete(id);
+        deleted += 1;
       }
     }
-    this.flush();
+    if (deleted > 0) {
+      this.flush();
+    }
+    return deleted;
   }
 };
 
@@ -942,8 +1040,56 @@ var OpenAIClient = class {
     }));
   }
 };
+function resolveLevel(options) {
+  if (options.level) {
+    return options.level;
+  }
+  if (options.verbose) {
+    return "debug";
+  }
+  const envLevel = process.env.LOG_LEVEL;
+  if (envLevel) {
+    return envLevel;
+  }
+  return "info";
+}
+function createLogger(options = {}) {
+  const level = resolveLevel(options);
+  const baseOptions = {
+    name: "elisym-cli",
+    level,
+    redact: {
+      paths: DEFAULT_REDACT_PATHS,
+      censor: makeCensor()
+    }
+  };
+  let logger;
+  if (options.destination) {
+    logger = pino(baseOptions, options.destination);
+  } else if (options.tty === true) {
+    logger = pino({
+      ...baseOptions,
+      transport: {
+        target: "pino-pretty",
+        options: { destination: 2, colorize: true, translateTime: "HH:MM:ss" }
+      }
+    });
+  } else {
+    logger = pino(baseOptions, pino.destination(2));
+  }
+  function logWithIndent(line) {
+    process.stdout.write(`  ${line}
+`);
+  }
+  return {
+    logger,
+    logWithIndent,
+    bannerLog: logWithIndent
+  };
+}
 var payment = new SolanaPaymentStrategy();
 var LEDGER_GC_INTERVAL_MS = 60 * 60 * 1e3;
+var LEDGER_RETENTION_MS = 30 * 24 * 60 * 60 * 1e3;
 var TOTAL_JOB_TIMEOUT_MS = 5 * 60 * 1e3;
 function resolveJobPrice(tags, skills) {
   const skill = skills.route(tags);
@@ -952,6 +1098,8 @@ function resolveJobPrice(tags, skills) {
 var RATE_LIMIT_WINDOW_MS = 10 * 60 * 1e3;
 var MAX_JOBS_PER_CUSTOMER = 20;
 var GLOBAL_MAX_JOBS_PER_WINDOW = 200;
+var MAX_TRACKED_CUSTOMERS = 1e3;
+var GLOBAL_LIMITER_KEY = "__global__";
 var AgentRuntime = class {
   constructor(transport, skills, skillCtx, config, ledger, callbacks = {}) {
     this.transport = transport;
@@ -972,10 +1120,18 @@ var AgentRuntime = class {
   recoveryInterval = null;
   gcInterval = null;
   stopped = false;
-  /** Per-customer sliding window rate limiter: pubkey -> timestamps. */
-  customerJobs = /* @__PURE__ */ new Map();
-  /** Global sliding window rate limiter (Sybil protection). */
-  globalJobs = [];
+  /** Per-customer sliding-window rate limiter (keyed on customer pubkey). */
+  customerLimiter = createSlidingWindowLimiter({
+    windowMs: RATE_LIMIT_WINDOW_MS,
+    maxPerWindow: MAX_JOBS_PER_CUSTOMER,
+    maxKeys: MAX_TRACKED_CUSTOMERS
+  });
+  /** Global sliding-window rate limiter (Sybil protection). */
+  globalLimiter = createSlidingWindowLimiter({
+    windowMs: RATE_LIMIT_WINDOW_MS,
+    maxPerWindow: GLOBAL_MAX_JOBS_PER_WINDOW,
+    maxKeys: 1
+  });
   /** Fetch on-chain protocol config (fee, treasury). Always fetches fresh to avoid stale treasury. */
   async fetchProtocolConfig() {
     if (this.config.network !== "devnet") {
@@ -990,7 +1146,7 @@ var AgentRuntime = class {
   }
   async run() {
     const log = this.callbacks.onLog ?? console.log;
-    this.ledger.gc();
+    this.ledger.pruneOldEntries(LEDGER_RETENTION_MS);
     await this.recoverPendingJobs();
     this.recoveryInterval = setInterval(
       () => this.recoverPendingJobs().catch((e) => log(`Recovery error: ${e}`)),
@@ -998,7 +1154,7 @@ var AgentRuntime = class {
     );
     this.gcInterval = setInterval(() => {
       try {
-        this.ledger.gc();
+        this.ledger.pruneOldEntries(LEDGER_RETENTION_MS);
       } catch (e) {
         log(`GC error: ${e.message}`);
       }
@@ -1022,17 +1178,18 @@ var AgentRuntime = class {
         });
         return;
       }
-      if (this.isGlobalRateLimited()) {
-        this.transport.sendFeedback(job, { type: "error", message: "Server busy, try again later" }).catch(() => {
+      if (!this.customerLimiter.peek(job.customerId).allowed) {
+        this.transport.sendFeedback(job, { type: "error", message: "Rate limited, try again later" }).catch(() => {
         });
         return;
       }
-      if (this.isCustomerRateLimited(job.customerId)) {
-        this.transport.sendFeedback(job, { type: "error", message: "Rate limited, try again later" }).catch(() => {
+      if (!this.globalLimiter.peek(GLOBAL_LIMITER_KEY).allowed) {
+        this.transport.sendFeedback(job, { type: "error", message: "Server busy, try again later" }).catch(() => {
         });
         return;
       }
-      this.recordJobAccepted(job.customerId);
+      this.customerLimiter.check(job.customerId);
+      this.globalLimiter.check(GLOBAL_LIMITER_KEY);
       this.callbacks.onJobReceived?.(job);
       this.inFlight.add(job.jobId);
       this.pending++;
@@ -1058,40 +1215,10 @@ var AgentRuntime = class {
       });
     });
   }
-  /** Returns true if global job throughput has been exceeded (Sybil protection). Pure check - no side effects. */
-  isGlobalRateLimited() {
-    const now = Date.now();
-    this.globalJobs = this.globalJobs.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
-    return this.globalJobs.length >= GLOBAL_MAX_JOBS_PER_WINDOW;
-  }
-  /** Returns true if customer has exceeded the per-window job limit. Pure check - no side effects. */
-  isCustomerRateLimited(customerId) {
-    const now = Date.now();
-    const timestamps = this.customerJobs.get(customerId) ?? [];
-    const recent = timestamps.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
-    this.customerJobs.set(customerId, recent);
-    return recent.length >= MAX_JOBS_PER_CUSTOMER;
-  }
-  /** Record a job acceptance for rate limiting. Called only after all checks pass. */
-  recordJobAccepted(customerId) {
-    const now = Date.now();
-    this.globalJobs.push(now);
-    const timestamps = this.customerJobs.get(customerId) ?? [];
-    timestamps.push(now);
-    this.customerJobs.set(customerId, timestamps);
-  }
-  /** Clean up expired rate limit entries. */
+  /** Drop expired hits from both sliding-window limiters. */
   cleanupRateLimits() {
-    const now = Date.now();
-    this.globalJobs = this.globalJobs.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
-    for (const [key, timestamps] of this.customerJobs) {
-      const recent = timestamps.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
-      if (recent.length === 0) {
-        this.customerJobs.delete(key);
-      } else {
-        this.customerJobs.set(key, recent);
-      }
-    }
+    this.customerLimiter.prune();
+    this.globalLimiter.prune();
   }
   stop() {
     if (this.stopped) {
@@ -1468,7 +1595,6 @@ var SkillRegistry = class {
     return this.skills;
   }
 };
-var MAX_TOOL_OUTPUT = 1e6;
 var ScriptSkill = class {
   name;
   description;
@@ -1476,10 +1602,7 @@ var ScriptSkill = class {
   priceLamports;
   image;
   imageFile;
-  skillDir;
-  systemPrompt;
-  tools;
-  maxToolRounds;
+  inner;
   constructor(name, description, capabilities, priceLamports, image, imageFile, skillDir, systemPrompt, tools, maxToolRounds) {
     this.name = name;
     this.description = description;
@@ -1487,155 +1610,25 @@ var ScriptSkill = class {
     this.priceLamports = priceLamports;
     this.image = image;
     this.imageFile = imageFile;
-    this.skillDir = skillDir;
-    this.systemPrompt = systemPrompt;
-    this.tools = tools;
-    this.maxToolRounds = maxToolRounds;
+    this.inner = new ScriptSkill$1({
+      name,
+      description,
+      capabilities,
+      priceLamports: BigInt(Math.round(priceLamports)),
+      skillDir,
+      systemPrompt,
+      tools,
+      maxToolRounds,
+      image,
+      imageFile
+    });
   }
   async execute(input, ctx) {
-    if (!ctx.llm) {
-      throw new Error("LLM client not configured");
-    }
-    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((t) => ({
-      name: t.name,
-      description: t.description,
-      parameters: (t.parameters ?? []).map((p) => ({
-        name: p.name,
-        description: p.description,
-        required: p.required ?? true
-      }))
-    }));
-    const messages = [{ role: "user", content: input.data }];
-    for (let round = 0; round < this.maxToolRounds; round++) {
-      if (ctx.signal?.aborted) {
-        throw new Error("Job aborted");
-      }
-      const result = await ctx.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((t) => t.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(...ctx.llm.formatToolResultMessages(toolResults));
-    }
-    throw new Error(`Max tool rounds (${this.maxToolRounds}) exceeded`);
-  }
-  runTool(toolDef, call, signal) {
-    return new Promise((resolve3, _reject) => {
-      const args = [...toolDef.command];
-      const cmd = args.shift();
-      const params = toolDef.parameters ?? [];
-      for (const param of params) {
-        const value = call.arguments[param.name];
-        if (value !== void 0) {
-          if (param.required && params.indexOf(param) === 0) {
-            args.push(String(value));
-          } else {
-            args.push(`--${param.name}`, String(value));
-          }
-        }
-      }
-      const child = spawn(cmd, args, {
-        cwd: this.skillDir,
-        stdio: ["pipe", "pipe", "pipe"],
-        timeout: 6e4,
-        killSignal: "SIGKILL",
-        signal
-      });
-      let stdout = "";
-      let stderr = "";
-      const stdoutDecoder = new StringDecoder("utf8");
-      const stderrDecoder = new 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) => {
-        if (code === 0) {
-          resolve3(stdout.trim());
-        } else {
-          resolve3(`Error (exit ${code}): ${stderr.trim() || stdout.trim()}`);
-        }
-      });
-      child.on("error", (err) => {
-        resolve3(`Error: ${err.message}`);
-      });
-    });
+    return this.inner.execute(input, ctx);
   }
 };
 
 // src/skill/loader.ts
-var LAMPORTS_PER_SOL = 1e9;
-function solToLamports(sol) {
-  if (!Number.isFinite(sol) || sol < 0) {
-    return 0;
-  }
-  return Math.round(sol * LAMPORTS_PER_SOL);
-}
-function parseSkillMd(content) {
-  const lines = content.split("\n");
-  let start = -1;
-  let end = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].trim() === "---") {
-      if (start === -1) {
-        start = i;
-      } else {
-        end = i;
-        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.parse(yamlStr);
-  if (!frontmatter.name || typeof frontmatter.name !== "string") {
-    throw new Error('SKILL.md: missing or invalid "name" field');
-  }
-  if (!frontmatter.description || typeof frontmatter.description !== "string") {
-    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 systemPrompt = lines.slice(end + 1).join("\n").trim();
-  return { frontmatter, systemPrompt };
-}
 function loadSkillsFromDir(skillsDir) {
   const skills = [];
   let entries;
@@ -1657,22 +1650,26 @@ function loadSkillsFromDir(skillsDir) {
     try {
       const content = readFileSync(skillMdPath, "utf-8");
       const { frontmatter, systemPrompt } = parseSkillMd(content);
+      const parsed = validateSkillFrontmatter(frontmatter, systemPrompt, {
+        allowFreeSkills: true
+      });
       skills.push(
         new ScriptSkill(
-          frontmatter.name,
-          frontmatter.description,
-          frontmatter.capabilities,
-          solToLamports(frontmatter.price ?? 0),
-          frontmatter.image,
-          frontmatter.image_file,
+          parsed.name,
+          parsed.description,
+          parsed.capabilities,
+          Number(parsed.priceLamports),
+          parsed.image,
+          parsed.imageFile,
           entryPath,
-          systemPrompt,
-          frontmatter.tools ?? [],
-          frontmatter.max_tool_rounds ?? 10
+          parsed.systemPrompt,
+          parsed.tools,
+          parsed.maxToolRounds
         )
       );
     } catch (e) {
-      console.warn(`  ! Skipping skill "${entry}": ${e?.message ?? "unknown error"}`);
+      const message = e instanceof Error ? e.message : String(e);
+      console.warn(`  ! Skipping skill "${entry}": ${message}`);
     }
   }
   return skills;
@@ -1791,6 +1788,7 @@ function startWatchdog(deps) {
     transport,
     onPing,
     log,
+    logger,
     probeIntervalMs = WATCHDOG_PROBE_INTERVAL_MS,
     probeTimeoutMs = WATCHDOG_PROBE_TIMEOUT_MS,
     selfPingIntervalMs = WATCHDOG_SELF_PING_INTERVAL_MS,
@@ -1816,10 +1814,12 @@ function startWatchdog(deps) {
         return;
       }
       log("[watchdog] relay probe failed, resetting pool and re-subscribing");
+      logger?.info({ event: "pool_reset", reason: "probe_failed" }, "pool reset");
       resetPoolAndResubscribe();
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       log(`[watchdog] probe/reset error: ${errorMessage}`);
+      logger?.warn({ event: "probe_error", error: errorMessage }, "watchdog probe/reset error");
     } finally {
       busy = false;
     }
@@ -1835,10 +1835,15 @@ function startWatchdog(deps) {
         return;
       }
       log("[watchdog] self-ping failed, resetting pool and re-subscribing");
+      logger?.info({ event: "pool_reset", reason: "self_ping_failed" }, "pool reset");
       resetPoolAndResubscribe();
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       log(`[watchdog] self-ping/reset error: ${errorMessage}`);
+      logger?.warn(
+        { event: "self_ping_error", error: errorMessage },
+        "watchdog self-ping/reset error"
+      );
     } finally {
       busy = false;
     }
@@ -1857,13 +1862,18 @@ function startWatchdog(deps) {
 }
 
 // src/commands/start.ts
-async function cmdStart(nameArg) {
+async function cmdStart(nameArg, options = {}) {
   const cwd = process.cwd();
   const agentName = await resolveStartAgentName(nameArg, cwd);
   if (!agentName) {
     return;
   }
   const loaded = await loadAgentWithPrompt(agentName, cwd);
+  const verbose = options.verbose === true || process.env.ELISYM_DEBUG === "1" || process.env.LOG_LEVEL === "debug";
+  const { logger, logWithIndent } = createLogger({
+    verbose,
+    tty: Boolean(process.stdout.isTTY)
+  });
   console.log(`
   Starting agent ${agentName} (${loaded.source})...
 `);
@@ -1873,6 +1883,9 @@ async function cmdStart(nameArg) {
 `
     );
   }
+  if (verbose) {
+    console.log("  [debug] Verbose logging enabled. Structured diagnostics -> stderr.");
+  }
   const solPayment = loaded.yaml.payments.find((entry) => entry.chain === "solana");
   const solanaAddress = solPayment?.address;
   const walletNetwork = solPayment?.network ?? "devnet";
@@ -1949,6 +1962,18 @@ async function cmdStart(nameArg) {
   const identity = ElisymIdentity.fromHex(loaded.secrets.nostr_secret_key);
   const relays = loaded.yaml.relays.length > 0 ? loaded.yaml.relays : [...RELAYS];
   const client = new ElisymClient({ relays });
+  if (process.env.ELISYM_NET_DIAG === "1") {
+    console.log("  [net-diag] Probing relay DNS + TCP connectivity...");
+    const results = await probeRelays(relays, logger);
+    for (const result of results) {
+      const ipSummary = result.ips.length > 0 ? result.ips.join(",") : "-";
+      if (result.tcpOpenMs !== void 0) {
+        console.log(`  [net-diag] ${result.url} -> ${ipSummary} TCP open in ${result.tcpOpenMs}ms`);
+      } else {
+        console.log(`  [net-diag] ${result.url} -> ${ipSummary} FAILED: ${result.error ?? "?"}`);
+      }
+    }
+  }
   const media = new MediaService();
   const mediaCache = await readMediaCache(loaded.dir);
   let mediaCacheDirty = false;
@@ -1990,6 +2015,7 @@ async function cmdStart(nameArg) {
   if (mediaCacheDirty) {
     await writeMediaCache(loaded.dir, mediaCache);
   }
+  let profilePublished = false;
   try {
     await client.discovery.publishProfile(
       identity,
@@ -1998,8 +2024,11 @@ async function cmdStart(nameArg) {
       pictureUrl,
       bannerUrl
     );
+    profilePublished = true;
+    logger.debug({ event: "publish_ack", kind: 0 }, "profile published");
   } catch (e) {
     console.warn(`  ! Failed to publish profile: ${e.message}`);
+    logger.warn({ event: "publish_failed", kind: 0, error: e.message }, "profile publish failed");
   }
   const kinds = [jobRequestKind(DEFAULT_KIND_OFFSET)];
   function buildCard(skill) {
@@ -2016,11 +2045,21 @@ async function cmdStart(nameArg) {
       } : void 0
     };
   }
+  let cardsPublished = 0;
   for (const skill of allSkills) {
     try {
       await client.discovery.publishCapability(identity, buildCard(skill), kinds);
+      cardsPublished += 1;
+      logger.debug(
+        { event: "publish_ack", kind: 31990, skill: skill.name },
+        "capability card published"
+      );
     } catch (e) {
       console.warn(`  ! Failed to publish "${skill.name}": ${e.message}`);
+      logger.warn(
+        { event: "publish_failed", kind: 31990, skill: skill.name, error: e.message },
+        "capability publish failed"
+      );
     }
   }
   try {
@@ -2047,6 +2086,12 @@ async function cmdStart(nameArg) {
   } catch {
   }
   console.log("  Connected.\n");
+  if (verbose) {
+    console.log(
+      `  [debug] Published: profile=${profilePublished ? "ok" : "FAILED"} + ${cardsPublished}/${allSkills.length} capability cards (kind:31990)`
+    );
+    console.log(`  [debug] Relays: ${relays.length} configured (${relays.join(", ")})`);
+  }
   const onPing = (senderPubkey, nonce) => {
     client.ping.sendPong(identity, senderPubkey, nonce).catch(() => {
     });
@@ -2057,7 +2102,10 @@ async function cmdStart(nameArg) {
     heartbeatTimer = setInterval(async () => {
       try {
         await client.discovery.publishCapability(identity, heartbeatCard, kinds);
-      } catch {
+        logger.debug({ event: "heartbeat_ack", skill: heartbeatCard.name }, "heartbeat ok");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn({ event: "heartbeat_failed", error: message }, "heartbeat publish failed");
       }
     }, HEARTBEAT_INTERVAL_MS);
   }
@@ -2071,26 +2119,49 @@ async function cmdStart(nameArg) {
     network: walletNetwork,
     solanaAddress
   };
-  const logWithIndent = (msg) => console.log(`  ${msg}`);
+  const rpcUrlForLog = stripRpcSecrets(process.env.SOLANA_RPC_URL ?? getRpcUrl());
+  logger.debug(
+    {
+      event: "config_resolved",
+      agent: agentName,
+      source: loaded.source,
+      network: walletNetwork,
+      relays,
+      solanaAddress,
+      rpcUrl: rpcUrlForLog
+    },
+    "config resolved"
+  );
+  const diagLog = (msg) => {
+    logWithIndent(msg);
+    logger.info({ event: "runtime_diag" }, msg);
+  };
   const watchdog = startWatchdog({
     client,
     identity,
     transport,
     onPing,
-    log: logWithIndent
+    log: diagLog,
+    logger
   });
   const runtime = new AgentRuntime(transport, registry, skillCtx, runtimeConfig, ledger, {
     onJobReceived: (job) => {
       const cap = job.tags.find((t) => t !== "elisym") ?? "unknown";
-      console.log(`  [job] ${job.jobId.slice(0, 16)} | cap=${cap}`);
+      process.stdout.write(`  [job] ${job.jobId.slice(0, 16)} | cap=${cap}
+`);
+      logger.info({ event: "job_received", jobId: job.jobId, capability: cap });
     },
     onJobCompleted: (jobId) => {
-      console.log(`  [job] ${jobId.slice(0, 16)} | delivered`);
+      process.stdout.write(`  [job] ${jobId.slice(0, 16)} | delivered
+`);
+      logger.info({ event: "job_delivered", jobId });
     },
     onJobError: (jobId, error) => {
-      console.error(`  [job] ${jobId.slice(0, 16)} | error: ${error}`);
+      process.stderr.write(`  [job] ${jobId.slice(0, 16)} | error: ${error}
+`);
+      logger.error({ event: "job_error", jobId, error });
     },
-    onLog: logWithIndent,
+    onLog: diagLog,
     onStop: () => {
       watchdog.stop();
       if (heartbeatTimer) {
@@ -2101,6 +2172,18 @@ async function cmdStart(nameArg) {
   console.log("  * Running. Press Ctrl+C to stop.\n");
   await runtime.run();
 }
+function stripRpcSecrets(raw) {
+  try {
+    const parsed = new URL(raw);
+    parsed.username = "";
+    parsed.password = "";
+    const marker = parsed.search.length > 0 ? "?***" : "";
+    parsed.search = "";
+    return `${parsed.toString()}${marker}`;
+  } catch {
+    return "[unparseable RPC URL]";
+  }
+}
 async function resolveMediaField(value, agentDir, cache, media, identity, onCacheUpdate) {
   if (!value) {
     return void 0;
@@ -2285,7 +2368,14 @@ program.command("init [name]").description("Create a new agent").option("-c, --c
   })
 );
 program.command("profile [name]").description("Edit agent profile, wallet, and LLM settings").action(safe(cmdProfile));
-program.command("start [name]").description("Start agent in provider mode").action(safe(cmdStart));
+program.command("start [name]").description("Start agent in provider mode").option(
+  "-v, --verbose",
+  "Enable debug logging (relay lifecycle, publish acks, subscription EOSE). Also togglable via ELISYM_DEBUG=1 or LOG_LEVEL=debug."
+).action(
+  safe(async (name, options) => {
+    await cmdStart(name, options);
+  })
+);
 program.command("list").description("List all agents (project-local and home-global)").action(
   safe(async () => {
     const cwd = process.cwd();