@senpi/runtime 3.0.79 → 3.0.81

package/dist/widgets/widgets/fund-strategy-wallet.js

@@ -0,0 +1,139 @@
+import { WidgetLookupError, WidgetValidationError } from "../errors.js";
+import { isWalletAddress } from "../strategy-lookup.js";
+const WIDGET_TYPE = "fund_strategy_wallet";
+const WIDGET_VERSION = 1;
+/**
+ * The tracking id becomes the top-up's `idempotencyKey`, so it has to be unique
+ * per intent and safe to carry as a key. The charset excludes `:`, which would
+ * otherwise let a digits-then-text id trip OpenClaw's value redaction and reach
+ * the client masked; the length floor keeps a model from minting "1".
+ */
+const TRACKING_ID_RE = /^[A-Za-z0-9._-]{8,128}$/;
+const TRACKING_ID_MAX = 128;
+/** Only a live strategy can take a top-up. */
+const ACTIVE = "ACTIVE";
+/** `strategyName` is nullable on the backend; the id is what always identifies a row. */
+function strategyLabel(match) {
+    return match.name.trim() || match.id;
+}
+function requireFormat(args) {
+    const wallet = String(args.strategy_wallet).trim();
+    const trackingId = String(args.tracking_id).trim();
+    const problems = [];
+    const fields = [];
+    if (!isWalletAddress(wallet)) {
+        fields.push("strategy_wallet");
+        problems.push(`strategy_wallet "${wallet}" is not a wallet address (expected 0x followed by 40 hex characters). ` +
+            "Call strategy_list and pass the strategyWalletAddress of the strategy you mean");
+    }
+    if (!TRACKING_ID_RE.test(trackingId)) {
+        fields.push("tracking_id");
+        problems.push("tracking_id must be 8-128 characters of letters, digits, dot, underscore or hyphen — " +
+            "generate a fresh UUID for this funding request");
+    }
+    if (problems.length > 0) {
+        throw new WidgetValidationError(`show_widget failed for widget_type "${WIDGET_TYPE}": ${problems.join("; ")}.`, WIDGET_TYPE, fields);
+    }
+    return { wallet, trackingId };
+}
+async function resolveStrategy(ctx, wallet) {
+    if (!ctx.strategies) {
+        throw new WidgetLookupError(`show_widget failed for widget_type "${WIDGET_TYPE}": the strategy wallet could not be verified ` +
+            "because this deployment has no Senpi backend configured. Do not retry; handle the request in text.", WIDGET_TYPE);
+    }
+    let match;
+    try {
+        match = await ctx.strategies.findByWallet(wallet);
+    }
+    catch (err) {
+        // The address was never judged. Saying "not yours" here would make the model
+        // swap a correct address for a wrong one.
+        throw new WidgetLookupError(`show_widget failed for widget_type "${WIDGET_TYPE}": strategy wallet ${wallet} could not be verified — ` +
+            "the Senpi backend did not answer. The address may well be correct. Try the same call again.", WIDGET_TYPE, err);
+    }
+    if (!match) {
+        throw new WidgetValidationError(`show_widget failed for widget_type "${WIDGET_TYPE}": ${wallet} is not one of your strategy wallets. ` +
+            "Call strategy_list and pass the strategyWalletAddress of the strategy you mean.", WIDGET_TYPE, ["strategy_wallet"]);
+    }
+    if (match.status.toUpperCase() !== ACTIVE) {
+        // `strategyName` is nullable and the status covers the whole onboarding
+        // lifecycle, not just PAUSED/CLOSED — so neither is quoted raw.
+        throw new WidgetValidationError(`show_widget failed for widget_type "${WIDGET_TYPE}": that wallet belongs to strategy ` +
+            `"${strategyLabel(match)}", whose status is ${match.status.trim() || "unknown"}, not ${ACTIVE}. ` +
+            `Only an ${ACTIVE} strategy can be funded — tell the user to resume or finish setting it up, ` +
+            "or pass a different strategy's wallet.", WIDGET_TYPE, ["strategy_wallet"]);
+    }
+    if (match.id.trim().length === 0) {
+        // The funding API takes a strategy id, never the address, so an id-less row
+        // is unusable even though the address checked out.
+        throw new WidgetLookupError(`show_widget failed for widget_type "${WIDGET_TYPE}": the backend matched the wallet but returned no ` +
+            "strategy id, so the card cannot be funded. Retrying is unlikely to help — tell the user this " +
+            "strategy cannot be funded right now.", WIDGET_TYPE);
+    }
+    return match;
+}
+/**
+ * `fund_strategy_wallet` — a card whose button tops the strategy up from the
+ * user's own Senpi wallet. This is an internal transfer, not a deposit: a
+ * strategy wallet has no deposit address anyone may be shown, because USDC sent
+ * to it directly bypasses accounting and may be unrecoverable.
+ *
+ * The address is validated here rather than at the schema, because "is one of
+ * this user's active strategies" is not something a JSON schema can state. The
+ * payload carries the resolved strategy id: the top-up API keys on the id.
+ */
+export const fundStrategyWalletSpec = {
+    widgetType: WIDGET_TYPE,
+    widgetVersion: WIDGET_VERSION,
+    description: "Show the user a card that funds one of their own strategies from their Senpi wallet. " +
+        "Use it when a strategy has too little balance to trade, or the user asks to fund, top up or add to a strategy. " +
+        "Never state a deposit address for a strategy wallet — funding a strategy is an internal transfer and the card owns it.",
+    fields: [
+        {
+            name: "strategy_wallet",
+            type: "string",
+            required: true,
+            description: "The strategyWalletAddress of one of the user's ACTIVE strategies, from strategy_list. " +
+                "Rejected if it is not one of theirs.",
+            maxLength: 64,
+        },
+        {
+            name: "tracking_id",
+            type: "string",
+            required: true,
+            description: "A fresh UUID you generate for this funding request, 8-128 characters of letters, digits, dot, " +
+                "underscore or hyphen. Never reuse one: it is the idempotency key, and a repeat replays the first top-up.",
+            maxLength: TRACKING_ID_MAX,
+        },
+        {
+            name: "reason",
+            type: "string",
+            required: false,
+            description: 'One plain sentence on why you are showing the card, e.g. "This strategy has no margin left." ' +
+                "Recorded with the call; the card renders its own copy, so this is not displayed to the user.",
+            maxLength: 280,
+        },
+    ],
+    handler: async (args, ctx) => {
+        const { wallet, trackingId } = requireFormat(args);
+        const match = await resolveStrategy(ctx, wallet);
+        return {
+            payload: {
+                widget_type: WIDGET_TYPE,
+                widget_version: WIDGET_VERSION,
+                status: "shown",
+                strategy_id: match.id,
+                // The backend's spelling, not the model's. The web client re-resolves
+                // the strategy from the args (the payload does not survive a reload),
+                // so this is carried for clients that render from the payload.
+                strategy_wallet: match.walletAddress,
+                tracking_id: trackingId,
+            },
+            // No address in here: this text is the agent's to repeat, and a strategy
+            // wallet address repeated in chat reads as a deposit address.
+            text: `Funding card shown for strategy "${strategyLabel(match)}". The user funds it from the card. ` +
+                "Do not show it again in this turn, and never give an address for funding a strategy.",
+        };
+    },
+};
+//# sourceMappingURL=fund-strategy-wallet.js.map

package/dist/widgets/widgets/fund-strategy-wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fund-strategy-wallet.js","sourceRoot":"","sources":["../../../src/widgets/widgets/fund-strategy-wallet.ts"],"names":[],"mappings":"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"}

package/dist/widgets/widgets/fund-user-wallet.d.ts

@@ -0,0 +1,13 @@
+import type { WidgetSpec } from "../types.js";
+/**
+ * `fund_user_wallet` — a card that opens the client's existing deposit modal
+ * for the user's own Senpi (Privy self-custody) wallet.
+ *
+ * The input surface is deliberately empty apart from a context sentence: the
+ * modal resolves the wallet address and the networks from the user's own
+ * session, so no amount, address or wallet id ever travels through the chat.
+ * Nothing is authorized by showing the card, so there is no request id, no TTL
+ * and no lifecycle.
+ */
+export declare const fundUserWalletSpec: WidgetSpec;
+//# sourceMappingURL=fund-user-wallet.d.ts.map

package/dist/widgets/widgets/fund-user-wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fund-user-wallet.d.ts","sourceRoot":"","sources":["../../../src/widgets/widgets/fund-user-wallet.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAiB,UAAU,EAAE,MAAM,aAAa,CAAC;AAoC7D;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAqChC,CAAC"}

package/dist/widgets/widgets/fund-user-wallet.js

@@ -0,0 +1,78 @@
+import { WidgetValidationError } from "../errors.js";
+import { isWalletAddress } from "../strategy-lookup.js";
+const WIDGET_TYPE = "fund_user_wallet";
+/**
+ * An address never belongs on this widget: the deposit modal resolves the
+ * user's own wallet from their session. The call is refused whatever the value
+ * is — the lookup only decides which correction the model is given, and a
+ * lookup that fails still leaves the refusal correct, so it is never a reason
+ * to accept.
+ */
+async function refuseValue(value, ctx) {
+    // Only an actual address can name a strategy, so anything else is refused
+    // without spending an MCP round trip on a value that cannot match.
+    const wallet = typeof value === "string" ? value.trim() : "";
+    let match = null;
+    if (isWalletAddress(wallet)) {
+        try {
+            match = (await ctx.strategies?.findByWallet(wallet)) ?? null;
+        }
+        catch {
+            // Unverified reads as unknown; the "remove the field" correction still holds.
+        }
+    }
+    throw new WidgetValidationError(match
+        ? `show_widget failed for widget_type "${WIDGET_TYPE}": ${wallet} is the wallet of your strategy ` +
+            `"${match.name.trim() || match.id}", not the user's own wallet. Call show_widget again with ` +
+            'widget_type "fund_strategy_wallet" and that address.'
+        : `show_widget failed for widget_type "${WIDGET_TYPE}": it takes no address — the card resolves the ` +
+            "user's own wallet from their session. Remove strategy_wallet and call again. To fund a strategy " +
+            'instead, use widget_type "fund_strategy_wallet".', WIDGET_TYPE, ["strategy_wallet"]);
+}
+/**
+ * `fund_user_wallet` — a card that opens the client's existing deposit modal
+ * for the user's own Senpi (Privy self-custody) wallet.
+ *
+ * The input surface is deliberately empty apart from a context sentence: the
+ * modal resolves the wallet address and the networks from the user's own
+ * session, so no amount, address or wallet id ever travels through the chat.
+ * Nothing is authorized by showing the card, so there is no request id, no TTL
+ * and no lifecycle.
+ */
+export const fundUserWalletSpec = {
+    widgetType: "fund_user_wallet",
+    widgetVersion: 1,
+    description: "Show the user a card that opens Senpi's deposit flow for their own wallet. " +
+        "Use it when the user has no funds, cannot trade for lack of balance, or asks how to add money. " +
+        "The card owns the address, the networks and the deposit copy — never restate them yourself.",
+    fields: [
+        {
+            name: "reason",
+            type: "string",
+            required: false,
+            description: "One plain sentence on why you are showing the card, e.g. \"Your wallet has no balance yet.\" " +
+                "Recorded with the call; the card renders its own copy, so this is not displayed to the user.",
+            maxLength: 280,
+        },
+    ],
+    guardedFields: [
+        {
+            name: "strategy_wallet",
+            description: "Always refused here; guarded so the misrouted call gets a targeted correction.",
+        },
+    ],
+    handler: async (args, ctx) => {
+        if (Object.hasOwn(args, "strategy_wallet"))
+            await refuseValue(args.strategy_wallet, ctx);
+        return {
+            payload: {
+                widget_type: WIDGET_TYPE,
+                widget_version: 1,
+                status: "shown",
+            },
+            text: "Funding card shown. The user can deposit from the card. " +
+                "Do not show it again in this turn; answer follow-up questions in text.",
+        };
+    },
+};
+//# sourceMappingURL=fund-user-wallet.js.map

package/dist/widgets/widgets/fund-user-wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fund-user-wallet.js","sourceRoot":"","sources":["../../../src/widgets/widgets/fund-user-wallet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,MAAM,WAAW,GAAG,kBAAkB,CAAC;AAEvC;;;;;;GAMG;AACH,KAAK,UAAU,WAAW,CAAC,KAAc,EAAE,GAAkB;IAC3D,0EAA0E;IAC1E,mEAAmE;IACnE,MAAM,MAAM,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,8EAA8E;QAChF,CAAC;IACH,CAAC;IACD,MAAM,IAAI,qBAAqB,CAC7B,KAAK;QACH,CAAC,CAAC,uCAAuC,WAAW,MAAM,MAAM,kCAAkC;YAChG,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,4DAA4D;YAC7F,sDAAsD;QACxD,CAAC,CAAC,uCAAuC,WAAW,iDAAiD;YACnG,kGAAkG;YAClG,kDAAkD,EACtD,WAAW,EACX,CAAC,iBAAiB,CAAC,CACpB,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAe;IAC5C,UAAU,EAAE,kBAAkB;IAC9B,aAAa,EAAE,CAAC;IAChB,WAAW,EACT,6EAA6E;QAC7E,iGAAiG;QACjG,6FAA6F;IAC/F,MAAM,EAAE;QACN;YACE,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,KAAK;YACf,WAAW,EACT,+FAA+F;gBAC/F,8FAA8F;YAChG,SAAS,EAAE,GAAG;SACf;KACF;IACD,aAAa,EAAE;QACb;YACE,IAAI,EAAE,iBAAiB;YACvB,WAAW,EAAE,gFAAgF;SAC9F;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC3B,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,iBAAiB,CAAC;YAAE,MAAM,WAAW,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;QACzF,OAAO;YACL,OAAO,EAAE;gBACP,WAAW,EAAE,WAAW;gBACxB,cAAc,EAAE,CAAC;gBACjB,MAAM,EAAE,OAAO;aAChB;YACD,IAAI,EACF,0DAA0D;gBAC1D,wEAAwE;SAC3E,CAAC;IACJ,CAAC;CACF,CAAC"}

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "runtime",
   "name": "Senpi Runtime",
   "description": "Senpi runtime plugin for OpenClaw. Orchestrates scanners, LLM-based trade decisions, and a DSL trailing stop-loss exit engine.",
-  "version": "3.0.79",
+  "version": "3.0.81",
   "commandAliases": [
     {
       "name": "senpi"
@@ -14,6 +14,14 @@
       "senpi"
     ]
   },
+  "contracts": {
+    "tools": [
+      "show_widget"
+    ]
+  },
+  "skills": [
+    "skills/senpi-widgets"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -156,6 +164,13 @@
           }
         }
       },
+      "widgets": {
+        "type": "object",
+        "description": "Per-widget-type on/off switch for the show_widget agent tool, keyed by widget_type (e.g. { \"fund_user_wallet\": false }). Absent or true enables a widget type; only an explicit false disables it. Adding a widget type does not change this schema. With every type disabled the tool is not registered.",
+        "additionalProperties": {
+          "type": "boolean"
+        }
+      },
       "api": {
         "type": "object",
         "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senpi/runtime",
-  "version": "3.0.79",
+  "version": "3.0.81",
   "description": "Senpi runtime plugin for OpenClaw",
   "type": "module",
   "main": "dist/index.js",
@@ -8,7 +8,8 @@
   "files": [
     "dist/",
     "openclaw.plugin.json",
-    "examples/"
+    "examples/",
+    "skills/senpi-widgets/"
   ],
   "scripts": {
     "setup:hooks": "sh -c 'git rev-parse --git-dir >/dev/null 2>&1 && git config core.hooksPath .githooks || true'",

package/skills/senpi-widgets/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: senpi-widgets
+description: "Use the show_widget tool to render a native Senpi card in the chat instead of describing a flow in text. Use when the user has no funds, cannot open a trade for lack of balance, asks how to deposit, add money, fund their wallet, fund or top up a strategy — and whenever you are about to explain a Senpi flow that the app already has a screen for. Triggers on: fund wallet, add funds, deposit, no balance, insufficient balance, how do I put money in, top up, fund my strategy, strategy has no margin, show widget, show card, funding card."
+---
+
+# Senpi widgets
+
+The Senpi web and mobile clients render cards from the `show_widget` tool call.
+Calling the tool puts a real, working card in the conversation. It is not a
+picture and not a description — the card's own button drives the product flow.
+
+## The one tool
+
+```
+show_widget(widget_type, <fields for that type>)
+```
+
+`widget_type` is an enum. Pass only the fields the tool description lists for
+that type; anything else is rejected.
+
+## Two wallets, two widgets
+
+There are two different wallets, and they are funded in two different ways.
+
+| | User wallet | Strategy wallet |
+|---|---|---|
+| Whose | The user's own Senpi (self-custody) wallet | One wallet per strategy |
+| How it is funded | External deposit — USDC sent to an address | Internal transfer from the user's own wallet |
+| Widget | `fund_user_wallet` | `fund_strategy_wallet` |
+
+Pick by the wallet the money is going *into*. If the user has no money in Senpi
+at all, that is `fund_user_wallet` — a strategy cannot be funded from an empty
+wallet.
+
+## Widget types
+
+### `fund_user_wallet`
+
+The card explains that Senpi wallets are self-custody and its button opens the
+deposit screen for the user's own wallet.
+
+Use it when:
+
+- the user has no balance, or too little balance to open the trade they asked for
+- the user asks how to deposit, add funds, or top up
+- you are about to explain the deposit flow in prose
+
+Fields:
+
+| Field | Required | Notes |
+|---|---|---|
+| `widget_type` | yes | `"fund_user_wallet"` |
+| `reason` | no | One plain sentence on why you are showing the card. Not displayed — the card owns its copy. Omit it rather than passing an empty string. |
+
+Worked example — the user says *"open a 5x long on HYPE"* and the account has
+no balance:
+
+```
+show_widget({
+  widget_type: "fund_user_wallet",
+  reason: "Your wallet needs a balance before this trade can open."
+})
+```
+
+Then answer in prose, for example: "Add funds from the card above and I'll open
+the 5x HYPE long straight after."
+
+Do not pass an address to this widget. The card resolves the user's own wallet
+from their session, and an address is rejected.
+
+### `fund_strategy_wallet`
+
+The card's button moves money from the user's own Senpi wallet into one of their
+strategies. It is an internal transfer, so no address is ever shown or needed by
+the user.
+
+Use it when:
+
+- a strategy is out of margin, or too small to take the trade the user wants
+- the user asks to fund, top up or add to a named strategy
+- you are about to explain how to move money into a strategy in prose
+
+Fields:
+
+| Field | Required | Notes |
+|---|---|---|
+| `widget_type` | yes | `"fund_strategy_wallet"` |
+| `strategy_wallet` | yes | The `strategyWalletAddress` of one of the user's **ACTIVE** strategies. Get it from `strategy_list`; never from memory or from the user's typing. |
+| `tracking_id` | yes | A fresh UUID **you** generate for this one funding request. 8-128 characters, letters/digits/`.`/`_`/`-` only. |
+| `reason` | no | One plain sentence on why you are showing the card. Not displayed. |
+
+Worked example — the user says *"put another $200 into my HYPE momentum
+strategy"*. First call `strategy_list` to get that strategy's
+`strategyWalletAddress`, then:
+
+```
+show_widget({
+  widget_type: "fund_strategy_wallet",
+  strategy_wallet: "0x1111111111111111111111111111111111111111",
+  tracking_id: "0d2f4a1c-3b7e-4f0a-9c11-6ad2e5b8c701",
+  reason: "The user wants to add $200 to this strategy."
+})
+```
+
+The user chooses the amount on the card. Do not put an amount in the call.
+
+## House rules
+
+**Show a card once per turn.** After the tool returns, the card is on screen.
+Answer every follow-up in text. Calling `show_widget` again in the same turn
+stacks duplicate cards in the transcript.
+
+**Never write a deposit address, QR code or network list in text.** The card and
+the deposit screen own those. A pasted address in chat is a phishing surface and
+can go stale.
+
+**Never give a deposit address for a strategy wallet — there is no such thing.**
+USDC sent straight to a strategy wallet skips Senpi's accounting, corrupts the
+strategy's PnL and may be unrecoverable. Funding a strategy is only ever the
+`fund_strategy_wallet` card. If a user asks where to send funds for a strategy,
+tell them it is an internal transfer and show the card.
+
+**Generate a new `tracking_id` for every `fund_strategy_wallet` call.** It is the
+idempotency key for the top-up. Reusing one from an earlier card replays that
+first top-up: the amount is whatever the user typed the first time, and nothing
+new is transferred. Never copy a tracking id out of the conversation.
+
+**Correct numbers when you talk about deposits in prose:** for a deposit into the
+user's own wallet the minimum is $10, and most traders start with $100-250. Do
+not invent other figures — the deposit card's own copy uses these. These are
+deposit figures; do not quote them for a strategy top-up.
+
+**Do not claim the deposit landed.** The tool result only says the card was
+shown. Wait for the user to say so, or for the client's own "I've funded my
+wallet" message, before acting as though there is a balance.
+
+**Do not ask the user to confirm before showing a card.** Showing it costs
+nothing and authorizes nothing.
+
+## When the tool returns an error
+
+The error names the exact fields that were wrong: missing, invalid, or
+unexpected. Fix those fields and call `show_widget` again. Keep the same
+`widget_type` unless the error itself names a different one. Dropping the call
+and describing the flow in prose instead is the wrong recovery.
+
+- `unexpected fields: amount` — that widget takes no amount. Remove the field.
+- `invalid fields: reason (must be a non-empty string; omit it instead)` — drop
+  `reason` entirely, or pass a real sentence.
+- `unknown widget_type "..."` — the message lists the available types. Pick one
+  of those; do not invent a name.
+- `... is not one of your strategy wallets` — call `strategy_list` and use a
+  `strategyWalletAddress` from it. Do not retry the same address.
+- `whose status is PAUSED, not ACTIVE` — only a live strategy can be funded. Tell
+  the user, or pass a different strategy's wallet.
+- `it takes no address` on `fund_user_wallet` — drop `strategy_wallet`, or switch
+  to `fund_strategy_wallet` if the money is meant for a strategy.
+- `tracking_id must be 8-128 characters ...` — generate a fresh UUID and call
+  again with everything else unchanged.
+
+**"could not be verified — the Senpi backend did not answer"** is different from
+every error above: nothing was found wrong with your call. Retry the *same* call,
+tracking id included — no card rendered, so that id is still unused. Do not swap
+the address, and do not tell the user their strategy does not exist.
+
+If a widget type is reported as not enabled on this deployment, do not retry it.
+Handle the request in prose instead.