@stina/extension-api 1.0.0 → 1.6.0

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

package/src/schemas/components.schema.ts

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

package/src/schemas/index.ts

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

package/src/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')
 
 /**

package/src/types.components.ts

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

package/src/types.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

@@ -73,6 +73,48 @@ export interface ToolResult {
    * would send her after a component that does not exist.
    */
   cardSuggestion?: string
+
+  /**
+   * Files to put in front of the user, in the conversation where the tool ran.
+   *
+   * For what a card cannot hold and the model cannot reproduce: a generated image,
+   * a photo fetched on the user's behalf, the PDF that came attached to a mail.
+   * Like {@link ToolResult.display}, this is for the user — it is lifted out before
+   * the result reaches the model, which would have nothing to do with the bytes but
+   * spend tokens on them. Say in `data` that a file was attached, so she can talk
+   * about it without reciting it.
+   *
+   * The host stores each one as an attachment of the conversation, exactly as a
+   * file the user sends is stored, so it is served to every client and can be saved
+   * or shared from there. The store's own rules apply: JPEG and PNG, PDF, and plain
+   * text, up to 20 MB (1 MB for text). What the file *is* is read from the bytes,
+   * not from `name`, so a PDF mislabelled `.png` still lands as a PDF. One that
+   * fails the rules is dropped with a warning rather than half-shown.
+   *
+   * Attaching a file does not read it to the model. What comes back in the result
+   * the model sees is a reference apiece — `{ id, mime, name? }` under this same
+   * key, in place of the bytes — and she reads one with `core_read_attachment` if
+   * she decides to. That is the intended flow for a mail's attachment: hand it over
+   * here, and let her choose whether to open it.
+   */
+  attachments?: ToolAttachment[]
+}
+
+/**
+ * One file a tool wants to put in the conversation. See {@link ToolResult.attachments}.
+ */
+export interface ToolAttachment {
+  /** The bytes, base64 encoded. What they are is read from them, not from `name`. */
+  data: string
+  /**
+   * A file name to offer when the user saves it, e.g. `friday.png` or
+   * `faktura-1042.pdf`.
+   *
+   * Worth sending for a picture and close to required for a document: it is the
+   * whole label the user sees in the conversation, and it is what Stina has to go
+   * on when she decides whether to read it.
+   */
+  name?: string
 }
 
 /**

package/src/types.ts

@@ -59,6 +59,7 @@ export type {
   ModelCapabilities,
   ChatMessage,
   ChatImage,
+  ChatFile,
   ToolCall,
   ChatOptions,
   GetModelsOptions,
@@ -69,7 +70,7 @@ export type {
 } from './types.provider.js'
 
 // Tools and Actions
-export type { Tool, ToolResult, Action, ActionResult } from './types.tools.js'
+export type { Tool, ToolResult, ToolAttachment, Action, ActionResult } from './types.tools.js'
 
 // Context and APIs
 export type {
@@ -100,6 +101,8 @@ export type {
   BackgroundTaskCallback,
   BackgroundTaskHealth,
   BackgroundWorkersAPI,
+  AttachmentsAPI,
+  AttachmentContent,
 } from './types.context.js'
 
 // Storage and Secrets