@stina/extension-api 1.3.1 → 1.6.0

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

@@ -1178,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.
@@ -1280,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 */
@@ -1299,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
  */
@@ -1714,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.
@@ -2353,30 +2441,44 @@ interface ToolResult {
      */
     cardSuggestion?: string;
     /**
-     * Pictures to show the user, rendered in the conversation where the tool ran.
+     * 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 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.
+     * 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, 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.
+     * 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 picture a tool wants shown. See {@link ToolResult.attachments}.
+ * One file a tool wants to put in the conversation. See {@link ToolResult.attachments}.
  */
 interface ToolAttachment {
-    /** The image bytes, base64 encoded. The format is read from the bytes. */
+    /** 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`. */
+    /**
+     * 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;
 }
 /**
@@ -2405,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 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 };
+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-C0GqXQlu.d.ts → types.tools-R0xGhiBa.d.ts}

@@ -1178,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.
@@ -1280,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 */
@@ -1299,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
  */
@@ -1714,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.
@@ -2353,30 +2441,44 @@ interface ToolResult {
      */
     cardSuggestion?: string;
     /**
-     * Pictures to show the user, rendered in the conversation where the tool ran.
+     * 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 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.
+     * 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, 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.
+     * 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 picture a tool wants shown. See {@link ToolResult.attachments}.
+ * One file a tool wants to put in the conversation. See {@link ToolResult.attachments}.
  */
 interface ToolAttachment {
-    /** The image bytes, base64 encoded. The format is read from the bytes. */
+    /** 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`. */
+    /**
+     * 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;
 }
 /**
@@ -2405,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 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 };
+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.3.1",
+  "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,

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,
+              })
+            },
+          },
+        }
+      : {}),
   }
 }

package/src/runtime.ts

@@ -105,6 +105,13 @@ const messagePort = getMessagePort()
 let extensionModule: ExtensionModule | null = null
 let extensionDisposable: Disposable | null = null
 let extensionContext: ExtensionContext | null = null
+/**
+ * What this extension was granted, kept from activation.
+ *
+ * A request-scoped context is built long after `handleActivate` has returned, and
+ * has to know the same things it did.
+ */
+let grantedPermissions: string[] = []
 let backgroundTaskManager: WorkerBackgroundTaskManager | null = null
 
 const pendingRequests = new Map<string, PendingRequest>()
@@ -284,6 +291,7 @@ async function handleActivate(payload: {
   settings: Record<string, unknown>
 }): Promise<void> {
   const { extensionId, extensionVersion, storagePath, permissions } = payload
+  grantedPermissions = permissions
 
   // Build the context based on permissions
   extensionContext = buildContext(extensionId, extensionVersion, storagePath, permissions)
@@ -346,7 +354,12 @@ function handleSettingsChanged(key: string, value: unknown): void {
 // ExecutionContext builder is in runtime/executionContext.ts
 
 async function handleSchedulerFire(payload: SchedulerFirePayload): Promise<void> {
-  const execContext = createExecutionContext(sendRequest, extensionContext!, payload.userId)
+  const execContext = createExecutionContext(
+      sendRequest,
+      extensionContext!,
+      payload.userId,
+      grantedPermissions.includes('attachments.read')
+    )
 
   // Run callbacks concurrently to avoid blocking
   const results = await Promise.allSettled(
@@ -543,7 +556,12 @@ async function handleToolExecuteRequest(
   }
 
   try {
-    const execContext = createExecutionContext(sendRequest, extensionContext!, payload.userId)
+    const execContext = createExecutionContext(
+      sendRequest,
+      extensionContext!,
+      payload.userId,
+      grantedPermissions.includes('attachments.read')
+    )
 
     const result = await tool.execute(payload.params, execContext)
 
@@ -586,7 +604,12 @@ async function handleActionExecuteRequest(
   }
 
   try {
-    const execContext = createExecutionContext(sendRequest, extensionContext!, payload.userId)
+    const execContext = createExecutionContext(
+      sendRequest,
+      extensionContext!,
+      payload.userId,
+      grantedPermissions.includes('attachments.read')
+    )
 
     const result = await action.execute(payload.params, execContext)
 

package/src/schemas/permissions.schema.ts

@@ -20,6 +20,7 @@ export const VALID_PERMISSIONS = [
   'user.location.read',
   'chat.history.read',
   'chat.current.read',
+  'attachments.read',
   'chat.message.write',
   'provider.register',
   'tools.register',
@@ -75,7 +76,14 @@ const StoragePermissionSchema = z.enum(['storage.collections', 'secrets.manage']
  * User data permission schema
  */
 const UserDataPermissionSchema = z
-  .enum(['user.profile.read', 'user.list', 'user.location.read', 'chat.history.read', 'chat.current.read'])
+  .enum([
+    'user.profile.read',
+    'user.list',
+    'user.location.read',
+    'chat.history.read',
+    'chat.current.read',
+    'attachments.read',
+  ])
   .describe('User data access permission')
 
 /**