@stina/extension-api 0.56.0 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stina/extension-api",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/schemas/card.schema.ts

@@ -578,7 +578,7 @@ export function validateChatCard(card: unknown): ChatCardValidation {
 // -----------------------------------------------------------------------------
 
 /**
- * Render one field's type compactly: `line|bar|area`, `number?`, `{a, b?}[]`.
+ * Render one field's type compactly: `line|bar|area`, `number?`, `{a, b?}[≤24]`.
  *
  * Enough for a reader to write a valid value, and short enough that the whole
  * vocabulary fits in a tool description without crowding out everything else
@@ -597,7 +597,12 @@ function describeType(schema: z.ZodTypeAny): string {
       return 'component[]'
     case 'ZodArray': {
       const inner = describeType((def as { type: z.ZodTypeAny }).type)
-      return `${inner}[]`
+      // The cap belongs in the vocabulary. A model writing a card from a tool's
+      // data has no other way to learn that a forecast takes 24 steps and not
+      // the 48 hours it is holding, and finds out by having the whole card
+      // refused — which is the expensive way to be told.
+      const max = (def as { maxLength?: { value: number } | null }).maxLength?.value
+      return typeof max === 'number' ? `${inner}[≤${max}]` : `${inner}[]`
     }
     case 'ZodObject': {
       const shape = (schema as unknown as z.AnyZodObject).shape

package/src/types.tools.ts

@@ -52,8 +52,27 @@ export interface ToolResult {
    * Validate with `validateChatCard` before returning one. A card that fails the
    * profile is dropped by the host rather than half-rendered, so a tool that
    * skips the check finds out from the user, which is the wrong end.
+   *
+   * Most tools should prefer {@link ToolResult.cardSuggestion}: a card drawn here
+   * is shown whatever the user asked, and a timeline of ten mails is the wrong
+   * answer to "did Anna write back?".
    */
   display?: ExtensionComponentData
+
+  /**
+   * The shape this tool thinks its answer has: one component name from the chat
+   * card profile, such as `"Timeline"` or `"WeatherForecast"`.
+   *
+   * A suggestion, not a drawing. It travels to the model with the result, and
+   * Stina decides whether to show a card at all, what goes in it, and how much of
+   * the data belongs there — summing three days into one figure, or answering in
+   * a sentence because the user asked a yes-or-no question. The tool knows the
+   * shape of its data; only she knows the shape of the question.
+   *
+   * A name outside the profile is dropped by the host with a warning, since it
+   * would send her after a component that does not exist.
+   */
+  cardSuggestion?: string
 }
 
 /**