@stina/extension-api 1.3.1 → 1.7.0

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

@@ -789,6 +789,8 @@ interface ExtensionContributions {
     commands?: CommandDefinition[];
     /** Prompt contributions for the system prompt */
     prompts?: PromptContribution[];
+    /** External accounts the extension works through, signed in once in Stina's settings */
+    accounts?: AccountContribution[];
     /** Storage collection declarations */
     storage?: {
         collections: {
@@ -799,6 +801,45 @@ interface ExtensionContributions {
         };
     };
 }
+/**
+ * An external account provider the host can sign in to on the user's behalf.
+ *
+ * Only Microsoft for now, and only through Microsoft Graph: mail and calendar
+ * then share one sign-in and one token, instead of an IMAP token and a Graph
+ * token that an admin has to approve separately.
+ */
+type AccountProvider = 'microsoft';
+/**
+ * What an extension needs from an account the user connects to Stina.
+ *
+ * Stina asks the provider for every scope that the enabled extensions declare,
+ * all at once, so that the user - and, at work, their administrator - approves
+ * one request instead of one per extension. Declaring a scope here is therefore
+ * also what makes it show up in that request, and in the list of what is asked
+ * for in the settings.
+ *
+ * @example
+ * ```json
+ * "accounts": [
+ *   {
+ *     "provider": "microsoft",
+ *     "scopes": ["Calendars.ReadWrite"],
+ *     "reason": { "en": "Read and book events in your calendar", "sv": "Läsa och boka i din kalender" }
+ *   }
+ * ]
+ * ```
+ */
+interface AccountContribution {
+    provider: AccountProvider;
+    /**
+     * Microsoft Graph delegated permissions, by name: `Mail.Read`,
+     * `Calendars.ReadWrite`. The host adds `offline_access` and `User.Read`
+     * itself, so they are not declared here.
+     */
+    scopes: string[];
+    /** Why the extension needs them, shown next to the scopes in the settings. */
+    reason?: LocalizedString;
+}
 /**
  * Tool settings view definition (UI schema)
  */
@@ -1178,9 +1219,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 +1334,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 +1365,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 +1803,109 @@ 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;
+    /**
+     * The external accounts this user has connected to Stina.
+     *
+     * Present only for an extension holding `accounts.use`, and only on a request
+     * that knows whose it is - an account belongs to somebody, like an attachment.
+     */
+    readonly accounts?: ConnectedAccountsAPI;
+}
+/**
+ * Working through an account the user signed in to in Stina's settings.
+ *
+ * The user connects a Microsoft account once, and every extension that declares
+ * Microsoft under `contributes.accounts` can use it. The extension never sees the
+ * refresh token; it asks for an access token when it needs one and gets a fresh
+ * one back, refreshed by the host when the old one has run out.
+ *
+ * One thing the host cannot narrow: Microsoft issues a Graph token carrying every
+ * permission the user has granted Stina, not only the ones this extension
+ * declared. The declaration decides whether an extension gets a token at all,
+ * and what the user is asked to approve - not what the token can do.
+ */
+interface ConnectedAccountsAPI {
+    /**
+     * The accounts this user has connected for a provider, newest first.
+     *
+     * An empty list is the normal answer for a user who has not connected one yet:
+     * the extension should point them at Stina's settings rather than start a
+     * sign-in of its own.
+     */
+    list(provider: 'microsoft'): Promise<ConnectedAccount[]>;
+    /**
+     * An access token for one of those accounts, for the scopes this extension
+     * declared.
+     *
+     * Rejects when the account is gone, when the user has not granted every
+     * declared scope yet, or when the provider has revoked the sign-in. The
+     * message says which, in words the user can act on - it is fine to show it.
+     */
+    getAccessToken(accountId: string): Promise<AccountAccessToken>;
+}
+/** An account the user has connected, as an extension sees it. */
+interface ConnectedAccount {
+    /** Stable id, to store alongside whatever the extension keeps for this account. */
+    id: string;
+    provider: 'microsoft';
+    /** The address the user signs in with. */
+    email: string;
+    displayName?: string;
+    /**
+     * Whether the user has granted every scope this extension declared. False when
+     * the extension was installed after the account was connected, and the user has
+     * yet to reconnect it in the settings.
+     */
+    hasRequiredScopes: boolean;
+    /** Set when the provider has refused the stored sign-in and it has to be redone. */
+    needsReconnect: boolean;
+}
+/** An access token, and when it stops working. */
+interface AccountAccessToken {
+    /** Bearer token for Microsoft Graph. */
+    token: string;
+    /** ISO timestamp. Ask again after this; the host refreshes. */
+    expiresAt: string;
+}
+/**
+ * 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 +2545,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 +2611,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 ConnectedAccountsAPI as $, type ActionResult as A, type ProvidersAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type ToolsAPI as F, type GetModelsOptions as G, type HugeIconName as H, type ActionsAPI as I, type EventsAPI as J, type SchedulerAPI as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type SchedulerJobRequest as O, type PanelDefinition as P, type SchedulerSchedule as Q, type UserProfile as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type VoiceSessionOptions as V, type ChatAPI as W, type ChatInstructionMessage as X, type ConversationPresentation as Y, type AttachmentsAPI as Z, type AttachmentContent as _, type ChatOptions as a, type MarkdownProps as a$, type ConnectedAccount as a0, type AccountAccessToken as a1, type LogAPI as a2, type BackgroundWorkersAPI as a3, type BackgroundTaskConfig as a4, type BackgroundTaskCallback as a5, type BackgroundTaskContext as a6, type BackgroundTaskHealth as a7, type BackgroundRestartPolicy as a8, type Query as a9, type ClockProps as aA, type ParagraphProps as aB, type ButtonProps as aC, type TextInputProps as aD, type PasswordInputProps as aE, type NumberInputProps as aF, type TextAreaProps as aG, type DateTimeInputProps as aH, type SelectProps as aI, type IconPickerProps as aJ, type VerticalStackProps as aK, type HorizontalStackProps as aL, type GridProps as aM, type DividerProps as aN, type IconProps as aO, type IconButtonType as aP, type IconButtonProps as aQ, type PanelAction as aR, type PanelProps as aS, type ToggleProps as aT, type CollapsibleProps as aU, type FrameVariant as aV, type FrameProps as aW, type ListProps as aX, type PillVariant as aY, type PillProps as aZ, type CheckboxProps as a_, type QueryOptions as aa, type StorageAPI as ab, type SecretsAPI as ac, type StorageCollectionConfig as ad, type StorageContributions as ae, type AIProvider as af, type ModelCapabilities as ag, type ChatImage as ah, type ChatFile as ai, type ToolCall as aj, type VoiceTransportRequest as ak, type Tool as al, type ToolAttachment as am, type Action as an, type ExtensionModule as ao, type AllowedCSSProperty as ap, type ExtensionComponentStyle as aq, type ExtensionComponentData as ar, type ExtensionComponentIterator as as, type ExtensionComponentChildren as at, type ExtensionActionCall as au, type ExtensionActionRef as av, type ExtensionDataSource as aw, type ExtensionPanelDefinition as ax, type HeaderProps as ay, type LabelProps as az, type StreamEvent as b, type TextPreviewProps as b0, type ModalProps as b1, type ConditionalGroupProps as b2, type WeatherCondition as b3, type WeatherWind as b4, type WeatherNowProps as b5, type WeatherForecastStep as b6, type WeatherForecastProps as b7, type ChartKind as b8, type ChartSeries as b9, type ChartProps as ba, type StatTrend as bb, type StatTileProps as bc, type ProgressShape as bd, type ProgressColor as be, type ProgressBarProps as bf, type KeyValueRow as bg, type KeyValueListProps as bh, type TimelineVariant as bi, type TimelineEntry as bj, type TimelineProps as bk, type NoteVariant as bl, type NoteProps as bm, type CalendarEventStatus as bn, type CalendarEventProps as bo, type ExecutionContext as bp, 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 AccountProvider as w, type AccountContribution as x, type ExtensionContext as y, type SettingsAPI as z };

package/dist/{types.tools-C0GqXQlu.d.ts → types.tools-DcFBsfRV.d.ts}

@@ -789,6 +789,8 @@ interface ExtensionContributions {
     commands?: CommandDefinition[];
     /** Prompt contributions for the system prompt */
     prompts?: PromptContribution[];
+    /** External accounts the extension works through, signed in once in Stina's settings */
+    accounts?: AccountContribution[];
     /** Storage collection declarations */
     storage?: {
         collections: {
@@ -799,6 +801,45 @@ interface ExtensionContributions {
         };
     };
 }
+/**
+ * An external account provider the host can sign in to on the user's behalf.
+ *
+ * Only Microsoft for now, and only through Microsoft Graph: mail and calendar
+ * then share one sign-in and one token, instead of an IMAP token and a Graph
+ * token that an admin has to approve separately.
+ */
+type AccountProvider = 'microsoft';
+/**
+ * What an extension needs from an account the user connects to Stina.
+ *
+ * Stina asks the provider for every scope that the enabled extensions declare,
+ * all at once, so that the user - and, at work, their administrator - approves
+ * one request instead of one per extension. Declaring a scope here is therefore
+ * also what makes it show up in that request, and in the list of what is asked
+ * for in the settings.
+ *
+ * @example
+ * ```json
+ * "accounts": [
+ *   {
+ *     "provider": "microsoft",
+ *     "scopes": ["Calendars.ReadWrite"],
+ *     "reason": { "en": "Read and book events in your calendar", "sv": "Läsa och boka i din kalender" }
+ *   }
+ * ]
+ * ```
+ */
+interface AccountContribution {
+    provider: AccountProvider;
+    /**
+     * Microsoft Graph delegated permissions, by name: `Mail.Read`,
+     * `Calendars.ReadWrite`. The host adds `offline_access` and `User.Read`
+     * itself, so they are not declared here.
+     */
+    scopes: string[];
+    /** Why the extension needs them, shown next to the scopes in the settings. */
+    reason?: LocalizedString;
+}
 /**
  * Tool settings view definition (UI schema)
  */
@@ -1178,9 +1219,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 +1334,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 +1365,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 +1803,109 @@ 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;
+    /**
+     * The external accounts this user has connected to Stina.
+     *
+     * Present only for an extension holding `accounts.use`, and only on a request
+     * that knows whose it is - an account belongs to somebody, like an attachment.
+     */
+    readonly accounts?: ConnectedAccountsAPI;
+}
+/**
+ * Working through an account the user signed in to in Stina's settings.
+ *
+ * The user connects a Microsoft account once, and every extension that declares
+ * Microsoft under `contributes.accounts` can use it. The extension never sees the
+ * refresh token; it asks for an access token when it needs one and gets a fresh
+ * one back, refreshed by the host when the old one has run out.
+ *
+ * One thing the host cannot narrow: Microsoft issues a Graph token carrying every
+ * permission the user has granted Stina, not only the ones this extension
+ * declared. The declaration decides whether an extension gets a token at all,
+ * and what the user is asked to approve - not what the token can do.
+ */
+interface ConnectedAccountsAPI {
+    /**
+     * The accounts this user has connected for a provider, newest first.
+     *
+     * An empty list is the normal answer for a user who has not connected one yet:
+     * the extension should point them at Stina's settings rather than start a
+     * sign-in of its own.
+     */
+    list(provider: 'microsoft'): Promise<ConnectedAccount[]>;
+    /**
+     * An access token for one of those accounts, for the scopes this extension
+     * declared.
+     *
+     * Rejects when the account is gone, when the user has not granted every
+     * declared scope yet, or when the provider has revoked the sign-in. The
+     * message says which, in words the user can act on - it is fine to show it.
+     */
+    getAccessToken(accountId: string): Promise<AccountAccessToken>;
+}
+/** An account the user has connected, as an extension sees it. */
+interface ConnectedAccount {
+    /** Stable id, to store alongside whatever the extension keeps for this account. */
+    id: string;
+    provider: 'microsoft';
+    /** The address the user signs in with. */
+    email: string;
+    displayName?: string;
+    /**
+     * Whether the user has granted every scope this extension declared. False when
+     * the extension was installed after the account was connected, and the user has
+     * yet to reconnect it in the settings.
+     */
+    hasRequiredScopes: boolean;
+    /** Set when the provider has refused the stored sign-in and it has to be redone. */
+    needsReconnect: boolean;
+}
+/** An access token, and when it stops working. */
+interface AccountAccessToken {
+    /** Bearer token for Microsoft Graph. */
+    token: string;
+    /** ISO timestamp. Ask again after this; the host refreshes. */
+    expiresAt: string;
+}
+/**
+ * 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 +2545,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 +2611,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 ConnectedAccountsAPI as $, type ActionResult as A, type ProvidersAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type ToolsAPI as F, type GetModelsOptions as G, type HugeIconName as H, type ActionsAPI as I, type EventsAPI as J, type SchedulerAPI as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type SchedulerJobRequest as O, type PanelDefinition as P, type SchedulerSchedule as Q, type UserProfile as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type VoiceSessionOptions as V, type ChatAPI as W, type ChatInstructionMessage as X, type ConversationPresentation as Y, type AttachmentsAPI as Z, type AttachmentContent as _, type ChatOptions as a, type MarkdownProps as a$, type ConnectedAccount as a0, type AccountAccessToken as a1, type LogAPI as a2, type BackgroundWorkersAPI as a3, type BackgroundTaskConfig as a4, type BackgroundTaskCallback as a5, type BackgroundTaskContext as a6, type BackgroundTaskHealth as a7, type BackgroundRestartPolicy as a8, type Query as a9, type ClockProps as aA, type ParagraphProps as aB, type ButtonProps as aC, type TextInputProps as aD, type PasswordInputProps as aE, type NumberInputProps as aF, type TextAreaProps as aG, type DateTimeInputProps as aH, type SelectProps as aI, type IconPickerProps as aJ, type VerticalStackProps as aK, type HorizontalStackProps as aL, type GridProps as aM, type DividerProps as aN, type IconProps as aO, type IconButtonType as aP, type IconButtonProps as aQ, type PanelAction as aR, type PanelProps as aS, type ToggleProps as aT, type CollapsibleProps as aU, type FrameVariant as aV, type FrameProps as aW, type ListProps as aX, type PillVariant as aY, type PillProps as aZ, type CheckboxProps as a_, type QueryOptions as aa, type StorageAPI as ab, type SecretsAPI as ac, type StorageCollectionConfig as ad, type StorageContributions as ae, type AIProvider as af, type ModelCapabilities as ag, type ChatImage as ah, type ChatFile as ai, type ToolCall as aj, type VoiceTransportRequest as ak, type Tool as al, type ToolAttachment as am, type Action as an, type ExtensionModule as ao, type AllowedCSSProperty as ap, type ExtensionComponentStyle as aq, type ExtensionComponentData as ar, type ExtensionComponentIterator as as, type ExtensionComponentChildren as at, type ExtensionActionCall as au, type ExtensionActionRef as av, type ExtensionDataSource as aw, type ExtensionPanelDefinition as ax, type HeaderProps as ay, type LabelProps as az, type StreamEvent as b, type TextPreviewProps as b0, type ModalProps as b1, type ConditionalGroupProps as b2, type WeatherCondition as b3, type WeatherWind as b4, type WeatherNowProps as b5, type WeatherForecastStep as b6, type WeatherForecastProps as b7, type ChartKind as b8, type ChartSeries as b9, type ChartProps as ba, type StatTrend as bb, type StatTileProps as bc, type ProgressShape as bd, type ProgressColor as be, type ProgressBarProps as bf, type KeyValueRow as bg, type KeyValueListProps as bh, type TimelineVariant as bi, type TimelineEntry as bj, type TimelineProps as bk, type NoteVariant as bl, type NoteProps as bm, type CalendarEventStatus as bn, type CalendarEventProps as bo, type ExecutionContext as bp, 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 AccountProvider as w, type AccountContribution as x, type ExtensionContext as y, type SettingsAPI as z };

package/package.json

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