runline 0.7.7 → 0.8.1

package/dist/commands/auth.js

@@ -5,6 +5,7 @@ import { addConnection } from "../config/loader.js";
 import { OAUTH_CALLBACK_PORT, runOAuth } from "../core/oauth.js";
 import { loadAllPlugins } from "../plugin/loader.js";
 import { registry } from "../plugin/registry.js";
+import { connectionFields } from "../plugin/schema.js";
 import { printError, printJson, printSuccess } from "../utils/output.js";
 export async function auth(plugin, options) {
     await loadAllPlugins();
@@ -20,8 +21,9 @@ export async function auth(plugin, options) {
     // Client credentials: CLI flag > env > interactive prompt.
     // Env var names follow the plugin's own convention when declared
     // on its connection schema; fall back to generic names otherwise.
-    const envIdVar = def.connectionConfigSchema?.clientId?.env;
-    const envSecretVar = def.connectionConfigSchema?.clientSecret?.env;
+    const connectionSchema = connectionFields(def.connectionConfigSchema);
+    const envIdVar = connectionSchema.clientId?.env;
+    const envSecretVar = connectionSchema.clientSecret?.env;
     const resolvedClientId = options.clientId ?? (envIdVar ? process.env[envIdVar] : undefined);
     const resolvedClientSecret = options.clientSecret ??
         (envSecretVar ? process.env[envSecretVar] : undefined);

package/dist/config/loader.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectionConfig } from "../plugin/types.js";
+import type { ConnectionConfig, ConnectionSchema } from "../plugin/types.js";
 import { type RunlineConfig } from "./types.js";
 export declare function findConfigDir(): string | null;
 export declare function loadConfig(): RunlineConfig;
@@ -17,6 +17,4 @@ export declare function removeConnection(name: string): boolean;
  */
 export declare function updateConnectionConfig(name: string, patch: Record<string, unknown>): Promise<void>;
 export declare function getConnection(plugin: string, name?: string): ConnectionConfig | undefined;
-export declare function applyEnvOverrides(conn: ConnectionConfig, schema?: Record<string, {
-    env?: string;
-}>): ConnectionConfig;
+export declare function applyEnvOverrides(conn: ConnectionConfig, schema?: ConnectionSchema): ConnectionConfig;

package/dist/config/loader.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import lockfile from "proper-lockfile";
+import { connectionFields } from "../plugin/schema.js";
 import { DEFAULT_CONFIG } from "./types.js";
 const CONFIG_DIR_NAME = ".runline";
 const CONFIG_FILE = "config.json";
@@ -117,7 +118,7 @@ export function applyEnvOverrides(conn, schema) {
     if (!schema)
         return conn;
     const config = { ...conn.config };
-    for (const [key, field] of Object.entries(schema)) {
+    for (const [key, field] of Object.entries(connectionFields(schema))) {
         if (field.env && !config[key]) {
             const envVal = process.env[field.env];
             if (envVal)

package/dist/core/engine.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { getQuickJS, shouldInterruptAfterDeadline, } from "quickjs-emscripten";
 import { applyEnvOverrides, updateConnectionConfig } from "../config/loader.js";
+import { formatValidationError, helpInputs, isTypedInputSchema, validateTypedInput, } from "../plugin/schema.js";
 export class ExecutionEngine {
     registry;
     config;
@@ -146,6 +147,12 @@ export class ExecutionEngine {
                 await updateConnectionConfig(connection.name, patch);
             },
         };
+        if (isTypedInputSchema(action.inputSchema)) {
+            const validation = validateTypedInput(action.inputSchema, args);
+            if (!validation.ok) {
+                throw new Error(formatValidationError(path, validation));
+            }
+        }
         return action.execute(args, ctx);
     }
     resolveConnection(plugin) {
@@ -230,14 +237,7 @@ function buildHelpData(plugins) {
         data[p.name] = p.actions.map((a) => ({
             action: a.name,
             description: a.description,
-            inputs: Object.fromEntries(Object.entries(a.inputSchema ?? {}).map(([k, v]) => [
-                k,
-                {
-                    type: v.type,
-                    required: !!v.required,
-                    description: v.description,
-                },
-            ])),
+            inputs: helpInputs(a.inputSchema),
         }));
     }
     return data;
@@ -291,7 +291,7 @@ const __index = (() => {
 
 const __formatSignature = (plugin, entry) => {
   const fields = Object.entries(entry.inputs || {})
-    .map(([k, v]) => k + (v.required ? '' : '?') + ': ' + v.type)
+    .map(([k, v]) => k + (v.required ? '' : '?') + ': ' + (v.displayType || v.type))
     .join(', ');
   return plugin + '.' + entry.action + (fields ? '({ ' + fields + ' })' : '()');
 };
@@ -370,10 +370,15 @@ const __actionsApi = {
     for (const k of Object.keys(provided)) {
       if (!(k in inputs)) unknown.push(k);
       else {
-        const expected = inputs[k].type;
-        const actual = Array.isArray(provided[k]) ? 'array' : typeof provided[k];
-        if (expected !== actual && !(provided[k] === null || provided[k] === undefined)) {
-          typeErrors.push({ field: k, expected, actual });
+        const spec = inputs[k];
+        const expected = spec.type;
+        const actual = Array.isArray(provided[k]) ? 'array' : provided[k] === null ? 'null' : typeof provided[k];
+        if (provided[k] !== null && provided[k] !== undefined && expected !== actual) {
+          typeErrors.push({ field: k, expected: spec.displayType || expected, actual });
+        } else if (spec.enum && !spec.enum.includes(provided[k])) {
+          typeErrors.push({ field: k, expected: spec.enum.map(String).join(' | '), actual: __fmt(provided[k]) });
+        } else if ('const' in spec && provided[k] !== spec.const) {
+          typeErrors.push({ field: k, expected: __fmt(spec.const), actual: __fmt(provided[k]) });
         }
       }
     }

package/dist/index.d.ts

@@ -5,13 +5,13 @@ export type { EngineOptions, ExecuteResult } from "./core/engine.js";
 export { ExecutionEngine } from "./core/engine.js";
 export type { BuildAuthUrlOptions, ExchangeCodeOptions, OAuthTokens, PKCEPair, RunOAuthOptions, } from "./core/oauth.js";
 export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, runOAuth, } from "./core/oauth.js";
-export type { ActionDefinition, PluginFunction, RunlinePluginAPI, SchemaField, } from "./plugin/api.js";
+export type { ActionDefinition, PluginFunction, RunlinePluginAPI, } from "./plugin/api.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export type { InstalledPlugin, PluginSource } from "./plugin/installer.js";
 export { installPlugin, listInstalled, parsePluginSource, removePlugin, } from "./plugin/installer.js";
 export { discoverPlugins, loadAllPlugins, loadPluginFromPath, loadPluginsFromConfig, } from "./plugin/loader.js";
 export { PluginRegistry, registry } from "./plugin/registry.js";
-export type { ActionContext, ActionDef, ConnectionConfig, InputField, InputSchema, OAuthConfig, PluginDef, } from "./plugin/types.js";
+export type { ActionContext, ActionDef, ConnectionConfig, ConnectionSchema, ConnectionSchemaField, InputField, InputSchema, LegacyConnectionSchema, OAuthConfig, PluginDef, } from "./plugin/types.js";
 export type { RunlineOptions } from "./sdk.js";
 export { Runline } from "./sdk.js";
 export type { ExecOptions, ExecResult, OutputParser } from "./utils/cli.js";

package/dist/plugin/api.d.ts

@@ -1,11 +1,4 @@
-import type { ActionDef, InputSchema, OAuthConfig, PluginDef } from "./types.js";
-export interface SchemaField {
-    type: "string" | "number" | "boolean";
-    required?: boolean;
-    description?: string;
-    default?: unknown;
-    env?: string;
-}
+import type { ActionDef, ConnectionSchema, InputSchema, OAuthConfig, PluginDef } from "./types.js";
 export interface ActionDefinition {
     description?: string;
     inputSchema?: InputSchema;
@@ -13,7 +6,7 @@ export interface ActionDefinition {
 }
 export interface RunlinePluginAPI {
     registerAction(name: string, def: ActionDefinition): void;
-    setConnectionSchema(schema: Record<string, SchemaField>): void;
+    setConnectionSchema(schema: ConnectionSchema): void;
     setName(name: string): void;
     setVersion(version: string): void;
     /**

package/dist/plugin/api.js

@@ -19,10 +19,7 @@ export function createPluginAPI(pluginId) {
             actions.push({ name: actionName, ...def });
         },
         setConnectionSchema(schema) {
-            connectionConfigSchema = {};
-            for (const [key, field] of Object.entries(schema)) {
-                connectionConfigSchema[key] = { ...field };
-            }
+            connectionConfigSchema = { ...schema };
         },
         setOAuth(cfg) {
             oauth = { ...cfg };

package/dist/plugin/schema.d.ts

@@ -0,0 +1,19 @@
+import type { ConnectionSchema, HelpInput, InputSchema, LegacyConnectionSchema, LegacyInputSchema, TypedInputSchema } from "./types.js";
+export interface ValidationResult {
+    ok: boolean;
+    missing: string[];
+    unknown: string[];
+    typeErrors: Array<{
+        field: string;
+        expected: string;
+        actual: string;
+    }>;
+    errors: string[];
+}
+export declare function isTypedInputSchema(schema: InputSchema | undefined): schema is TypedInputSchema;
+export declare function legacyFields(schema: InputSchema | undefined): LegacyInputSchema;
+export declare function connectionFields(schema: ConnectionSchema | undefined): LegacyConnectionSchema;
+export declare function helpInputs(schema: InputSchema | undefined): Record<string, HelpInput>;
+export declare function validateLegacyInput(schema: LegacyInputSchema, input: unknown): ValidationResult;
+export declare function validateTypedInput(schema: TypedInputSchema, input: unknown): ValidationResult;
+export declare function formatValidationError(path: string, result: ValidationResult): string;

package/dist/plugin/schema.js

@@ -0,0 +1,168 @@
+import { Check, Errors } from "typebox/value";
+export function isTypedInputSchema(schema) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    const candidate = schema;
+    return typeof candidate.type === "string" || Array.isArray(candidate.anyOf);
+}
+export function legacyFields(schema) {
+    if (!schema || isTypedInputSchema(schema))
+        return {};
+    return schema;
+}
+export function connectionFields(schema) {
+    if (!schema)
+        return {};
+    if (!isTypedInputSchema(schema))
+        return schema;
+    const metadata = schema;
+    if (metadata.type !== "object")
+        return {};
+    const required = new Set(metadata.required ?? []);
+    return Object.fromEntries(Object.entries(metadata.properties ?? {}).map(([key, field]) => [
+        key,
+        {
+            type: baseType(field),
+            required: required.has(key),
+            description: field.description,
+            default: field.default,
+            env: field.env,
+        },
+    ]));
+}
+export function helpInputs(schema) {
+    if (!schema)
+        return {};
+    if (!isTypedInputSchema(schema)) {
+        const legacy = schema;
+        return Object.fromEntries(Object.entries(legacy).map(([key, field]) => [
+            key,
+            {
+                type: field.type,
+                required: !!field.required,
+                description: field.description,
+            },
+        ]));
+    }
+    const metadata = schema;
+    if (metadata.type !== "object")
+        return {};
+    const required = new Set(metadata.required ?? []);
+    return Object.fromEntries(Object.entries(metadata.properties ?? {}).map(([key, field]) => [
+        key,
+        {
+            type: baseType(field),
+            displayType: displayType(field),
+            required: required.has(key),
+            description: field.description,
+            enum: enumValues(field),
+            const: field.const,
+        },
+    ]));
+}
+export function validateLegacyInput(schema, input) {
+    const provided = input && typeof input === "object"
+        ? input
+        : {};
+    const missing = [];
+    const unknown = [];
+    const typeErrors = [];
+    for (const [key, spec] of Object.entries(schema)) {
+        if (spec.required && !(key in provided))
+            missing.push(key);
+    }
+    for (const key of Object.keys(provided)) {
+        if (!(key in schema)) {
+            unknown.push(key);
+            continue;
+        }
+        const expected = schema[key].type;
+        const actual = valueType(provided[key]);
+        if (provided[key] !== null &&
+            provided[key] !== undefined &&
+            expected !== actual) {
+            typeErrors.push({ field: key, expected, actual });
+        }
+    }
+    return validationResult({ missing, unknown, typeErrors });
+}
+export function validateTypedInput(schema, input) {
+    if (Check(schema, input))
+        return validationResult({});
+    return validationResult({
+        errors: [...Errors(schema, input)].map((error) => {
+            const path = error.instancePath || "/";
+            return `${path} ${error.message}`;
+        }),
+    });
+}
+export function formatValidationError(path, result) {
+    const parts = [`Invalid input for ${path}.`];
+    if (result.missing.length > 0) {
+        parts.push(`Missing required fields: ${result.missing.join(", ")}.`);
+    }
+    if (result.unknown.length > 0) {
+        parts.push(`Unknown fields: ${result.unknown.join(", ")}.`);
+    }
+    if (result.typeErrors.length > 0) {
+        parts.push(`Type errors: ${result.typeErrors
+            .map((e) => `${e.field} expected ${e.expected}, got ${e.actual}`)
+            .join("; ")}.`);
+    }
+    if (result.errors.length > 0) {
+        parts.push(`Validation errors: ${result.errors.join("; ")}.`);
+    }
+    return parts.join(" ");
+}
+function validationResult(input) {
+    const missing = input.missing ?? [];
+    const unknown = input.unknown ?? [];
+    const typeErrors = input.typeErrors ?? [];
+    const errors = input.errors ?? [];
+    return {
+        ok: missing.length === 0 &&
+            unknown.length === 0 &&
+            typeErrors.length === 0 &&
+            errors.length === 0,
+        missing,
+        unknown,
+        typeErrors,
+        errors,
+    };
+}
+function displayType(schema) {
+    if (schema.anyOf?.length)
+        return schema.anyOf.map(displayType).join(" | ");
+    if (schema.enum?.length)
+        return schema.enum.map(String).join(" | ");
+    if (schema.const !== undefined)
+        return JSON.stringify(schema.const);
+    return schema.type ?? "unknown";
+}
+function baseType(schema) {
+    if (schema.anyOf?.length) {
+        const types = [...new Set(schema.anyOf.map(baseType))];
+        return types.length === 1 ? types[0] : types.join(" | ");
+    }
+    if (schema.type)
+        return schema.type;
+    if (schema.const !== undefined)
+        return valueType(schema.const);
+    return "unknown";
+}
+function enumValues(schema) {
+    if (schema.enum?.length)
+        return schema.enum;
+    if (schema.anyOf?.length &&
+        schema.anyOf.every((s) => s.const !== undefined)) {
+        return schema.anyOf.map((s) => s.const);
+    }
+    return undefined;
+}
+function valueType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}

package/dist/plugin/types.d.ts

@@ -1,10 +1,30 @@
+import type { TSchema } from "typebox";
 export interface InputField {
     type: "string" | "number" | "boolean" | "object" | "array";
     description?: string;
     required?: boolean;
     default?: unknown;
 }
-export type InputSchema = Record<string, InputField>;
+export type LegacyInputSchema = Record<string, InputField>;
+export type TypedInputSchema = TSchema;
+export type InputSchema = LegacyInputSchema | TypedInputSchema;
+export interface ConnectionSchemaField {
+    type: string;
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+    env?: string;
+}
+export type LegacyConnectionSchema = Record<string, ConnectionSchemaField>;
+export type ConnectionSchema = LegacyConnectionSchema | TSchema;
+export interface HelpInput {
+    type: string;
+    displayType?: string;
+    required: boolean;
+    description?: string;
+    enum?: unknown[];
+    const?: unknown;
+}
 export interface ActionDef {
     name: string;
     description?: string;
@@ -73,13 +93,7 @@ export interface PluginDef {
     name: string;
     version: string;
     actions: ActionDef[];
-    connectionConfigSchema?: Record<string, {
-        type: string;
-        required?: boolean;
-        description?: string;
-        default?: unknown;
-        env?: string;
-    }>;
+    connectionConfigSchema?: ConnectionSchema;
     /** OAuth2 config for `runline auth <plugin>`. */
     oauth?: OAuthConfig;
     /** @internal */

package/dist/plugins/_shared/imageFile.js

@@ -0,0 +1,40 @@
+/**
+ * Shared helper for image-generation plugins: write generated bytes to a
+ * file and return its path, instead of returning raw base64.
+ *
+ * Base64 image payloads in an action result bloat the agent context and are
+ * stripped by many hosts before reaching the model, so the agent can never
+ * actually deliver the image. A file `path` hands straight to a host
+ * send_file/attachment tool. Plugins load in-process via jiti, so node:fs is
+ * available (same pattern as googleDrive/googleSlides).
+ */
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const MIME_EXT = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/jpg": "jpg",
+    "image/webp": "webp",
+    "image/gif": "gif",
+    "image/svg+xml": "svg",
+};
+export function extForMime(mimeType) {
+    if (!mimeType)
+        return "png";
+    return MIME_EXT[mimeType] ?? mimeType.split("/")[1]?.split("+")[0] ?? "png";
+}
+/**
+ * Decode base64 image bytes and write them to `saveDir` (or the OS temp dir),
+ * named `<provider>-<stamp>-<index>.<ext>`. Returns the file path + size.
+ */
+export function writeImageFile(opts) {
+    const mimeType = opts.mimeType ?? "image/png";
+    const dir = (typeof opts.saveDir === "string" && opts.saveDir.trim()) || tmpdir();
+    const bytes = Buffer.from(opts.base64 ?? "", "base64");
+    const stamp = opts.stamp ?? Date.now();
+    const path = join(dir, `${opts.provider}-${stamp}-${opts.index}.${extForMime(mimeType)}`);
+    writeFileSync(path, bytes);
+    return { path, mimeType, byteLength: bytes.length };
+}
+export const SEND_FILE_NOTE = "Image(s) written to disk. Deliver each to the user with send_file using its `path`.";

package/dist/plugins/_shared/microsoftAuth.js

@@ -0,0 +1,100 @@
+const REFRESH_SKEW_MS = 60_000;
+function authority(cfg) {
+    return `https://login.microsoftonline.com/${cfg.tenantId || "common"}/oauth2/v2.0/token`;
+}
+export function isAppOnly(cfg) {
+    return !cfg.refreshToken && !!(cfg.tenantId && cfg.clientId && cfg.clientSecret);
+}
+/** Graph path prefix for the acting principal: /me (delegated) or /users/{upn} (app-only). */
+export function userBase(ctx) {
+    const cfg = ctx.connection.config;
+    if (cfg.refreshToken)
+        return "/me";
+    if (cfg.userUpn)
+        return `/users/${encodeURIComponent(cfg.userUpn)}`;
+    throw new Error("microsoft: app-only mode requires userUpn (target mailbox/drive). Set MS_GRAPH_USER_UPN, or connect via OAuth.");
+}
+export async function microsoftAccessToken(ctx, pluginName, scopes) {
+    const cfg = ctx.connection.config;
+    if (cfg.accessToken &&
+        typeof cfg.accessTokenExpiresAt === "number" &&
+        Date.now() < cfg.accessTokenExpiresAt - REFRESH_SKEW_MS) {
+        return cfg.accessToken;
+    }
+    let body;
+    if (cfg.refreshToken) {
+        if (!cfg.clientId || !cfg.clientSecret) {
+            throw new Error(`${pluginName}: missing clientId/clientSecret for OAuth refresh.`);
+        }
+        body = new URLSearchParams({
+            client_id: cfg.clientId,
+            client_secret: cfg.clientSecret,
+            refresh_token: cfg.refreshToken,
+            grant_type: "refresh_token",
+            scope: [...scopes, "offline_access"].join(" "),
+        });
+    }
+    else if (isAppOnly(cfg)) {
+        body = new URLSearchParams({
+            client_id: cfg.clientId,
+            client_secret: cfg.clientSecret,
+            grant_type: "client_credentials",
+            scope: "https://graph.microsoft.com/.default",
+        });
+    }
+    else {
+        throw new Error(`${pluginName}: no credentials. Connect via OAuth, or set tenantId/clientId/clientSecret (app-only).`);
+    }
+    const res = await fetch(authority(cfg), {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`${pluginName}: token request failed (${res.status}): ${await res.text()}`);
+    }
+    const data = (await res.json());
+    const patch = {
+        accessToken: data.access_token,
+        accessTokenExpiresAt: Date.now() + data.expires_in * 1000,
+    };
+    // Microsoft rotates refresh tokens — persist the new one when present.
+    if (data.refresh_token)
+        patch.refreshToken = data.refresh_token;
+    await ctx.updateConnection(patch);
+    return data.access_token;
+}
+/** Authenticated Graph v1.0 request. Returns parsed JSON ({success:true} for 204). */
+export async function graphRequest(ctx, pluginName, scopes, method, path, body) {
+    const token = await microsoftAccessToken(ctx, pluginName, scopes);
+    const init = {
+        method,
+        headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+    };
+    if (body !== undefined) {
+        init.headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(body);
+    }
+    const res = await fetch(`https://graph.microsoft.com/v1.0${path}`, init);
+    if (res.status === 204)
+        return { success: true };
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`${pluginName}: ${method} ${path} → ${res.status} ${text}`);
+    return text ? JSON.parse(text) : { success: true };
+}
+/** Setup help shown by the OAuth wizard for all Microsoft plugins. */
+export function microsoftSetupHelp(apiName) {
+    return [
+        `You need a Microsoft Entra (Azure AD) app registration. One-time, ~5 minutes.`,
+        "",
+        "1. Register an app: https://entra.microsoft.com → App registrations → New registration.",
+        "   Supported account types: your org (single tenant) is fine.",
+        "2. Add a Web redirect URI (Authentication → Add platform → Web):",
+        "     {{redirectUri}}",
+        "3. Certificates & secrets → New client secret → copy the VALUE (not the Secret ID).",
+        `4. API permissions → Add → Microsoft Graph → Delegated → add the ${apiName} scopes,`,
+        "   then 'Grant admin consent'.",
+        "5. Paste the Application (client) ID and the client secret VALUE below.",
+    ];
+}

package/dist/plugins/gmail/src/index.js

@@ -27,6 +27,11 @@ async function accessToken(ctx) {
 }
 // ─── Request ─────────────────────────────────────────────────────
 const API_BASE = "https://gmail.googleapis.com/gmail/v1/users/me";
+function sendFailureRetryHint(method, path) {
+    if (method !== "POST" || !path.endsWith("/send"))
+        return "";
+    return " Before retrying, check whether the email was already sent using gmail.message.list({ q: 'in:sent to:<recipient> subject:\"<subject>\"', maxResults: 10 }) and inspect likely matches with gmail.message.get({ id, format: 'metadata' }).";
+}
 async function gmailRequest(ctx, method, path, body, qs) {
     const token = await accessToken(ctx);
     const url = new URL(`${API_BASE}${path}`);
@@ -55,12 +60,19 @@ async function gmailRequest(ctx, method, path, body, qs) {
             "application/json";
         init.body = JSON.stringify(body);
     }
-    const res = await fetch(url.toString(), init);
+    let res;
+    try {
+        res = await fetch(url.toString(), init);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`gmail: ${method} ${path} failed: ${msg}.${sendFailureRetryHint(method, path)}`);
+    }
     if (res.status === 204)
         return { success: true };
     const text = await res.text();
     if (!res.ok) {
-        throw new Error(`gmail: ${method} ${path} → ${res.status} ${text}`);
+        throw new Error(`gmail: ${method} ${path} → ${res.status} ${text}${sendFailureRetryHint(method, path)}`);
     }
     return text ? JSON.parse(text) : { success: true };
 }
@@ -108,6 +120,18 @@ function header(name, value) {
 function foldedBase64ByteLength(length) {
     return length === 0 ? 0 : length + Math.floor((length - 1) / 76) * CRLF.length;
 }
+function normalizeMimeBase64(value, index) {
+    const compact = value.replace(/\s+/g, "");
+    if (!/^[A-Za-z0-9+/=_-]*$/.test(compact)) {
+        throw new Error(`gmail: attachment ${index} contentBase64 contains invalid base64 characters`);
+    }
+    const standard = compact.replace(/-/g, "+").replace(/_/g, "/");
+    const remainder = standard.length % 4;
+    if (remainder === 1) {
+        throw new Error(`gmail: attachment ${index} contentBase64 has invalid base64 length`);
+    }
+    return remainder === 0 ? standard : `${standard}${"=".repeat(4 - remainder)}`;
+}
 function foldBase64(encoded) {
     let folded = "";
     for (let i = 0; i < encoded.length; i += 76) {
@@ -147,7 +171,7 @@ function normalizeAttachment(input, index) {
     return {
         name: input.name ?? input.filename ?? `attachment-${index + 1}`,
         mimeType: input.mimeType ?? "application/octet-stream",
-        contentBase64,
+        contentBase64: normalizeMimeBase64(contentBase64, index),
     };
 }
 function attachmentPart(att) {