@stina/extension-api 1.0.0 → 1.3.1

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

@@ -171,6 +171,18 @@ interface LabelProps extends ExtensionComponentData {
     component: 'Label';
     text: string;
 }
+/**
+ * The extension API properties for the Clock component.
+ *
+ * The odd one out among the display components: it takes no facts, because the
+ * fact it shows is what time it is, and that is not something an action can
+ * hand over once. It reads the clock and the timezone from the host and keeps
+ * itself current, so a card carrying one stays right while the window is left
+ * open.
+ */
+interface ClockProps extends ExtensionComponentData {
+    component: 'Clock';
+}
 /** The extension API properties for the paragraph component. */
 interface ParagraphProps extends ExtensionComponentData {
     component: 'Paragraph';
@@ -2340,6 +2352,32 @@ interface ToolResult {
      * would send her after a component that does not exist.
      */
     cardSuggestion?: string;
+    /**
+     * Pictures to show the user, rendered in the conversation where the tool ran.
+     *
+     * For what a card cannot hold and the model cannot reproduce: a generated
+     * image, a rendered document, a photo fetched on the user's behalf. Like
+     * {@link ToolResult.display}, this is for the user only — it is lifted out
+     * before the result reaches the model, which would have nothing to do with
+     * the bytes but spend tokens on them. Say in `data` that a picture was shown,
+     * so she can talk about it without describing it back.
+     *
+     * The host stores each one as an attachment of the conversation, the same way
+     * a picture the user sends is stored, so it is served to every client and can
+     * be saved or shared from there. JPEG and PNG only, and 20 MB at most, since
+     * those are the limits the attachment store already holds users to. One that
+     * fails them is dropped with a warning rather than half-shown.
+     */
+    attachments?: ToolAttachment[];
+}
+/**
+ * One picture a tool wants shown. See {@link ToolResult.attachments}.
+ */
+interface ToolAttachment {
+    /** The image bytes, base64 encoded. The format is read from the bytes. */
+    data: string;
+    /** A file name to offer when the user saves it, e.g. `friday.png`. */
+    name?: string;
 }
 /**
  * Action implementation for UI interactions.
@@ -2367,4 +2405,4 @@ interface ActionResult {
     error?: string;
 }
 
-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 };
+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 WeatherForecastProps 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 SelectProps as aA, type IconPickerProps as aB, type VerticalStackProps as aC, type HorizontalStackProps as aD, type GridProps as aE, type DividerProps as aF, type IconProps as aG, type IconButtonType as aH, type IconButtonProps as aI, type PanelAction as aJ, type PanelProps as aK, type ToggleProps as aL, type CollapsibleProps as aM, type FrameVariant as aN, type FrameProps as aO, type ListProps as aP, type PillVariant as aQ, type PillProps as aR, type CheckboxProps as aS, type MarkdownProps as aT, type TextPreviewProps as aU, type ModalProps as aV, type ConditionalGroupProps as aW, type WeatherCondition as aX, type WeatherWind as aY, type WeatherNowProps as aZ, type WeatherForecastStep as a_, type ChatImage as aa, type ToolCall as ab, type VoiceTransportRequest as ac, type Tool as ad, type ToolAttachment as ae, type Action as af, type ExtensionModule as ag, type AllowedCSSProperty as ah, type ExtensionComponentStyle as ai, type ExtensionComponentData as aj, type ExtensionComponentIterator as ak, type ExtensionComponentChildren as al, type ExtensionActionCall as am, type ExtensionActionRef as an, type ExtensionDataSource as ao, type ExtensionPanelDefinition as ap, type HeaderProps as aq, type LabelProps as ar, type ClockProps as as, type ParagraphProps as at, type ButtonProps as au, type TextInputProps as av, type PasswordInputProps as aw, type NumberInputProps as ax, type TextAreaProps as ay, type DateTimeInputProps as az, type StreamEvent as b, type ChartKind as b0, type ChartSeries as b1, type ChartProps as b2, type StatTrend as b3, type StatTileProps as b4, type ProgressShape as b5, type ProgressColor as b6, type ProgressBarProps as b7, type KeyValueRow as b8, type KeyValueListProps as b9, type TimelineVariant as ba, type TimelineEntry as bb, type TimelineProps as bc, type NoteVariant as bd, type NoteProps as be, type CalendarEventStatus as bf, type CalendarEventProps as bg, type ExecutionContext as bh, 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-CQrbET-n.d.ts → types.tools-C0GqXQlu.d.ts}

@@ -171,6 +171,18 @@ interface LabelProps extends ExtensionComponentData {
     component: 'Label';
     text: string;
 }
+/**
+ * The extension API properties for the Clock component.
+ *
+ * The odd one out among the display components: it takes no facts, because the
+ * fact it shows is what time it is, and that is not something an action can
+ * hand over once. It reads the clock and the timezone from the host and keeps
+ * itself current, so a card carrying one stays right while the window is left
+ * open.
+ */
+interface ClockProps extends ExtensionComponentData {
+    component: 'Clock';
+}
 /** The extension API properties for the paragraph component. */
 interface ParagraphProps extends ExtensionComponentData {
     component: 'Paragraph';
@@ -2340,6 +2352,32 @@ interface ToolResult {
      * would send her after a component that does not exist.
      */
     cardSuggestion?: string;
+    /**
+     * Pictures to show the user, rendered in the conversation where the tool ran.
+     *
+     * For what a card cannot hold and the model cannot reproduce: a generated
+     * image, a rendered document, a photo fetched on the user's behalf. Like
+     * {@link ToolResult.display}, this is for the user only — it is lifted out
+     * before the result reaches the model, which would have nothing to do with
+     * the bytes but spend tokens on them. Say in `data` that a picture was shown,
+     * so she can talk about it without describing it back.
+     *
+     * The host stores each one as an attachment of the conversation, the same way
+     * a picture the user sends is stored, so it is served to every client and can
+     * be saved or shared from there. JPEG and PNG only, and 20 MB at most, since
+     * those are the limits the attachment store already holds users to. One that
+     * fails them is dropped with a warning rather than half-shown.
+     */
+    attachments?: ToolAttachment[];
+}
+/**
+ * One picture a tool wants shown. See {@link ToolResult.attachments}.
+ */
+interface ToolAttachment {
+    /** The image bytes, base64 encoded. The format is read from the bytes. */
+    data: string;
+    /** A file name to offer when the user saves it, e.g. `friday.png`. */
+    name?: string;
 }
 /**
  * Action implementation for UI interactions.
@@ -2367,4 +2405,4 @@ interface ActionResult {
     error?: string;
 }
 
-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 };
+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 WeatherForecastProps 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 SelectProps as aA, type IconPickerProps as aB, type VerticalStackProps as aC, type HorizontalStackProps as aD, type GridProps as aE, type DividerProps as aF, type IconProps as aG, type IconButtonType as aH, type IconButtonProps as aI, type PanelAction as aJ, type PanelProps as aK, type ToggleProps as aL, type CollapsibleProps as aM, type FrameVariant as aN, type FrameProps as aO, type ListProps as aP, type PillVariant as aQ, type PillProps as aR, type CheckboxProps as aS, type MarkdownProps as aT, type TextPreviewProps as aU, type ModalProps as aV, type ConditionalGroupProps as aW, type WeatherCondition as aX, type WeatherWind as aY, type WeatherNowProps as aZ, type WeatherForecastStep as a_, type ChatImage as aa, type ToolCall as ab, type VoiceTransportRequest as ac, type Tool as ad, type ToolAttachment as ae, type Action as af, type ExtensionModule as ag, type AllowedCSSProperty as ah, type ExtensionComponentStyle as ai, type ExtensionComponentData as aj, type ExtensionComponentIterator as ak, type ExtensionComponentChildren as al, type ExtensionActionCall as am, type ExtensionActionRef as an, type ExtensionDataSource as ao, type ExtensionPanelDefinition as ap, type HeaderProps as aq, type LabelProps as ar, type ClockProps as as, type ParagraphProps as at, type ButtonProps as au, type TextInputProps as av, type PasswordInputProps as aw, type NumberInputProps as ax, type TextAreaProps as ay, type DateTimeInputProps as az, type StreamEvent as b, type ChartKind as b0, type ChartSeries as b1, type ChartProps as b2, type StatTrend as b3, type StatTileProps as b4, type ProgressShape as b5, type ProgressColor as b6, type ProgressBarProps as b7, type KeyValueRow as b8, type KeyValueListProps as b9, type TimelineVariant as ba, type TimelineEntry as bb, type TimelineProps as bc, type NoteVariant as bd, type NoteProps as be, type CalendarEventStatus as bf, type CalendarEventProps as bg, type ExecutionContext as bh, 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": "1.0.0",
+  "version": "1.3.1",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -100,6 +100,7 @@ export type {
   // Tools
   Tool,
   ToolResult,
+  ToolAttachment,
 
   // Actions
   Action,
@@ -163,6 +164,7 @@ export type {
   // Component Props
   HeaderProps,
   LabelProps,
+  ClockProps,
   ParagraphProps,
   ButtonProps,
   TextInputProps,

package/src/runtime.ts

@@ -648,11 +648,36 @@ function buildContext(
   if (permissions.some((p) => p.startsWith('network:'))) {
     const networkApi: NetworkAPI = {
       async fetch(url: string, options?: RequestInit): Promise<Response> {
-        const result = await sendRequest<{ status: number; statusText: string; headers: Record<string, string>; body: string }>('network.fetch', { url, options })
-        return new Response(result.body, {
+        const result = await sendRequest<{
+          status: number
+          statusText: string
+          headers: Record<string, string>
+          body: string
+          bodyEncoding?: 'base64'
+        }>('network.fetch', { url, options })
+        // The host sends a body that is not text as base64, since the bridge is
+        // JSON. Turn it back into bytes here so `response.arrayBuffer()` gives
+        // the extension what the server sent and `text()` still works.
+        const isBase64 = result.bodyEncoding === 'base64'
+        const body = isBase64
+          ? Uint8Array.from(atob(result.body), (char) => char.charCodeAt(0))
+          : result.body
+
+        // The host says the same thing in a header, for extensions whose bundled
+        // copy of this runtime is older than the encoding and would hand the
+        // base64 on as text. This runtime just decoded it, so the header would be
+        // a lie by the time the extension reads it: take it back out.
+        const headers = { ...result.headers }
+        if (isBase64) {
+          for (const name of Object.keys(headers)) {
+            if (name.toLowerCase() === 'x-stina-body-encoding') delete headers[name]
+          }
+        }
+
+        return new Response(body, {
           status: result.status,
           statusText: result.statusText,
-          headers: result.headers,
+          headers,
         })
       },
 
@@ -996,6 +1021,7 @@ export type {
   Tool,
   ToolDefinition,
   ToolResult,
+  ToolAttachment,
   ToolCall,
   Action,
   ActionResult,

package/src/schemas/components.schema.ts

@@ -197,6 +197,14 @@ export const LabelPropsSchema = z
   .passthrough()
   .describe('Label component')
 
+export const ClockPropsSchema = z
+  .object({
+    component: z.literal('Clock'),
+    style: ExtensionComponentStyleSchema.optional(),
+  })
+  .passthrough()
+  .describe('Clock component: the current date and time where the user is')
+
 export const ParagraphPropsSchema = z
   .object({
     component: z.literal('Paragraph'),
@@ -820,6 +828,7 @@ 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 ClockProps = z.infer<typeof ClockPropsSchema>
 export type ProgressShape = z.infer<typeof ProgressShapeSchema>
 export type ProgressColor = z.infer<typeof ProgressColorSchema>
 export type ProgressBarProps = z.infer<typeof ProgressBarPropsSchema>

package/src/schemas/index.ts

@@ -96,6 +96,7 @@ export {
   PanelActionSchema,
   HeaderPropsSchema,
   LabelPropsSchema,
+  ClockPropsSchema,
   ParagraphPropsSchema,
   ButtonPropsSchema,
   TextInputPropsSchema,
@@ -155,6 +156,7 @@ export {
   type PanelAction,
   type HeaderProps,
   type LabelProps,
+  type ClockProps,
   type ParagraphProps,
   type ButtonProps,
   type TextInputProps,

package/src/types.components.ts

@@ -251,6 +251,19 @@ export interface LabelProps extends ExtensionComponentData {
   text: string
 }
 
+/**
+ * The extension API properties for the Clock component.
+ *
+ * The odd one out among the display components: it takes no facts, because the
+ * fact it shows is what time it is, and that is not something an action can
+ * hand over once. It reads the clock and the timezone from the host and keeps
+ * itself current, so a card carrying one stays right while the window is left
+ * open.
+ */
+export interface ClockProps extends ExtensionComponentData {
+  component: 'Clock'
+}
+
 /** The extension API properties for the paragraph component. */
 export interface ParagraphProps extends ExtensionComponentData {
   component: 'Paragraph'

package/src/types.tools.ts

@@ -73,6 +73,34 @@ export interface ToolResult {
    * would send her after a component that does not exist.
    */
   cardSuggestion?: string
+
+  /**
+   * Pictures to show the user, rendered in the conversation where the tool ran.
+   *
+   * For what a card cannot hold and the model cannot reproduce: a generated
+   * image, a rendered document, a photo fetched on the user's behalf. Like
+   * {@link ToolResult.display}, this is for the user only — it is lifted out
+   * before the result reaches the model, which would have nothing to do with
+   * the bytes but spend tokens on them. Say in `data` that a picture was shown,
+   * so she can talk about it without describing it back.
+   *
+   * The host stores each one as an attachment of the conversation, the same way
+   * a picture the user sends is stored, so it is served to every client and can
+   * be saved or shared from there. JPEG and PNG only, and 20 MB at most, since
+   * those are the limits the attachment store already holds users to. One that
+   * fails them is dropped with a warning rather than half-shown.
+   */
+  attachments?: ToolAttachment[]
+}
+
+/**
+ * One picture a tool wants shown. See {@link ToolResult.attachments}.
+ */
+export interface ToolAttachment {
+  /** The image bytes, base64 encoded. The format is read from the bytes. */
+  data: string
+  /** A file name to offer when the user saves it, e.g. `friday.png`. */
+  name?: string
 }
 
 /**

package/src/types.ts

@@ -69,7 +69,7 @@ export type {
 } from './types.provider.js'
 
 // Tools and Actions
-export type { Tool, ToolResult, Action, ActionResult } from './types.tools.js'
+export type { Tool, ToolResult, ToolAttachment, Action, ActionResult } from './types.tools.js'
 
 // Context and APIs
 export type {