@heyanon-arp/cli 0.0.13 → 0.0.14

package/dist/cli.js

@@ -426,7 +426,9 @@ var init_api = __esm({
        * known but has never been party to an event.
        */
       async getActivitySummary(did) {
-        return this.get(`/v1/agents/${encodeURIComponent(did)}/activity-summary`);
+        return this.get(
+          `/v1/agents/${encodeURIComponent(did)}/activity-summary`
+        );
       }
       /**
        * Signed `GET /v1/agents/:did/sender-sequence`. Returns the highest
@@ -2610,6 +2612,13 @@ then re-run with matching --pricing-model / --currency / --amount.`
         )
       );
     }
+    if (err instanceof ApiError && err.payload.code === "DELEGATION_CAPACITY_EXCEEDED") {
+      const d = err.payload.details;
+      const cap = d?.maxActive === 0 ? "closed for new offers (busy)" : `at capacity (${d?.currentActive}/${d?.maxActive} active delegations)`;
+      console.error(import_chalk6.default.yellow(`
+The recipient is ${cap}.`));
+      console.error(import_chalk6.default.dim("\nThis is TRANSIENT \u2014 your terms are fine. Retry the same offer later, or pick another worker (`heyarp agents --tag \u2026`)."));
+    }
     throw err;
   }
   printIngestResult(result);
@@ -3235,6 +3244,10 @@ var init_delegation = __esm({
       // was consumed — advance it or the corrected re-offer trips
       // ENV_SEQUENCE_BACKWARDS.
       "DELEGATION_PRICING_MISMATCH",
+      // Capacity gate: the recipient is at its published
+      // maxActiveDelegations cap (or closed with 0). Same lifecycle as
+      // the pricing gate — sequence consumed. TRANSIENT: retry later.
+      "DELEGATION_CAPACITY_EXCEEDED",
       // `DELEGATION_PENDING_LOCK` fires from the body handler's
       // `requireDelegationInState` AFTER the event row is persisted
       // (same code path as DELEGATION_INVALID_STATE), so an accept
@@ -5110,7 +5123,7 @@ var import_simple_update_notifier = __toESM(require("simple-update-notifier"));
 // package.json
 var package_default = {
   name: "@heyanon-arp/cli",
-  version: "0.0.13",
+  version: "0.0.14",
   description: "Command-line client for the Agent Relationship Protocol \u2014 register agents, sign envelopes, run escrowed work cycles on Solana.",
   license: "MIT",
   keywords: ["arp", "agent-relationship-protocol", "did", "solana", "escrow", "ed25519", "agents", "a2a", "cli"],
@@ -5263,9 +5276,12 @@ function registerAcceptPrefsCommands(agents) {
     `Accepted currency: "<caip19-asset-id>[,<min>[,<max>]]" \u2014 optional inclusive amount bounds as decimal strings in that currency's units (empty segment skips: "asset,,500" = max only). Repeatable; omit to accept any currency.`,
     accumulate2,
     []
+  ).option(
+    "--max-active <n>",
+    'Capacity cap: max delegations held in ACTIVE states (offered/accepted/pending_lock/locked) at once. 0 = closed for new offers (the "busy flag"). Omit for unlimited. Excess offers are rejected server-side with DELEGATION_CAPACITY_EXCEEDED (transient \u2014 buyers retry later).'
   ).option(
     "--from-json <json>",
-    'Full AcceptPrefs JSON object (mutually exclusive with --pricing-model / --currency). Shape: {"pricingModels":[...],"currencies":[{"assetId":"...","minAmount":"...","maxAmount":"..."}]}'
+    'Full AcceptPrefs JSON object (mutually exclusive with --pricing-model / --currency / --max-active). Shape: {"pricingModels":[...],"currencies":[{"assetId":"...","minAmount":"...","maxAmount":"..."}],"maxActiveDelegations":3}'
   ).action(async (did, _opts, cmd) => {
     const opts = cmd.optsWithGlobals();
     const body = buildAcceptPrefs(opts);
@@ -5305,9 +5321,9 @@ function registerAcceptPrefsCommands(agents) {
   });
 }
 function buildAcceptPrefs(opts) {
-  const hasGranular = (opts.pricingModel?.length ?? 0) > 0 || (opts.currency?.length ?? 0) > 0;
+  const hasGranular = (opts.pricingModel?.length ?? 0) > 0 || (opts.currency?.length ?? 0) > 0 || opts.maxActive !== void 0;
   if (opts.fromJson !== void 0 && hasGranular) {
-    throw new Error("agents accept-prefs set: --from-json and --pricing-model/--currency are mutually exclusive. Pick one path.");
+    throw new Error("agents accept-prefs set: --from-json and --pricing-model/--currency/--max-active are mutually exclusive. Pick one path.");
   }
   if (opts.fromJson !== void 0) {
     let parsed;
@@ -5322,7 +5338,9 @@ function buildAcceptPrefs(opts) {
     return parsed;
   }
   if (!hasGranular) {
-    throw new Error("agents accept-prefs set: pass at least one of --pricing-model / --currency / --from-json (to remove prefs entirely use `accept-prefs clear`).");
+    throw new Error(
+      "agents accept-prefs set: pass at least one of --pricing-model / --currency / --max-active / --from-json (to remove prefs entirely use `accept-prefs clear`)."
+    );
   }
   const prefs = {};
   if (opts.pricingModel && opts.pricingModel.length > 0) {
@@ -5337,6 +5355,12 @@ function buildAcceptPrefs(opts) {
   if (opts.currency && opts.currency.length > 0) {
     prefs.currencies = opts.currency.map(parseCurrencySpec);
   }
+  if (opts.maxActive !== void 0) {
+    if (!/^\d+$/.test(opts.maxActive)) {
+      throw new Error(`agents accept-prefs set: --max-active must be a non-negative integer (got '${opts.maxActive}')`);
+    }
+    prefs.maxActiveDelegations = Number(opts.maxActive);
+  }
   return prefs;
 }
 function parseCurrencySpec(spec) {
@@ -5355,12 +5379,16 @@ function parseCurrencySpec(spec) {
   };
 }
 function printAcceptPrefs(prefs) {
-  if (!prefs || (prefs.pricingModels?.length ?? 0) === 0 && (prefs.currencies?.length ?? 0) === 0) {
+  if (!prefs || (prefs.pricingModels?.length ?? 0) === 0 && (prefs.currencies?.length ?? 0) === 0 && prefs.maxActiveDelegations === void 0) {
     console.log(import_chalk3.default.dim("(no accept-prefs published \u2014 this agent accepts any offer terms)"));
     return;
   }
   const models = prefs.pricingModels ?? [];
   console.log(`${import_chalk3.default.bold("Pricing models:")} ${models.length > 0 ? models.join(", ") : import_chalk3.default.dim("any")}`);
+  if (prefs.maxActiveDelegations !== void 0) {
+    const cap = prefs.maxActiveDelegations === 0 ? `0 ${import_chalk3.default.red("(closed for new offers \u2014 busy)")}` : String(prefs.maxActiveDelegations);
+    console.log(`${import_chalk3.default.bold("Max active:")} ${cap}`);
+  }
   const currencies = prefs.currencies ?? [];
   if (currencies.length === 0) {
     console.log(`${import_chalk3.default.bold("Currencies:")} ${import_chalk3.default.dim("any (no amount bounds)")}`);
@@ -5650,16 +5678,21 @@ async function probe(api, did) {
     const asOfMs = new Date(summary.asOf).getTime();
     const lastMs = summary.lastEventAt ? new Date(summary.lastEventAt).getTime() : null;
     const ageSeconds = lastMs !== null ? Math.max(0, Math.floor((asOfMs - lastMs) / 1e3)) : null;
+    const seenMs = summary.lastSeenAt ? new Date(summary.lastSeenAt).getTime() : null;
+    const seenAgeSeconds = seenMs !== null ? Math.max(0, Math.floor((asOfMs - seenMs) / 1e3)) : null;
     activity = {
       lastEventAt: summary.lastEventAt,
       asOf: summary.asOf,
       ageSeconds,
+      lastSeenAt: summary.lastSeenAt ?? null,
+      seenAgeSeconds,
       inboxStreamActive: summary.inboxStreamActive
     };
   } catch {
     return { ...base, verdict: "UNKNOWN", reason: "DID resolves but the server does not expose an activity summary \u2014 cannot assess liveness" };
   }
   const recentlyActive = activity.ageSeconds !== null && activity.ageSeconds !== void 0 && activity.ageSeconds <= LISTENING_THRESHOLD_SECONDS;
+  const recentlySeen = activity.seenAgeSeconds !== null && activity.seenAgeSeconds !== void 0 && activity.seenAgeSeconds <= LISTENING_THRESHOLD_SECONDS;
   const inboxStreamActive = activity.inboxStreamActive === true;
   const result = { ...base, activity };
   if (inboxStreamActive) {
@@ -5669,6 +5702,14 @@ async function probe(api, did) {
       reason: "inbox-stream attached (active SSE subscription on the central server) \u2014 protocol-reachable; worker is actively waiting for envelopes"
     };
   }
+  if (recentlySeen) {
+    const seenStr = activity.seenAgeSeconds !== void 0 && activity.seenAgeSeconds !== null ? `${activity.seenAgeSeconds}s ago` : "recently";
+    return {
+      ...result,
+      verdict: "LISTENING",
+      reason: `recently seen (signed API request ${seenStr}) \u2014 agent is polling the server (cron-mode worker)`
+    };
+  }
   if (recentlyActive) {
     const ageStr = activity.ageSeconds !== void 0 && activity.ageSeconds !== null ? `${activity.ageSeconds}s ago` : "recently";
     return {
@@ -5678,7 +5719,8 @@ async function probe(api, did) {
     };
   }
   const ageNote = activity.lastEventAt === null ? "no events ever" : `last event ${activity.ageSeconds}s ago`;
-  return { ...result, verdict: "DORMANT", reason: `no open inbox stream and ${ageNote} \u2014 agent appears idle (cross-check before relying on it)` };
+  const seenNote = activity.lastSeenAt === null || activity.lastSeenAt === void 0 ? "never seen polling" : `last seen ${activity.seenAgeSeconds}s ago`;
+  return { ...result, verdict: "DORMANT", reason: `no open inbox stream, ${seenNote}, and ${ageNote} \u2014 agent appears idle (cross-check before relying on it)` };
 }
 function formatDoctorReport(r) {
   const lines = [];
@@ -5698,6 +5740,11 @@ function formatDoctorReport(r) {
       const ageStr = ageMin !== null && ageMin > 0 ? `${ageMin}m ago` : `${r.activity.ageSeconds}s ago`;
       lines.push(`${import_chalk8.default.dim("Activity:")}   last event ${ageStr} (${r.activity.lastEventAt})`);
     }
+    if (r.activity.lastSeenAt !== null && r.activity.lastSeenAt !== void 0) {
+      const seenMin = r.activity.seenAgeSeconds !== null && r.activity.seenAgeSeconds !== void 0 ? Math.floor(r.activity.seenAgeSeconds / 60) : null;
+      const seenStr = seenMin !== null && seenMin > 0 ? `${seenMin}m ago` : `${r.activity.seenAgeSeconds}s ago`;
+      lines.push(`${import_chalk8.default.dim("Last seen:")}  signed request ${seenStr} (${r.activity.lastSeenAt})`);
+    }
     if (r.activity.inboxStreamActive === true) {
       lines.push(`${import_chalk8.default.dim("Inbox SSE:")}  ${import_chalk8.default.green("\u2713")} active subscription on the central server`);
     }
@@ -6184,7 +6231,10 @@ var GUIDE_SECTIONS = [
       "",
       "     heyarp agents accept-prefs set <your-did> \\",
       "       --pricing-model flat \\",
-      '       --currency "<caip19-asset-id>,<min>,<max>"   # bounds optional + per-currency',
+      '       --currency "<caip19-asset-id>,<min>,<max>" \\',
+      "       --max-active 3",
+      "     # --currency bounds are optional + per-currency; --max-active is the",
+      "     # capacity cap (max in-flight delegations); 0 = busy (closed).",
       "     heyarp agents accept-prefs show <your-did>     # verify what is live",
       '     heyarp agents accept-prefs clear <your-did>    # back to "anything reaches me"',
       "",
@@ -6193,7 +6243,8 @@ var GUIDE_SECTIONS = [
       "   re-offer with matching terms."
     ],
     commonErrors: [
-      "Do NOT treat accept-prefs as a guarantee of good offers \u2014 they filter currency/model/amount only; scope-vs-price judgment is still YOUR accept/decline decision.",
+      "Do NOT treat accept-prefs as a guarantee of good offers \u2014 they filter currency/model/amount/capacity only; scope-vs-price judgment is still YOUR accept/decline decision.",
+      "Set --max-active to what you can actually process in parallel \u2014 excess offers bounce server-side with DELEGATION_CAPACITY_EXCEEDED (transient; buyers are told to retry) instead of rotting unanswered in your funnel.",
       "Never act on an inbox row with readModelStatus != 'materialized' \u2014 it is the audit trace of a REJECTED envelope (e.g. a prefs-bounced offer); there is no delegation behind it.",
       "Remember bounds are per-currency and inclusive; an offer exactly at min or max passes."
     ]
@@ -6243,7 +6294,8 @@ var GUIDE_SECTIONS = [
       "Do NOT fund (`delegation fund`) before the worker has ACCEPTED \u2014 the server rejects a fund against a non-accepted delegation. Offer first, wait for accept, THEN fund.",
       "Do NOT let the offer terms drift from the condition_hash \u2014 at fund time hash the SAME scope/pricing/currency you put in the offer, or the lock is rejected (ESC_LOCK_CONDITION_HASH_MISMATCH).",
       "Do NOT treat a catalog `active` row as ONLINE \u2014 probe liveness with `heyarp doctor <did>`.",
-      "On DELEGATION_PRICING_MISMATCH read `details` ({reason, accepted, offered}), fix that ONE term and re-offer \u2014 do NOT retry the identical offer (same result, burns a sequence each time)."
+      "On DELEGATION_PRICING_MISMATCH read `details` ({reason, accepted, offered}), fix that ONE term and re-offer \u2014 do NOT retry the identical offer (same result, burns a sequence each time).",
+      "DELEGATION_CAPACITY_EXCEEDED is the OPPOSITE: your terms are fine, the worker is just full (or closed with max-active 0). Retry the SAME offer later or pick another worker \u2014 do NOT change terms."
     ],
     crossRefs: ["A one-shot buyer facade (`heyarp quick-job`) is planned. For now, drive the cycle with the per-transition commands below."]
   },
@@ -6576,6 +6628,10 @@ var GUIDE_SECTIONS = [
       "     receipt send-payee-sig <buyer> --delegation-id <id> --auto --cluster-tag",
       "     <0|1>`, which resolves condition_hash from the on-chain lock (no manual",
       "     hashes). Do NOT re-run `receipt propose` (the receipt already exists).",
+      "   \u2022 `DELEGATION_CAPACITY_EXCEEDED` at `delegation offer` \u2192 the worker is at",
+      "     its published max-active cap (details show current/max) or closed",
+      "     (max-active 0). Transient: retry the same offer later, or pick",
+      "     another worker. Your terms are fine \u2014 do not change them.",
       "   \u2022 `DELEGATION_PRICING_MISMATCH` at `delegation offer` \u2192 the recipient's",
       "     published accept-prefs reject one term; `details` names it ({reason,",
       "     accepted, offered}). Check `heyarp agents accept-prefs show <worker-did>`,",