@stina/extension-api 0.52.0 → 0.56.0

package/src/schemas/components.schema.ts

@@ -518,6 +518,228 @@ export const ListPropsSchema = z
   .passthrough()
   .describe('List component')
 
+// =============================================================================
+// Purpose-built Display Components
+// =============================================================================
+
+/**
+ * The skies the weather components know how to draw. Closed on purpose: the
+ * icon is chosen from this list, and a string outside it has no picture.
+ */
+export const WeatherConditionSchema = z
+  .enum([
+    'clear',
+    'partly-cloudy',
+    'cloudy',
+    'overcast',
+    'fog',
+    'light-rain',
+    'rain',
+    'heavy-rain',
+    'sleet',
+    'light-snow',
+    'snow',
+    'heavy-snow',
+    'thunderstorm',
+    'hail',
+    'windy',
+  ])
+  .describe('Weather condition')
+
+export const WeatherWindSchema = z
+  .object({
+    speed: z.number().describe('Sustained wind speed'),
+    unit: z.string().optional().describe('Unit written after the speed. Defaults to m/s'),
+    direction: z.string().optional().describe('Compass direction, in the caller\'s own words'),
+    gust: z.number().optional().describe('Gust speed, in the same unit'),
+  })
+  .passthrough()
+  .describe('Wind reading')
+
+export const WeatherNowPropsSchema = z
+  .object({
+    component: z.literal('WeatherNow'),
+    place: z.string().describe('Where the reading is from'),
+    condition: WeatherConditionSchema,
+    conditionLabel: z.string().optional().describe('The condition in the user\'s own language'),
+    temperature: z.number().describe('Current temperature'),
+    feelsLike: z.number().optional().describe('Apparent temperature'),
+    unit: z.string().optional().describe('Written after every temperature. Defaults to °'),
+    wind: WeatherWindSchema.optional(),
+    night: z.boolean().optional().describe('Draw the night variant of the icon'),
+    summary: z.string().optional().describe('One line of context under the numbers'),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Current weather component')
+
+export const WeatherForecastStepSchema = z
+  .object({
+    label: z.string().describe('Short step label, e.g. 14 or Tors'),
+    condition: WeatherConditionSchema,
+    conditionLabel: z.string().optional(),
+    high: z.number().describe('The warmer temperature, or the only one'),
+    low: z.number().optional().describe('The colder temperature'),
+    night: z.boolean().optional(),
+    precipitation: z.number().min(0).max(100).optional().describe('Chance of precipitation, 0-100'),
+    current: z.boolean().optional().describe('The step the reader is at; drawn larger'),
+  })
+  .passthrough()
+  .describe('One forecast step')
+
+export const WeatherForecastPropsSchema = z
+  .object({
+    component: z.literal('WeatherForecast'),
+    title: z.string().optional().describe('Heading above the row'),
+    icon: z.string().optional().describe('Icon shown to the left of the title'),
+    unit: z.string().optional().describe('Written after every temperature. Defaults to °'),
+    steps: z.array(WeatherForecastStepSchema).min(1).describe('Steps, hourly or daily'),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Weather forecast component')
+
+export const ChartKindSchema = z.enum(['line', 'bar', 'area']).describe('How the chart draws')
+
+export const ChartSeriesSchema = z
+  .object({
+    name: z.string().optional().describe('Named in the legend'),
+    points: z
+      .array(z.number().nullable())
+      .describe('One value per label. null is a gap, drawn as one'),
+  })
+  .passthrough()
+  .describe('One chart series')
+
+/**
+ * Eight series is the ceiling because the host palette has eight slots, assigned
+ * in a fixed order so a series keeps its colour wherever it appears. A ninth
+ * would need a generated hue, and a generated hue is how a chart stops being
+ * readable to colour-blind viewers.
+ */
+export const ChartPropsSchema = z
+  .object({
+    component: z.literal('Chart'),
+    chart: ChartKindSchema.optional().describe('Defaults to line'),
+    series: z.array(ChartSeriesSchema).min(1).max(8).describe('At most eight series'),
+    labels: z.array(z.string()).optional().describe('One per point, along the horizontal axis'),
+    title: z.string().optional().describe('Heading above the plot'),
+    icon: z.string().optional().describe('Icon shown to the left of the title'),
+    unit: z.string().optional().describe('Written after every value'),
+    zeroBaseline: z.boolean().optional().describe('Force the value axis to include zero'),
+    height: z.number().min(4).max(24).optional().describe('Plot height in rem. Defaults to 9'),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Chart component')
+
+export const StatTrendSchema = z.enum(['up', 'down', 'flat']).describe('Direction of change')
+
+export const StatTilePropsSchema = z
+  .object({
+    component: z.literal('StatTile'),
+    label: z.string().describe('What the number is'),
+    value: z.union([z.string(), z.number()]).describe('The number itself'),
+    unit: z.string().optional().describe('Written after the value in smaller type'),
+    caption: z.string().optional().describe('One quiet line under the number'),
+    icon: z.string().optional().describe('Icon name'),
+    trend: StatTrendSchema.optional(),
+    trendLabel: z.string().optional().describe('The change in words'),
+    trendIsGood: z.boolean().optional().describe('Whether up is the good direction. Defaults to true'),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Single-number stat tile component')
+
+export const KeyValueRowSchema = z
+  .object({
+    label: z.string(),
+    value: z.string(),
+    icon: z.string().optional().describe('Icon name'),
+  })
+  .passthrough()
+  .describe('One key/value row')
+
+export const KeyValueListPropsSchema = z
+  .object({
+    component: z.literal('KeyValueList'),
+    rows: z.array(KeyValueRowSchema).min(1).describe('Facts in two aligned columns'),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Key/value list component')
+
+export const TimelineVariantSchema = z
+  .enum(['default', 'accent', 'success', 'warning', 'danger'])
+  .describe('How much a timeline entry stands out')
+
+export const TimelineEntrySchema = z
+  .object({
+    time: z.string().describe('When it happens, worded as it should be read'),
+    title: z.string(),
+    description: z.string().optional().describe('A line under the title'),
+    icon: z.string().optional().describe('Icon name'),
+    duration: z.string().optional().describe('How long it lasts, in words'),
+    badge: z.string().optional().describe('Trailing badge'),
+    current: z.boolean().optional().describe('The entry the reader is at'),
+    past: z.boolean().optional().describe('Already behind us; drawn recessive'),
+    variant: TimelineVariantSchema.optional(),
+  })
+  .passthrough()
+  .describe('One timeline entry')
+
+export const TimelinePropsSchema = z
+  .object({
+    component: z.literal('Timeline'),
+    title: z.string().optional().describe('Heading above the rail'),
+    icon: z.string().optional().describe('Icon shown to the left of the title'),
+    entries: z.array(TimelineEntrySchema).min(1).describe('Entries, in the order they happen'),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Vertical timeline component')
+
+export const NoteVariantSchema = z
+  .enum(['default', 'accent', 'success', 'warning', 'danger'])
+  .describe('How much a note stands out')
+
+export const NotePropsSchema = z
+  .object({
+    component: z.literal('Note'),
+    title: z.string().optional(),
+    icon: z.string().optional().describe('Icon shown to the left of the title'),
+    badge: z.string().optional().describe('Trailing badge next to the title'),
+    content: z.string().describe('The body, as markdown'),
+    footer: z.string().optional().describe('One quiet line at the bottom'),
+    variant: NoteVariantSchema.optional(),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Titled block of prose component')
+
+export const CalendarEventStatusSchema = z
+  .enum(['confirmed', 'tentative', 'cancelled'])
+  .describe('Whether an event is going ahead')
+
+export const CalendarEventPropsSchema = z
+  .object({
+    component: z.literal('CalendarEvent'),
+    title: z.string(),
+    start: z.string().describe('ISO 8601 with an offset'),
+    end: z.string().optional().describe('ISO 8601 with an offset'),
+    allDay: z.boolean().optional(),
+    location: z.string().optional(),
+    organizer: z.string().optional(),
+    attendees: z.array(z.string()).optional(),
+    calendar: z.string().optional().describe('Which calendar it sits in; shown as a badge'),
+    status: CalendarEventStatusSchema.optional(),
+    recurrence: z.string().optional().describe('How it repeats, in words'),
+    notes: z.string().optional(),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Single calendar event component')
+
 // =============================================================================
 // Type Exports
 // =============================================================================
@@ -562,3 +784,22 @@ export type ConditionalGroupProps = z.infer<typeof ConditionalGroupPropsSchema>
 export type FrameVariant = z.infer<typeof FrameVariantSchema>
 export type FrameProps = z.infer<typeof FramePropsSchema>
 export type ListProps = z.infer<typeof ListPropsSchema>
+export type WeatherCondition = z.infer<typeof WeatherConditionSchema>
+export type WeatherWind = z.infer<typeof WeatherWindSchema>
+export type WeatherNowProps = z.infer<typeof WeatherNowPropsSchema>
+export type WeatherForecastStep = z.infer<typeof WeatherForecastStepSchema>
+export type WeatherForecastProps = z.infer<typeof WeatherForecastPropsSchema>
+export type ChartKind = z.infer<typeof ChartKindSchema>
+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 KeyValueRow = z.infer<typeof KeyValueRowSchema>
+export type KeyValueListProps = z.infer<typeof KeyValueListPropsSchema>
+export type TimelineVariant = z.infer<typeof TimelineVariantSchema>
+export type TimelineEntry = z.infer<typeof TimelineEntrySchema>
+export type TimelineProps = z.infer<typeof TimelinePropsSchema>
+export type NoteVariant = z.infer<typeof NoteVariantSchema>
+export type NoteProps = z.infer<typeof NotePropsSchema>
+export type CalendarEventStatus = z.infer<typeof CalendarEventStatusSchema>
+export type CalendarEventProps = z.infer<typeof CalendarEventPropsSchema>

package/src/schemas/index.ts

@@ -118,6 +118,25 @@ export {
   MarkdownPropsSchema,
   ModalPropsSchema,
   ConditionalGroupPropsSchema,
+  WeatherConditionSchema,
+  WeatherWindSchema,
+  WeatherNowPropsSchema,
+  WeatherForecastStepSchema,
+  WeatherForecastPropsSchema,
+  ChartKindSchema,
+  ChartSeriesSchema,
+  ChartPropsSchema,
+  StatTrendSchema,
+  StatTilePropsSchema,
+  KeyValueRowSchema,
+  KeyValueListPropsSchema,
+  TimelineVariantSchema,
+  TimelineEntrySchema,
+  TimelinePropsSchema,
+  NoteVariantSchema,
+  NotePropsSchema,
+  CalendarEventStatusSchema,
+  CalendarEventPropsSchema,
   type ExtensionComponentData,
   type ExtensionComponentStyle,
   type ExtensionActionCall,
@@ -156,3 +175,14 @@ export {
   type ModalProps,
   type ConditionalGroupProps,
 } from './components.schema.js'
+
+// Chat card profile - the subset of the DSL a tool may put in a conversation
+export {
+  ChatCardSchema,
+  ChatCardComponentSchema,
+  CHAT_CARD_COMPONENTS,
+  validateChatCard,
+  describeChatCardProfile,
+  type ChatCardComponent,
+  type ChatCardValidation,
+} from './card.schema.js'

package/src/types.components.ts

@@ -536,3 +536,339 @@ export interface ListProps extends ExtensionComponentData {
   /** Child components to render as list items. Supports iteration. */
   children: ExtensionComponentChildren
 }
+
+// =============================================================================
+// Purpose-built display components
+// =============================================================================
+
+/*
+ * The components below differ in kind from the ones above. Those are building
+ * blocks — a stack, a label, a button — and what they mean is whatever the
+ * author arranges them into. These name a *subject*: weather, a measurement,
+ * a series over time. The caller supplies the facts and the host decides how
+ * they look, which is what lets the same declaration render as HTML on the web
+ * and as native geometry on a phone without either side guessing.
+ *
+ * That is also why they take no colors and no layout. A chart that let its
+ * author pick series colors would be eight different charts across eight
+ * extensions; the palette is the host's, assigned in a fixed order, and it has
+ * been validated for colour-vision deficiency against the app's own surfaces.
+ */
+
+/**
+ * A sky the DSL knows how to draw.
+ *
+ * A closed list rather than free text: the drawing has to be chosen from it, and
+ * an unrecognised string would leave a hole where the icon goes. Providers name
+ * conditions in wildly different vocabularies, so the caller maps theirs onto
+ * this list and passes the provider's own words as `conditionLabel` — the enum
+ * picks the picture, the label is what gets read.
+ */
+export type WeatherCondition =
+  | 'clear'
+  | 'partly-cloudy'
+  | 'cloudy'
+  | 'overcast'
+  | 'fog'
+  | 'light-rain'
+  | 'rain'
+  | 'heavy-rain'
+  | 'sleet'
+  | 'light-snow'
+  | 'snow'
+  | 'heavy-snow'
+  | 'thunderstorm'
+  | 'hail'
+  | 'windy'
+
+/** Wind, as shown by the weather components. */
+export interface WeatherWind {
+  speed: number
+  /** Written after the speed. Defaults to `m/s`. */
+  unit?: string
+  /** Compass direction as the caller words it, e.g. `NV` or `sydväst`. */
+  direction?: string
+  /** Gust speed, in the same unit. Shown next to the sustained speed when present. */
+  gust?: number
+}
+
+/** The extension API properties for the WeatherNow component. */
+export interface WeatherNowProps extends ExtensionComponentData {
+  component: 'WeatherNow'
+  /** Where the reading is from. */
+  place: string
+  condition: WeatherCondition
+  /** The condition in the user's own language. Falls back to the host's wording for `condition`. */
+  conditionLabel?: string
+  temperature: number
+  /** What it feels like, when that differs enough to be worth saying. */
+  feelsLike?: number
+  /** Written after every temperature. Defaults to `°`. */
+  unit?: string
+  wind?: WeatherWind
+  /** Draws the night variant of the icon. Only affects conditions that have one. */
+  night?: boolean
+  /** One line of context under the numbers, e.g. "Regn från tretiden". */
+  summary?: string
+}
+
+/**
+ * One step of a forecast.
+ *
+ * Deliberately the same shape whether the steps are hours or days — the only
+ * difference is what `label` says and whether there are two temperatures. A
+ * separate hourly component would have been the same component twice.
+ */
+export interface WeatherForecastStep {
+  /** Short: `14`, `Tors`, `Nu`. */
+  label: string
+  condition: WeatherCondition
+  conditionLabel?: string
+  /** The warmer of the two, or the only one for a single-temperature step. */
+  high: number
+  /** The colder one. Absent when the step has a single temperature. */
+  low?: number
+  night?: boolean
+  /** Chance of precipitation as a percentage, 0–100. */
+  precipitation?: number
+  /**
+   * The step the reader is at — this hour, today. Drawn larger than its
+   * neighbours, so the eye lands on it before reading the row.
+   *
+   * Same word as `TimelineEntry.current`, and the same meaning: mark one, and
+   * only one. Marking several is marking none.
+   */
+  current?: boolean
+}
+
+/** The extension API properties for the WeatherForecast component. */
+export interface WeatherForecastProps extends ExtensionComponentData {
+  component: 'WeatherForecast'
+  /** Heading above the row, e.g. "Kommande timmar". */
+  title?: string
+  /** Icon shown to the left of the title. */
+  icon?: HugeIconName
+  /** Written after every temperature. Defaults to `°`. */
+  unit?: string
+  steps: WeatherForecastStep[]
+}
+
+/** How a chart draws its series. */
+export type ChartKind = 'line' | 'bar' | 'area'
+
+/**
+ * One series of a chart.
+ *
+ * `points` lines up with the chart's `labels` by position. A `null` is a gap in
+ * the data and is drawn as one — a missing reading joined up as if it were a
+ * value is a lie the chart would tell on the caller's behalf.
+ */
+export interface ChartSeries {
+  /** Named in the legend. Required in practice once there is more than one series. */
+  name?: string
+  points: Array<number | null>
+}
+
+/**
+ * The extension API properties for the Chart component.
+ *
+ * There is no colour option and no second axis, on purpose. Colours come from
+ * the host's categorical palette in slot order, so the same series keeps the
+ * same colour everywhere and the whole set stays legible to colour-blind
+ * readers. Two measurements of different magnitude are two charts.
+ */
+export interface ChartProps extends ExtensionComponentData {
+  component: 'Chart'
+  /** Defaults to `line`. */
+  chart?: ChartKind
+  /** At most eight. Past that the ninth would need a colour the palette does not have. */
+  series: ChartSeries[]
+  /** One per point, along the horizontal axis. */
+  labels?: string[]
+  /** Heading above the plot. With a single series this is what names it, so no legend is drawn. */
+  title?: string
+  /** Icon shown to the left of the title. */
+  icon?: HugeIconName
+  /** Written after every value, e.g. `°`, ` mm`, ` kr`. */
+  unit?: string
+  /**
+   * Whether the value axis must include zero. Defaults to true for `bar` and
+   * `area`, where the fill's height is the reading, and false for `line`, where
+   * forcing zero can flatten the shape the chart exists to show.
+   */
+  zeroBaseline?: boolean
+  /** Plot height in rem. Defaults to 9. */
+  height?: number
+}
+
+/** Which way a stat tile's trend points. */
+export type StatTrend = 'up' | 'down' | 'flat'
+
+/**
+ * The extension API properties for the StatTile component.
+ *
+ * For the single number that does not need a plot. A chart of one value is a
+ * chart that spends a lot of space saying very little.
+ */
+export interface StatTileProps extends ExtensionComponentData {
+  component: 'StatTile'
+  /** What the number is, e.g. "Förbrukning i går". */
+  label: string
+  value: string | number
+  /** Written after the value in smaller type, e.g. `kWh`. */
+  unit?: string
+  /** One quiet line under the number. */
+  caption?: string
+  icon?: HugeIconName
+  /** `flat` draws no arrow. */
+  trend?: StatTrend
+  /** The change in words, e.g. "+12 % mot förra veckan". Shown beside the arrow. */
+  trendLabel?: string
+  /**
+   * Whether up is the good direction. Defaults to true. Colours the trend;
+   * the arrow and the label carry the same meaning without it.
+   */
+  trendIsGood?: boolean
+}
+
+/** One row of a KeyValueList. */
+export interface KeyValueRow {
+  label: string
+  value: string
+  icon?: HugeIconName
+}
+
+/**
+ * The extension API properties for the KeyValueList component.
+ *
+ * Facts in two columns, aligned. What a stack of `HorizontalStack`s was always
+ * being used for, without each caller having to get the alignment right.
+ */
+export interface KeyValueListProps extends ExtensionComponentData {
+  component: 'KeyValueList'
+  rows: KeyValueRow[]
+}
+
+/** How much a timeline entry stands out. */
+export type TimelineVariant = 'default' | 'accent' | 'success' | 'warning' | 'danger'
+
+/**
+ * One entry on a timeline.
+ *
+ * `time` is a string, not a timestamp, because the component draws order rather
+ * than duration: entries sit evenly on the rail whether they are minutes or
+ * decades apart. That is what makes the same component work for today's
+ * calendar and for a project's milestones, and it means the caller writes the
+ * time the way it should be read — `09:00`, `Tors 14 mar`, `2019`.
+ */
+export interface TimelineEntry {
+  /** When it happens, worded as it should be read. */
+  time: string
+  title: string
+  /** A line under the title. */
+  description?: string
+  icon?: HugeIconName
+  /** How long it lasts, in the caller's own words: `1 h`, `3 dagar`. */
+  duration?: string
+  /** Trailing badge, e.g. a place or a category. */
+  badge?: string
+  /** Marks the entry the reader is at. Drawn with a filled marker and a heavier rule. */
+  current?: boolean
+  /** Already behind us. Drawn recessive, so what is left to come reads first. */
+  past?: boolean
+  variant?: TimelineVariant
+}
+
+/**
+ * The extension API properties for the Timeline component.
+ *
+ * A vertical rail with one marker per entry. For a day's events, or for the
+ * order things happened in over a longer stretch.
+ */
+export interface TimelineProps extends ExtensionComponentData {
+  component: 'Timeline'
+  /** Heading above the rail, e.g. "I dag". */
+  title?: string
+  /** Icon shown to the left of the title. */
+  icon?: HugeIconName
+  entries: TimelineEntry[]
+}
+
+/** How much a note stands out. */
+export type NoteVariant = 'default' | 'accent' | 'success' | 'warning' | 'danger'
+
+/**
+ * The extension API properties for the Note component.
+ *
+ * A titled block of prose: a heading, markdown, and a quiet line at the bottom.
+ * For the answer that *is* text but wants a shape — one of five news summaries,
+ * one of three things worth doing this weekend — where a single long reply would
+ * run them all together and the reader would lose which sentence belonged to
+ * which item.
+ *
+ * The body is markdown rather than components because prose is what it is for.
+ * A note that wants a chart in it is a `Frame` with a `Note` and a `Chart`
+ * inside; keeping those separate is what stops this from becoming a second,
+ * worse layout system.
+ */
+export interface NoteProps extends ExtensionComponentData {
+  component: 'Note'
+  title?: string
+  /** Icon shown to the left of the title. */
+  icon?: HugeIconName
+  /** Trailing badge next to the title: a source, a category, a time. */
+  badge?: string
+  /** The body, as markdown. */
+  content: string
+  /** One quiet line at the bottom: where it came from, when, or a caveat. */
+  footer?: string
+  /** Colours the rail down the left edge. Defaults to none. */
+  variant?: NoteVariant
+}
+
+/** Whether an event is going ahead. */
+export type CalendarEventStatus = 'confirmed' | 'tentative' | 'cancelled'
+
+/**
+ * The extension API properties for the CalendarEvent component.
+ *
+ * One event, shown properly. It is the thing Stina most often has to say
+ * something *about* — a meeting starting shortly, a booking she is reminding you
+ * of — and a sentence carrying a time, a place and four names is a sentence
+ * nobody reads to the end.
+ *
+ * For a whole day, use `Timeline`. This is the single event that has the floor.
+ *
+ * `start` and `end` are timestamps rather than the worded strings `Timeline`
+ * takes, and that is the one place in the DSL where live computation is right:
+ * the card is *about* a moment, so the host works out "om tolv minuter" and
+ * "pågår nu" and keeps them true. A caller who wrote those as text would have
+ * written a card that lies the moment it is scrolled back to.
+ */
+export interface CalendarEventProps extends ExtensionComponentData {
+  component: 'CalendarEvent'
+  title: string
+  /** ISO 8601, with an offset. The host formats it in the reader's own locale. */
+  start: string
+  /** ISO 8601, with an offset. Absent for an event with no stated end. */
+  end?: string
+  /** Draws a day rather than a clock time. */
+  allDay?: boolean
+  location?: string
+  /** Who called it. */
+  organizer?: string
+  /** Names as the calendar has them. Shown in full up to a few, then counted. */
+  attendees?: string[]
+  /** Which calendar it sits in. Shown as a badge. */
+  calendar?: string
+  /** Defaults to `confirmed`. */
+  status?: CalendarEventStatus
+  /**
+   * How it repeats, in words: `Varje tisdag`. The recurrence rule itself is not
+   * something this component parses — the caller already knows what it means,
+   * and a component guessing at an RRULE would get the exceptions wrong.
+   */
+  recurrence?: string
+  /** One short line of context. */
+  notes?: string
+}

package/src/types.context.ts

@@ -320,7 +320,21 @@ export interface UserProfile {
  * User API for profile access
  */
 export interface UserAPI {
-  getProfile(): Promise<UserProfile>
+  /**
+   * Read a user's profile, including the timezone their clock times are written in.
+   *
+   * Pass the id of the user this work belongs to — `ctx.userId` in a background task,
+   * `context.userId` in a tool call, the fired job's `userId` in a scheduler callback.
+   * A host serving more than one user cannot guess which profile was meant, and answers
+   * with an empty profile when the id is left out.
+   *
+   * This matters most for `timezone`. An extension that turns a wall-clock time into an
+   * instant without it falls back to the machine's timezone, which on a server is UTC,
+   * and schedules the user's 11:30 for 11:30 UTC.
+   *
+   * @param userId The user whose profile to read. Optional only for single-user hosts.
+   */
+  getProfile(userId?: string): Promise<UserProfile>
   listIds(): Promise<string[]>
 }
 

package/src/types.tools.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ExecutionContext } from './types.context.js'
+import type { ExtensionComponentData } from './types.components.js'
 
 /**
  * Tool implementation
@@ -39,6 +40,20 @@ export interface ToolResult {
   message?: string
   /** Error message if failed */
   error?: string
+  /**
+   * Something to show the user that is not text.
+   *
+   * A component from the chat card profile — a chart, a weather reading, a
+   * timeline. It is rendered in the conversation where the tool ran, and it is
+   * *not* part of what goes back to the model: the model already knows what it
+   * asked to be shown, and sending the drawing back would spend the tokens
+   * twice and invite it to summarise its own picture.
+   *
+   * 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.
+   */
+  display?: ExtensionComponentData
 }
 
 /**