@stina/extension-api 1.3.1 → 1.6.0

package/src/types.context.ts

@@ -85,6 +85,49 @@ export interface ExecutionContext {
 
   /** 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.
+ */
+export 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. */
+export 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
 }
 
 /**

package/src/types.permissions.ts

@@ -28,6 +28,13 @@ export type UserDataPermission =
   | 'user.location.read'
   | 'chat.history.read'
   | 'chat.current.read'
+  /**
+   * Read the bytes of a file attached to one of this user's conversations, given
+   * its id. For handing a file on — mailing the PDF she was shown, printing it —
+   * not for reading what it says, which `core_read_attachment` does without an
+   * extension.
+   */
+  | 'attachments.read'
 
 /** Capability permissions */
 export type CapabilityPermission =

package/src/types.provider.ts

@@ -89,9 +89,23 @@ export 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
 }
 
 /**
@@ -189,6 +203,18 @@ export 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 */
@@ -210,6 +236,30 @@ export interface ChatImage {
   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.
+ */
+export 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
  */

package/src/types.tools.ts

@@ -75,31 +75,45 @@ export 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}.
  */
 export 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
 }
 

package/src/types.ts

@@ -59,6 +59,7 @@ export type {
   ModelCapabilities,
   ChatMessage,
   ChatImage,
+  ChatFile,
   ToolCall,
   ChatOptions,
   GetModelsOptions,
@@ -100,6 +101,8 @@ export type {
   BackgroundTaskCallback,
   BackgroundTaskHealth,
   BackgroundWorkersAPI,
+  AttachmentsAPI,
+  AttachmentContent,
 } from './types.context.js'
 
 // Storage and Secrets