@stina/extension-api 1.0.0 → 1.6.0

package/dist/{types.tools-CQrbET-n.d.cts → types.tools-R0xGhiBa.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';
@@ -1166,9 +1178,22 @@ interface ModelCapabilities {
      * Report this per model *and* per auth mode, like `voiceDuplex`: the same
      * provider often serves both a vision model and a text-only one, and a picture
      * sent to the latter is at best ignored and at worst an error mid-conversation.
-     * Stina uses it to decide whether the paperclip is offered at all.
      */
     vision?: boolean;
+    /**
+     * The model can be given files to read alongside the text of a message, and
+     * the provider folds {@link ChatMessage.files} into whatever its API calls them.
+     *
+     * Separate from `vision` because the two come apart in both directions: a model
+     * that reads a PDF natively is not necessarily one that looks at a photograph,
+     * and an OpenAI-compatible server with a vision model behind it may take images
+     * and nothing else. Report it per model and per auth mode for the same reason
+     * `vision` is reported that way.
+     *
+     * A provider that says nothing here keeps behaving exactly as before: it is
+     * handed the text, and `files` is simply a field it does not read.
+     */
+    documents?: boolean;
 }
 /**
  * How the client wants to connect to the voice session.
@@ -1268,6 +1293,18 @@ interface ChatMessage {
      * Only ever `image/jpeg` or `image/png` — see `ChatAttachmentDTO` for why.
      */
     images?: ChatImage[];
+    /**
+     * Files the user attached for the model to read: PDFs and plain text.
+     *
+     * Additive in the same way `images` is, and split from it for the same reason
+     * the two capabilities are separate — a provider folds a document into a
+     * different content block than a picture, and many can do one and not the other.
+     * A provider that ignores the field behaves exactly as it did before.
+     *
+     * Only present on user messages, because that is where both hosted providers
+     * require a document to sit.
+     */
+    files?: ChatFile[];
     /** For assistant messages: tool calls made by the model */
     tool_calls?: ToolCall[];
     /** For tool messages: the ID of the tool call this is a response to */
@@ -1287,6 +1324,29 @@ interface ChatImage {
     /** The image itself, base64 with no data-URI prefix. */
     data: string;
 }
+/**
+ * One file the user attached for the model to read, rather than to look at.
+ *
+ * `application/pdf` and `text/plain` are what the host stores, so those are what
+ * arrive. Both hosted providers read a PDF natively and want it as its own content
+ * block; plain text needs no such thing and can simply be put in the prompt, which
+ * is why a provider with no document support at all can still do something useful
+ * with a `text/plain` file if it chooses to.
+ */
+interface ChatFile {
+    /** `application/pdf` or `text/plain`. */
+    mime: string;
+    /** The file itself, base64 with no data-URI prefix. */
+    data: string;
+    /**
+     * The name the file arrived under, when it had one.
+     *
+     * Worth passing on rather than dropping: `faktura-1042.pdf` is most of what is
+     * known about a file before it is opened, and both providers have somewhere to
+     * put it — a file name on the one, a document title on the other.
+     */
+    name?: string;
+}
 /**
  * A tool call made by the model
  */
@@ -1702,6 +1762,46 @@ interface ExecutionContext {
     readonly secrets: SecretsAPI;
     /** User-scoped secrets */
     readonly userSecrets: SecretsAPI;
+    /**
+     * The files attached to this user's conversations.
+     *
+     * Present only for an extension holding `attachments.read`, and only on a request
+     * that knows whose it is. Absent otherwise, so a tool that wants files has to say
+     * so in its manifest and check before reaching for them.
+     */
+    readonly attachments?: AttachmentsAPI;
+}
+/**
+ * Reading a file that is already in a conversation.
+ *
+ * For handing one on: mailing back the PDF she was just shown, printing it, putting
+ * it somewhere. Not for finding out what it says — `core_read_attachment` does that
+ * without an extension, and getting the text is nearly always what she actually
+ * wants.
+ */
+interface AttachmentsAPI {
+    /**
+     * Read one attachment by id.
+     *
+     * The id comes from Stina, which is the whole point: she gets it from the message
+     * a file arrived on, or from the result of the tool that handed it over, and
+     * passes it to a tool as a parameter.
+     *
+     * Resolves `null` when no such attachment belongs to this user — deleted, or
+     * never theirs. The two are the same answer on purpose.
+     */
+    read(attachmentId: string): Promise<AttachmentContent | null>;
+}
+/** One attachment's bytes, with what is known about them. */
+interface AttachmentContent {
+    id: string;
+    /** `image/jpeg`, `image/png`, `application/pdf` or `text/plain`, read from the bytes. */
+    mime: string;
+    /** base64, no data-URI prefix. */
+    data: string;
+    byteSize: number;
+    /** The name it was stored under, when it had one. */
+    name?: string;
 }
 /**
  * Context provided to extension's activate function.
@@ -2340,6 +2440,46 @@ interface ToolResult {
      * would send her after a component that does not exist.
      */
     cardSuggestion?: string;
+    /**
+     * Files to put in front of the user, in the conversation where the tool ran.
+     *
+     * For what a card cannot hold and the model cannot reproduce: a generated image,
+     * a photo fetched on the user's behalf, the PDF that came attached to a mail.
+     * Like {@link ToolResult.display}, this is for the user — 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 file was attached, so she can talk
+     * about it without reciting it.
+     *
+     * The host stores each one as an attachment of the conversation, exactly as a
+     * file the user sends is stored, so it is served to every client and can be saved
+     * or shared from there. The store's own rules apply: JPEG and PNG, PDF, and plain
+     * text, up to 20 MB (1 MB for text). What the file *is* is read from the bytes,
+     * not from `name`, so a PDF mislabelled `.png` still lands as a PDF. One that
+     * fails the rules is dropped with a warning rather than half-shown.
+     *
+     * Attaching a file does not read it to the model. What comes back in the result
+     * the model sees is a reference apiece — `{ id, mime, name? }` under this same
+     * key, in place of the bytes — and she reads one with `core_read_attachment` if
+     * she decides to. That is the intended flow for a mail's attachment: hand it over
+     * here, and let her choose whether to open it.
+     */
+    attachments?: ToolAttachment[];
+}
+/**
+ * One file a tool wants to put in the conversation. See {@link ToolResult.attachments}.
+ */
+interface ToolAttachment {
+    /** The bytes, base64 encoded. What they are is read from them, not from `name`. */
+    data: string;
+    /**
+     * A file name to offer when the user saves it, e.g. `friday.png` or
+     * `faktura-1042.pdf`.
+     *
+     * Worth sending for a picture and close to required for a document: it is the
+     * whole label the user sees in the conversation, and it is what Stina has to go
+     * on when she decides whether to read it.
+     */
+    name?: string;
 }
 /**
  * Action implementation for UI interactions.
@@ -2367,4 +2507,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 BackgroundTaskConfig 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 AttachmentsAPI as X, type AttachmentContent as Y, type LogAPI as Z, type BackgroundWorkersAPI as _, type ChatOptions as a, type WeatherWind as a$, type BackgroundTaskCallback as a0, type BackgroundTaskContext as a1, type BackgroundTaskHealth as a2, type BackgroundRestartPolicy as a3, type Query as a4, type QueryOptions as a5, type StorageAPI as a6, type SecretsAPI as a7, type StorageCollectionConfig as a8, type StorageContributions as a9, type NumberInputProps as aA, type TextAreaProps as aB, type DateTimeInputProps as aC, type SelectProps as aD, type IconPickerProps as aE, type VerticalStackProps as aF, type HorizontalStackProps as aG, type GridProps as aH, type DividerProps as aI, type IconProps as aJ, type IconButtonType as aK, type IconButtonProps as aL, type PanelAction as aM, type PanelProps as aN, type ToggleProps as aO, type CollapsibleProps as aP, type FrameVariant as aQ, type FrameProps as aR, type ListProps as aS, type PillVariant as aT, type PillProps as aU, type CheckboxProps as aV, type MarkdownProps as aW, type TextPreviewProps as aX, type ModalProps as aY, type ConditionalGroupProps as aZ, type WeatherCondition as a_, type AIProvider as aa, type ModelCapabilities as ab, type ChatImage as ac, type ChatFile as ad, type ToolCall as ae, type VoiceTransportRequest as af, type Tool as ag, type ToolAttachment as ah, type Action as ai, type ExtensionModule as aj, type AllowedCSSProperty as ak, type ExtensionComponentStyle as al, type ExtensionComponentData as am, type ExtensionComponentIterator as an, type ExtensionComponentChildren as ao, type ExtensionActionCall as ap, type ExtensionActionRef as aq, type ExtensionDataSource as ar, type ExtensionPanelDefinition as as, type HeaderProps as at, type LabelProps as au, type ClockProps as av, type ParagraphProps as aw, type ButtonProps as ax, type TextInputProps as ay, type PasswordInputProps as az, type StreamEvent as b, type WeatherNowProps as b0, type WeatherForecastStep as b1, type WeatherForecastProps as b2, type ChartKind as b3, type ChartSeries as b4, type ChartProps as b5, type StatTrend as b6, type StatTileProps as b7, type ProgressShape as b8, type ProgressColor as b9, type ProgressBarProps as ba, type KeyValueRow as bb, type KeyValueListProps as bc, type TimelineVariant as bd, type TimelineEntry as be, type TimelineProps as bf, type NoteVariant as bg, type NoteProps as bh, type CalendarEventStatus as bi, type CalendarEventProps as bj, type ExecutionContext as bk, 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-R0xGhiBa.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';
@@ -1166,9 +1178,22 @@ interface ModelCapabilities {
      * Report this per model *and* per auth mode, like `voiceDuplex`: the same
      * provider often serves both a vision model and a text-only one, and a picture
      * sent to the latter is at best ignored and at worst an error mid-conversation.
-     * Stina uses it to decide whether the paperclip is offered at all.
      */
     vision?: boolean;
+    /**
+     * The model can be given files to read alongside the text of a message, and
+     * the provider folds {@link ChatMessage.files} into whatever its API calls them.
+     *
+     * Separate from `vision` because the two come apart in both directions: a model
+     * that reads a PDF natively is not necessarily one that looks at a photograph,
+     * and an OpenAI-compatible server with a vision model behind it may take images
+     * and nothing else. Report it per model and per auth mode for the same reason
+     * `vision` is reported that way.
+     *
+     * A provider that says nothing here keeps behaving exactly as before: it is
+     * handed the text, and `files` is simply a field it does not read.
+     */
+    documents?: boolean;
 }
 /**
  * How the client wants to connect to the voice session.
@@ -1268,6 +1293,18 @@ interface ChatMessage {
      * Only ever `image/jpeg` or `image/png` — see `ChatAttachmentDTO` for why.
      */
     images?: ChatImage[];
+    /**
+     * Files the user attached for the model to read: PDFs and plain text.
+     *
+     * Additive in the same way `images` is, and split from it for the same reason
+     * the two capabilities are separate — a provider folds a document into a
+     * different content block than a picture, and many can do one and not the other.
+     * A provider that ignores the field behaves exactly as it did before.
+     *
+     * Only present on user messages, because that is where both hosted providers
+     * require a document to sit.
+     */
+    files?: ChatFile[];
     /** For assistant messages: tool calls made by the model */
     tool_calls?: ToolCall[];
     /** For tool messages: the ID of the tool call this is a response to */
@@ -1287,6 +1324,29 @@ interface ChatImage {
     /** The image itself, base64 with no data-URI prefix. */
     data: string;
 }
+/**
+ * One file the user attached for the model to read, rather than to look at.
+ *
+ * `application/pdf` and `text/plain` are what the host stores, so those are what
+ * arrive. Both hosted providers read a PDF natively and want it as its own content
+ * block; plain text needs no such thing and can simply be put in the prompt, which
+ * is why a provider with no document support at all can still do something useful
+ * with a `text/plain` file if it chooses to.
+ */
+interface ChatFile {
+    /** `application/pdf` or `text/plain`. */
+    mime: string;
+    /** The file itself, base64 with no data-URI prefix. */
+    data: string;
+    /**
+     * The name the file arrived under, when it had one.
+     *
+     * Worth passing on rather than dropping: `faktura-1042.pdf` is most of what is
+     * known about a file before it is opened, and both providers have somewhere to
+     * put it — a file name on the one, a document title on the other.
+     */
+    name?: string;
+}
 /**
  * A tool call made by the model
  */
@@ -1702,6 +1762,46 @@ interface ExecutionContext {
     readonly secrets: SecretsAPI;
     /** User-scoped secrets */
     readonly userSecrets: SecretsAPI;
+    /**
+     * The files attached to this user's conversations.
+     *
+     * Present only for an extension holding `attachments.read`, and only on a request
+     * that knows whose it is. Absent otherwise, so a tool that wants files has to say
+     * so in its manifest and check before reaching for them.
+     */
+    readonly attachments?: AttachmentsAPI;
+}
+/**
+ * Reading a file that is already in a conversation.
+ *
+ * For handing one on: mailing back the PDF she was just shown, printing it, putting
+ * it somewhere. Not for finding out what it says — `core_read_attachment` does that
+ * without an extension, and getting the text is nearly always what she actually
+ * wants.
+ */
+interface AttachmentsAPI {
+    /**
+     * Read one attachment by id.
+     *
+     * The id comes from Stina, which is the whole point: she gets it from the message
+     * a file arrived on, or from the result of the tool that handed it over, and
+     * passes it to a tool as a parameter.
+     *
+     * Resolves `null` when no such attachment belongs to this user — deleted, or
+     * never theirs. The two are the same answer on purpose.
+     */
+    read(attachmentId: string): Promise<AttachmentContent | null>;
+}
+/** One attachment's bytes, with what is known about them. */
+interface AttachmentContent {
+    id: string;
+    /** `image/jpeg`, `image/png`, `application/pdf` or `text/plain`, read from the bytes. */
+    mime: string;
+    /** base64, no data-URI prefix. */
+    data: string;
+    byteSize: number;
+    /** The name it was stored under, when it had one. */
+    name?: string;
 }
 /**
  * Context provided to extension's activate function.
@@ -2340,6 +2440,46 @@ interface ToolResult {
      * would send her after a component that does not exist.
      */
     cardSuggestion?: string;
+    /**
+     * Files to put in front of the user, in the conversation where the tool ran.
+     *
+     * For what a card cannot hold and the model cannot reproduce: a generated image,
+     * a photo fetched on the user's behalf, the PDF that came attached to a mail.
+     * Like {@link ToolResult.display}, this is for the user — 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 file was attached, so she can talk
+     * about it without reciting it.
+     *
+     * The host stores each one as an attachment of the conversation, exactly as a
+     * file the user sends is stored, so it is served to every client and can be saved
+     * or shared from there. The store's own rules apply: JPEG and PNG, PDF, and plain
+     * text, up to 20 MB (1 MB for text). What the file *is* is read from the bytes,
+     * not from `name`, so a PDF mislabelled `.png` still lands as a PDF. One that
+     * fails the rules is dropped with a warning rather than half-shown.
+     *
+     * Attaching a file does not read it to the model. What comes back in the result
+     * the model sees is a reference apiece — `{ id, mime, name? }` under this same
+     * key, in place of the bytes — and she reads one with `core_read_attachment` if
+     * she decides to. That is the intended flow for a mail's attachment: hand it over
+     * here, and let her choose whether to open it.
+     */
+    attachments?: ToolAttachment[];
+}
+/**
+ * One file a tool wants to put in the conversation. See {@link ToolResult.attachments}.
+ */
+interface ToolAttachment {
+    /** The bytes, base64 encoded. What they are is read from them, not from `name`. */
+    data: string;
+    /**
+     * A file name to offer when the user saves it, e.g. `friday.png` or
+     * `faktura-1042.pdf`.
+     *
+     * Worth sending for a picture and close to required for a document: it is the
+     * whole label the user sees in the conversation, and it is what Stina has to go
+     * on when she decides whether to read it.
+     */
+    name?: string;
 }
 /**
  * Action implementation for UI interactions.
@@ -2367,4 +2507,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 BackgroundTaskConfig 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 AttachmentsAPI as X, type AttachmentContent as Y, type LogAPI as Z, type BackgroundWorkersAPI as _, type ChatOptions as a, type WeatherWind as a$, type BackgroundTaskCallback as a0, type BackgroundTaskContext as a1, type BackgroundTaskHealth as a2, type BackgroundRestartPolicy as a3, type Query as a4, type QueryOptions as a5, type StorageAPI as a6, type SecretsAPI as a7, type StorageCollectionConfig as a8, type StorageContributions as a9, type NumberInputProps as aA, type TextAreaProps as aB, type DateTimeInputProps as aC, type SelectProps as aD, type IconPickerProps as aE, type VerticalStackProps as aF, type HorizontalStackProps as aG, type GridProps as aH, type DividerProps as aI, type IconProps as aJ, type IconButtonType as aK, type IconButtonProps as aL, type PanelAction as aM, type PanelProps as aN, type ToggleProps as aO, type CollapsibleProps as aP, type FrameVariant as aQ, type FrameProps as aR, type ListProps as aS, type PillVariant as aT, type PillProps as aU, type CheckboxProps as aV, type MarkdownProps as aW, type TextPreviewProps as aX, type ModalProps as aY, type ConditionalGroupProps as aZ, type WeatherCondition as a_, type AIProvider as aa, type ModelCapabilities as ab, type ChatImage as ac, type ChatFile as ad, type ToolCall as ae, type VoiceTransportRequest as af, type Tool as ag, type ToolAttachment as ah, type Action as ai, type ExtensionModule as aj, type AllowedCSSProperty as ak, type ExtensionComponentStyle as al, type ExtensionComponentData as am, type ExtensionComponentIterator as an, type ExtensionComponentChildren as ao, type ExtensionActionCall as ap, type ExtensionActionRef as aq, type ExtensionDataSource as ar, type ExtensionPanelDefinition as as, type HeaderProps as at, type LabelProps as au, type ClockProps as av, type ParagraphProps as aw, type ButtonProps as ax, type TextInputProps as ay, type PasswordInputProps as az, type StreamEvent as b, type WeatherNowProps as b0, type WeatherForecastStep as b1, type WeatherForecastProps as b2, type ChartKind as b3, type ChartSeries as b4, type ChartProps as b5, type StatTrend as b6, type StatTileProps as b7, type ProgressShape as b8, type ProgressColor as b9, type ProgressBarProps as ba, type KeyValueRow as bb, type KeyValueListProps as bc, type TimelineVariant as bd, type TimelineEntry as be, type TimelineProps as bf, type NoteVariant as bg, type NoteProps as bh, type CalendarEventStatus as bi, type CalendarEventProps as bj, type ExecutionContext as bk, 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.6.0",
   "private": false,
   "repository": {
     "type": "git",

package/schema/extension-manifest.schema.json

@@ -110,6 +110,7 @@
                   "user.location.read",
                   "chat.history.read",
                   "chat.current.read",
+                  "attachments.read",
                   "chat.message.write",
                   "provider.register",
                   "tools.register",

package/src/index.ts

@@ -63,6 +63,8 @@ export type {
   ChatAPI,
   ChatInstructionMessage,
   ConversationPresentation,
+  AttachmentsAPI,
+  AttachmentContent,
   LogAPI,
 
   // Background workers
@@ -87,6 +89,7 @@ export type {
   ModelCapabilities,
   ChatMessage,
   ChatImage,
+  ChatFile,
   ChatOptions,
   GetModelsOptions,
   StreamEvent,
@@ -100,6 +103,7 @@ export type {
   // Tools
   Tool,
   ToolResult,
+  ToolAttachment,
 
   // Actions
   Action,
@@ -163,6 +167,7 @@ export type {
   // Component Props
   HeaderProps,
   LabelProps,
+  ClockProps,
   ParagraphProps,
   ButtonProps,
   TextInputProps,

package/src/messages.ts

@@ -264,6 +264,8 @@ export type RequestMethod =
   // Tools cross-extension methods
   | 'tools.list'
   | 'tools.execute'
+  // Attachments
+  | 'attachments.read'
 
 export interface ProviderRegisteredMessage {
   type: 'provider-registered'

package/src/runtime/executionContext.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createExecutionContext } from './executionContext.js'
+import type { ExtensionContext } from '../types.js'
+
+const extensionContext = {
+  extension: { id: 'mail-reader', version: '1.0.0', storagePath: '/tmp/x' },
+} as ExtensionContext
+
+/**
+ * What a tool is handed when it runs.
+ *
+ * The attachments API is the part worth pinning: it is absent unless the extension
+ * asked for the permission *and* the request knows whose work it is, and an absent
+ * API is what makes a tool check before reaching for files it may not have.
+ */
+describe('createExecutionContext', () => {
+  it('leaves attachments out without the permission', () => {
+    const context = createExecutionContext(vi.fn(), extensionContext, 'user-1', false)
+
+    expect(context.attachments).toBeUndefined()
+  })
+
+  it('leaves attachments out without a user, whatever the permission says', () => {
+    // An attachment belongs to somebody. A request that cannot say whose work it is
+    // doing has no business reading one.
+    const context = createExecutionContext(vi.fn(), extensionContext, undefined, true)
+
+    expect(context.attachments).toBeUndefined()
+  })
+
+  it('reads an attachment for the user the request belongs to', async () => {
+    const sendRequest = vi.fn().mockResolvedValue({
+      id: 'att-7',
+      mime: 'application/pdf',
+      data: 'JVBE',
+      byteSize: 4,
+    })
+
+    const context = createExecutionContext(sendRequest, extensionContext, 'user-1', true)
+    const content = await context.attachments!.read('att-7')
+
+    // The user id is the runtime's to supply, not the tool's: it comes from the
+    // request, so a tool cannot reach another user's file by passing a different one.
+    expect(sendRequest).toHaveBeenCalledWith('attachments.read', {
+      attachmentId: 'att-7',
+      userId: 'user-1',
+    })
+    expect(content?.mime).toBe('application/pdf')
+  })
+
+  it('passes a missing attachment through as nothing', async () => {
+    const context = createExecutionContext(
+      vi.fn().mockResolvedValue(null),
+      extensionContext,
+      'user-1',
+      true
+    )
+
+    expect(await context.attachments!.read('gone')).toBeNull()
+  })
+
+  it('still builds the rest of the context without the permission', () => {
+    const context = createExecutionContext(vi.fn(), extensionContext, 'user-1')
+
+    expect(context.userId).toBe('user-1')
+    expect(context.storage).toBeDefined()
+    expect(context.userStorage).toBeDefined()
+    expect(context.secrets).toBeDefined()
+    expect(context.userSecrets).toBeDefined()
+  })
+})

package/src/runtime/executionContext.ts

@@ -2,7 +2,7 @@
  * Shared execution context builder for tool, action, and scheduler operations.
  */
 
-import type { ExecutionContext, ExtensionContext } from '../types.js'
+import type { AttachmentContent, ExecutionContext, ExtensionContext } from '../types.js'
 import type { RequestMessage } from '../messages.js'
 import { buildExtensionStorageAPI, buildUserStorageAPI } from './storageApi.js'
 import { buildExtensionSecretsAPI, buildUserSecretsAPI } from './secretsApi.js'
@@ -16,7 +16,13 @@ type SendRequest = <T>(method: RequestMessage['method'], payload: unknown) => Pr
 export function createExecutionContext(
   sendRequest: SendRequest,
   extensionContext: ExtensionContext,
-  userId?: string
+  userId?: string,
+  /**
+   * Whether the extension declared `attachments.read`. Checked here rather than in
+   * the host alone so a tool can see whether the capability is there at all, the
+   * way it can for storage — the host refuses it regardless.
+   */
+  canReadAttachments = false
 ): ExecutionContext {
   return {
     userId,
@@ -33,5 +39,19 @@ export function createExecutionContext(
     userSecrets: userId
       ? buildUserSecretsAPI(sendRequest, userId)
       : buildExtensionSecretsAPI(sendRequest),
+    // Only with a user to scope it to. An attachment belongs to somebody, and a
+    // request that cannot say whose work it is doing has no business reading one.
+    ...(canReadAttachments && userId
+      ? {
+          attachments: {
+            async read(attachmentId: string): Promise<AttachmentContent | null> {
+              return sendRequest<AttachmentContent | null>('attachments.read', {
+                attachmentId,
+                userId,
+              })
+            },
+          },
+        }
+      : {}),
   }
 }