@buoy-gg/agent-core 7.0.33

package/lib/module/blocks/uiTool.js

@@ -0,0 +1,987 @@
+"use strict";
+
+/**
+ * `buoy_ui` — the one tool the model uses to SHOW or ASK instead of writing
+ * prose. One tool with `action` as the block kind, like every other Buoy
+ * tool, so tool selection stays good; the params are the block itself.
+ *
+ * Validation is the same `validateParams` every other action gets, and an
+ * invalid block goes back as a schema error for self-correction. A valid
+ * block is stamped with an id and yielded as a `block` event; an Ask block
+ * also ends the turn (see runAgentTurn).
+ */
+import { validateParams } from "../catalog/validateParams";
+import { CAPS, MODEL_KINDS } from "./types";
+export const UI_TOOL_NAME = "buoy_ui";
+const tone = {
+  type: "string",
+  enum: ["muted", "accent", "warning", "danger", "info"]
+};
+const action = {
+  type: "object",
+  properties: {
+    label: {
+      type: "string",
+      description: "Button text, 1–4 words."
+    },
+    primary: {
+      type: "boolean"
+    },
+    send: {
+      type: "string",
+      description: "Text sent as the user's next message when tapped."
+    },
+    dispatch: {
+      type: "object",
+      description: "A Buoy action to run when tapped — same policy and undo as if you called it.",
+      properties: {
+        toolId: {
+          type: "string"
+        },
+        action: {
+          type: "string"
+        },
+        params: {
+          type: "object"
+        }
+      },
+      required: ["toolId", "action"]
+    },
+    openTool: {
+      type: "object",
+      properties: {
+        toolId: {
+          type: "string"
+        },
+        select: {
+          type: "string"
+        }
+      },
+      required: ["toolId"]
+    },
+    minimize: {
+      type: "boolean",
+      description: "Collapse the chat so the user can look at the app."
+    }
+  },
+  required: ["label"],
+  additionalProperties: false
+};
+const cell = {
+  anyOf: [{
+    type: "string"
+  }, {
+    type: "object",
+    properties: {
+      text: {
+        type: "string"
+      },
+      tone
+    },
+    required: ["text"]
+  }]
+};
+
+/** Per-kind param schemas. Keys are block kinds; `kind` itself is the `action`. */
+export const UI_PARAMS = {
+  choice: {
+    type: "object",
+    properties: {
+      question: {
+        type: "string",
+        description: "`title` is accepted as a synonym."
+      },
+      title: {
+        type: "string",
+        description: "Synonym for `question`."
+      },
+      options: {
+        type: "array",
+        maxItems: CAPS.choiceOptions,
+        items: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string"
+            },
+            label: {
+              type: "string"
+            },
+            detail: {
+              type: "string"
+            }
+          },
+          required: ["id", "label"]
+        }
+      },
+      allowFreeText: {
+        type: "boolean"
+      }
+    },
+    // `question` is satisfied by `title` too — see normaliseChoice. Same
+    // lesson the confirm block cost us: a schema that rejects the obvious
+    // synonym sends a model into a retry loop and the user is never asked.
+    required: ["options"],
+    additionalProperties: false
+  },
+  confirm: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string",
+        description: "Optional heading. Defaults to \"Confirm\"."
+      },
+      change: {
+        type: "string",
+        description: "What will change, in the user's words. `message` is accepted as a synonym."
+      },
+      message: {
+        type: "string",
+        description: "Synonym for `change`."
+      },
+      consequence: {
+        type: "string"
+      },
+      approveLabel: {
+        type: "string"
+      },
+      declineLabel: {
+        type: "string"
+      }
+    },
+    // ONLY `change` is required, and `message` satisfies it (see
+    // normaliseConfirm). Requiring both `title` AND `change` while rejecting
+    // `message` sent a live model into a four-attempt failure loop — it kept
+    // sending the universal {title, message} shape, and the validator
+    // answered "change: required" then "title: required", which reads as
+    // contradictory. It gave up and the user never got asked.
+    required: [],
+    additionalProperties: false
+  },
+  input: {
+    type: "object",
+    properties: {
+      label: {
+        type: "string"
+      },
+      type: {
+        type: "string",
+        enum: ["text", "number", "secret"]
+      },
+      placeholder: {
+        type: "string"
+      },
+      submitLabel: {
+        type: "string"
+      }
+    },
+    required: ["label"],
+    additionalProperties: false
+  },
+  table: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      columns: {
+        type: "array",
+        maxItems: 4,
+        items: {
+          type: "string"
+        }
+      },
+      rows: {
+        type: "array",
+        items: {
+          type: "array",
+          items: cell
+        }
+      },
+      total: {
+        type: "number"
+      }
+    },
+    required: ["columns", "rows"],
+    additionalProperties: false
+  },
+  keyValue: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      pairs: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            key: {
+              type: "string"
+            },
+            value: {}
+          },
+          required: ["key"]
+        }
+      }
+    },
+    required: ["pairs"],
+    additionalProperties: false
+  },
+  list: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string"
+            },
+            title: {
+              type: "string"
+            },
+            subtitle: {
+              type: "string"
+            },
+            trailing: {
+              type: "string"
+            },
+            image: {
+              type: "string",
+              description: "Only a URL you read from the app this turn."
+            },
+            tone,
+            action
+          },
+          required: ["title"]
+        }
+      },
+      total: {
+        type: "number"
+      }
+    },
+    required: ["items"],
+    additionalProperties: false
+  },
+  imageGrid: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      images: {
+        type: "array",
+        maxItems: CAPS.gridMax,
+        items: {
+          type: "object",
+          properties: {
+            url: {
+              type: "string",
+              description: "Only a URL you read from the app this turn."
+            },
+            alt: {
+              type: "string"
+            },
+            caption: {
+              type: "string"
+            }
+          },
+          required: ["url", "alt"]
+        }
+      },
+      total: {
+        type: "number"
+      }
+    },
+    required: ["images"],
+    additionalProperties: false
+  },
+  diff: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      changes: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string"
+            },
+            before: {},
+            after: {}
+          },
+          required: ["path"]
+        }
+      }
+    },
+    required: ["changes"],
+    additionalProperties: false
+  },
+  chart: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      bars: {
+        type: "array",
+        maxItems: CAPS.chartBars,
+        items: {
+          type: "object",
+          properties: {
+            label: {
+              type: "string"
+            },
+            value: {
+              type: "number"
+            },
+            unit: {
+              type: "string"
+            },
+            tone
+          },
+          required: ["label", "value"]
+        }
+      },
+      max: {
+        type: "number"
+      }
+    },
+    required: ["bars"],
+    additionalProperties: false
+  },
+  steps: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      steps: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            text: {
+              type: "string"
+            },
+            state: {
+              type: "string",
+              enum: ["todo", "done", "failed"]
+            }
+          },
+          required: ["text"]
+        }
+      }
+    },
+    required: ["steps"],
+    additionalProperties: false
+  },
+  code: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      language: {
+        type: "string",
+        enum: ["json", "text"]
+      },
+      text: {
+        type: "string"
+      }
+    },
+    required: ["text"],
+    additionalProperties: false
+  },
+  actions: {
+    type: "object",
+    properties: {
+      actions: {
+        type: "array",
+        maxItems: CAPS.actions,
+        items: action
+      }
+    },
+    required: ["actions"],
+    additionalProperties: false
+  },
+  suggestions: {
+    type: "object",
+    properties: {
+      chips: {
+        type: "array",
+        maxItems: 4,
+        items: {
+          type: "object",
+          properties: {
+            label: {
+              type: "string"
+            },
+            send: {
+              type: "string"
+            }
+          },
+          required: ["label"]
+        }
+      }
+    },
+    required: ["chips"],
+    additionalProperties: false
+  },
+  multiSelect: {
+    type: "object",
+    properties: {
+      question: {
+        type: "string"
+      },
+      options: {
+        type: "array",
+        maxItems: 12,
+        items: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string"
+            },
+            label: {
+              type: "string"
+            },
+            detail: {
+              type: "string"
+            }
+          },
+          required: ["id", "label"]
+        }
+      },
+      min: {
+        type: "number"
+      },
+      max: {
+        type: "number"
+      },
+      submitLabel: {
+        type: "string"
+      }
+    },
+    required: ["question", "options"],
+    additionalProperties: false
+  },
+  select: {
+    type: "object",
+    properties: {
+      label: {
+        type: "string"
+      },
+      options: {
+        type: "array",
+        maxItems: 100,
+        items: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string"
+            },
+            label: {
+              type: "string"
+            },
+            detail: {
+              type: "string"
+            }
+          },
+          required: ["id", "label"]
+        }
+      },
+      searchable: {
+        type: "boolean"
+      }
+    },
+    required: ["label", "options"],
+    additionalProperties: false
+  },
+  slider: {
+    type: "object",
+    properties: {
+      label: {
+        type: "string"
+      },
+      min: {
+        type: "number"
+      },
+      max: {
+        type: "number"
+      },
+      step: {
+        type: "number"
+      },
+      value: {
+        type: "number"
+      },
+      unit: {
+        type: "string"
+      }
+    },
+    required: ["label", "min", "max"],
+    additionalProperties: false
+  },
+  dateTime: {
+    type: "object",
+    properties: {
+      label: {
+        type: "string"
+      },
+      mode: {
+        type: "string",
+        enum: ["date", "time", "datetime"]
+      },
+      presets: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            label: {
+              type: "string"
+            },
+            value: {
+              type: "string"
+            }
+          },
+          required: ["label", "value"]
+        }
+      }
+    },
+    required: ["label"],
+    additionalProperties: false
+  },
+  form: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      fields: {
+        type: "array",
+        maxItems: 6,
+        items: {
+          type: "object"
+        }
+      },
+      submitLabel: {
+        type: "string"
+      }
+    },
+    required: ["fields"],
+    additionalProperties: false
+  },
+  proposal: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      change: {
+        type: "string"
+      },
+      fields: {
+        type: "array",
+        maxItems: 6,
+        items: {
+          type: "object"
+        }
+      },
+      consequence: {
+        type: "string"
+      },
+      approveLabel: {
+        type: "string"
+      }
+    },
+    required: ["title", "change", "fields"],
+    additionalProperties: false
+  },
+  claim: {
+    type: "object",
+    properties: {
+      text: {
+        type: "string"
+      },
+      sources: {
+        type: "array",
+        maxItems: 4,
+        items: {
+          type: "object",
+          properties: {
+            label: {
+              type: "string"
+            },
+            detail: {
+              type: "string"
+            }
+          },
+          required: ["label"]
+        }
+      },
+      verify: action
+    },
+    required: ["text", "sources"],
+    additionalProperties: false
+  },
+  details: {
+    type: "object",
+    properties: {
+      summary: {
+        type: "string"
+      },
+      body: {
+        type: "string"
+      },
+      open: {
+        type: "boolean"
+      }
+    },
+    required: ["summary", "body"],
+    additionalProperties: false
+  },
+  compare: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      left: {
+        type: "object",
+        properties: {
+          title: {
+            type: "string"
+          },
+          pairs: {
+            type: "array",
+            items: {
+              type: "object"
+            }
+          }
+        },
+        required: ["title", "pairs"]
+      },
+      right: {
+        type: "object",
+        properties: {
+          title: {
+            type: "string"
+          },
+          pairs: {
+            type: "array",
+            items: {
+              type: "object"
+            }
+          }
+        },
+        required: ["title", "pairs"]
+      }
+    },
+    required: ["left", "right"],
+    additionalProperties: false
+  },
+  card: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      subtitle: {
+        type: "string"
+      },
+      image: {
+        type: "string"
+      },
+      facts: {
+        type: "array",
+        maxItems: 6,
+        items: {
+          type: "object",
+          properties: {
+            label: {
+              type: "string"
+            },
+            value: {
+              type: "string"
+            },
+            tone
+          },
+          required: ["label", "value"]
+        }
+      },
+      actions: {
+        type: "array",
+        maxItems: CAPS.actions,
+        items: action
+      }
+    },
+    required: ["title"],
+    additionalProperties: false
+  },
+  cardCarousel: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      cards: {
+        type: "array",
+        maxItems: 8,
+        items: {
+          type: "object"
+        }
+      },
+      total: {
+        type: "number"
+      }
+    },
+    required: ["cards"],
+    additionalProperties: false
+  },
+  sparkline: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      series: {
+        type: "array",
+        maxItems: 120,
+        items: {
+          type: "number"
+        }
+      },
+      unit: {
+        type: "string"
+      },
+      label: {
+        type: "string"
+      },
+      current: {
+        type: "number"
+      }
+    },
+    required: ["series"],
+    additionalProperties: false
+  },
+  plan: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      steps: {
+        type: "array",
+        maxItems: 10,
+        items: {
+          type: "object",
+          properties: {
+            text: {
+              type: "string"
+            },
+            state: {
+              type: "string",
+              enum: ["todo", "running", "done", "failed"]
+            }
+          },
+          required: ["text"]
+        }
+      },
+      pending: {
+        type: "boolean"
+      },
+      actions: {
+        type: "array",
+        maxItems: CAPS.actions,
+        items: action
+      }
+    },
+    required: ["title", "steps"],
+    additionalProperties: false
+  },
+  finding: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string"
+      },
+      evidence: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            label: {
+              type: "string"
+            },
+            value: {
+              type: "string"
+            },
+            tone
+          },
+          required: ["label", "value"]
+        }
+      },
+      actions: {
+        type: "array",
+        maxItems: CAPS.actions,
+        items: action
+      }
+    },
+    required: ["title", "evidence"],
+    additionalProperties: false
+  }
+};
+const KIND_HELP = {
+  choice: "ASK the user to pick one of 2–5 options when a request could mean different things. Ends your turn; their pick comes back as their next message.",
+  confirm: "ASK before a change you are guessing at (a shape you haven't read, a user you invented, anything destructive). Ends your turn.",
+  input: "ASK for one value you need (an order id, a quantity). Ends your turn.",
+  table: "Show rows of comparable facts — prices before/after, requests, counts. ≤4 columns, ≤8 rows; put the rest in total.",
+  keyValue: "Show one record's fields — a profile, a store's state, a stored value.",
+  list: "Show several things with a title each — items, orders, users. Add image only from URLs you read. Each item may carry one action.",
+  imageGrid: "Show pictures — menu items, loaded images. Only URLs you read from the app this turn. ≤24; grid up to 6, carousel after.",
+  diff: "Show what changed: path, before, after. Use for compare questions and after any write.",
+  chart: "Show numbers side by side as bars — render counts, timings, sizes. ≤8 bars.",
+  steps: "Show a procedure or a plan as a checklist (to reproduce, to test).",
+  code: "Show a raw value only when the user asked for the raw thing.",
+  actions: "Offer up to two buttons for what to do next instead of writing 'say X and I'll…'. Use send for a chat reply, dispatch to run an action directly, minimize to let them look at the app.",
+  finding: "Report something worth filing: a title plus evidence rows (request → status, screen → what it showed). Add a button to reproduce or open the tool.",
+  suggestions: "Offer 2–4 follow-up questions the user might ask next. Put it last.",
+  multiSelect: "ASK the user to pick several (which stores, which keys). Ends your turn.",
+  select: "ASK the user to pick one from a long list (routes, stores) — searchable. Ends your turn.",
+  slider: "ASK for a number in a range (a delay, a quantity). Ends your turn.",
+  dateTime: "ASK for a date or time. Ends your turn.",
+  form: "ASK for several coupled values at once. Ends your turn.",
+  proposal: "ASK to approve a change whose values the user may edit first. Ends your turn.",
+  claim: "State one fact with the evidence chips it rests on and a Verify button that re-reads it.",
+  details: "A collapsed detail the user can open — long explanations, raw values.",
+  compare: "Two things side by side with differences highlighted.",
+  card: "One entity: title, image, facts, up to two actions.",
+  cardCarousel: "3–8 cards to scan and pick from (scenarios, snapshots, items).",
+  sparkline: "A series over time — FPS, memory, request timing.",
+  plan: "Before multi-step work: the steps you intend, with Go/Stop. Update states as you go."
+};
+
+/** The provider-facing tool definition. */
+export function uiProviderTool() {
+  const kinds = MODEL_KINDS.join(" | ");
+  const help = MODEL_KINDS.map(k => `- ${k}: ${KIND_HELP[k]}`).join("\n");
+  return {
+    name: UI_TOOL_NAME,
+    description: `Show the user something richer than text, or ask them something. Blocks render inline in the chat, ABOVE your text — so your text should say what the block means, never repeat it. Kinds: ${kinds}.\n${help}\n\nRules: choice/confirm/input END your turn — send them last, alone, with no other tool calls, and the answer arrives as the user's next message. Never put URLs, ids or numbers in a block that you did not read from a tool result this turn. Prefer the smallest block that answers.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: [...MODEL_KINDS],
+          description: "The block kind."
+        },
+        params: {
+          type: "object",
+          description: "The block's fields; see the kind's schema."
+        }
+      },
+      required: ["action", "params"],
+      additionalProperties: false
+    }
+  };
+}
+let seq = 0;
+
+/** Validate a `buoy_ui` call and build the block. */
+/**
+ * Accept the shape models actually send for a confirm. `message` is the
+ * near-universal field name, and `title` alone is a perfectly clear ask —
+ * so fold them into the block's own vocabulary rather than bouncing the
+ * call. Returns null only when there is genuinely nothing to agree to.
+ */
+function normaliseConfirm(params) {
+  const str = v => typeof v === "string" && v.trim() ? v.trim() : undefined;
+  const {
+    message,
+    ...rest
+  } = params;
+  const change = str(rest.change) ?? str(message) ?? str(rest.title);
+  if (!change) return null;
+  // When both arrived, the one we didn't use as `change` still carries
+  // meaning — keep it as the consequence line rather than dropping it.
+  const spare = str(rest.change) ? str(message) : undefined;
+  return {
+    ...rest,
+    title: str(rest.title) ?? "Confirm",
+    change,
+    consequence: str(rest.consequence) ?? spare
+  };
+}
+
+/** Accept `title` where the schema says `question` — see normaliseConfirm. */
+function normaliseChoice(params) {
+  const str = v => typeof v === "string" && v.trim() ? v.trim() : undefined;
+  const {
+    title,
+    ...rest
+  } = params;
+  const question = str(rest.question) ?? str(title);
+  if (!question) return null;
+  return {
+    ...rest,
+    question
+  };
+}
+export function buildUiBlock(input) {
+  const kind = input.action;
+  if (!kind || !MODEL_KINDS.includes(kind)) {
+    return {
+      ok: false,
+      errors: [`"action" must be one of: ${MODEL_KINDS.join(", ")}`]
+    };
+  }
+  const schema = UI_PARAMS[kind];
+  const check = validateParams(input.params, schema);
+  if (!check.ok) return {
+    ok: false,
+    errors: check.errors
+  };
+  let params = input.params ?? {};
+  if (kind === "choice") {
+    const fixed = normaliseChoice(params);
+    if (!fixed) {
+      return {
+        ok: false,
+        errors: ['choice needs the question being asked: pass `question` (or `title`), e.g. { "question": "Which checkout?", "options": [...] }']
+      };
+    }
+    params = fixed;
+  }
+  if (kind === "confirm") {
+    const fixed = normaliseConfirm(params);
+    if (!fixed) {
+      return {
+        ok: false,
+        errors: ['confirm needs what the user is agreeing to: pass `change` (or `message`), e.g. { "change": "Wipe all app storage", "consequence": "This cannot be undone." }']
+      };
+    }
+    params = fixed;
+  }
+  const block = {
+    ...params,
+    kind,
+    id: `ui${++seq}`,
+    source: "model"
+  };
+  return {
+    ok: true,
+    errors: [],
+    block
+  };
+}
+//# sourceMappingURL=uiTool.js.map