@senpi/runtime 3.0.80 → 3.0.81

package/dist/widgets/registry.d.ts

@@ -0,0 +1,24 @@
+import type { RegisteredWidget, WidgetSpec } from "./types.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 declare const WIDGET_SPECS: readonly WidgetSpec[];
+/**
+ * Plugin config gate, keyed by `widget_type`. Absent or `true` means enabled;
+ * only an explicit `false` turns a widget off. Config keys the registry does
+ * not know are ignored, and so is a config value that is not an object.
+ */
+export type WidgetsConfig = Record<string, boolean>;
+export interface WidgetRegistry {
+    /** Every spec, including disabled ones. */
+    all(): readonly RegisteredWidget[];
+    /** Specs the model may call. Source for the enum and the description. */
+    enabled(): readonly RegisteredWidget[];
+    /** Lookup by `widget_type`, enabled or not. */
+    get(widgetType: string): RegisteredWidget | undefined;
+    enabledTypes(): string[];
+}
+export declare function buildWidgetRegistry(config?: unknown, specs?: readonly WidgetSpec[]): WidgetRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +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;AAI/D;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAiD,CAAC;AAEhG;;;;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,CAiBhB"}

package/dist/widgets/registry.js

@@ -0,0 +1,26 @@
+import { fundStrategyWalletSpec } from "./widgets/fund-strategy-wallet.js";
+import { fundUserWalletSpec } from "./widgets/fund-user-wallet.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, fundStrategyWalletSpec];
+export function buildWidgetRegistry(config, specs = WIDGET_SPECS) {
+    const gate = config && typeof config === "object" && !Array.isArray(config)
+        ? config
+        : undefined;
+    const widgets = specs.map((spec) => ({
+        ...spec,
+        enabled: gate?.[spec.widgetType] !== false,
+    }));
+    const byType = new Map(widgets.map((w) => [w.widgetType, w]));
+    const enabled = widgets.filter((w) => w.enabled);
+    return {
+        all: () => widgets,
+        enabled: () => enabled,
+        get: (widgetType) => byType.get(widgetType),
+        enabledTypes: () => enabled.map((w) => w.widgetType),
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/widgets/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/widgets/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAA0B,CAAC,kBAAkB,EAAE,sBAAsB,CAAC,CAAC;AAmBhG,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,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,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/strategy-lookup.d.ts

@@ -0,0 +1,39 @@
+import type { StrategyLookup } from "./types.js";
+/**
+ * Bounds one validation lookup. The user is waiting on a card, and the tool
+ * result is what unblocks the turn, so a backend that never answers has to
+ * become an error the model can retry rather than a hung turn.
+ */
+export declare const STRATEGY_LOOKUP_TIMEOUT_MS = 10000;
+export declare function isWalletAddress(value: string): boolean;
+/** The `strategy_list` row fields this lookup reads. */
+interface StrategyRow {
+    id: string;
+    strategyWalletAddress: string;
+    status: string;
+    strategyName: string;
+}
+/** The slice of `SenpiClient` this lookup needs. */
+export interface StrategyLister {
+    listStrategies(filters?: {
+        strategyAddresses?: string[];
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<StrategyRow[]>;
+}
+/**
+ * Address → strategy, over `strategy_list` with an address filter.
+ *
+ * Deliberately not `SenpiClient.getStrategy`: that one falls back to the first
+ * row when no row matches the requested address, and drops the address from its
+ * result, so a backend that ignored the filter would resolve any address to
+ * some strategy. Both are fine for a details read and fatal for a gate, so this
+ * matches the address itself and never falls back.
+ *
+ * `listStrategies` already fails closed — an unrecognizable response throws
+ * instead of reading as an empty list — so an empty result here is a real
+ * "no strategy of yours holds that address" and is returned as `null`.
+ */
+export declare function createSenpiStrategyLookup(withClient: <T>(fn: (client: StrategyLister) => Promise<T>) => Promise<T>): StrategyLookup;
+export {};
+//# sourceMappingURL=strategy-lookup.d.ts.map

package/dist/widgets/strategy-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-lookup.d.ts","sourceRoot":"","sources":["../../src/widgets/strategy-lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAyBjD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wDAAwD;AACxD,UAAU,WAAW;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB,EAAE,MAAM,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,cAAc,CACZ,OAAO,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,EAC1C,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC9B,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACxE,cAAc,CA+BhB"}

package/dist/widgets/strategy-lookup.js

@@ -0,0 +1,70 @@
+/**
+ * Bounds one validation lookup. The user is waiting on a card, and the tool
+ * result is what unblocks the turn, so a backend that never answers has to
+ * become an error the model can retry rather than a hung turn.
+ */
+export const STRATEGY_LOOKUP_TIMEOUT_MS = 10_000;
+/**
+ * Bounds the whole lookup, not just the MCP request.
+ *
+ * The signal passed to `listStrategies` covers the request only. Reaching it
+ * means first connecting a client, and the MCP SDK gives `initialize` its own
+ * 60s default — so an unreachable backend held the agent turn for over a minute
+ * while this module advertised a ten-second bound. The race is what makes the
+ * bound true; the signal stays so the in-flight request is really cancelled.
+ */
+async function withDeadline(work, ms) {
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`strategy lookup timed out after ${ms}ms`)), ms);
+    });
+    try {
+        return await Promise.race([work, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const WALLET_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+export function isWalletAddress(value) {
+    return WALLET_ADDRESS_RE.test(value);
+}
+/**
+ * Address → strategy, over `strategy_list` with an address filter.
+ *
+ * Deliberately not `SenpiClient.getStrategy`: that one falls back to the first
+ * row when no row matches the requested address, and drops the address from its
+ * result, so a backend that ignored the filter would resolve any address to
+ * some strategy. Both are fine for a details read and fatal for a gate, so this
+ * matches the address itself and never falls back.
+ *
+ * `listStrategies` already fails closed — an unrecognizable response throws
+ * instead of reading as an empty list — so an empty result here is a real
+ * "no strategy of yours holds that address" and is returned as `null`.
+ */
+export function createSenpiStrategyLookup(withClient) {
+    return {
+        async findByWallet(wallet) {
+            // Lowercased for the backend, not just for the comparison below. The
+            // `strategy_addresses` filter is an exact SQL `in` against a column
+            // written lowercase, so a checksummed address matches nothing and comes
+            // back as an ordinary empty list — a correct address reported as "not
+            // yours", which is the one answer this gate must never invent.
+            const wanted = wallet.toLowerCase();
+            const rows = await withDeadline(withClient((client) => client.listStrategies({ strategyAddresses: [wanted] }, { signal: AbortSignal.timeout(STRATEGY_LOOKUP_TIMEOUT_MS) })), STRATEGY_LOOKUP_TIMEOUT_MS);
+            const matches = rows.filter((row) => row.strategyWalletAddress.toLowerCase() === wanted);
+            // An address may carry more than one row over its lifetime; a live
+            // strategy on it is the answer, and its status is what the gate judges.
+            const match = matches.find((row) => row.status.toUpperCase() === "ACTIVE") ?? matches[0];
+            if (!match)
+                return null;
+            return {
+                id: match.id,
+                walletAddress: match.strategyWalletAddress,
+                status: match.status,
+                name: match.strategyName,
+            };
+        },
+    };
+}
+//# sourceMappingURL=strategy-lookup.js.map

package/dist/widgets/strategy-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-lookup.js","sourceRoot":"","sources":["../../src/widgets/strategy-lookup.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAEjD;;;;;;;;GAQG;AACH,KAAK,UAAU,YAAY,CAAI,IAAgB,EAAE,EAAU;IACzD,IAAI,KAAgD,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;QACvD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,mCAAmC,EAAE,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7F,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC9C,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEhD,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAkBD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAAyE;IAEzE,OAAO;QACL,KAAK,CAAC,YAAY,CAAC,MAAc;YAC/B,qEAAqE;YACrE,oEAAoE;YACpE,wEAAwE;YACxE,sEAAsE;YACtE,+DAA+D;YAC/D,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,MAAM,YAAY,CAC7B,UAAU,CAAC,CAAC,MAAM,EAAE,EAAE,CACpB,MAAM,CAAC,cAAc,CACnB,EAAE,iBAAiB,EAAE,CAAC,MAAM,CAAC,EAAE,EAC/B,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,0BAA0B,CAAC,EAAE,CAC5D,CACF,EACD,0BAA0B,CAC3B,CAAC;YACF,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,qBAAqB,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC;YACzF,mEAAmE;YACnE,wEAAwE;YACxE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;YACzF,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;YACxB,OAAO;gBACL,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,aAAa,EAAE,KAAK,CAAC,qBAAqB;gBAC1C,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,IAAI,EAAE,KAAK,CAAC,YAAY;aACzB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/widgets/tool.d.ts

@@ -0,0 +1,51 @@
+import type { WidgetRegistry } from "./registry.js";
+import type { StrategyLookup, 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
+ * `openclaw.plugin.json` under `contracts.tools`.
+ */
+export declare const SHOW_WIDGET_TOOL_NAME = "show_widget";
+export interface ShowWidgetToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: WidgetPayload;
+}
+export interface ShowWidgetTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute(toolCallId: string, params: unknown): Promise<ShowWidgetToolResult>;
+}
+export interface CreateShowWidgetToolOptions {
+    registry: WidgetRegistry;
+    logger?: WidgetLogger;
+    /** Ephemeral session id from the plugin tool factory context; logged only. */
+    sessionId?: string;
+    /** Backend a widget validates addresses against. Absent = those widgets fail closed. */
+    strategies?: StrategyLookup;
+}
+/**
+ * Tool description, generated from the enabled specs. This is the text the
+ * model selects a `widget_type` on, so it carries the per-type field list that
+ * the flat JSON schema cannot express.
+ */
+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 — so a discriminated
+ * union on `widget_type` would buy nothing. Only `widget_type` is required;
+ * per-widget requiredness is enforced in `execute()`.
+ */
+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.
+ */
+export declare function createShowWidgetTool(options: CreateShowWidgetToolOptions): ShowWidgetTool;
+//# sourceMappingURL=tool.d.ts.map

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

@@ -0,0 +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,EAEV,cAAc,EAEd,YAAY,EACZ,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;;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,wFAAwF;IACxF,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAQD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAuB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyD3F;AAyID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,cAAc,CA2CzF"}

package/dist/widgets/tool.js

@@ -0,0 +1,250 @@
+import { WidgetLookupError, WidgetValidationError } from "./errors.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
+ * `openclaw.plugin.json` under `contracts.tools`.
+ */
+export const SHOW_WIDGET_TOOL_NAME = "show_widget";
+const WIDGET_TYPE_PARAM = "widget_type";
+function fieldLine(field) {
+    const parts = [`${field.required ? "required" : "optional"} ${field.type}`];
+    if (field.maxLength !== undefined)
+        parts.push(`max ${field.maxLength} chars`);
+    return `    ${field.name} (${parts.join(", ")}): ${field.description}`;
+}
+/**
+ * Tool description, generated from the enabled specs. This is the text the
+ * model selects a `widget_type` on, so it carries the per-type field list that
+ * the flat JSON schema cannot express.
+ */
+export function buildShowWidgetDescription(registry) {
+    const widgets = registry.enabled();
+    const lines = [
+        "Render a Senpi UI card in the user's chat, for cases where a card communicates better than text.",
+        "",
+        `Pass ${WIDGET_TYPE_PARAM} plus only the fields listed for that type. Any other field is rejected.`,
+        "",
+    ];
+    if (widgets.length === 0) {
+        lines.push("No widget types are enabled on this deployment.");
+        return lines.join("\n");
+    }
+    lines.push("Widget types:");
+    for (const widget of widgets) {
+        lines.push(`- ${widget.widgetType}: ${widget.description}`);
+        lines.push("  fields:");
+        if (widget.fields.length === 0) {
+            lines.push("    none — pass widget_type only");
+            continue;
+        }
+        lines.push(...widget.fields.map(fieldLine));
+    }
+    return lines.join("\n");
+}
+/**
+ * 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 — so a discriminated
+ * union on `widget_type` would buy nothing. Only `widget_type` is required;
+ * per-widget requiredness is enforced in `execute()`.
+ */
+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");
+    }
+    const properties = {
+        [WIDGET_TYPE_PARAM]: {
+            type: "string",
+            enum: widgets.map((w) => w.widgetType),
+            description: "Which widget to render.",
+        },
+    };
+    // Fields shared by several widget types collapse into one property, so the
+    // shared property has to admit every owner's input: per-widget limits are
+    // enforced in execute(), and a declared bound stricter than one owner's would
+    // make the provider reject a call that execute() would have accepted.
+    const owners = new Map();
+    for (const widget of widgets) {
+        for (const field of widget.fields) {
+            if (field.name === WIDGET_TYPE_PARAM) {
+                throw new Error(`show_widget: ${widget.widgetType} declares a field named "${WIDGET_TYPE_PARAM}", which is the discriminator`);
+            }
+            const entry = owners.get(field.name);
+            if (entry) {
+                entry.types.push(widget.widgetType);
+                entry.fields.push(field);
+                continue;
+            }
+            owners.set(field.name, { types: [widget.widgetType], fields: [field] });
+        }
+    }
+    for (const [name, { types, fields }] of owners) {
+        const valueTypes = [...new Set(fields.map((f) => f.type))];
+        if (valueTypes.length > 1) {
+            throw new Error(`show_widget: field "${name}" is declared as ${valueTypes.join(" and ")} by ${types.join(", ")}; one schema property cannot be both`);
+        }
+        const property = { type: valueTypes[0] };
+        const bounds = fields.map((f) => f.maxLength);
+        if (bounds.every((b) => b !== undefined)) {
+            property.maxLength = Math.max(...bounds);
+        }
+        property.description =
+            types.length === 1
+                ? `${fields[0].description} Accepted by: ${types[0]}.`
+                : fields.map((f, i) => `${types[i]}: ${f.description}`).join(" ");
+        properties[name] = property;
+    }
+    return {
+        type: "object",
+        properties,
+        required: [WIDGET_TYPE_PARAM],
+        additionalProperties: false,
+    };
+}
+function availableTypesSentence(registry) {
+    const types = registry.enabledTypes();
+    return types.length === 0
+        ? "No widget types are available."
+        : `Available widget types: ${types.join(", ")}.`;
+}
+/** Anything that is not a plain object carries no fields — treat it as empty. */
+function toArgs(params) {
+    return params && typeof params === "object" && !Array.isArray(params)
+        ? params
+        : {};
+}
+function resolveWidget(registry, args) {
+    const raw = args[WIDGET_TYPE_PARAM];
+    const available = availableTypesSentence(registry);
+    if (raw === undefined || raw === null) {
+        throw new WidgetValidationError(`show_widget failed: "${WIDGET_TYPE_PARAM}" is required. ${available}`, "(none)", [WIDGET_TYPE_PARAM]);
+    }
+    if (typeof raw !== "string") {
+        throw new WidgetValidationError(`show_widget failed: "${WIDGET_TYPE_PARAM}" must be a string. ${available}`, "(none)", [WIDGET_TYPE_PARAM]);
+    }
+    const widget = registry.get(raw);
+    if (!widget) {
+        throw new WidgetValidationError(`show_widget failed: unknown ${WIDGET_TYPE_PARAM} "${raw}". ${available}`, raw, [WIDGET_TYPE_PARAM]);
+    }
+    if (!widget.enabled) {
+        throw new WidgetValidationError(`show_widget failed: ${WIDGET_TYPE_PARAM} "${raw}" is not enabled on this deployment. ${available}`, raw, [WIDGET_TYPE_PARAM]);
+    }
+    return widget;
+}
+/**
+ * Validate the remaining args against the widget's own field list. Every
+ * problem is reported in one message so the model can fix them all in a single
+ * retry instead of discovering them one call at a time.
+ */
+function validateFields(widget, args) {
+    // Guarded fields are accepted as keys so the widget can answer them itself;
+    // they are absent from the description and the declared schema.
+    const guarded = widget.guardedFields ?? [];
+    const allowed = new Set([
+        WIDGET_TYPE_PARAM,
+        ...widget.fields.map((f) => f.name),
+        ...guarded.map((f) => f.name),
+    ]);
+    const problems = [];
+    const offending = [];
+    const unexpected = Object.keys(args).filter((key) => !allowed.has(key));
+    if (unexpected.length > 0) {
+        offending.push(...unexpected);
+        // Guarded names are parseable but not on offer, so they stay out of this list.
+        const offered = [WIDGET_TYPE_PARAM, ...widget.fields.map((f) => f.name)];
+        problems.push(`unexpected fields: ${unexpected.join(", ")} (allowed: ${offered.join(", ")})`);
+    }
+    const missing = [];
+    const invalid = [];
+    const values = {};
+    // A guarded field goes to the handler exactly as it arrived. Its answer is
+    // "drop this field", which is the same for every value, so complaining about
+    // the type or the length first would only buy a retry that corrects a field
+    // the model then has to remove anyway.
+    for (const field of guarded) {
+        const value = Object.hasOwn(args, field.name) ? args[field.name] : undefined;
+        if (value !== undefined && value !== null)
+            values[field.name] = value;
+    }
+    for (const field of widget.fields) {
+        // Own keys only: an inherited `reason`/`toString` must not read as a value
+        // the caller passed, since the unexpected-key check above only sees own keys.
+        const value = Object.hasOwn(args, field.name) ? args[field.name] : undefined;
+        if (value === undefined || value === null) {
+            if (field.required)
+                missing.push(field.name);
+            continue;
+        }
+        if (typeof value !== "string") {
+            invalid.push(`${field.name} (must be a ${field.type})`);
+            continue;
+        }
+        if (value.trim().length === 0) {
+            invalid.push(`${field.name} (must be a non-empty ${field.type}; omit it instead)`);
+            continue;
+        }
+        if (field.maxLength !== undefined && value.length > field.maxLength) {
+            invalid.push(`${field.name} (${value.length} chars, limit is ${field.maxLength})`);
+            continue;
+        }
+        values[field.name] = value;
+    }
+    if (missing.length > 0) {
+        offending.push(...missing);
+        problems.push(`missing required fields: ${missing.join(", ")}`);
+    }
+    if (invalid.length > 0) {
+        offending.push(...invalid.map((entry) => entry.split(" ")[0]));
+        problems.push(`invalid fields: ${invalid.join(", ")}`);
+    }
+    if (problems.length > 0) {
+        throw new WidgetValidationError(`show_widget failed for ${WIDGET_TYPE_PARAM} "${widget.widgetType}": ${problems.join("; ")}. ` +
+            "Fix the named fields and call show_widget again with the same widget_type.", widget.widgetType, offending);
+    }
+    return values;
+}
+/**
+ * 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.
+ */
+export function createShowWidgetTool(options) {
+    const { registry, logger, sessionId, strategies } = options;
+    const session = sessionId ?? "(unknown)";
+    const ctx = { strategies };
+    return {
+        name: SHOW_WIDGET_TOOL_NAME,
+        description: buildShowWidgetDescription(registry),
+        parameters: buildShowWidgetParameters(registry),
+        async execute(_toolCallId, params) {
+            try {
+                const args = toArgs(params);
+                const widget = resolveWidget(registry, args);
+                const values = validateFields(widget, args);
+                const result = await widget.handler(values, ctx);
+                logger?.info(`[senpi-widgets] widget shown | widget_type=${widget.widgetType} widget_version=${widget.widgetVersion} session=${session}`);
+                return {
+                    content: [{ type: "text", text: result.text }],
+                    details: result.payload,
+                };
+            }
+            catch (err) {
+                if (err instanceof WidgetValidationError) {
+                    logger?.warn(`[senpi-widgets] validation failed | widget_type=${err.widgetType} fields=${err.fields.join(",")} session=${session} | ${err.message}`);
+                }
+                else if (err instanceof WidgetLookupError) {
+                    // The args were never judged — this is a backend problem, and it is the
+                    // only signal that a card the user asked for could not be built.
+                    logger?.warn(`[senpi-widgets] lookup failed | widget_type=${err.widgetType} session=${session} | ${err.message} | cause=${err.cause instanceof Error ? err.cause.message : String(err.cause ?? "(none)")}`);
+                }
+                else {
+                    logger?.error?.(`[senpi-widgets] unhandled failure | session=${session} | ${err instanceof Error ? err.message : String(err)}`);
+                }
+                throw err;
+            }
+        },
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/widgets/tool.js.map

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

package/dist/widgets/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Widget spec types.
+ *
+ * A widget spec is the single source for one `widget_type`: the fields it
+ * accepts, the text that teaches the model about it, and the handler that
+ * builds the result. The `show_widget` tool descriptor (enum + description) is
+ * generated from the spec list, so the two cannot drift.
+ */
+/** Field value kinds a widget may declare. Extend as new widgets need them. */
+export type WidgetFieldType = "string";
+export interface WidgetFieldSpec {
+    readonly name: string;
+    readonly type: WidgetFieldType;
+    /** Enforced in `execute()`; the declared JSON schema keeps every field optional. */
+    readonly required: boolean;
+    /** One line, shown to the model in the generated tool description. */
+    readonly description: string;
+    /** Upper bound for string fields. */
+    readonly maxLength?: number;
+}
+/** Rendered by the client. Always carries the three shared keys. */
+export interface WidgetPayload {
+    readonly widget_type: string;
+    readonly widget_version: number;
+    readonly status: string;
+    readonly [key: string]: unknown;
+}
+export interface WidgetResult {
+    readonly payload: WidgetPayload;
+    /** Short line for the agent — what happened and what not to do next. */
+    readonly text: string;
+}
+/** One of the caller's strategies, as the backend reported it. */
+export interface StrategyMatch {
+    readonly id: string;
+    /** The address exactly as the backend spells it, not as the model typed it. */
+    readonly walletAddress: string;
+    /** Lifecycle status, e.g. "ACTIVE", "PAUSED", "CLOSED". */
+    readonly status: string;
+    readonly name: string;
+}
+export interface StrategyLookup {
+    /**
+     * `null` means the backend answered and no strategy of the caller's holds that
+     * address. A backend that did not answer usably **throws** — the two must never
+     * collapse, or one timeout turns a good address into "not yours".
+     */
+    findByWallet(wallet: string): Promise<StrategyMatch | null>;
+}
+/** Everything a handler may reach for beyond its own args. */
+export interface WidgetContext {
+    /** Absent when the plugin registered the tool without a backend. */
+    readonly strategies?: StrategyLookup;
+}
+/**
+ * A field a widget always refuses but wants to diagnose itself, because another
+ * widget type declares it and the model can misroute it here.
+ *
+ * Matched by name only. No type or length check is applied, and the value
+ * reaches the handler exactly as it arrived: the widget's answer is "drop this
+ * field", which does not change with the value, and a type complaint would send
+ * the model back to correct a field it should be removing.
+ */
+export interface GuardedFieldSpec {
+    readonly name: string;
+    /** Why it is refused. For readers of the spec; the model sees the widget's own error. */
+    readonly description: string;
+}
+export interface WidgetSpec {
+    readonly widgetType: string;
+    /** Bumped when the payload shape changes; the client falls back on unknown versions. */
+    readonly widgetVersion: number;
+    /** When to use this widget. Reproduced verbatim in the tool description. */
+    readonly description: string;
+    readonly fields: readonly WidgetFieldSpec[];
+    /** Never advertised in the description or the declared schema. */
+    readonly guardedFields?: readonly GuardedFieldSpec[];
+    /** Receives args validated against `fields`, plus any guarded field verbatim. */
+    readonly handler: (args: Readonly<Record<string, unknown>>, ctx: WidgetContext) => WidgetResult | Promise<WidgetResult>;
+}
+/** A spec plus its resolved on/off state from plugin config. */
+export interface RegisteredWidget extends WidgetSpec {
+    readonly enabled: boolean;
+}
+export interface WidgetLogger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    /** Unhandled failures only; every expected rejection is a WARN. */
+    error?(...args: unknown[]): void;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/widgets/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;AAEvC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,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,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACrD,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,aAAa,KACf,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

@@ -0,0 +1,10 @@
+/**
+ * Widget spec types.
+ *
+ * A widget spec is the single source for one `widget_type`: the fields it
+ * accepts, the text that teaches the model about it, and the handler that
+ * builds the result. The `show_widget` tool descriptor (enum + description) is
+ * generated from the spec list, so the two cannot drift.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/widgets/types.js.map

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

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

@@ -0,0 +1,13 @@
+import type { WidgetSpec } from "../types.js";
+/**
+ * `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 declare const fundStrategyWalletSpec: WidgetSpec;
+//# sourceMappingURL=fund-strategy-wallet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fund-strategy-wallet.d.ts","sourceRoot":"","sources":["../../../src/widgets/widgets/fund-strategy-wallet.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAgC,UAAU,EAAE,MAAM,aAAa,CAAC;AA4G5E;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,UA0DpC,CAAC"}