@senpi/runtime 3.0.148 → 3.0.150

package/dist/widgets/index.d.ts

@@ -1,10 +1,11 @@
 import type { WidgetLogger } from "./types.js";
+import type { QuantRunReader } from "../quant/types.js";
 export { WIDGET_SPECS, buildWidgetRegistry } from "./registry.js";
 export type { WidgetRegistry, WidgetsConfig } from "./registry.js";
 export { WidgetValidationError } from "./errors.js";
 export { SHOW_WIDGET_TOOL_NAME, buildShowWidgetDescription, buildShowWidgetParameters, createShowWidgetTool, } from "./tool.js";
 export type { ShowWidgetTool, ShowWidgetToolResult } from "./tool.js";
-export type { RegisteredWidget, WidgetPayload, WidgetResult, WidgetSpec } from "./types.js";
+export type { RegisteredWidget, WidgetHandlerContext, WidgetPayload, WidgetResult, WidgetSpec } from "./types.js";
 /** The slice of the OpenClaw plugin API this module needs. */
 export interface WidgetToolPluginApi {
     registerTool(tool: (ctx: {
@@ -19,6 +20,12 @@ export interface RegisterShowWidgetToolOptions {
     /** The plugin config `widgets` block: `{ "<widget_type>": boolean }`. */
     widgetsConfig?: unknown;
     logger?: WidgetLogger;
+    /**
+     * The quant desk's run registry (read side), for `quant_desk_recommendations`. Absent when the
+     * desk failed to build: the tool still registers, and that type answers with a teaching error
+     * telling the model to relay the desk's next steps as text.
+     */
+    quantRuns?: QuantRunReader;
 }
 /**
  * Register `show_widget` as a plugin tool factory.

package/dist/widgets/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/widgets/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5F,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,YAAY,CACV,IAAI,EAAE,CAAC,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,EAC9C,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9C,IAAI,CAAC;CACT;AAED,MAAM,WAAW,6BAA6B;IAC5C,GAAG,EAAE,mBAAmB,CAAC;IACzB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CA0BtF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/widgets/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAElH,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,YAAY,CACV,IAAI,EAAE,CAAC,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,EAC9C,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9C,IAAI,CAAC;CACT;AAED,MAAM,WAAW,6BAA6B;IAC5C,GAAG,EAAE,mBAAmB,CAAC;IACzB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CA2BtF"}

package/dist/widgets/index.js

@@ -26,6 +26,7 @@ export function registerShowWidgetTool(options) {
         registry,
         logger,
         sessionId: ctx?.sessionId,
+        handlerContext: options.quantRuns ? { quantRuns: options.quantRuns } : {},
     }), { names: [SHOW_WIDGET_TOOL_NAME] });
     logger?.info(`[senpi-widgets] ${SHOW_WIDGET_TOOL_NAME} registered | widget_types=${enabled.join(",")}`);
     return true;

package/dist/widgets/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/widgets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAmBnB;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAsC;IAC3E,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAChC,2EAA2E;IAC3E,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAC;IACxC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,EAAE,IAAI,CACV,6FAA6F,CAC9F,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IACpC,GAAG,CAAC,YAAY,CACd,CAAC,GAA2B,EAAE,EAAE,CAC9B,oBAAoB,CAAC;QACnB,QAAQ;QACR,MAAM;QACN,SAAS,EAAE,GAAG,EAAE,SAAS;KAC1B,CAAC,EACJ,EAAE,KAAK,EAAE,CAAC,qBAAqB,CAAC,EAAE,CACnC,CAAC;IACF,MAAM,EAAE,IAAI,CACV,mBAAmB,qBAAqB,8BAA8B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAC1F,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/widgets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAyBnB;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAsC;IAC3E,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAChC,2EAA2E;IAC3E,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAC;IACxC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,EAAE,IAAI,CACV,6FAA6F,CAC9F,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;IACD,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IACpC,GAAG,CAAC,YAAY,CACd,CAAC,GAA2B,EAAE,EAAE,CAC9B,oBAAoB,CAAC;QACnB,QAAQ;QACR,MAAM;QACN,SAAS,EAAE,GAAG,EAAE,SAAS;QACzB,cAAc,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE;KAC1E,CAAC,EACJ,EAAE,KAAK,EAAE,CAAC,qBAAqB,CAAC,EAAE,CACnC,CAAC;IACF,MAAM,EAAE,IAAI,CACV,mBAAmB,qBAAqB,8BAA8B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAC1F,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/widgets/registry.d.ts

@@ -20,5 +20,13 @@ export interface WidgetRegistry {
     get(widgetType: string): RegisteredWidget | undefined;
     enabledTypes(): string[];
 }
+/**
+ * Resolve the spec list against plugin config.
+ *
+ * @param config The plugin config `widgets` block (see {@link WidgetsConfig}).
+ * @param specs The spec list; defaults to {@link WIDGET_SPECS}. Injected by tests.
+ * @throws Error when two specs share a `widget_type`, when two specs declare the same extra
+ *   parameter name, or when a spec declares `widget_type` as an extra parameter.
+ */
 export declare function buildWidgetRegistry(config?: unknown, specs?: readonly WidgetSpec[]): WidgetRegistry;
 //# sourceMappingURL=registry.d.ts.map

package/dist/widgets/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/widgets/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG/D;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAyB,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,GAAG,IAAI,SAAS,gBAAgB,EAAE,CAAC;IACnC,yEAAyE;IACzE,OAAO,IAAI,SAAS,gBAAgB,EAAE,CAAC;IACvC,+CAA+C;IAC/C,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACtD,YAAY,IAAI,MAAM,EAAE,CAAC;CAC1B;AAED,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,OAAO,EAChB,KAAK,GAAE,SAAS,UAAU,EAAiB,GAC1C,cAAc,CAyBhB"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/widgets/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI/D;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAuD,CAAC;AAEtG;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,GAAG,IAAI,SAAS,gBAAgB,EAAE,CAAC;IACnC,yEAAyE;IACzE,OAAO,IAAI,SAAS,gBAAgB,EAAE,CAAC;IACvC,+CAA+C;IAC/C,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACtD,YAAY,IAAI,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,OAAO,EAChB,KAAK,GAAE,SAAS,UAAU,EAAiB,GAC1C,cAAc,CAyChB"}

package/dist/widgets/registry.js

@@ -1,11 +1,36 @@
 import { fundUserWalletSpec } from "./widgets/fund-user-wallet.js";
+import { quantDeskRecommendationsSpec } from "./widgets/quant-desk-recommendations.js";
 /**
  * Every widget type this plugin can render. Adding one here adds it to the
  * `show_widget` enum, to the generated tool description, and to the config
  * gate — the tool name and the manifest are untouched.
  */
-export const WIDGET_SPECS = [fundUserWalletSpec];
+export const WIDGET_SPECS = [fundUserWalletSpec, quantDeskRecommendationsSpec];
+/**
+ * Resolve the spec list against plugin config.
+ *
+ * @param config The plugin config `widgets` block (see {@link WidgetsConfig}).
+ * @param specs The spec list; defaults to {@link WIDGET_SPECS}. Injected by tests.
+ * @throws Error when two specs share a `widget_type`, when two specs declare the same extra
+ *   parameter name, or when a spec declares `widget_type` as an extra parameter.
+ */
 export function buildWidgetRegistry(config, specs = WIDGET_SPECS) {
+    // Parameters are one flat object shared by every type, so each extra name has exactly one owner.
+    // Checked over ALL specs, not just enabled ones: a clash hidden while one type is disabled would
+    // surface the day config flips it on.
+    const paramOwner = new Map();
+    for (const spec of specs) {
+        for (const key of Object.keys(spec.extraParameters ?? {})) {
+            if (key === "widget_type") {
+                throw new Error(`show_widget: ${spec.widgetType} declares "widget_type" as an extra parameter; it is the shared discriminator`);
+            }
+            const owner = paramOwner.get(key);
+            if (owner) {
+                throw new Error(`show_widget: parameter "${key}" is declared by both ${owner} and ${spec.widgetType}; each name has one owner`);
+            }
+            paramOwner.set(key, spec.widgetType);
+        }
+    }
     const gate = config && typeof config === "object" && !Array.isArray(config)
         ? config
         : undefined;

package/dist/widgets/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/widgets/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAA0B,CAAC,kBAAkB,CAAC,CAAC;AAmBxE,MAAM,UAAU,mBAAmB,CACjC,MAAgB,EAChB,QAA+B,YAAY;IAE3C,MAAM,IAAI,GACR,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAC5D,CAAC,CAAE,MAAkC;QACrC,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,OAAO,GAAuB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvD,GAAG,IAAI;QACP,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,KAAK;KAC3C,CAAC,CAAC,CAAC;IACJ,MAAM,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IACnD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,4EAA4E;QAC5E,sEAAsE;QACtE,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,sDAAsD,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO;QAClB,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO;QACtB,GAAG,EAAE,CAAC,UAAkB,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC;QACnD,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;KACrD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/widgets/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,4BAA4B,EAAE,MAAM,yCAAyC,CAAC;AAEvF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAA0B,CAAC,kBAAkB,EAAE,4BAA4B,CAAC,CAAC;AAmBtG;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAgB,EAChB,QAA+B,YAAY;IAE3C,iGAAiG;IACjG,iGAAiG;IACjG,sCAAsC;IACtC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE,CAAC;YAC1D,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,CAAC,UAAU,+EAA+E,CAAC,CAAC;YAClI,CAAC;YACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,yBAAyB,KAAK,QAAQ,IAAI,CAAC,UAAU,2BAA2B,CAAC,CAAC;YAClI,CAAC;YACD,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GACR,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAC5D,CAAC,CAAE,MAAkC;QACrC,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,OAAO,GAAuB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvD,GAAG,IAAI;QACP,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,KAAK;KAC3C,CAAC,CAAC,CAAC;IACJ,MAAM,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IACnD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,4EAA4E;QAC5E,sEAAsE;QACtE,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,sDAAsD,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO;QAClB,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO;QACtB,GAAG,EAAE,CAAC,UAAkB,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC;QACnD,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;KACrD,CAAC;AACJ,CAAC"}

package/dist/widgets/tool.d.ts

@@ -1,5 +1,5 @@
 import type { WidgetRegistry } from "./registry.js";
-import type { WidgetLogger, WidgetPayload } from "./types.js";
+import type { WidgetHandlerContext, WidgetLogger, WidgetPayload } from "./types.js";
 /**
  * The plugin's single agent tool. The name is static — new widget types are
  * new `widget_type` enum values, never new tools — so it is declared once in
@@ -24,25 +24,35 @@ export interface CreateShowWidgetToolOptions {
     logger?: WidgetLogger;
     /** Ephemeral session id from the plugin tool factory context; logged only. */
     sessionId?: string;
+    /** Collaborators handed to every handler (e.g. the quant run reader). Defaults to `{}`. */
+    handlerContext?: WidgetHandlerContext;
 }
 /**
  * Tool description, generated from the enabled specs. Nothing else teaches the
  * model about these cards, so this text carries the condition that should make
  * it call the tool, not just the shape of the call.
+ *
+ * The shared header claims nothing that is true of only one type: how a card is
+ * acted on (`card:`) and which fields it takes (`fields:`) are stated per type,
+ * because not every card has a button and not every type takes widget_type only.
  */
 export declare function buildShowWidgetDescription(registry: WidgetRegistry): string;
 /**
  * Declared JSON schema: one flat object, no unions at any depth.
  *
  * OpenClaw flattens top-level unions, Gemini flattens nested ones, and OpenAI
- * strict mode rejects a schema containing one anywhere. `widget_type` is the
- * only parameter, and it is required.
+ * strict mode rejects a schema containing one anywhere. So there is no per-type
+ * branch: `widget_type` is the one required property, and every enabled spec's
+ * `extraParameters` are merged in beside it as optional properties. Each such
+ * property belongs to one type (the registry refuses a shared name) and is
+ * validated by that type's handler; `rejectExtraFields` refuses one sent with
+ * any other type.
  */
 export declare function buildShowWidgetParameters(registry: WidgetRegistry): Record<string, unknown>;
 /**
  * Build the `show_widget` tool for one agent turn. `sessionId` comes from the
  * plugin tool factory context and is used for logging only — nothing about the
- * result depends on it.
+ * result depends on it. `handlerContext` is passed to every handler as-is.
  */
 export declare function createShowWidgetTool(options: CreateShowWidgetToolOptions): ShowWidgetTool;
 //# sourceMappingURL=tool.d.ts.map

package/dist/widgets/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/widgets/tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAoB,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAInD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAsB3E;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiB3F;AAmED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,cAAc,CAkCzF"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/widgets/tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAoB,oBAAoB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAInD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAwB3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAc3F;AAuED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,cAAc,CAmCzF"}

package/dist/widgets/tool.js

@@ -10,6 +10,10 @@ const WIDGET_TYPE_PARAM = "widget_type";
  * Tool description, generated from the enabled specs. Nothing else teaches the
  * model about these cards, so this text carries the condition that should make
  * it call the tool, not just the shape of the call.
+ *
+ * The shared header claims nothing that is true of only one type: how a card is
+ * acted on (`card:`) and which fields it takes (`fields:`) are stated per type,
+ * because not every card has a button and not every type takes widget_type only.
  */
 export function buildShowWidgetDescription(registry) {
     const widgets = registry.enabled();
@@ -17,16 +21,18 @@ export function buildShowWidgetDescription(registry) {
         return "Render a Senpi UI card in the user's chat.\n\nNo widget types are enabled on this deployment.";
     }
     const lines = [
-        "Render a Senpi UI card in the user's chat. The card is live UI: its button runs the flow, so showing it is how the user acts.",
+        "Render a Senpi UI card in the user's chat.",
         "",
         "Call it yourself as part of your answer — the user does not have to ask for a card. Each type below states when to call it; the examples illustrate that rule, they are not a checklist to match.",
         "",
-        `Pass ${WIDGET_TYPE_PARAM} and nothing else.`,
+        `Pass ${WIDGET_TYPE_PARAM} plus the fields listed for that type, and nothing else.`,
         "",
         "Widget types:",
     ];
     for (const widget of widgets) {
         lines.push(`- ${widget.widgetType}: ${widget.description}`);
+        lines.push(`  card: ${widget.affordance}`);
+        lines.push(`  fields: ${widget.fields ?? `none — ${WIDGET_TYPE_PARAM} only`}`);
         lines.push(`  when: ${widget.callWhen}`);
         lines.push(`  not this card: ${widget.notFor}`);
         lines.push("  for example:");
@@ -38,26 +44,28 @@ export function buildShowWidgetDescription(registry) {
  * Declared JSON schema: one flat object, no unions at any depth.
  *
  * OpenClaw flattens top-level unions, Gemini flattens nested ones, and OpenAI
- * strict mode rejects a schema containing one anywhere. `widget_type` is the
- * only parameter, and it is required.
+ * strict mode rejects a schema containing one anywhere. So there is no per-type
+ * branch: `widget_type` is the one required property, and every enabled spec's
+ * `extraParameters` are merged in beside it as optional properties. Each such
+ * property belongs to one type (the registry refuses a shared name) and is
+ * validated by that type's handler; `rejectExtraFields` refuses one sent with
+ * any other type.
  */
 export function buildShowWidgetParameters(registry) {
     const widgets = registry.enabled();
     if (widgets.length === 0) {
         throw new Error("show_widget has no enabled widget types; do not register the tool");
     }
-    return {
-        type: "object",
-        properties: {
-            [WIDGET_TYPE_PARAM]: {
-                type: "string",
-                enum: widgets.map((w) => w.widgetType),
-                description: "Which card to render.",
-            },
+    const properties = {
+        [WIDGET_TYPE_PARAM]: {
+            type: "string",
+            enum: widgets.map((w) => w.widgetType),
+            description: "Which card to render.",
         },
-        required: [WIDGET_TYPE_PARAM],
-        additionalProperties: false,
     };
+    for (const widget of widgets)
+        Object.assign(properties, widget.extraParameters ?? {});
+    return { type: "object", properties, required: [WIDGET_TYPE_PARAM], additionalProperties: false };
 }
 function availableTypesSentence(registry) {
     const types = registry.enabledTypes();
@@ -90,24 +98,28 @@ function resolveWidget(registry, args) {
     return widget;
 }
 /**
- * The tool takes one argument, so any other key is a field the model invented.
- * Every one is named in a single message: the correction is the same for all of
- * them, and the model can apply it in one retry.
+ * A type takes `widget_type` plus its own `extraParameters`, so any other key is
+ * a field the model invented — or one that belongs to another type, which the
+ * merged schema cannot refuse on its own. Every one is named in a single
+ * message, with the fields this type does take: the correction is the same for
+ * all of them, and the model can apply it in one retry.
  */
 function rejectExtraFields(widget, args) {
-    const unexpected = Object.keys(args).filter((key) => key !== WIDGET_TYPE_PARAM);
+    const allowed = [WIDGET_TYPE_PARAM, ...Object.keys(widget.extraParameters ?? {})];
+    const unexpected = Object.keys(args).filter((key) => !allowed.includes(key));
     if (unexpected.length === 0)
         return;
+    const takes = allowed.length === 1 ? `${WIDGET_TYPE_PARAM} only` : `${allowed.join(", ")} for ${widget.widgetType}`;
     throw new WidgetValidationError(`show_widget failed for ${WIDGET_TYPE_PARAM} "${widget.widgetType}": unexpected fields: ` +
-        `${unexpected.join(", ")}. show_widget takes ${WIDGET_TYPE_PARAM} only — drop them and call it again.`, widget.widgetType, unexpected);
+        `${unexpected.join(", ")}. show_widget takes ${takes} — drop them and call it again.`, widget.widgetType, unexpected);
 }
 /**
  * Build the `show_widget` tool for one agent turn. `sessionId` comes from the
  * plugin tool factory context and is used for logging only — nothing about the
- * result depends on it.
+ * result depends on it. `handlerContext` is passed to every handler as-is.
  */
 export function createShowWidgetTool(options) {
-    const { registry, logger, sessionId } = options;
+    const { registry, logger, sessionId, handlerContext } = options;
     const session = sessionId ?? "(unknown)";
     return {
         name: SHOW_WIDGET_TOOL_NAME,
@@ -118,8 +130,9 @@ export function createShowWidgetTool(options) {
                 const args = toArgs(params);
                 const widget = resolveWidget(registry, args);
                 rejectExtraFields(widget, args);
-                const result = await widget.handler();
-                logger?.info(`[senpi-widgets] widget shown | widget_type=${widget.widgetType} widget_version=${widget.widgetVersion} session=${session}`);
+                const result = await widget.handler(args, handlerContext ?? {});
+                logger?.info(`[senpi-widgets] widget shown | widget_type=${widget.widgetType} widget_version=${widget.widgetVersion}` +
+                    `${typeof args.run_id === "string" ? ` run_id=${args.run_id}` : ""} session=${session}`);
                 return {
                     content: [{ type: "text", text: result.text }],
                     details: result.payload,

package/dist/widgets/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/widgets/tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAEnD,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAqBxC;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAwB;IACjE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC;IACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,+FAA+F,CAAC;IACzG,CAAC;IACD,MAAM,KAAK,GAAG;QACZ,+HAA+H;QAC/H,EAAE;QACF,mMAAmM;QACnM,EAAE;QACF,QAAQ,iBAAiB,oBAAoB;QAC7C,EAAE;QACF,eAAe;KAChB,CAAC;IACF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,oBAAoB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAwB;IAChE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC;IACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,CAAC,iBAAiB,CAAC,EAAE;gBACnB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;gBACtC,WAAW,EAAE,uBAAuB;aACrC;SACF;QACD,QAAQ,EAAE,CAAC,iBAAiB,CAAC;QAC7B,oBAAoB,EAAE,KAAK;KAC5B,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAAC,QAAwB;IACtD,MAAM,KAAK,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAC;IACtC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;QACvB,CAAC,CAAC,gCAAgC;QAClC,CAAC,CAAC,2BAA2B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACrD,CAAC;AAED,iFAAiF;AACjF,SAAS,MAAM,CAAC,MAAe;IAC7B,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACnE,CAAC,CAAE,MAAkC;QACrC,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,SAAS,aAAa,CAAC,QAAwB,EAAE,IAA6B;IAC5E,MAAM,GAAG,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACtC,MAAM,IAAI,qBAAqB,CAC7B,wBAAwB,iBAAiB,kBAAkB,SAAS,EAAE,EACtE,QAAQ,EACR,CAAC,iBAAiB,CAAC,CACpB,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,qBAAqB,CAC7B,wBAAwB,iBAAiB,uBAAuB,SAAS,EAAE,EAC3E,QAAQ,EACR,CAAC,iBAAiB,CAAC,CACpB,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,qBAAqB,CAC7B,+BAA+B,iBAAiB,KAAK,GAAG,MAAM,SAAS,EAAE,EACzE,GAAG,EACH,CAAC,iBAAiB,CAAC,CACpB,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,qBAAqB,CAC7B,uBAAuB,iBAAiB,KAAK,GAAG,wCAAwC,SAAS,EAAE,EACnG,GAAG,EACH,CAAC,iBAAiB,CAAC,CACpB,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,MAAwB,EAAE,IAA6B;IAChF,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,iBAAiB,CAAC,CAAC;IAChF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACpC,MAAM,IAAI,qBAAqB,CAC7B,0BAA0B,iBAAiB,KAAK,MAAM,CAAC,UAAU,wBAAwB;QACvF,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,uBAAuB,iBAAiB,sCAAsC,EACxG,MAAM,CAAC,UAAU,EACjB,UAAU,CACX,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAoC;IACvE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAChD,MAAM,OAAO,GAAG,SAAS,IAAI,WAAW,CAAC;IACzC,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EAAE,0BAA0B,CAAC,QAAQ,CAAC;QACjD,UAAU,EAAE,yBAAyB,CAAC,QAAQ,CAAC;QAC/C,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,MAAe;YAChD,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC5B,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;gBAC7C,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAChC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;gBACtC,MAAM,EAAE,IAAI,CACV,8CAA8C,MAAM,CAAC,UAAU,mBAAmB,MAAM,CAAC,aAAa,YAAY,OAAO,EAAE,CAC5H,CAAC;gBACF,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;oBAC9C,OAAO,EAAE,MAAM,CAAC,OAAO;iBACxB,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;oBACzC,MAAM,EAAE,IAAI,CACV,mDAAmD,GAAG,CAAC,UAAU,WAAW,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,OAAO,MAAM,GAAG,CAAC,OAAO,EAAE,CACvI,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,MAAM,EAAE,KAAK,EAAE,CACb,+CAA+C,OAAO,MAAM,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC/G,CAAC;gBACJ,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/widgets/tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAEnD,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAuBxC;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAwB;IACjE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC;IACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,+FAA+F,CAAC;IACzG,CAAC;IACD,MAAM,KAAK,GAAG;QACZ,4CAA4C;QAC5C,EAAE;QACF,mMAAmM;QACnM,EAAE;QACF,QAAQ,iBAAiB,0DAA0D;QACnF,EAAE;QACF,eAAe;KAChB,CAAC;IACF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,MAAM,IAAI,UAAU,iBAAiB,OAAO,EAAE,CAAC,CAAC;QAC/E,KAAK,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,oBAAoB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAwB;IAChE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC;IACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,UAAU,GAA4B;QAC1C,CAAC,iBAAiB,CAAC,EAAE;YACnB,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;YACtC,WAAW,EAAE,uBAAuB;SACrC;KACF,CAAC;IACF,KAAK,MAAM,MAAM,IAAI,OAAO;QAAE,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IACtF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,iBAAiB,CAAC,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC;AACpG,CAAC;AAED,SAAS,sBAAsB,CAAC,QAAwB;IACtD,MAAM,KAAK,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAC;IACtC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;QACvB,CAAC,CAAC,gCAAgC;QAClC,CAAC,CAAC,2BAA2B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACrD,CAAC;AAED,iFAAiF;AACjF,SAAS,MAAM,CAAC,MAAe;IAC7B,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACnE,CAAC,CAAE,MAAkC;QACrC,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,SAAS,aAAa,CAAC,QAAwB,EAAE,IAA6B;IAC5E,MAAM,GAAG,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACtC,MAAM,IAAI,qBAAqB,CAC7B,wBAAwB,iBAAiB,kBAAkB,SAAS,EAAE,EACtE,QAAQ,EACR,CAAC,iBAAiB,CAAC,CACpB,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,qBAAqB,CAC7B,wBAAwB,iBAAiB,uBAAuB,SAAS,EAAE,EAC3E,QAAQ,EACR,CAAC,iBAAiB,CAAC,CACpB,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,qBAAqB,CAC7B,+BAA+B,iBAAiB,KAAK,GAAG,MAAM,SAAS,EAAE,EACzE,GAAG,EACH,CAAC,iBAAiB,CAAC,CACpB,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,qBAAqB,CAC7B,uBAAuB,iBAAiB,KAAK,GAAG,wCAAwC,SAAS,EAAE,EACnG,GAAG,EACH,CAAC,iBAAiB,CAAC,CACpB,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,MAAwB,EAAE,IAA6B;IAChF,MAAM,OAAO,GAAG,CAAC,iBAAiB,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,CAAC;IAClF,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,iBAAiB,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,MAAM,CAAC,UAAU,EAAE,CAAC;IACpH,MAAM,IAAI,qBAAqB,CAC7B,0BAA0B,iBAAiB,KAAK,MAAM,CAAC,UAAU,wBAAwB;QACvF,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,uBAAuB,KAAK,iCAAiC,EACvF,MAAM,CAAC,UAAU,EACjB,UAAU,CACX,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAoC;IACvE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;IAChE,MAAM,OAAO,GAAG,SAAS,IAAI,WAAW,CAAC;IACzC,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EAAE,0BAA0B,CAAC,QAAQ,CAAC;QACjD,UAAU,EAAE,yBAAyB,CAAC,QAAQ,CAAC;QAC/C,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,MAAe;YAChD,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC5B,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;gBAC7C,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAChC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,cAAc,IAAI,EAAE,CAAC,CAAC;gBAChE,MAAM,EAAE,IAAI,CACV,8CAA8C,MAAM,CAAC,UAAU,mBAAmB,MAAM,CAAC,aAAa,EAAE;oBACtG,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,OAAO,EAAE,CAC1F,CAAC;gBACF,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;oBAC9C,OAAO,EAAE,MAAM,CAAC,OAAO;iBACxB,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;oBACzC,MAAM,EAAE,IAAI,CACV,mDAAmD,GAAG,CAAC,UAAU,WAAW,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,OAAO,MAAM,GAAG,CAAC,OAAO,EAAE,CACvI,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,MAAM,EAAE,KAAK,EAAE,CACb,+CAA+C,OAAO,MAAM,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC/G,CAAC;gBACJ,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/widgets/turn-cap.d.ts

@@ -0,0 +1,33 @@
+/** How long a run's entry is kept after its last touch. */
+export declare const TURN_CAP_TTL_MS: number;
+/** The reason the model reads on a blocked call. */
+export declare const TURN_CAP_BLOCK_REASON = "[E_WIDGET_TURN_CAP] recommendation cards were already shown in this answer; fold anything else into text.";
+/** The cap's two hook bodies, exposed for tests. */
+export interface QuantWidgetTurnCap {
+    beforeToolCall(event: unknown, ctx?: unknown): {
+        block: true;
+        blockReason: string;
+    } | undefined;
+    afterToolCall(event: unknown, ctx?: unknown): void;
+    trackedRuns(): number;
+}
+/** Build the cap's state machine. `now` is injected so expiry is testable. */
+export declare function createQuantWidgetTurnCap(opts: {
+    now(): number;
+    ttlMs?: number;
+}): QuantWidgetTurnCap;
+/** The slice of the plugin API the cap needs. */
+export interface TurnCapPluginApi {
+    on(hookName: string, handler: (...args: unknown[]) => unknown, opts?: {
+        priority?: number;
+    }): void;
+}
+/** Register the cap on `before_tool_call` / `after_tool_call`. Fails open on any internal error. */
+export declare function registerQuantWidgetTurnCap(api: TurnCapPluginApi, opts: {
+    now(): number;
+    logger?: {
+        info(...a: unknown[]): void;
+        warn(...a: unknown[]): void;
+    };
+}): QuantWidgetTurnCap;
+//# sourceMappingURL=turn-cap.d.ts.map

package/dist/widgets/turn-cap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-cap.d.ts","sourceRoot":"","sources":["../../src/widgets/turn-cap.ts"],"names":[],"mappings":"AA2BA,2DAA2D;AAC3D,eAAO,MAAM,eAAe,QAAc,CAAC;AAC3C,oDAAoD;AACpD,eAAO,MAAM,qBAAqB,8GAC2E,CAAC;AAe9G,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAChG,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACnD,WAAW,IAAI,MAAM,CAAC;CACvB;AAmBD,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAAE,GAAG,IAAI,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,kBAAkB,CAwCpG;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACpG;AAED,oGAAoG;AACpG,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE;IAAE,GAAG,IAAI,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;KAAE,CAAA;CAAE,GAC7F,kBAAkB,CAoBpB"}

package/dist/widgets/turn-cap.js

@@ -0,0 +1,119 @@
+/**
+ * Per-run cap on `quant_desk_recommendations` (spec D8).
+ *
+ * `maxItems` bounds one call; a model that wants seven cards parallelises instead (field finding
+ * 4). Tool factories carry no run id, hooks do, so the cap lives in `before_tool_call`: while a
+ * quant card call is in flight or has succeeded in an agent run, any further one in that run is
+ * blocked with a teaching reason. `after_tool_call` makes the cap exact rather than a counter: a
+ * FAILED call (a mistyped run id) frees the slot so the corrected retry renders, and the after-event
+ * of a call the cap itself blocked is ignored (matched by toolCallId). Entries expire after 10 min.
+ * No run id from the host → fail open. The hooks never throw into the tool pipeline.
+ *
+ * Host shapes (OpenClaw `PluginHookBeforeToolCallEvent` / `PluginHookAfterToolCallEvent` /
+ * `PluginHookToolContext`): both the event and the ctx carry optional `runId` and `toolCallId`, so
+ * the event is read first and the ctx is the fallback. The event carries `toolName` and `params`;
+ * the after-event adds `result` and `error` (a string, set when the tool threw or returned an error
+ * result — `show_widget` throws on every refusal). A `{ block, blockReason }` return from
+ * `before_tool_call` stops the call and hands `blockReason` to the model as the tool error.
+ *
+ * Parallel calls in one assistant message (the fleet model's way past `maxItems`) all reach
+ * `before_tool_call` before any `after_tool_call`; the in-flight `pendingCallId` is what blocks
+ * the second one in that window.
+ */
+import { SHOW_WIDGET_TOOL_NAME } from "./tool.js";
+const QUANT_WIDGET_TYPE = "quant_desk_recommendations";
+/** The call id recorded when the host supplies none; it cannot identify a call on its own. */
+const UNKNOWN_CALL_ID = "(unknown)";
+/** How long a run's entry is kept after its last touch. */
+export const TURN_CAP_TTL_MS = 10 * 60_000;
+/** The reason the model reads on a blocked call. */
+export const TURN_CAP_BLOCK_REASON = "[E_WIDGET_TURN_CAP] recommendation cards were already shown in this answer; fold anything else into text.";
+function str(x) {
+    return typeof x === "string" && x.length > 0 ? x : undefined;
+}
+function read(event, ctx) {
+    const ev = (event && typeof event === "object" ? event : {});
+    const c = (ctx && typeof ctx === "object" ? ctx : {});
+    const params = ev.params && typeof ev.params === "object" ? ev.params : undefined;
+    const runId = str(ev.runId) ?? str(c.runId);
+    return {
+        ev,
+        ...(runId ? { runId } : {}),
+        callId: str(ev.toolCallId) ?? str(c.toolCallId) ?? UNKNOWN_CALL_ID,
+        isQuant: ev.toolName === SHOW_WIDGET_TOOL_NAME && params?.widget_type === QUANT_WIDGET_TYPE,
+    };
+}
+/** Build the cap's state machine. `now` is injected so expiry is testable. */
+export function createQuantWidgetTurnCap(opts) {
+    const ttl = opts.ttlMs ?? TURN_CAP_TTL_MS;
+    const runs = new Map();
+    const sweep = () => {
+        const cutoff = opts.now() - ttl;
+        for (const [k, e] of runs)
+            if (e.touchedAt <= cutoff)
+                runs.delete(k);
+    };
+    return {
+        beforeToolCall(event, ctx) {
+            const { runId, callId, isQuant } = read(event, ctx);
+            if (!isQuant || !runId)
+                return undefined;
+            sweep();
+            const entry = runs.get(runId);
+            if (entry && (entry.shown || entry.pendingCallId !== undefined)) {
+                entry.touchedAt = opts.now();
+                return { block: true, blockReason: TURN_CAP_BLOCK_REASON };
+            }
+            runs.set(runId, { shown: false, pendingCallId: callId, touchedAt: opts.now() });
+            return undefined;
+        },
+        afterToolCall(event, ctx) {
+            // No `isQuant` gate here: only a quant call can have set `pendingCallId`, so the toolCallId
+            // match is the identity. Re-deriving it from `params` would leave the entry pending forever
+            // when a host's after-event omits or empties them. The one exception is a call the host gave
+            // no id: then "(unknown)" matches any id-less event, so the tool itself must be the quant one.
+            const { ev, runId, callId, isQuant } = read(event, ctx);
+            if (!runId)
+                return;
+            const entry = runs.get(runId);
+            if (!entry || entry.pendingCallId !== callId)
+                return;
+            if (callId === UNKNOWN_CALL_ID && !isQuant)
+                return;
+            if (ev.error !== undefined && ev.error !== null && ev.error !== "") {
+                runs.delete(runId);
+                return;
+            }
+            entry.shown = true;
+            entry.pendingCallId = undefined;
+            entry.touchedAt = opts.now();
+        },
+        trackedRuns: () => runs.size,
+    };
+}
+/** Register the cap on `before_tool_call` / `after_tool_call`. Fails open on any internal error. */
+export function registerQuantWidgetTurnCap(api, opts) {
+    const cap = createQuantWidgetTurnCap(opts);
+    api.on("before_tool_call", (event, ctx) => {
+        try {
+            const verdict = cap.beforeToolCall(event, ctx);
+            if (verdict)
+                opts.logger?.info(`[senpi-widgets] turn cap blocked a second ${QUANT_WIDGET_TYPE} call`);
+            return verdict;
+        }
+        catch (err) {
+            opts.logger?.warn(`[senpi-widgets] turn cap failed open: ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    });
+    api.on("after_tool_call", (event, ctx) => {
+        try {
+            cap.afterToolCall(event, ctx);
+        }
+        catch {
+            // the cap never breaks the tool pipeline
+        }
+    });
+    return cap;
+}
+//# sourceMappingURL=turn-cap.js.map

package/dist/widgets/turn-cap.js.map

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

package/dist/widgets/types.d.ts

@@ -2,10 +2,12 @@
  * Widget spec types.
  *
  * A widget spec is the single source for one `widget_type`: the text that
- * teaches the model when to reach for the card, and the handler that builds
- * the result. The `show_widget` descriptor (enum + description) is generated
- * from the spec list, so the two cannot drift.
+ * teaches the model when to reach for the card, the extra arguments it takes,
+ * and the handler that builds the result. The `show_widget` descriptor (enum,
+ * merged parameters, description) is generated from the spec list, so the two
+ * cannot drift.
  */
+import type { QuantRunReader } from "../quant/types.js";
 /** Rendered by the client. Always carries the three shared keys. */
 export interface WidgetPayload {
     readonly widget_type: string;
@@ -18,6 +20,14 @@ export interface WidgetResult {
     /** Short line for the agent — what happened and what not to do next. */
     readonly text: string;
 }
+/**
+ * Collaborators a handler may read, injected at registration. Optional so a deployment without a
+ * collaborator still registers the tool; a handler that needs one fails with a teaching error.
+ */
+export interface WidgetHandlerContext {
+    /** The quant desk's stored runs (`src/quant/registry.ts`), read-only. Absent when the desk failed to build. */
+    readonly quantRuns?: QuantRunReader;
+}
 export interface WidgetSpec {
     readonly widgetType: string;
     /** Bumped when the payload shape changes; the client falls back on unknown versions. */
@@ -37,8 +47,26 @@ export interface WidgetSpec {
     readonly notFor: string;
     /** Situations illustrating the condition. One line each, reproduced verbatim. */
     readonly examples: readonly string[];
-    /** Takes no arguments: `show_widget` accepts `widget_type` and nothing else. */
-    readonly handler: () => WidgetResult | Promise<WidgetResult>;
+    /** How the rendered card is acted on — one line in the description. Per type: not every card has a button. */
+    readonly affordance: string;
+    /** One line naming the fields beyond widget_type, reproduced in the description. Absent = widget_type only. */
+    readonly fields?: string;
+    /**
+     * JSON-schema properties beyond widget_type, merged into the ONE flat parameter object. Each name
+     * has one owner across all specs (checked at registry build) and none may be `widget_type`.
+     * Flat and union-free, like the rest of the schema (see `buildShowWidgetParameters`).
+     */
+    readonly extraParameters?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    /**
+     * Builds the result. `args` has already passed the extra-field check for this type (only
+     * `widget_type` and this spec's `extraParameters` keys are present); the handler still validates
+     * their values, since the schema is advisory to the model and the handler is the real boundary.
+     *
+     * @param args The call's arguments, `widget_type` included.
+     * @param ctx Collaborators injected at registration; a handler needing an absent one throws a
+     *   teaching error (a `WidgetValidationError`) naming the fallback.
+     */
+    readonly handler: (args: Readonly<Record<string, unknown>>, ctx: WidgetHandlerContext) => WidgetResult | Promise<WidgetResult>;
 }
 /** A spec plus its resolved on/off state from plugin config. */
 export interface RegisteredWidget extends WidgetSpec {

package/dist/widgets/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/widgets/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC9D;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,mEAAmE;IACnE,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/widgets/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,+GAA+G;IAC/G,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;CACrC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,8GAA8G;IAC9G,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+GAA+G;IAC/G,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,oBAAoB,KACtB,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,mEAAmE;IACnE,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClC"}

package/dist/widgets/types.js

@@ -2,9 +2,10 @@
  * Widget spec types.
  *
  * A widget spec is the single source for one `widget_type`: the text that
- * teaches the model when to reach for the card, and the handler that builds
- * the result. The `show_widget` descriptor (enum + description) is generated
- * from the spec list, so the two cannot drift.
+ * teaches the model when to reach for the card, the extra arguments it takes,
+ * and the handler that builds the result. The `show_widget` descriptor (enum,
+ * merged parameters, description) is generated from the spec list, so the two
+ * cannot drift.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/widgets/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/widgets/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/widgets/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

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

@@ -1 +1 @@
-{"version":3,"file":"fund-user-wallet.d.ts","sourceRoot":"","sources":["../../../src/widgets/widgets/fund-user-wallet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK9C;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,UA6BhC,CAAC"}
+{"version":3,"file":"fund-user-wallet.d.ts","sourceRoot":"","sources":["../../../src/widgets/widgets/fund-user-wallet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK9C;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,UA8BhC,CAAC"}

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

@@ -15,6 +15,7 @@ export const fundUserWalletSpec = {
     description: "Opens Senpi's deposit flow for the user's OWN Senpi wallet, the one they deposit into from outside. " +
         "The card owns the address, the networks and the deposit copy — never write a deposit address, a QR code " +
         "or a network list in chat.",
+    affordance: "live UI: its button runs the flow, so showing it is how the user acts.",
     callWhen: "Call it whenever you want money to arrive in the user's own Senpi wallet, whether or not the user " +
         "mentions a deposit or a card.",
     notFor: "Funding, topping up or adding margin to a STRATEGY — a strategy is funded from the user's own wallet " +

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

@@ -1 +1 @@
-{"version":3,"file":"fund-user-wallet.js","sourceRoot":"","sources":["../../../src/widgets/widgets/fund-user-wallet.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,GAAG,kBAAkB,CAAC;AACvC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAe;IAC5C,UAAU,EAAE,WAAW;IACvB,aAAa,EAAE,cAAc;IAC7B,WAAW,EACT,sGAAsG;QACtG,0GAA0G;QAC1G,4BAA4B;IAC9B,QAAQ,EACN,oGAAoG;QACpG,+BAA+B;IACjC,MAAM,EACJ,uGAAuG;QACvG,iEAAiE;IACnE,QAAQ,EAAE;QACR,kFAAkF;QAClF,sCAAsC;QACtC,2FAA2F;QAC3F,4FAA4F;KAC7F;IACD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QACd,OAAO,EAAE;YACP,WAAW,EAAE,WAAW;YACxB,cAAc,EAAE,cAAc;YAC9B,MAAM,EAAE,OAAO;SAChB;QACD,IAAI,EACF,0DAA0D;YAC1D,wEAAwE;KAC3E,CAAC;CACH,CAAC"}
+{"version":3,"file":"fund-user-wallet.js","sourceRoot":"","sources":["../../../src/widgets/widgets/fund-user-wallet.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,GAAG,kBAAkB,CAAC;AACvC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAe;IAC5C,UAAU,EAAE,WAAW;IACvB,aAAa,EAAE,cAAc;IAC7B,WAAW,EACT,sGAAsG;QACtG,0GAA0G;QAC1G,4BAA4B;IAC9B,UAAU,EAAE,wEAAwE;IACpF,QAAQ,EACN,oGAAoG;QACpG,+BAA+B;IACjC,MAAM,EACJ,uGAAuG;QACvG,iEAAiE;IACnE,QAAQ,EAAE;QACR,kFAAkF;QAClF,sCAAsC;QACtC,2FAA2F;QAC3F,4FAA4F;KAC7F;IACD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QACd,OAAO,EAAE;YACP,WAAW,EAAE,WAAW;YACxB,cAAc,EAAE,cAAc;YAC9B,MAAM,EAAE,OAAO;SAChB;QACD,IAAI,EACF,0DAA0D;YAC1D,wEAAwE;KAC3E,CAAC;CACH,CAAC"}