@stina/extension-api 0.57.0 → 1.0.0

package/dist/{types.tools-BL9WPsi_.d.cts → types.tools-CQrbET-n.d.cts}

@@ -581,6 +581,50 @@ interface StatTileProps extends ExtensionComponentData {
      */
     trendIsGood?: boolean;
 }
+/** Whether a progress reading is drawn as a rail or as a ring. */
+type ProgressShape = 'bar' | 'circle';
+/**
+ * The colours a progress reading may take.
+ *
+ * A closed list rather than a colour string: the caller is usually a language
+ * model, and the six names here are the six the themes actually define, so a
+ * reading cannot end up in a hue the current theme has no contrast for.
+ */
+type ProgressColor = 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'neutral';
+/**
+ * The extension API properties for the ProgressBar component.
+ *
+ * One value seen against the range it lives in — how far along something is,
+ * how loaded a day looks, how high a level sits. A StatTile says what the
+ * number *is*; this says where it *sits*, which is the thing a number alone
+ * cannot show.
+ *
+ * `min` and `max` are the range, not decoration: a value is drawn as its
+ * position between them, so "3 of 5" and "60 of 100" fill the same amount.
+ * Values outside the range are clamped rather than refused — a reading that
+ * ran past its ceiling should still draw as full.
+ */
+interface ProgressBarProps extends ExtensionComponentData {
+    component: 'ProgressBar';
+    /** What is being measured, e.g. "Stressnivå". Shown beside the reading. */
+    label: string;
+    value: number;
+    /** Bottom of the range. Defaults to 0. */
+    min?: number;
+    /** Top of the range. Defaults to 100. */
+    max?: number;
+    /** Defaults to `bar`. */
+    shape?: ProgressShape;
+    /** Defaults to `accent`. */
+    color?: ProgressColor;
+    /** Written after the value, e.g. `%` or ` av 5`. */
+    unit?: string;
+    /** The readout in words, when the bare number does not say it. Replaces value and unit. */
+    valueLabel?: string;
+    /** One quiet line under the reading. */
+    caption?: string;
+    icon?: HugeIconName;
+}
 /** One row of a KeyValueList. */
 interface KeyValueRow {
     label: string;
@@ -721,6 +765,8 @@ interface CalendarEventProps extends ExtensionComponentData {
 interface ExtensionContributions {
     /** Tool settings views for UI */
     toolSettings?: ToolSettingsViewDefinition[];
+    /** Cards for the strip above the conversation list */
+    statusCards?: StatusCardDefinition[];
     /** Right panel contributions */
     panels?: PanelDefinition[];
     /** AI providers */
@@ -861,6 +907,38 @@ interface PanelDefinition {
     /** Panel view schema */
     view: PanelView;
 }
+/**
+ * A card for the strip above the conversation list.
+ *
+ * The same declarative machinery as a panel, in a much smaller space and with
+ * one rule that is not a style guide: a card says what is true right now. It
+ * has no controls, because a sidebar is read in passing and anything the user
+ * wants to do about what it says, they say in words.
+ *
+ * The user chooses which cards they want and in what order, so an extension
+ * offering three is offering three, not imposing them.
+ */
+interface StatusCardDefinition {
+    /** Unique card ID within the extension */
+    id: string;
+    /** What it is called where the user picks it */
+    title: string;
+    /** Icon name (from huge-icons) */
+    icon?: string;
+    /**
+     * How much room it may take.
+     *
+     * Part of the contract rather than a guideline, because the sidebar is a few
+     * hundred pixels wide and the first card written without a limit will be
+     * written against a screen.
+     *
+     * - `line`: one row. A figure, a label, a pill.
+     * - `block`: up to three rows.
+     */
+    size: 'line' | 'block';
+    /** What it draws, and where the data comes from */
+    view: PanelComponentView;
+}
 /**
  * Panel view schema (declarative)
  */
@@ -2242,8 +2320,26 @@ 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;
 }
 /**
  * Action implementation for UI interactions.
@@ -2271,4 +2367,4 @@ interface ActionResult {
     error?: string;
 }
 
-export { type BackgroundTaskHealth as $, type ActionResult as A, type EventsAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type SchedulerAPI as F, type GetModelsOptions as G, type HugeIconName as H, type SchedulerJobRequest as I, type SchedulerSchedule as J, type UserProfile as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type ChatAPI as O, type PanelDefinition as P, type ChatInstructionMessage as Q, type ConversationPresentation as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type VoiceSessionOptions as V, type LogAPI as W, type BackgroundWorkersAPI as X, type BackgroundTaskConfig as Y, type BackgroundTaskCallback as Z, type BackgroundTaskContext as _, type ChatOptions as a, type ChartProps as a$, type BackgroundRestartPolicy as a0, type Query as a1, type QueryOptions as a2, type StorageAPI as a3, type SecretsAPI as a4, type StorageCollectionConfig as a5, type StorageContributions as a6, type AIProvider as a7, type ModelCapabilities as a8, type ChatImage as a9, type HorizontalStackProps as aA, type GridProps as aB, type DividerProps as aC, type IconProps as aD, type IconButtonType as aE, type IconButtonProps as aF, type PanelAction as aG, type PanelProps as aH, type ToggleProps as aI, type CollapsibleProps as aJ, type FrameVariant as aK, type FrameProps as aL, type ListProps as aM, type PillVariant as aN, type PillProps as aO, type CheckboxProps as aP, type MarkdownProps as aQ, type TextPreviewProps as aR, type ModalProps as aS, type ConditionalGroupProps as aT, type WeatherCondition as aU, type WeatherWind as aV, type WeatherNowProps as aW, type WeatherForecastStep as aX, type WeatherForecastProps as aY, type ChartKind as aZ, type ChartSeries as a_, type ToolCall as aa, type VoiceTransportRequest as ab, type Tool as ac, type Action as ad, type ExtensionModule as ae, type AllowedCSSProperty as af, type ExtensionComponentStyle as ag, type ExtensionComponentData as ah, type ExtensionComponentIterator as ai, type ExtensionComponentChildren as aj, type ExtensionActionCall as ak, type ExtensionActionRef as al, type ExtensionDataSource as am, type ExtensionPanelDefinition as an, type HeaderProps as ao, type LabelProps as ap, type ParagraphProps as aq, type ButtonProps as ar, type TextInputProps as as, type PasswordInputProps as at, type NumberInputProps as au, type TextAreaProps as av, type DateTimeInputProps as aw, type SelectProps as ax, type IconPickerProps as ay, type VerticalStackProps as az, type StreamEvent as b, type StatTrend as b0, type StatTileProps as b1, type KeyValueRow as b2, type KeyValueListProps as b3, type TimelineVariant as b4, type TimelineEntry as b5, type TimelineProps as b6, type NoteVariant as b7, type NoteProps as b8, type CalendarEventStatus as b9, type CalendarEventProps as ba, type ExecutionContext as bb, type VoiceSessionDescriptor as c, type ToolSettingsViewDefinition as d, type ToolSettingsView as e, type ToolSettingsListView as f, type ToolSettingsListMapping as g, type ToolSettingsComponentView as h, type ToolSettingsActionDataSource as i, type PanelView as j, type PanelComponentView as k, type PanelActionDataSource as l, type PanelUnknownView as m, type ProviderDefinition as n, type ProviderConfigView as o, type PromptContribution as p, type PromptSection as q, resolveLocalizedString as r, type ToolDefinition as s, type ToolConfirmationConfig as t, type CommandDefinition as u, type ExtensionContext as v, type SettingsAPI as w, type ProvidersAPI as x, type ToolsAPI as y, type ActionsAPI as z };
+export { type BackgroundTaskContext as $, type ActionResult as A, type ActionsAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type EventsAPI as F, type GetModelsOptions as G, type HugeIconName as H, type SchedulerAPI as I, type SchedulerJobRequest as J, type SchedulerSchedule as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type UserProfile as O, type PanelDefinition as P, type ChatAPI as Q, type ChatInstructionMessage as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type VoiceSessionOptions as V, type ConversationPresentation as W, type LogAPI as X, type BackgroundWorkersAPI as Y, type BackgroundTaskConfig as Z, type BackgroundTaskCallback as _, type ChatOptions as a, type ChartSeries as a$, type BackgroundTaskHealth as a0, type BackgroundRestartPolicy as a1, type Query as a2, type QueryOptions as a3, type StorageAPI as a4, type SecretsAPI as a5, type StorageCollectionConfig as a6, type StorageContributions as a7, type AIProvider as a8, type ModelCapabilities as a9, type VerticalStackProps as aA, type HorizontalStackProps as aB, type GridProps as aC, type DividerProps as aD, type IconProps as aE, type IconButtonType as aF, type IconButtonProps as aG, type PanelAction as aH, type PanelProps as aI, type ToggleProps as aJ, type CollapsibleProps as aK, type FrameVariant as aL, type FrameProps as aM, type ListProps as aN, type PillVariant as aO, type PillProps as aP, type CheckboxProps as aQ, type MarkdownProps as aR, type TextPreviewProps as aS, type ModalProps as aT, type ConditionalGroupProps as aU, type WeatherCondition as aV, type WeatherWind as aW, type WeatherNowProps as aX, type WeatherForecastStep as aY, type WeatherForecastProps as aZ, type ChartKind as a_, type ChatImage as aa, type ToolCall as ab, type VoiceTransportRequest as ac, type Tool as ad, type Action as ae, type ExtensionModule as af, type AllowedCSSProperty as ag, type ExtensionComponentStyle as ah, type ExtensionComponentData as ai, type ExtensionComponentIterator as aj, type ExtensionComponentChildren as ak, type ExtensionActionCall as al, type ExtensionActionRef as am, type ExtensionDataSource as an, type ExtensionPanelDefinition as ao, type HeaderProps as ap, type LabelProps as aq, type ParagraphProps as ar, type ButtonProps as as, type TextInputProps as at, type PasswordInputProps as au, type NumberInputProps as av, type TextAreaProps as aw, type DateTimeInputProps as ax, type SelectProps as ay, type IconPickerProps as az, type StreamEvent as b, type ChartProps as b0, type StatTrend as b1, type StatTileProps as b2, type ProgressShape as b3, type ProgressColor as b4, type ProgressBarProps as b5, type KeyValueRow as b6, type KeyValueListProps as b7, type TimelineVariant as b8, type TimelineEntry as b9, type TimelineProps as ba, type NoteVariant as bb, type NoteProps as bc, type CalendarEventStatus as bd, type CalendarEventProps as be, type ExecutionContext as bf, type VoiceSessionDescriptor as c, type ToolSettingsViewDefinition as d, type ToolSettingsView as e, type ToolSettingsListView as f, type ToolSettingsListMapping as g, type ToolSettingsComponentView as h, type ToolSettingsActionDataSource as i, type StatusCardDefinition as j, type PanelView as k, type PanelComponentView as l, type PanelActionDataSource as m, type PanelUnknownView as n, type ProviderDefinition as o, type ProviderConfigView as p, type PromptContribution as q, resolveLocalizedString as r, type PromptSection as s, type ToolDefinition as t, type ToolConfirmationConfig as u, type CommandDefinition as v, type ExtensionContext as w, type SettingsAPI as x, type ProvidersAPI as y, type ToolsAPI as z };

package/dist/{types.tools-BL9WPsi_.d.ts → types.tools-CQrbET-n.d.ts}

@@ -581,6 +581,50 @@ interface StatTileProps extends ExtensionComponentData {
      */
     trendIsGood?: boolean;
 }
+/** Whether a progress reading is drawn as a rail or as a ring. */
+type ProgressShape = 'bar' | 'circle';
+/**
+ * The colours a progress reading may take.
+ *
+ * A closed list rather than a colour string: the caller is usually a language
+ * model, and the six names here are the six the themes actually define, so a
+ * reading cannot end up in a hue the current theme has no contrast for.
+ */
+type ProgressColor = 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'neutral';
+/**
+ * The extension API properties for the ProgressBar component.
+ *
+ * One value seen against the range it lives in — how far along something is,
+ * how loaded a day looks, how high a level sits. A StatTile says what the
+ * number *is*; this says where it *sits*, which is the thing a number alone
+ * cannot show.
+ *
+ * `min` and `max` are the range, not decoration: a value is drawn as its
+ * position between them, so "3 of 5" and "60 of 100" fill the same amount.
+ * Values outside the range are clamped rather than refused — a reading that
+ * ran past its ceiling should still draw as full.
+ */
+interface ProgressBarProps extends ExtensionComponentData {
+    component: 'ProgressBar';
+    /** What is being measured, e.g. "Stressnivå". Shown beside the reading. */
+    label: string;
+    value: number;
+    /** Bottom of the range. Defaults to 0. */
+    min?: number;
+    /** Top of the range. Defaults to 100. */
+    max?: number;
+    /** Defaults to `bar`. */
+    shape?: ProgressShape;
+    /** Defaults to `accent`. */
+    color?: ProgressColor;
+    /** Written after the value, e.g. `%` or ` av 5`. */
+    unit?: string;
+    /** The readout in words, when the bare number does not say it. Replaces value and unit. */
+    valueLabel?: string;
+    /** One quiet line under the reading. */
+    caption?: string;
+    icon?: HugeIconName;
+}
 /** One row of a KeyValueList. */
 interface KeyValueRow {
     label: string;
@@ -721,6 +765,8 @@ interface CalendarEventProps extends ExtensionComponentData {
 interface ExtensionContributions {
     /** Tool settings views for UI */
     toolSettings?: ToolSettingsViewDefinition[];
+    /** Cards for the strip above the conversation list */
+    statusCards?: StatusCardDefinition[];
     /** Right panel contributions */
     panels?: PanelDefinition[];
     /** AI providers */
@@ -861,6 +907,38 @@ interface PanelDefinition {
     /** Panel view schema */
     view: PanelView;
 }
+/**
+ * A card for the strip above the conversation list.
+ *
+ * The same declarative machinery as a panel, in a much smaller space and with
+ * one rule that is not a style guide: a card says what is true right now. It
+ * has no controls, because a sidebar is read in passing and anything the user
+ * wants to do about what it says, they say in words.
+ *
+ * The user chooses which cards they want and in what order, so an extension
+ * offering three is offering three, not imposing them.
+ */
+interface StatusCardDefinition {
+    /** Unique card ID within the extension */
+    id: string;
+    /** What it is called where the user picks it */
+    title: string;
+    /** Icon name (from huge-icons) */
+    icon?: string;
+    /**
+     * How much room it may take.
+     *
+     * Part of the contract rather than a guideline, because the sidebar is a few
+     * hundred pixels wide and the first card written without a limit will be
+     * written against a screen.
+     *
+     * - `line`: one row. A figure, a label, a pill.
+     * - `block`: up to three rows.
+     */
+    size: 'line' | 'block';
+    /** What it draws, and where the data comes from */
+    view: PanelComponentView;
+}
 /**
  * Panel view schema (declarative)
  */
@@ -2242,8 +2320,26 @@ 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;
 }
 /**
  * Action implementation for UI interactions.
@@ -2271,4 +2367,4 @@ interface ActionResult {
     error?: string;
 }
 
-export { type BackgroundTaskHealth as $, type ActionResult as A, type EventsAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type SchedulerAPI as F, type GetModelsOptions as G, type HugeIconName as H, type SchedulerJobRequest as I, type SchedulerSchedule as J, type UserProfile as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type ChatAPI as O, type PanelDefinition as P, type ChatInstructionMessage as Q, type ConversationPresentation as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type VoiceSessionOptions as V, type LogAPI as W, type BackgroundWorkersAPI as X, type BackgroundTaskConfig as Y, type BackgroundTaskCallback as Z, type BackgroundTaskContext as _, type ChatOptions as a, type ChartProps as a$, type BackgroundRestartPolicy as a0, type Query as a1, type QueryOptions as a2, type StorageAPI as a3, type SecretsAPI as a4, type StorageCollectionConfig as a5, type StorageContributions as a6, type AIProvider as a7, type ModelCapabilities as a8, type ChatImage as a9, type HorizontalStackProps as aA, type GridProps as aB, type DividerProps as aC, type IconProps as aD, type IconButtonType as aE, type IconButtonProps as aF, type PanelAction as aG, type PanelProps as aH, type ToggleProps as aI, type CollapsibleProps as aJ, type FrameVariant as aK, type FrameProps as aL, type ListProps as aM, type PillVariant as aN, type PillProps as aO, type CheckboxProps as aP, type MarkdownProps as aQ, type TextPreviewProps as aR, type ModalProps as aS, type ConditionalGroupProps as aT, type WeatherCondition as aU, type WeatherWind as aV, type WeatherNowProps as aW, type WeatherForecastStep as aX, type WeatherForecastProps as aY, type ChartKind as aZ, type ChartSeries as a_, type ToolCall as aa, type VoiceTransportRequest as ab, type Tool as ac, type Action as ad, type ExtensionModule as ae, type AllowedCSSProperty as af, type ExtensionComponentStyle as ag, type ExtensionComponentData as ah, type ExtensionComponentIterator as ai, type ExtensionComponentChildren as aj, type ExtensionActionCall as ak, type ExtensionActionRef as al, type ExtensionDataSource as am, type ExtensionPanelDefinition as an, type HeaderProps as ao, type LabelProps as ap, type ParagraphProps as aq, type ButtonProps as ar, type TextInputProps as as, type PasswordInputProps as at, type NumberInputProps as au, type TextAreaProps as av, type DateTimeInputProps as aw, type SelectProps as ax, type IconPickerProps as ay, type VerticalStackProps as az, type StreamEvent as b, type StatTrend as b0, type StatTileProps as b1, type KeyValueRow as b2, type KeyValueListProps as b3, type TimelineVariant as b4, type TimelineEntry as b5, type TimelineProps as b6, type NoteVariant as b7, type NoteProps as b8, type CalendarEventStatus as b9, type CalendarEventProps as ba, type ExecutionContext as bb, type VoiceSessionDescriptor as c, type ToolSettingsViewDefinition as d, type ToolSettingsView as e, type ToolSettingsListView as f, type ToolSettingsListMapping as g, type ToolSettingsComponentView as h, type ToolSettingsActionDataSource as i, type PanelView as j, type PanelComponentView as k, type PanelActionDataSource as l, type PanelUnknownView as m, type ProviderDefinition as n, type ProviderConfigView as o, type PromptContribution as p, type PromptSection as q, resolveLocalizedString as r, type ToolDefinition as s, type ToolConfirmationConfig as t, type CommandDefinition as u, type ExtensionContext as v, type SettingsAPI as w, type ProvidersAPI as x, type ToolsAPI as y, type ActionsAPI as z };
+export { type BackgroundTaskContext as $, type ActionResult as A, type ActionsAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type EventsAPI as F, type GetModelsOptions as G, type HugeIconName as H, type SchedulerAPI as I, type SchedulerJobRequest as J, type SchedulerSchedule as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type UserProfile as O, type PanelDefinition as P, type ChatAPI as Q, type ChatInstructionMessage as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type VoiceSessionOptions as V, type ConversationPresentation as W, type LogAPI as X, type BackgroundWorkersAPI as Y, type BackgroundTaskConfig as Z, type BackgroundTaskCallback as _, type ChatOptions as a, type ChartSeries as a$, type BackgroundTaskHealth as a0, type BackgroundRestartPolicy as a1, type Query as a2, type QueryOptions as a3, type StorageAPI as a4, type SecretsAPI as a5, type StorageCollectionConfig as a6, type StorageContributions as a7, type AIProvider as a8, type ModelCapabilities as a9, type VerticalStackProps as aA, type HorizontalStackProps as aB, type GridProps as aC, type DividerProps as aD, type IconProps as aE, type IconButtonType as aF, type IconButtonProps as aG, type PanelAction as aH, type PanelProps as aI, type ToggleProps as aJ, type CollapsibleProps as aK, type FrameVariant as aL, type FrameProps as aM, type ListProps as aN, type PillVariant as aO, type PillProps as aP, type CheckboxProps as aQ, type MarkdownProps as aR, type TextPreviewProps as aS, type ModalProps as aT, type ConditionalGroupProps as aU, type WeatherCondition as aV, type WeatherWind as aW, type WeatherNowProps as aX, type WeatherForecastStep as aY, type WeatherForecastProps as aZ, type ChartKind as a_, type ChatImage as aa, type ToolCall as ab, type VoiceTransportRequest as ac, type Tool as ad, type Action as ae, type ExtensionModule as af, type AllowedCSSProperty as ag, type ExtensionComponentStyle as ah, type ExtensionComponentData as ai, type ExtensionComponentIterator as aj, type ExtensionComponentChildren as ak, type ExtensionActionCall as al, type ExtensionActionRef as am, type ExtensionDataSource as an, type ExtensionPanelDefinition as ao, type HeaderProps as ap, type LabelProps as aq, type ParagraphProps as ar, type ButtonProps as as, type TextInputProps as at, type PasswordInputProps as au, type NumberInputProps as av, type TextAreaProps as aw, type DateTimeInputProps as ax, type SelectProps as ay, type IconPickerProps as az, type StreamEvent as b, type ChartProps as b0, type StatTrend as b1, type StatTileProps as b2, type ProgressShape as b3, type ProgressColor as b4, type ProgressBarProps as b5, type KeyValueRow as b6, type KeyValueListProps as b7, type TimelineVariant as b8, type TimelineEntry as b9, type TimelineProps as ba, type NoteVariant as bb, type NoteProps as bc, type CalendarEventStatus as bd, type CalendarEventProps as be, type ExecutionContext as bf, type VoiceSessionDescriptor as c, type ToolSettingsViewDefinition as d, type ToolSettingsView as e, type ToolSettingsListView as f, type ToolSettingsListMapping as g, type ToolSettingsComponentView as h, type ToolSettingsActionDataSource as i, type StatusCardDefinition as j, type PanelView as k, type PanelComponentView as l, type PanelActionDataSource as m, type PanelUnknownView as n, type ProviderDefinition as o, type ProviderConfigView as p, type PromptContribution as q, resolveLocalizedString as r, type PromptSection as s, type ToolDefinition as t, type ToolConfirmationConfig as u, type CommandDefinition as v, type ExtensionContext as w, type SettingsAPI as x, type ProvidersAPI as y, type ToolsAPI as z };

package/package.json

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

package/schema/extension-manifest.schema.json

@@ -119,6 +119,7 @@
                   "settings.register",
                   "commands.register",
                   "panels.register",
+                  "statusCards.register",
                   "events.emit",
                   "scheduler.register",
                   "background.workers",
@@ -564,6 +565,63 @@
               },
               "description": "Right panel contributions"
             },
+            "statusCards": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "Unique card ID within the extension"
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "What it is called where the user picks it"
+                  },
+                  "icon": {
+                    "type": "string",
+                    "description": "Icon name (from huge-icons)"
+                  },
+                  "size": {
+                    "type": "string",
+                    "enum": [
+                      "line",
+                      "block"
+                    ],
+                    "description": "How much room it may take: one row, or up to three"
+                  },
+                  "view": {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "$ref": "#/definitions/ExtensionManifest/properties/contributes/properties/panels/items/properties/view/anyOf/0/properties/kind"
+                      },
+                      "data": {
+                        "$ref": "#/definitions/ExtensionManifest/properties/contributes/properties/panels/items/properties/view/anyOf/0/properties/data"
+                      },
+                      "content": {
+                        "$ref": "#/definitions/ExtensionManifest/properties/contributes/properties/panels/items/properties/view/anyOf/0/properties/content"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "content"
+                    ],
+                    "additionalProperties": false,
+                    "description": "What it draws, and where the data comes from"
+                  }
+                },
+                "required": [
+                  "id",
+                  "title",
+                  "size",
+                  "view"
+                ],
+                "additionalProperties": false,
+                "description": "Status card definition"
+              },
+              "description": "Cards for the strip above the conversation list"
+            },
             "providers": {
               "type": "array",
               "items": {

package/src/index.ts

@@ -24,6 +24,7 @@ export type {
   ToolSettingsComponentView,
   ToolSettingsActionDataSource,
   PanelDefinition,
+  StatusCardDefinition,
   PanelView,
   PanelComponentView,
   PanelActionDataSource,
@@ -203,6 +204,9 @@ export type {
   ChartProps,
   StatTrend,
   StatTileProps,
+  ProgressShape,
+  ProgressColor,
+  ProgressBarProps,
   KeyValueRow,
   KeyValueListProps,
   TimelineVariant,

package/src/schemas/card.schema.ts

@@ -34,6 +34,8 @@ import {
   WeatherWindSchema,
   ChartKindSchema,
   StatTrendSchema,
+  ProgressShapeSchema,
+  ProgressColorSchema,
   TimelineVariantSchema,
   NoteVariantSchema,
   CalendarEventStatusSchema,
@@ -259,6 +261,23 @@ const StatTileCardSchema = z
   })
   .strict()
 
+const ProgressBarCardSchema = z
+  .object({
+    component: z.literal('ProgressBar'),
+    label: z.string(),
+    value: z.number(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+    shape: ProgressShapeSchema.optional(),
+    color: ProgressColorSchema.optional(),
+    unit: z.string().optional(),
+    valueLabel: z.string().optional(),
+    caption: z.string().optional(),
+    icon: z.string().optional(),
+    style,
+  })
+  .strict()
+
 const KeyValueListCardSchema = z
   .object({
     component: z.literal('KeyValueList'),
@@ -350,6 +369,7 @@ export const CHAT_CARD_COMPONENTS = [
   'WeatherForecast',
   'Chart',
   'StatTile',
+  'ProgressBar',
   'KeyValueList',
   'Timeline',
   'Note',
@@ -382,12 +402,35 @@ const CARD_MEMBERS = [
   WeatherForecastCardSchema,
   ChartCardSchema,
   StatTileCardSchema,
+  ProgressBarCardSchema,
   KeyValueListCardSchema,
   TimelineCardSchema,
   NoteCardSchema,
   CalendarEventCardSchema,
 ] as const
 
+/**
+ * The properties each card component accepts, read off the schemas themselves.
+ *
+ * Derived rather than listed, for the same reason `describeChatCardProfile`
+ * is: a hand-kept copy of this drifts, and a drifted copy rejects components
+ * that are in fact legal.
+ *
+ * Used by profiles that validate a card *template* rather than a finished card
+ * — the status card, whose leaves are references to data that does not exist
+ * yet and so cannot be type-checked by these schemas. They can still be held to
+ * this vocabulary, which is what catches a property the model invented.
+ */
+export const CHAT_CARD_PROPS: Readonly<Record<string, readonly string[]>> = Object.freeze(
+  Object.fromEntries(
+    CARD_MEMBERS.map((member) => {
+      const shape = (member as unknown as z.AnyZodObject).shape as Record<string, z.ZodTypeAny>
+      const name = (shape['component']!._def as { value: string }).value
+      return [name, Object.freeze(Object.keys(shape))]
+    })
+  )
+)
+
 /**
  * One component of a chat card.
  *
@@ -578,7 +621,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 +640,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/schemas/components.schema.ts

@@ -651,6 +651,32 @@ export const StatTilePropsSchema = z
   .passthrough()
   .describe('Single-number stat tile component')
 
+export const ProgressShapeSchema = z
+  .enum(['bar', 'circle'])
+  .describe('Drawn as a rail or as a ring')
+
+export const ProgressColorSchema = z
+  .enum(['accent', 'success', 'warning', 'danger', 'info', 'neutral'])
+  .describe('One of the theme colours')
+
+export const ProgressBarPropsSchema = z
+  .object({
+    component: z.literal('ProgressBar'),
+    label: z.string().describe('What is being measured'),
+    value: z.number().describe('Where the reading sits. Clamped to the range'),
+    min: z.number().optional().describe('Bottom of the range. Defaults to 0'),
+    max: z.number().optional().describe('Top of the range. Defaults to 100'),
+    shape: ProgressShapeSchema.optional().describe('Defaults to bar'),
+    color: ProgressColorSchema.optional().describe('Defaults to accent'),
+    unit: z.string().optional().describe('Written after the value'),
+    valueLabel: z.string().optional().describe('The readout in words, replacing value and unit'),
+    caption: z.string().optional().describe('One quiet line under the reading'),
+    icon: z.string().optional().describe('Icon name'),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Progress component')
+
 export const KeyValueRowSchema = z
   .object({
     label: z.string(),
@@ -794,6 +820,9 @@ export type ChartSeries = z.infer<typeof ChartSeriesSchema>
 export type ChartProps = z.infer<typeof ChartPropsSchema>
 export type StatTrend = z.infer<typeof StatTrendSchema>
 export type StatTileProps = z.infer<typeof StatTilePropsSchema>
+export type ProgressShape = z.infer<typeof ProgressShapeSchema>
+export type ProgressColor = z.infer<typeof ProgressColorSchema>
+export type ProgressBarProps = z.infer<typeof ProgressBarPropsSchema>
 export type KeyValueRow = z.infer<typeof KeyValueRowSchema>
 export type KeyValueListProps = z.infer<typeof KeyValueListPropsSchema>
 export type TimelineVariant = z.infer<typeof TimelineVariantSchema>

package/src/schemas/contributions.schema.ts

@@ -176,6 +176,27 @@ export const PanelDefinitionSchema = z
   })
   .describe('Panel definition')
 
+/**
+ * A card for the strip above the conversation list.
+ *
+ * Deliberately the panel's component view rather than a profile of its own: a
+ * card and a panel are the same declarative idea at two sizes, and a second
+ * vocabulary would be a second thing to keep in step. `size` is what makes it a
+ * card, and it is checked rather than suggested because the sidebar is a few
+ * hundred pixels wide.
+ */
+export const StatusCardDefinitionSchema = z
+  .object({
+    id: z.string().describe('Unique card ID within the extension'),
+    title: z.string().describe('What it is called where the user picks it'),
+    icon: z.string().optional().describe('Icon name (from huge-icons)'),
+    size: z
+      .enum(['line', 'block'])
+      .describe('How much room it may take: one row, or up to three'),
+    view: PanelComponentViewSchema.describe('What it draws, and where the data comes from'),
+  })
+  .describe('Status card definition')
+
 // =============================================================================
 // Providers
 // =============================================================================
@@ -294,6 +315,10 @@ export const ExtensionContributionsSchema = z
   .object({
     toolSettings: z.array(ToolSettingsViewDefinitionSchema).optional().describe('Tool settings views'),
     panels: z.array(PanelDefinitionSchema).optional().describe('Right panel contributions'),
+    statusCards: z
+      .array(StatusCardDefinitionSchema)
+      .optional()
+      .describe('Cards for the strip above the conversation list'),
     providers: z.array(ProviderDefinitionSchema).optional().describe('AI providers'),
     tools: z.array(ToolDefinitionSchema).optional().describe('Tools for Stina to use'),
     commands: z.array(CommandDefinitionSchema).optional().describe('Slash commands'),
@@ -306,6 +331,7 @@ export const ExtensionContributionsSchema = z
 // Type Exports
 // =============================================================================
 
+export type StatusCardDefinition = z.infer<typeof StatusCardDefinitionSchema>
 export type LocalizedString = z.infer<typeof LocalizedStringSchema>
 export type ToolSettingsListMapping = z.infer<typeof ToolSettingsListMappingSchema>
 export type ToolSettingsActionDataSource = z.infer<typeof ToolSettingsActionDataSourceSchema>

package/src/schemas/index.ts

@@ -47,6 +47,7 @@ export {
   ToolSettingsListMappingSchema,
   ToolSettingsActionDataSourceSchema,
   PanelDefinitionSchema,
+  StatusCardDefinitionSchema,
   PanelViewSchema,
   PanelComponentViewSchema,
   PanelUnknownViewSchema,
@@ -67,6 +68,7 @@ export {
   type ToolSettingsListMapping,
   type ToolSettingsActionDataSource,
   type PanelDefinition,
+  type StatusCardDefinition,
   type PanelView,
   type PanelComponentView,
   type PanelUnknownView,
@@ -128,6 +130,9 @@ export {
   ChartPropsSchema,
   StatTrendSchema,
   StatTilePropsSchema,
+  ProgressShapeSchema,
+  ProgressColorSchema,
+  ProgressBarPropsSchema,
   KeyValueRowSchema,
   KeyValueListPropsSchema,
   TimelineVariantSchema,
@@ -181,8 +186,10 @@ export {
   ChatCardSchema,
   ChatCardComponentSchema,
   CHAT_CARD_COMPONENTS,
+  CHAT_CARD_PROPS,
   validateChatCard,
   describeChatCardProfile,
   type ChatCardComponent,
   type ChatCardValidation,
 } from './card.schema.js'
+

package/src/schemas/permissions.schema.ts

@@ -29,6 +29,7 @@ export const VALID_PERMISSIONS = [
   'settings.register',
   'commands.register',
   'panels.register',
+  'statusCards.register',
   'events.emit',
   'scheduler.register',
   'background.workers',
@@ -90,6 +91,7 @@ const CapabilityPermissionSchema = z
     'settings.register',
     'commands.register',
     'panels.register',
+    'statusCards.register',
     'events.emit',
     'scheduler.register',
     'chat.message.write',