smoltalk 0.6.0 → 0.7.0

package/dist/files/BaseFileProvider.d.ts

@@ -0,0 +1,29 @@
+import type { FileProvider, FileProviderContext } from "../files.js";
+import type { ProviderFileRef } from "../classes/message/contentParts.js";
+import { Result } from "../types/result.js";
+/**
+ * Shared behaviour for the built-in file providers: the try/catch, secret
+ * redaction, logging, and Result wrapping are identical across providers, so
+ * they live here. Subclasses implement only the SDK-specific upload/delete and
+ * may throw freely — this class turns a thrown error into a redacted Failure.
+ */
+export declare abstract class BaseFileProvider implements FileProvider {
+    /** Human-readable provider label used in log and error messages, e.g. "OpenAI". */
+    protected abstract readonly label: string;
+    /** SDK-specific upload. May throw; the base class handles logging + redaction. */
+    protected abstract doUpload(data: Uint8Array, mimeType: string, ctx: FileProviderContext): Promise<ProviderFileRef>;
+    /** SDK-specific delete. May throw; the base class handles logging + redaction. */
+    protected abstract doDelete(ref: ProviderFileRef, ctx: {
+        apiKey: string;
+    }): Promise<void>;
+    upload(data: Uint8Array, mimeType: string, ctx: FileProviderContext): Promise<Result<ProviderFileRef>>;
+    delete(ref: ProviderFileRef, ctx: {
+        apiKey: string;
+    }): Promise<Result<void>>;
+    /**
+     * Redact the API key once, then reuse the scrubbed message for BOTH the log
+     * call and the returned Failure. The raw error object is never handed to the
+     * logger — SDKs sometimes attach the Authorization header to it. (B1)
+     */
+    private fail;
+}

package/dist/files/BaseFileProvider.js

@@ -0,0 +1,38 @@
+import { success, failure } from "../types/result.js";
+import { getLogger } from "../util/logger.js";
+import { redactSecret } from "../util/redact.js";
+/**
+ * Shared behaviour for the built-in file providers: the try/catch, secret
+ * redaction, logging, and Result wrapping are identical across providers, so
+ * they live here. Subclasses implement only the SDK-specific upload/delete and
+ * may throw freely — this class turns a thrown error into a redacted Failure.
+ */
+export class BaseFileProvider {
+    async upload(data, mimeType, ctx) {
+        try {
+            return success(await this.doUpload(data, mimeType, ctx));
+        }
+        catch (err) {
+            return this.fail("upload", err, ctx.apiKey);
+        }
+    }
+    async delete(ref, ctx) {
+        try {
+            await this.doDelete(ref, ctx);
+            return success(undefined);
+        }
+        catch (err) {
+            return this.fail("delete", err, ctx.apiKey);
+        }
+    }
+    /**
+     * Redact the API key once, then reuse the scrubbed message for BOTH the log
+     * call and the returned Failure. The raw error object is never handed to the
+     * logger — SDKs sometimes attach the Authorization header to it. (B1)
+     */
+    fail(op, err, apiKey) {
+        const message = redactSecret(err?.message ?? String(err), apiKey);
+        getLogger().error(`${this.label} file ${op} failed:`, message);
+        return failure(`${this.label} file ${op} failed: ${message}`);
+    }
+}

package/dist/files/anthropic.d.ts

@@ -0,0 +1,16 @@
+import type { FileProviderContext } from "../files.js";
+import type { ProviderFileRef } from "../classes/message/contentParts.js";
+import { BaseFileProvider } from "./BaseFileProvider.js";
+export declare function anthropicFileRef(uploaded: {
+    id: string;
+    mime_type?: string;
+}, mimeType: string): ProviderFileRef;
+declare class AnthropicFileProvider extends BaseFileProvider {
+    protected readonly label = "Anthropic";
+    protected doUpload(data: Uint8Array, mimeType: string, ctx: FileProviderContext): Promise<ProviderFileRef>;
+    protected doDelete(ref: ProviderFileRef, ctx: {
+        apiKey: string;
+    }): Promise<void>;
+}
+export declare const anthropicFileProvider: AnthropicFileProvider;
+export {};

package/dist/files/anthropic.js

@@ -0,0 +1,20 @@
+import Anthropic, { toFile } from "@anthropic-ai/sdk";
+import { BaseFileProvider } from "./BaseFileProvider.js";
+const FILES_BETA = "files-api-2025-04-14";
+export function anthropicFileRef(uploaded, mimeType) {
+    return { kind: "providerFile", provider: "anthropic", id: uploaded.id, mimeType: uploaded.mime_type ?? mimeType };
+}
+class AnthropicFileProvider extends BaseFileProvider {
+    label = "Anthropic";
+    async doUpload(data, mimeType, ctx) {
+        const client = new Anthropic({ apiKey: ctx.apiKey });
+        const file = await toFile(data, ctx.filename ?? "upload", { type: mimeType });
+        const uploaded = await client.beta.files.upload({ file, betas: [FILES_BETA] });
+        return anthropicFileRef(uploaded, mimeType);
+    }
+    async doDelete(ref, ctx) {
+        const client = new Anthropic({ apiKey: ctx.apiKey });
+        await client.beta.files.delete(ref.id, { betas: [FILES_BETA] });
+    }
+}
+export const anthropicFileProvider = new AnthropicFileProvider();

package/dist/files/google.d.ts

@@ -0,0 +1,18 @@
+import type { FileProviderContext } from "../files.js";
+import type { ProviderFileRef } from "../classes/message/contentParts.js";
+import { BaseFileProvider } from "./BaseFileProvider.js";
+export declare function googleFileRef(uploaded: {
+    name?: string;
+    uri?: string;
+    mimeType?: string;
+    expirationTime?: string;
+}, mimeType: string): ProviderFileRef;
+declare class GoogleFileProvider extends BaseFileProvider {
+    protected readonly label = "Google";
+    protected doUpload(data: Uint8Array, mimeType: string, ctx: FileProviderContext): Promise<ProviderFileRef>;
+    protected doDelete(ref: ProviderFileRef, ctx: {
+        apiKey: string;
+    }): Promise<void>;
+}
+export declare const googleFileProvider: GoogleFileProvider;
+export {};

package/dist/files/google.js

@@ -0,0 +1,38 @@
+import { GoogleGenAI } from "@google/genai";
+import { BaseFileProvider } from "./BaseFileProvider.js";
+export function googleFileRef(uploaded, mimeType) {
+    if (!uploaded.name) {
+        throw new Error("Google files.upload returned no name; cannot build a ProviderFileRef.");
+    }
+    let expiresAt;
+    if (uploaded.expirationTime) {
+        const parsed = Date.parse(uploaded.expirationTime);
+        if (Number.isFinite(parsed)) {
+            expiresAt = parsed;
+        }
+    }
+    return {
+        kind: "providerFile",
+        provider: "google",
+        id: uploaded.name,
+        uri: uploaded.uri,
+        mimeType: uploaded.mimeType ?? mimeType,
+        expiresAt,
+    };
+}
+class GoogleFileProvider extends BaseFileProvider {
+    label = "Google";
+    async doUpload(data, mimeType, ctx) {
+        const ai = new GoogleGenAI({ apiKey: ctx.apiKey });
+        // P2 (follow-up): `new Blob([data])` copies the buffer; prefer a no-copy /
+        // streaming form if the SDK supports it. Blob is acceptable for v1.
+        const blob = new Blob([data], { type: mimeType });
+        const uploaded = await ai.files.upload({ file: blob, config: { mimeType } });
+        return googleFileRef(uploaded, mimeType);
+    }
+    async doDelete(ref, ctx) {
+        const ai = new GoogleGenAI({ apiKey: ctx.apiKey });
+        await ai.files.delete({ name: ref.id });
+    }
+}
+export const googleFileProvider = new GoogleFileProvider();

package/dist/files/openai.d.ts

@@ -0,0 +1,16 @@
+import type { FileProviderContext } from "../files.js";
+import type { ProviderFileRef } from "../classes/message/contentParts.js";
+import { BaseFileProvider } from "./BaseFileProvider.js";
+/** Maps a created OpenAI file (extra response fields intentionally ignored) to a ref. */
+export declare function openaiFileRef(created: {
+    id: string;
+}, mimeType: string): ProviderFileRef;
+declare class OpenAIFileProvider extends BaseFileProvider {
+    protected readonly label = "OpenAI";
+    protected doUpload(data: Uint8Array, mimeType: string, ctx: FileProviderContext): Promise<ProviderFileRef>;
+    protected doDelete(ref: ProviderFileRef, ctx: {
+        apiKey: string;
+    }): Promise<void>;
+}
+export declare const openaiFileProvider: OpenAIFileProvider;
+export {};

package/dist/files/openai.js

@@ -0,0 +1,23 @@
+import OpenAI from "openai";
+import { toFile } from "openai/uploads";
+import { BaseFileProvider } from "./BaseFileProvider.js";
+/** Maps a created OpenAI file (extra response fields intentionally ignored) to a ref. */
+export function openaiFileRef(created, mimeType) {
+    return { kind: "providerFile", provider: "openai", id: created.id, mimeType };
+}
+class OpenAIFileProvider extends BaseFileProvider {
+    label = "OpenAI";
+    async doUpload(data, mimeType, ctx) {
+        const client = new OpenAI({ apiKey: ctx.apiKey });
+        const file = await toFile(data, ctx.filename ?? "upload", { type: mimeType });
+        // S5: the mapper below is trivial and won't throw post-create, so no orphan
+        // is left here; a provider whose mapper does real work should best-effort delete.
+        const created = await client.files.create({ file, purpose: "user_data" });
+        return openaiFileRef(created, mimeType);
+    }
+    async doDelete(ref, ctx) {
+        const client = new OpenAI({ apiKey: ctx.apiKey });
+        await client.files.delete(ref.id);
+    }
+}
+export const openaiFileProvider = new OpenAIFileProvider();

package/dist/files.d.ts

@@ -0,0 +1,46 @@
+import { Result } from "./types/result.js";
+import type { SmolConfig } from "./types.js";
+import { ProviderFileRef } from "./classes/message/contentParts.js";
+import { BlobRef } from "./util/imageRef.js";
+/** Default cap on a resolved upload's size. Callers can raise it via opts.maxBytes. */
+export declare const DEFAULT_UPLOAD_BYTES: number;
+/**
+ * Options for {@link uploadFile}.
+ *
+ * ⚠️ Security: `{ kind: "path" }` sources read any file the process can access —
+ * do NOT pass untrusted user input as a path. `{ kind: "url" }` sources fetch
+ * arbitrary http(s) URLs; in a server that accepts user URLs, treat this as an
+ * SSRF surface (a full private-IP guard is a planned follow-up).
+ *
+ * Lifecycle: uploaded files persist on the provider until you call `deleteFile`
+ * (OpenAI keeps them indefinitely — storage bills accrue; Anthropic applies a
+ * retention window, so a cached ref can 404 later; Google auto-expires ~48h,
+ * surfaced as `expiresAt`). `uploadFile` is the recommended path for files more
+ * than a few MB — it sends bytes directly, avoiding the base64 round-trip that
+ * inline attachments pay.
+ */
+export type UploadFileOptions = {
+    provider: string;
+    mimeType?: string;
+    filename?: string;
+    /** Max resolved size in bytes. Default {@link DEFAULT_UPLOAD_BYTES} (100 MB). */
+    maxBytes?: number;
+    apiKey?: SmolConfig["apiKey"];
+};
+export type FileProviderContext = {
+    apiKey: string;
+    filename?: string;
+};
+export type FileProvider = {
+    upload(data: Uint8Array, mimeType: string, ctx: FileProviderContext): Promise<Result<ProviderFileRef>>;
+    delete(ref: ProviderFileRef, ctx: {
+        apiKey: string;
+    }): Promise<Result<void>>;
+};
+export declare function registerFileProvider(name: string, impl: FileProvider): void;
+/** Test-only: clear all registered custom providers so registrations don't leak across tests. */
+export declare function _resetForTests(): void;
+export declare function uploadFile(source: BlobRef, opts: UploadFileOptions): Promise<Result<ProviderFileRef>>;
+export declare function deleteFile(ref: ProviderFileRef, opts?: {
+    apiKey?: SmolConfig["apiKey"];
+}): Promise<Result<void>>;

package/dist/files.js

@@ -0,0 +1,70 @@
+import { failure } from "./types/result.js";
+import { loadBlob } from "./util/imageRef.js";
+import { fileFamily } from "./util/attachments.js";
+import { resolveApiKey } from "./util/provider.js";
+import { openaiFileProvider } from "./files/openai.js";
+import { anthropicFileProvider } from "./files/anthropic.js";
+import { googleFileProvider } from "./files/google.js";
+/** Default cap on a resolved upload's size. Callers can raise it via opts.maxBytes. */
+export const DEFAULT_UPLOAD_BYTES = 100 * 1024 * 1024;
+const BUILT_INS = {
+    openai: openaiFileProvider,
+    anthropic: anthropicFileProvider,
+    google: googleFileProvider,
+};
+const registered = Object.create(null);
+export function registerFileProvider(name, impl) {
+    registered[name] = impl;
+}
+/** Test-only: clear all registered custom providers so registrations don't leak across tests. */
+export function _resetForTests() {
+    for (const name of Object.keys(registered)) {
+        delete registered[name];
+    }
+}
+// First-party built-ins win (not registry-overridable); unknown → registry.
+function selectProvider(provider) {
+    const family = fileFamily(provider);
+    if (family !== null) {
+        return { impl: BUILT_INS[family], builtin: true };
+    }
+    const custom = registered[provider];
+    if (custom) {
+        return { impl: custom, builtin: false };
+    }
+    return null;
+}
+export async function uploadFile(source, opts) {
+    const sel = selectProvider(opts.provider);
+    if (!sel) {
+        return failure(`Provider "${opts.provider}" has no Files API. Supported: openai, anthropic, google.`);
+    }
+    const maxBytes = opts.maxBytes ?? DEFAULT_UPLOAD_BYTES;
+    let loaded;
+    try {
+        loaded = await loadBlob(source, { maxBytes });
+    }
+    catch (err) {
+        return failure(`Failed to load file for upload: ${err.message}`);
+    }
+    const mimeType = opts.mimeType ?? loaded.mimeType;
+    if (!mimeType || mimeType.trim() === "") {
+        return failure("Could not determine the file's MIME type; pass opts.mimeType.");
+    }
+    const apiKey = resolveApiKey(opts.provider, { apiKey: opts.apiKey });
+    if (sel.builtin && !apiKey) {
+        return failure(`No API key for provider "${opts.provider}". Set config.apiKey or the provider's env var.`);
+    }
+    return sel.impl.upload(loaded.data, mimeType, { apiKey: apiKey ?? "", filename: opts.filename });
+}
+export async function deleteFile(ref, opts = {}) {
+    const sel = selectProvider(ref.provider);
+    if (!sel) {
+        return failure(`Provider "${ref.provider}" has no Files API.`);
+    }
+    const apiKey = resolveApiKey(ref.provider, { apiKey: opts.apiKey });
+    if (sel.builtin && !apiKey) {
+        return failure(`No API key for provider "${ref.provider}".`);
+    }
+    return sel.impl.delete(ref, { apiKey: apiKey ?? "" });
+}

package/dist/index.d.ts

@@ -11,5 +11,9 @@ export * from "./functions.js";
 export * from "./classes/ToolCall.js";
 export * from "./embed.js";
 export * from "./image.js";
+export { uploadFile, deleteFile, registerFileProvider, DEFAULT_UPLOAD_BYTES } from "./files.js";
+export type { UploadFileOptions, FileProviderContext, FileProvider } from "./files.js";
+export { normalizeImageRef, loadBlob } from "./util/imageRef.js";
+export type { BlobRef } from "./util/imageRef.js";
 export { getLogger, EgonLog } from "./util/logger.js";
 export type { LogLevel } from "./util/logger.js";

package/dist/index.js

@@ -11,4 +11,7 @@ export * from "./functions.js";
 export * from "./classes/ToolCall.js";
 export * from "./embed.js";
 export * from "./image.js";
+// Explicit (not `export *`) so the test-only `_resetForTests` stays off the public surface.
+export { uploadFile, deleteFile, registerFileProvider, DEFAULT_UPLOAD_BYTES } from "./files.js";
+export { normalizeImageRef, loadBlob } from "./util/imageRef.js";
 export { getLogger, EgonLog } from "./util/logger.js";

package/dist/models.d.ts

@@ -2,11 +2,11 @@ import { z } from "zod";
 import { type ModelDataBlob, type HostedTool, type HostedToolPrice } from "./modelData.js";
 export declare const providers: readonly ["ollama", "openai", "openai-responses", "anthropic", "google", "replicate", "modal", "openrouter", "deepinfra", "litellm", "openai-compat"];
 export declare const ProviderSchema: z.ZodEnum<{
-    ollama: "ollama";
     openai: "openai";
-    "openai-responses": "openai-responses";
     anthropic: "anthropic";
     google: "google";
+    "openai-responses": "openai-responses";
+    ollama: "ollama";
     replicate: "replicate";
     modal: "modal";
     openrouter: "openrouter";
@@ -1454,7 +1454,22 @@ export declare function registerTextModel(model: Omit<TextModel, "type"> & {
 export declare function registerModelData(blob: ModelDataBlob): void;
 export declare function clearModelData(): void;
 export declare function getRegisteredModelData(): ModelDataBlob | null;
+/**
+ * All known models: the baked-in catalog merged with any registered
+ * (refreshed) model data and optional per-request overrides. This is the same
+ * data `getModel` searches, exposed as a list so callers can enumerate, filter,
+ * or display the catalog (e.g. a model picker). Fields worth filtering on live
+ * on `ModelType`: `provider`, `openWeights`, `inputTokenCost` / `outputTokenCost`,
+ * `maxInputTokens`, and `modalities`.
+ */
+export declare function getAllModels(requestData?: ModelDataBlob): ModelType[];
 export declare function getModel(modelName: ModelName, requestData?: ModelDataBlob): ModelType | undefined;
+/**
+ * Whether a model is known to accept the given input modality ("image", "pdf", …).
+ * Returns undefined when the model is unknown or carries no `modalities` data —
+ * callers should treat undefined as "don't gate".
+ */
+export declare function modelSupportsInputModality(modelName: ModelName, modality: string, requestData?: ModelDataBlob): boolean | undefined;
 export declare function getHostedTools(opts?: {
     provider?: string;
     model?: string;

package/dist/models.js

@@ -1597,7 +1597,15 @@ function baselineModels() {
         ...embeddingsModels,
     ];
 }
-export function getModel(modelName, requestData) {
+/**
+ * All known models: the baked-in catalog merged with any registered
+ * (refreshed) model data and optional per-request overrides. This is the same
+ * data `getModel` searches, exposed as a list so callers can enumerate, filter,
+ * or display the catalog (e.g. a model picker). Fields worth filtering on live
+ * on `ModelType`: `provider`, `openWeights`, `inputTokenCost` / `outputTokenCost`,
+ * `maxInputTokens`, and `modalities`.
+ */
+export function getAllModels(requestData) {
     let models = baselineModels();
     if (registeredModelData) {
         models = mergeModelData(models, registeredModelData.models);
@@ -1605,7 +1613,26 @@ export function getModel(modelName, requestData) {
     if (requestData) {
         models = mergeModelData(models, requestData.models);
     }
-    return models.find((model) => model.modelName === modelName);
+    return models;
+}
+export function getModel(modelName, requestData) {
+    return getAllModels(requestData).find((model) => model.modelName === modelName);
+}
+/**
+ * Whether a model is known to accept the given input modality ("image", "pdf", …).
+ * Returns undefined when the model is unknown or carries no `modalities` data —
+ * callers should treat undefined as "don't gate".
+ */
+export function modelSupportsInputModality(modelName, modality, requestData) {
+    const model = getModel(modelName, requestData);
+    if (!model || model.type !== "text") {
+        return undefined;
+    }
+    const inputs = model.modalities?.input;
+    if (!inputs) {
+        return undefined;
+    }
+    return inputs.includes(modality);
 }
 export function getHostedTools(opts = {}) {
     // Start from a copy so callers can never mutate the baseline registry.

package/dist/statelogClient.js

@@ -1,5 +1,6 @@
 import { nanoid } from "nanoid";
 import { failure, mergeResults, success } from "./types/result.js";
+import { redactAttachments } from "./util/redact.js";
 export function mergeUploadResults(_results) {
     const results = mergeResults(_results);
     if (!results.success) {
@@ -277,7 +278,7 @@ export class StatelogClient {
         const postBody = JSON.stringify({
             trace_id: this.traceId,
             project_id: this.projectId,
-            data: { ...body, timestamp: new Date().toISOString() },
+            data: redactAttachments({ ...body, timestamp: new Date().toISOString() }),
         });
         if (this.host.toLowerCase() === "stdout") {
             console.log(postBody);

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 export * from "./types/result.js";
+export * from "./classes/message/contentParts.js";
 import { LogLevel } from "./util/logger.js";
 import z, { ZodType } from "zod";
 import { Message } from "./classes/message/index.js";
@@ -57,6 +58,11 @@ export type SmolConfig = {
     }>;
     /** Arbitrary metadata passed to custom model providers. */
     metadata?: Record<string, any>;
+    /** Options for image/PDF attachments on user messages. */
+    attachments?: {
+        /** Max resolved attachment size in bytes. Default 20 MB. Over → Failure. */
+        maxBytes?: number;
+    };
     /** Refreshed model/hosted-tool data (from refreshModels) to layer over the baked-in registry for this call. */
     modelData?: ModelDataBlob;
     /** The conversation messages to send to the model. */
@@ -173,10 +179,6 @@ export interface SmolClient {
     textStream(config: SmolConfig): AsyncGenerator<StreamChunk>;
     _textStream(config: SmolConfig): AsyncGenerator<StreamChunk>;
 }
-export type TextPart = {
-    type: "text";
-    text: string;
-};
 /** Loose variant of SmolConfig for `getClient()` — messages are not required at construction time. */
 export type SmolClientConfig = Omit<SmolConfig, "messages"> & {
     messages?: Message[];
@@ -186,10 +188,6 @@ export type ThinkingBlock = {
     text: string;
     signature: string;
 };
-export declare const TextPartSchema: z.ZodObject<{
-    type: z.ZodLiteral<"text">;
-    text: z.ZodString;
-}, z.z.core.$strip>;
 export declare const ThinkingBlockSchema: z.ZodObject<{
     text: z.ZodString;
     signature: z.ZodString;

package/dist/types.js

@@ -1,4 +1,5 @@
 export * from "./types/result.js";
+export * from "./classes/message/contentParts.js";
 import z from "zod";
 export * from "./types/costEstimate.js";
 export * from "./types/tokenUsage.js";
@@ -13,10 +14,6 @@ export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, m
         hostedToolResults,
     };
 }
-export const TextPartSchema = z.object({
-    type: z.literal("text"),
-    text: z.string(),
-});
 export const ThinkingBlockSchema = z.object({
     text: z.string(),
     signature: z.string(),

package/dist/util/attachments.d.ts

@@ -0,0 +1,34 @@
+import type { ImageRef } from "./imageRef.js";
+/** Filename sent to providers that require one when a file part omits its own. */
+export declare const DEFAULT_ATTACHMENT_FILENAME = "attachment.pdf";
+/** A file part's filename, falling back to the shared default when unset. */
+export declare function attachmentFilename(filename?: string): string;
+/**
+ * Extract base64 + MIME from an ImageRef that has already been resolved to
+ * in-memory bytes. `path`/`url` refs must be resolved (via the BaseClient
+ * normalize pass) before serialization — reaching here with one is a bug.
+ */
+export declare function refToBase64(ref: ImageRef): {
+    base64: string;
+    mimeType: string;
+};
+export declare function toDataUri(base64: string, mimeType: string): string;
+/** The Files-API namespace for a provider, or null when it has no Files API. */
+export declare function fileFamily(provider: string): "openai" | "anthropic" | "google" | null;
+/**
+ * OpenAI-style image URL: a passthrough `url` ref stays a remote URL; anything
+ * else becomes a base64 data URI.
+ */
+export declare function openAiImageUrl(ref: ImageRef): string;
+/**
+ * Anthropic image/document source: a passthrough `url` ref becomes a url source;
+ * anything else becomes a base64 source.
+ */
+export declare function anthropicSource(ref: ImageRef): {
+    type: "url";
+    url: string;
+} | {
+    type: "base64";
+    media_type: string;
+    data: string;
+};

package/dist/util/attachments.js

@@ -0,0 +1,62 @@
+/** Filename sent to providers that require one when a file part omits its own. */
+export const DEFAULT_ATTACHMENT_FILENAME = "attachment.pdf";
+/** A file part's filename, falling back to the shared default when unset. */
+export function attachmentFilename(filename) {
+    if (filename === undefined) {
+        return DEFAULT_ATTACHMENT_FILENAME;
+    }
+    return filename;
+}
+/**
+ * Extract base64 + MIME from an ImageRef that has already been resolved to
+ * in-memory bytes. `path`/`url` refs must be resolved (via the BaseClient
+ * normalize pass) before serialization — reaching here with one is a bug.
+ */
+export function refToBase64(ref) {
+    if (ref.kind === "base64") {
+        return { base64: ref.base64, mimeType: ref.mimeType };
+    }
+    if (ref.kind === "bytes") {
+        return { base64: Buffer.from(ref.data).toString("base64"), mimeType: ref.mimeType };
+    }
+    throw new Error(`Attachment ref must be resolved to base64 or bytes before serialization ` +
+        `(got kind="${ref.kind}"). This is a smoltalk bug.`);
+}
+export function toDataUri(base64, mimeType) {
+    return `data:${mimeType};base64,${base64}`;
+}
+/** The Files-API namespace for a provider, or null when it has no Files API. */
+export function fileFamily(provider) {
+    if (provider === "openai" || provider === "openai-responses") {
+        return "openai";
+    }
+    if (provider === "anthropic") {
+        return "anthropic";
+    }
+    if (provider === "google") {
+        return "google";
+    }
+    return null;
+}
+/**
+ * OpenAI-style image URL: a passthrough `url` ref stays a remote URL; anything
+ * else becomes a base64 data URI.
+ */
+export function openAiImageUrl(ref) {
+    if (ref.kind === "url") {
+        return ref.url;
+    }
+    const { base64, mimeType } = refToBase64(ref);
+    return toDataUri(base64, mimeType);
+}
+/**
+ * Anthropic image/document source: a passthrough `url` ref becomes a url source;
+ * anything else becomes a base64 source.
+ */
+export function anthropicSource(ref) {
+    if (ref.kind === "url") {
+        return { type: "url", url: ref.url };
+    }
+    const { base64, mimeType } = refToBase64(ref);
+    return { type: "base64", media_type: mimeType, data: base64 };
+}

package/dist/util/hostedTools.js

@@ -27,7 +27,11 @@ export function validateHostedTools(requested, model, provider, modelData) {
             if (!effectiveProvider) {
                 effectiveProvider = getModel(model, modelData)?.provider ?? "unknown";
             }
-            return `${name} is a hosted capability; ${model} (${effectiveProvider}) doesn't offer it — pass a search function as a tool instead.`;
+            let err = `${name} is a hosted capability; ${model} (${effectiveProvider}) doesn't offer it — pass a search function as a tool instead.`;
+            if (effectiveProvider === "openai") {
+                err += " You can also use the provider 'openai-responses' to access hosted tools for OpenAI models (you're currently using the base 'openai' provider).";
+            }
+            return err;
         }
     }
     return null;

package/dist/util/imageRef.d.ts

@@ -20,10 +20,25 @@ export type ImageRef = {
      */
     timeoutMs?: number;
 };
+/** Neutral alias of the source union for non-image uses (uploads via {@link loadBlob}). */
+export type BlobRef = ImageRef;
 export type NormalizedImage = {
     data: Uint8Array;
     mimeType: string;
 };
 /** Default timeout for fetching image URLs during normalization (60 seconds). */
 export declare const DEFAULT_FETCH_TIMEOUT_MS = 60000;
-export declare function normalizeImageRef(ref: ImageRef): Promise<NormalizedImage>;
+export declare function normalizeImageRef(ref: ImageRef, options?: {
+    allowedMimePrefixes?: string[];
+    maxBytes?: number;
+}): Promise<NormalizedImage>;
+/**
+ * Load a source to bytes WITHOUT the image MIME gate (used by file uploads,
+ * which accept any type). Enforces `maxBytes` across all kinds.
+ */
+export declare function loadBlob(ref: ImageRef, options?: {
+    maxBytes?: number;
+}): Promise<{
+    data: Uint8Array;
+    mimeType?: string;
+}>;