@matatbread/matbot-plugin-api 0.4.7 → 0.4.8

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.7",
+  "version": "0.4.8",
   "engines": {
     "node": ">=24.0.0"
   },

package/src/base64.ts

@@ -0,0 +1,19 @@
+/*
+ * Base64 over bytes. Not part of the plugin *contract*, but shared by core, workspace and telegram —
+ * the AsyncIterable-broadcaster case: a small stable utility earns a home here once a second package
+ * needs it, rather than being copy-pasted. No `Buffer`: these run in the browser too.
+ */
+
+/** Bytes, not text: `atob` alone yields latin-1 code units, which is wrong for anything non-ASCII. */
+export function decodeBase64(data: string): Uint8Array {
+  return Uint8Array.from(atob(data), ch => ch.charCodeAt(0));
+}
+
+export function encodeBase64(bytes: Uint8Array): string {
+  // Chunked: String.fromCharCode(...bytes) blows the argument limit somewhere around a megabyte, and a
+  // per-byte loop is an order of magnitude slower on the multi-megabyte files media allows.
+  const CHUNK = 0x8000;
+  let bin = '';
+  for (let i = 0; i < bytes.length; i += CHUNK) bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  return btoa(bin);
+}

package/src/bytes.ts

@@ -0,0 +1,19 @@
+/*
+ * Byte-stream helpers. Like ./base64.js: not part of the plugin *contract*, but shared often enough
+ * that a copy per package was already drifting. Nothing node-specific — no `Buffer`.
+ */
+
+/**
+ * Drain a byte stream into one array. `Uint8Array<ArrayBuffer>` rather than the `ArrayBufferLike`
+ * default because callers hand the result to APIs that reject a `SharedArrayBuffer`-backed view
+ * (an OPFS writable, a Drive upload body), and `new Uint8Array(n)` satisfies it for free.
+ */
+export async function collectBytes(data: AsyncIterable<Uint8Array>): Promise<Uint8Array<ArrayBuffer>> {
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for await (const chunk of data) { chunks.push(chunk); total += chunk.byteLength; }
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const chunk of chunks) { out.set(chunk, at); at += chunk.byteLength; }
+  return out;
+}

package/src/errors.ts

@@ -16,7 +16,7 @@
 
 const BRAND = 'matbot';
 
-export type MatbotErrorKind = 'MissingSecret' | 'IncompatibleRuntime' | 'NotAPlugin' | 'PromptCancelled' | 'ReadOnly';
+export type MatbotErrorKind = 'MissingSecret' | 'IncompatibleRuntime' | 'NotAPlugin' | 'PromptCancelled' | 'ReadOnly' | 'MediaRejected';
 
 function isKind(e: unknown, kind: MatbotErrorKind): boolean {
   return typeof e === 'object' && e !== null && (e as Record<string, unknown>)[BRAND] === kind;
@@ -125,3 +125,36 @@ export function readOnlyError(namespace: string, id: string, owner: string): Rea
 export function isReadOnlyError(e: unknown): e is ReadOnlyError {
   return isKind(e, 'ReadOnly');
 }
+
+/**
+ * Thrown by `SessionRunner.open()` when media attached to a submission cannot be accepted. Refusing at
+ * the boundary is the whole point: the alternative is a provider 400 part-way through a turn the user
+ * already believes was sent, with no way back. `reason` says which limit bit, and the message NAMES the
+ * offending file and its size — a bare "too large" leaves a person guessing which of five attachments
+ * to drop.
+ *
+ * A frontend catches this (via {@link isMediaRejectedError}, never `instanceof`) and tells the user;
+ * nothing has been enqueued, so there is no turn to clean up.
+ */
+export interface MediaRejectedError extends Error {
+  matbot: 'MediaRejected';
+  /** `no-store` — nothing is registered under `MediaStore`, so there is nowhere to put the bytes.
+   *  `too-large` — one file exceeds the per-file cap. `session-quota` — this session's stored media
+   *  would exceed its total. `unreadable` — the bytes were malformed: not valid base64, or not the file
+   *  type they claim (a renamed, truncated or placeholder file, caught by a magic-byte check).
+   *  `unsupported-type` — a type no provider decodes (an iPhone HEIC, an SVG), which would 400 the
+   *  request rather than degrade. `unknown-ref` — a submitted `file-ref` does not name media attached
+   *  to this session; phrased as unknown rather than forbidden, exactly as `GET /media/:id` reports a
+   *  file it will not serve, so a refusal never confirms that an id exists. */
+  readonly reason: 'no-store' | 'too-large' | 'session-quota' | 'unreadable' | 'unsupported-type' | 'unknown-ref';
+  /** The attachment's display name, when one file is to blame. */
+  readonly file?:  string;
+}
+export function mediaRejectedError(reason: MediaRejectedError['reason'], message: string, file?: string): MediaRejectedError {
+  const e = new Error(message);
+  e.name = 'MediaRejectedError';
+  return Object.assign(e, { matbot: 'MediaRejected' as const, reason, ...(file !== undefined ? { file } : {}) });
+}
+export function isMediaRejectedError(e: unknown): e is MediaRejectedError {
+  return isKind(e, 'MediaRejected');
+}

package/src/host-machine.ts

@@ -206,7 +206,7 @@ export function singleTurnRequest(req: SingleTurnRequest): CompletionRequest {
     provider: req.provider,
     messages: [{
       id: '', traceId: '', createdAt: new Date().toISOString(), role: 'user',
-      content: [{ type: 'text', text: req.prompt }],
+      content: typeof req.prompt === 'string' ? [{ type: 'text', text: req.prompt }] : req.prompt,
     }],
     ...(req.system     !== undefined ? { system: req.system } : {}),
     ...(req.parameters !== undefined ? { parameters: req.parameters } : {}),

package/src/index.ts

@@ -11,6 +11,8 @@
 export type * from './types.js';
 export { CONFIRM_YES, CONFIRM_NO, isTruncatedToolResult } from './types.js';
 
+export * from './base64.js';
+export * from './bytes.js';
 export * from './store-query.js';
 export * from './errors.js';
 export * from './vault.js';

package/src/plugin.ts

@@ -1,8 +1,8 @@
 import type {
-  FileStore, Principal, Vault, Message, ModelParameters,
+  FileStore, MediaStore, Principal, Vault, Message, ModelParameters,
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage, HookRegistrar,
-  TypeScriptStripper, ToolTypeIndex, ToolPresenter, SteeringPolicy,
+  TypeScriptStripper, ToolTypeIndex, ToolPresenter, SteeringPolicy, UserContent,
 } from './types.js';
 import type { Notifications, Notifier } from './notify.js';
 
@@ -53,7 +53,11 @@ export interface CompletionResponse {
 
 export interface SingleTurnRequest {
   provider: string;
-  prompt:   string;
+  /** The one user message. A plain string is the common case; a {@link UserContent}[] carries media
+   *  alongside the text, for a one-shot that has to *look* at something. Any `file-ref` arm is passed
+   *  through as-is — a one-shot has no session and no residency window, so the caller resolves bytes
+   *  itself (as the `single_turn` tool's `attach` does) rather than the builder guessing a store. */
+  prompt:   string | UserContent[];
   system?:  string;
   /** Forwarded verbatim to {@link CompletionRequest.parameters} — same merge, same guidance. */
   parameters?: Partial<ModelParameters>;
@@ -158,6 +162,13 @@ export interface MatbotServices {
    *  runner uses its own defaults. A plain registered service, consumed by the runner as a member.
    *  See {@link SteeringPolicy}. */
   readonly SteeringPolicy?: SteeringPolicy | undefined;
+  /** Where user-attached session media is written at the submission boundary and read back from on the
+   *  wire. A host that has a file area registers its own as the boot default, so this is normally
+   *  present; a plugin may register a different medium (media on S3, sessions on disk). Absent ⇒ a
+   *  by-value attachment is REFUSED at the boundary naming the reason, and an already-persisted
+   *  `file-ref` degrades to the converters' `[Attached file: x]` note. A text-only deployment is
+   *  unaffected either way. See {@link MediaStore}. */
+  readonly MediaStore?: MediaStore | undefined;
 }
 
 /** The assembled machine: registry services wired to the fixed runtime — what `setup()` receives. */

package/src/types/files.ts

@@ -30,6 +30,20 @@ export interface FileFilter {
   createdBefore?: ISODate;
 }
 
+/**
+ * Where user-supplied session media lives — the bytes a person attached to a message, resolved back
+ * onto the wire by the runner for as long as they stay inside the residency budget.
+ *
+ * Deliberately an ALIAS of {@link FileStore} rather than an interface of its own: `FileMetaData`
+ * already carries `sessionId`/`messageId`/`namespace`/`allowed` and `FileFilter` already filters on
+ * `sessionId`, so session-scoped lifetime, per-message attribution and a servable flag are in the
+ * shape already. The consequence is the point — every existing FileStore (filesystem, SQLite, OPFS,
+ * Drive) is a candidate media store unchanged, so putting media on one medium and everything else on
+ * another is a *registration*, not a port. Two implementations of one interface get an alias, never an
+ * invented role name (cf. `SessionStore`).
+ */
+export type MediaStore = FileStore;
+
 export interface FileStore {
   /** Store a file. When `name` is provided, upserts by (name + namespace); otherwise always creates a new entry. */
   put(

package/src/types/messages.ts

@@ -15,9 +15,11 @@ export type MessageContent = (
   | { type: 'refusal';           text: string }
 
   // ── inline media: bytes plus a mime type. The first three are also `ModelContent` — the arms a tool
-  //    may hand the model to look at (see the `model-content` ToolEvent). `image-url` and `file-ref`
-  //    are references rather than data, and nothing produces them yet; they are reconsidered together
-  //    when durable user-supplied media is built (a `document` / `document-reference` split). ──
+  //    may hand the model to look at (see the `model-content` ToolEvent) — AND the boundary form of
+  //    `UserContent`, the arms a person may attach to a submission. `file-ref` is what such an
+  //    attachment becomes once `open()` has written it through the `MediaStore`: it is the only media
+  //    arm that ever persists, and the runner resolves it back to inline bytes on the outgoing copy
+  //    while it fits the residency budget. `image-url` remains unproduced. ──
   | { type: 'image';             data: string; mimeType: MimeType }
   | { type: 'document';          data: string; mimeType: MimeType; name?: string }
   | { type: 'audio';             data: string; mimeType: MimeType }

package/src/types/session-runner.ts

@@ -1,5 +1,6 @@
 import type { PipelineEvent } from './events.js';
 import type { MessageContent, Session } from './messages.js';
+import type { MimeType } from './primitives.js';
 import type { Principal } from './principal.js';
 import type { SteeringMode } from './steering.js';
 import type { PromptFn } from './tools.js';
@@ -30,10 +31,41 @@ export interface OpenOpts {
   traceId?:  string;
 }
 
+/**
+ * What a *person* may submit — deliberately a narrow subset of {@link MessageContent}, not all of it.
+ * A submission crosses a wire boundary (an HTTP body, a chat platform's update), and widening it to
+ * the full union would let a client post a forged `tool-result`, `thinking` block or `marker` straight
+ * into persisted history.
+ *
+ * The three inline media arms are a **boundary form only**: `open()` writes them through the
+ * `MediaStore` and replaces each with a `file-ref` before the submission is enqueued, so what persists
+ * is always a reference. Bytes are never written into a session document — a 5MB image is ~6.7MB of
+ * base64 riding *both* whole-document writes of every subsequent turn, for the rest of the session.
+ * A caller that has already uploaded (or, like the web composer, would rather not re-post bytes) may
+ * pass the `file-ref` itself and skip the rewrite.
+ */
+export type UserContent = (
+  | { type: 'text';          text: string }
+  | { type: 'image';         data: string; mimeType: MimeType; name?: string }
+  | { type: 'document';      data: string; mimeType: MimeType; name?: string }
+  | { type: 'audio';         data: string; mimeType: MimeType; name?: string }
+  | { type: 'file-ref';      fileId: string; name: string; mimeType: MimeType }
+  | { type: 'form-response'; values: Record<string, string> }
+) & {
+  /** Authorship, carried through exactly as on {@link MessageContent} — an in-process caller driving a
+   *  session (the skills compiler's scratch run) submits machine-authored content and must be able to
+   *  say so. Unlike the arms above this is presentation, not protocol: a remote client asserting it only
+   *  makes its own bubble render agent-side, so it costs the boundary nothing to accept. */
+  origin?: 'robo';
+};
+
 /** Observe a session AND enqueue a submission. The compiler enforces provider/principal here;
  *  a remote frontend deserializing a request body must still validate the wire input itself. */
 export interface SubmitOpenOpts extends OpenOpts {
-  content:      MessageContent[];
+  /** Text plus, optionally, media. Inline media arms are rewritten to `file-ref`s against the
+   *  `MediaStore` before enqueue; with no store registered the submission is refused (see
+   *  {@link MediaRejectedError}) rather than silently dropping what the user attached. */
+  content:      UserContent[];
   provider:     string;
   principal:    Principal;
   /** When true, this submission may be merged with others drained in the same batch. Default false

package/src/types/system-context.ts

@@ -7,9 +7,20 @@ export type SystemContextContributor = (ctx: {
   signal:    AbortSignal;
 }) => string | null | Promise<string | null>;
 
+/** One contributor's contribution to a turn's system prompt, with the plugin that registered it.
+ *  `plugin` is absent for a contributor registered outside the plugin-scoped facade (the host's own),
+ *  since `register`'s `pluginName` is optional. */
+export interface SystemContextPart {
+  plugin?: string;
+  text:    string;
+}
+
 export interface SystemContextRegistry {
   register(contributor: SystemContextContributor, pluginName?: string): void;
   removeByPlugin(pluginName: string): void;
   /** Calls all contributors and joins non-null, non-empty results with double newlines. */
   build(ctx: { session: Session; signal: AbortSignal }): Promise<string | null>;
+  /** The same contributions {@link build} joins, kept apart and attributed — what `about_matbot`
+   *  reports so "why is this in my prompt?" has an answer naming the plugin that put it there. */
+  parts(ctx: { session: Session; signal: AbortSignal }): Promise<SystemContextPart[]>;
 }

package/src/types/tools.ts

@@ -221,6 +221,9 @@ export interface ToolContext {
  * `files`, `prompt` and plugin (un)loading stay off a surface authored by a model and reachable only
  * through the tool contracts. A tool with real source takes `ToolContext` and needs none of this.
  *
+ * `progress` is the one method here and does not breach that, because the reason capabilities are kept
+ * off this surface is authority: it carries none — write-only, reading nothing and reaching nothing.
+ *
  * Not `ToolCallContext` — that name belongs to the `toolcall` hook's context; this is the composed
  * caller's own view, not a hook's view of a call about to run.
  */
@@ -231,6 +234,13 @@ export interface ComposedCallContext {
   readonly provider?: string;
   readonly workdir?:  string;
   readonly signal:    AbortSignal;
+  /**
+   * Report how far along the body is — a `progress` {@link ToolEvent}, identical to what a hand-written
+   * tool yields: surfaced live by the frontend, and neither persisted nor part of the result. A composed
+   * body is a plain async function and so cannot `yield`, which would otherwise leave the event channel
+   * its own nested `tool.x(…)` calls already stream on unreachable from the one place a long run happens.
+   */
+  readonly progress:  (pct: number, message?: string) => void;
 }
 
 /**