@steve31415/baselib 3.40.1 → 3.42.0

package/dist/db.d.ts

@@ -49,6 +49,9 @@ export interface PoolOptions {
     /** Receives idle-client errors (see logPoolErrors). Without one they go to
      *  stderr — on the Cloud Logging backstop, but not in Axiom. */
     logger?: Logger;
+    /** Tuning for `probeIdleCheckouts` (defaults IDLE_PROBE_AFTER_MS and
+     *  IDLE_PROBE_TIMEOUT_MS); tests shorten them. */
+    idleProbe?: IdleProbeOptions;
 }
 /** Why a fleet-wide statement timeout (mirror, 2026-09-08): a transaction an
  * app deliberately holds open across an application await (mirror's job
@@ -78,12 +81,34 @@ export interface PoolLoggingOptions {
  *  instead of hanging, and TCP keepalive so a half-open socket is noticed
  *  while the process has CPU. No max lifetime: reconnecting is the
  *  operation that fails on a throttled instance, so forcing more of it
- *  would be backwards. */
+ *  would be backwards.
+ *
+ *  One warm connection (2026-10-30, `~/migration/prompts/baselib-pool-idle-timeout.md`):
+ *  pg-pool's default 10 s idle timeout emptied every pool between a single
+ *  user's requests, so nearly every request paid a ~77 ms Cloud SQL connect.
+ *  pg-pool 3.14's `min` does not open connections; it exempts the first
+ *  `min` connections from the idle timeout, so the pool keeps one once it
+ *  has made one. Connections above it close after `idleTimeoutMillis` (a
+ *  bound, never unlimited). A held connection can die while idle (the
+ *  weekly Thursday bursts), unnoticed until a checkout, so `createPool`
+ *  also probes a client that sat idle (`probeIdleCheckouts`). Budget: one
+ *  connection per pool per instance at rest, about +12 fleet-wide. A
+ *  process that forgets `pool.end()` no longer exits by itself: end pools
+ *  in scripts and jobs. */
 export declare const FLEET_POOL_DEFAULTS: {
     readonly connectionTimeoutMillis: 15000;
     readonly keepAlive: true;
     readonly keepAliveInitialDelayMillis: 10000;
+    readonly min: 1;
+    readonly idleTimeoutMillis: 60000;
 };
+/** A client idle at least this long is probed before it is handed out.
+ *  Below it the pool reused connections without a probe before 2026-10-30
+ *  too (they lived 10 s), so nothing is less safe than it was. */
+export declare const IDLE_PROBE_AFTER_MS = 10000;
+/** How long the probe waits. A healthy `select 1` takes a millisecond or
+ *  two; a half-open socket would otherwise wait for TCP to give up. */
+export declare const IDLE_PROBE_TIMEOUT_MS = 3000;
 /** Keep a pg connection's death from killing the process, and log every
  *  way a pool loses or fails to get a connection as one WARN family:
  *  `kind=db-connection-loss`, `meta.phase`:
@@ -93,7 +118,9 @@ export declare const FLEET_POOL_DEFAULTS: {
  *  - `wait`: the checkout timed out waiting for a free client. Pool
  *    starvation, not loss: the pool's `max` or a client held too long.
  *  - `idle`: a client idle in the pool died; pg-pool discards it and the
- *    next checkout opens a fresh one. Harmless by construction.
+ *    next checkout opens a fresh one. Harmless by construction. With
+ *    `meta.detectedAt: 'checkout'` the death went unnoticed until a
+ *    checkout's probe found it (`probeIdleCheckouts`); also harmless.
  *  - `checked-out`: a borrowed client died. Its next query fails (pg has
  *    already failed its queued queries and marked it unqueryable, so the
  *    borrower cannot mistake the dead transaction for a live one), and
@@ -117,6 +144,24 @@ export declare const FLEET_POOL_DEFAULTS: {
  *  `createPool` attaches all of this; exported for a pool an app built
  *  itself. Idempotent per pool. */
 export declare function logPoolErrors(pool: pg.Pool, logger?: Logger, options?: PoolLoggingOptions): void;
+export interface IdleProbeOptions {
+    afterIdleMs?: number;
+    timeoutMs?: number;
+}
+/** Hand out no pooled client that died while idle. A client idle for
+ *  `afterIdleMs` or more runs `select 1` (bounded by `timeoutMs`) before
+ *  the borrower gets it; if that fails the client is discarded, one WARN
+ *  (`kind=db-connection-loss`, `phase=idle`, `detectedAt=checkout`) is
+ *  logged, and the checkout is retried, ending at a fresh connection at
+ *  worst. Retrying is safe because the probe is the only statement that
+ *  ran on the dead client. What stays unretried, as before: a connection
+ *  that dies after the probe, mid-statement or mid-transaction (the
+ *  borrower sees the error; whether a lone statement took effect is
+ *  unknowable), and a failed new connection (`phase=connect`). New clients
+ *  and recently used ones are not probed. Both connect forms are covered
+ *  (`pool.query` checks out in callback form). `createPool` attaches this;
+ *  exported for a pool an app built itself. Idempotent per pool. */
+export declare function probeIdleCheckouts(pool: pg.Pool, logger?: Logger, options?: IdleProbeOptions): void;
 export declare function createPool(opts?: PoolOptions): Promise<pg.Pool>;
 /** End a pool and resolve only once every client's connection has actually
  * closed. pg-pool's own `end()` resolves as soon as it has *asked* its idle

package/dist/db.js

@@ -78,18 +78,69 @@ export const DEFAULT_STATEMENT_TIMEOUT_MS = 10 * 60_000;
  *  instead of hanging, and TCP keepalive so a half-open socket is noticed
  *  while the process has CPU. No max lifetime: reconnecting is the
  *  operation that fails on a throttled instance, so forcing more of it
- *  would be backwards. */
+ *  would be backwards.
+ *
+ *  One warm connection (2026-10-30, `~/migration/prompts/baselib-pool-idle-timeout.md`):
+ *  pg-pool's default 10 s idle timeout emptied every pool between a single
+ *  user's requests, so nearly every request paid a ~77 ms Cloud SQL connect.
+ *  pg-pool 3.14's `min` does not open connections; it exempts the first
+ *  `min` connections from the idle timeout, so the pool keeps one once it
+ *  has made one. Connections above it close after `idleTimeoutMillis` (a
+ *  bound, never unlimited). A held connection can die while idle (the
+ *  weekly Thursday bursts), unnoticed until a checkout, so `createPool`
+ *  also probes a client that sat idle (`probeIdleCheckouts`). Budget: one
+ *  connection per pool per instance at rest, about +12 fleet-wide. A
+ *  process that forgets `pool.end()` no longer exits by itself: end pools
+ *  in scripts and jobs. */
 export const FLEET_POOL_DEFAULTS = {
     connectionTimeoutMillis: 15_000,
     keepAlive: true,
     keepAliveInitialDelayMillis: 10_000,
+    min: 1,
+    idleTimeoutMillis: 60_000,
 };
+/** A client idle at least this long is probed before it is handed out.
+ *  Below it the pool reused connections without a probe before 2026-10-30
+ *  too (they lived 10 s), so nothing is less safe than it was. */
+export const IDLE_PROBE_AFTER_MS = 10_000;
+/** How long the probe waits. A healthy `select 1` takes a millisecond or
+ *  two; a half-open socket would otherwise wait for TCP to give up. */
+export const IDLE_PROBE_TIMEOUT_MS = 3_000;
+const IDLE_PROBE_SQL = 'select 1 /* baselib idle probe */';
 const CONNECTION_LOSS_KIND = 'db-connection-loss';
 const ACQUIRE_FAILED_MESSAGE = {
     connect: 'database pool: new connection failed',
     wait: 'database pool: checkout timed out waiting for a free client',
 };
 const instrumented = new WeakSet();
+// Clients under an idle probe: their death is reported once, by the probe,
+// as an idle loss rather than a checked-out one.
+const probing = new WeakSet();
+/** One `kind=db-connection-loss` WARN, the shape every pool loss shares. */
+function connectionLossWarner(pool, logger, credentialExpiry) {
+    const log = logger?.with({ kind: CONNECTION_LOSS_KIND });
+    return (phase, message, err, since, extra = {}) => {
+        const expiry = credentialExpiry?.();
+        const meta = {
+            phase,
+            ...extra,
+            ...(since === undefined ? {} : { elapsedMs: Date.now() - since }),
+            code: err.code,
+            pool: { total: pool.totalCount, idle: pool.idleCount, waiting: pool.waitingCount },
+            ...(credentialExpiry
+                ? expiry === undefined
+                    ? { credentialUnknown: true }
+                    : { credentialRemainingMs: expiry - Date.now() }
+                : {}),
+            error: err,
+        };
+        if (log)
+            log.warn(message, meta);
+        // No logger to add the activity fields, so add them here.
+        else
+            console.warn(message, { kind: CONNECTION_LOSS_KIND, ...processMeta(), ...meta, error: serializeError(err) });
+    };
+}
 /** Keep a pg connection's death from killing the process, and log every
  *  way a pool loses or fails to get a connection as one WARN family:
  *  `kind=db-connection-loss`, `meta.phase`:
@@ -99,7 +150,9 @@ const instrumented = new WeakSet();
  *  - `wait`: the checkout timed out waiting for a free client. Pool
  *    starvation, not loss: the pool's `max` or a client held too long.
  *  - `idle`: a client idle in the pool died; pg-pool discards it and the
- *    next checkout opens a fresh one. Harmless by construction.
+ *    next checkout opens a fresh one. Harmless by construction. With
+ *    `meta.detectedAt: 'checkout'` the death went unnoticed until a
+ *    checkout's probe found it (`probeIdleCheckouts`); also harmless.
  *  - `checked-out`: a borrowed client died. Its next query fails (pg has
  *    already failed its queued queries and marked it unqueryable, so the
  *    borrower cannot mistake the dead transaction for a live one), and
@@ -126,27 +179,7 @@ export function logPoolErrors(pool, logger, options = {}) {
     if (instrumented.has(pool))
         return;
     instrumented.add(pool);
-    const log = logger?.with({ kind: CONNECTION_LOSS_KIND });
-    const warn = (phase, message, err, since) => {
-        const expiry = options.credentialExpiry?.();
-        const meta = {
-            phase,
-            ...(since === undefined ? {} : { elapsedMs: Date.now() - since }),
-            code: err.code,
-            pool: { total: pool.totalCount, idle: pool.idleCount, waiting: pool.waitingCount },
-            ...(options.credentialExpiry
-                ? expiry === undefined
-                    ? { credentialUnknown: true }
-                    : { credentialRemainingMs: expiry - Date.now() }
-                : {}),
-            error: err,
-        };
-        if (log)
-            log.warn(message, meta);
-        // No logger to add the activity fields, so add them here.
-        else
-            console.warn(message, { kind: CONNECTION_LOSS_KIND, ...processMeta(), ...meta, error: serializeError(err) });
-    };
+    const warn = connectionLossWarner(pool, logger, options.credentialExpiry);
     // Per-client bookkeeping across one checkout: the borrower-side error
     // listener (pg-pool drops its own at checkout) and when the client was
     // taken and given back.
@@ -167,7 +200,7 @@ export function logPoolErrors(pool, logger, options = {}) {
         // close); one line per checkout is enough.
         let logged = false;
         entry.listener = (err) => {
-            if (logged)
+            if (logged || probing.has(client))
                 return;
             logged = true;
             warn('checked-out', 'database pool: checked-out client lost its connection (any transaction or advisory lock it held is gone; its next query fails)', err, entry.acquiredAt);
@@ -208,6 +241,76 @@ export function logPoolErrors(pool, logger, options = {}) {
         });
     });
 }
+const probed = new WeakSet();
+/** Hand out no pooled client that died while idle. A client idle for
+ *  `afterIdleMs` or more runs `select 1` (bounded by `timeoutMs`) before
+ *  the borrower gets it; if that fails the client is discarded, one WARN
+ *  (`kind=db-connection-loss`, `phase=idle`, `detectedAt=checkout`) is
+ *  logged, and the checkout is retried, ending at a fresh connection at
+ *  worst. Retrying is safe because the probe is the only statement that
+ *  ran on the dead client. What stays unretried, as before: a connection
+ *  that dies after the probe, mid-statement or mid-transaction (the
+ *  borrower sees the error; whether a lone statement took effect is
+ *  unknowable), and a failed new connection (`phase=connect`). New clients
+ *  and recently used ones are not probed. Both connect forms are covered
+ *  (`pool.query` checks out in callback form). `createPool` attaches this;
+ *  exported for a pool an app built itself. Idempotent per pool. */
+export function probeIdleCheckouts(pool, logger, options = {}) {
+    if (probed.has(pool))
+        return;
+    probed.add(pool);
+    const afterIdleMs = options.afterIdleMs ?? IDLE_PROBE_AFTER_MS;
+    const timeoutMs = options.timeoutMs ?? IDLE_PROBE_TIMEOUT_MS;
+    const releasedAt = new WeakMap();
+    pool.on('release', (_err, client) => releasedAt.set(client, Date.now()));
+    const warn = connectionLossWarner(pool, logger);
+    const connect = pool.connect.bind(pool);
+    const checkout = async () => {
+        // Each failed probe removes a client, so this ends at a client that
+        // passes or a fresh one (or a connect error, which propagates).
+        for (;;) {
+            const client = await connect();
+            const idleSince = releasedAt.get(client);
+            if (idleSince === undefined || Date.now() - idleSince < afterIdleMs)
+                return client;
+            probing.add(client);
+            // The death also arrives as a client 'error', possibly after the
+            // discard below; the probe reports it, and a discarded client keeps
+            // this listener so a late socket error cannot go unhandled.
+            const ignore = () => { };
+            client.on('error', ignore);
+            let timer;
+            try {
+                const probe = client.query(IDLE_PROBE_SQL);
+                // On a timeout the release below destroys the socket (pg's end()
+                // with a query active), which rejects the probe; nothing awaits it.
+                probe.catch(() => { });
+                await Promise.race([
+                    probe,
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error(`idle probe timed out after ${timeoutMs} ms`)), timeoutMs);
+                    }),
+                ]);
+                client.removeListener('error', ignore);
+                return client;
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                warn('idle', 'database pool: idle client found dead at checkout; replaced', error, idleSince, { detectedAt: 'checkout' });
+                client.release(error);
+            }
+            finally {
+                clearTimeout(timer);
+                probing.delete(client);
+            }
+        }
+    };
+    pool.connect = ((cb) => {
+        if (typeof cb !== 'function')
+            return checkout();
+        checkout().then((client) => cb(undefined, client, (release) => client.release(release)), (err) => cb(err));
+    });
+}
 export async function createPool(opts = {}) {
     // pg sends statement_timeout in the startup packet of every connection —
     // server-enforced, no per-connection SET. A 0 is falsy, so pg omits it and
@@ -230,6 +333,7 @@ export async function createPool(opts = {}) {
             max: opts.max ?? 3, // shared instance: default max_connections is low
         });
         logPoolErrors(pool, opts.logger, { credentialExpiry });
+        probeIdleCheckouts(pool, opts.logger, opts.idleProbe);
         return pool;
     }
     const url = new URL(requireEnv('DATABASE_URL'));
@@ -239,6 +343,7 @@ export async function createPool(opts = {}) {
         url.username = opts.user;
     const pool = new pg.Pool({ connectionString: url.toString(), ...shared, max: opts.max ?? 5 });
     logPoolErrors(pool, opts.logger);
+    probeIdleCheckouts(pool, opts.logger, opts.idleProbe);
     return pool;
 }
 /** End a pool and resolve only once every client's connection has actually

package/dist/llm/complete.js

@@ -39,6 +39,19 @@ export async function llmComplete(request) {
             isRetryable: false,
         });
     }
+    // A request with images may only run on models that take them. The
+    // requested model not taking them is the caller's bug, so say so rather
+    // than silently answering from a fallback; fallbacks without image input
+    // are skipped in the loop below.
+    const hasImages = (request.images?.length ?? 0) > 0;
+    if (hasImages && !entry.supportsImages) {
+        throw new LLMError({
+            message: `Model ${request.model} does not accept image input. Image-capable models: ${Object.keys(MODEL_REGISTRY).filter((m) => MODEL_REGISTRY[m].supportsImages).join(', ')}`,
+            provider: entry.provider,
+            model: entry.apiModelId,
+            isRetryable: false,
+        });
+    }
     const maxTokens = request.maxTokens ?? DEFAULT_MAX_TOKENS;
     const temperature = request.temperature ?? DEFAULT_TEMPERATURE;
     const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -75,6 +88,12 @@ export async function llmComplete(request) {
         const modelEntry = MODEL_REGISTRY[modelName];
         if (!modelEntry)
             continue;
+        if (hasImages && !modelEntry.supportsImages) {
+            request.logger?.debug('llm.skip_provider', {
+                model: modelName, provider: modelEntry.provider, reason: 'no image input',
+            });
+            continue;
+        }
         const apiKey = request.apiKeys[modelEntry.provider];
         if (!apiKey) {
             request.logger?.debug('llm.skip_provider', {
@@ -88,6 +107,7 @@ export async function llmComplete(request) {
             const result = await provider.complete({
                 apiModelId: modelEntry.apiModelId,
                 prompt: request.prompt,
+                images: hasImages ? request.images : undefined,
                 systemPrompt: request.systemPrompt,
                 maxTokens,
                 temperature,

package/dist/llm/index.d.ts

@@ -1,4 +1,4 @@
 export { llmComplete } from './complete.js';
 export { MODEL_REGISTRY } from './models.js';
 export type { ModelEntry } from './models.js';
-export { LLMError, EFFORT_LEVELS, type Effort, type LLMRequest, type LLMResponse, type FailedAttempt, type FinishCategory, type ProviderName, type ApiKeys, type JsonSchema, } from './types.js';
+export { LLMError, EFFORT_LEVELS, type Effort, type LLMRequest, type LLMResponse, type FailedAttempt, type FinishCategory, type ProviderName, type ApiKeys, type JsonSchema, type LLMImage, type LLMImageMediaType, } from './types.js';

package/dist/llm/models.d.ts

@@ -59,6 +59,13 @@ export interface ModelEntry {
      * `output_config.format` instead.
      */
     supportsForcedToolChoice?: boolean;
+    /**
+     * Whether this model accepts image input (`LLMRequest.images`). Defaults to
+     * `false`: a request with images is rejected for a model without it, and
+     * failover skips such fallbacks. Set only on models whose image handling
+     * was verified live (test/helpers/llm.ts records the probe).
+     */
+    supportsImages?: boolean;
 }
 /**
  * Output budget below which a `thinksByDefault` model is considered at risk of

package/dist/llm/models.js

@@ -26,10 +26,15 @@ export const MODEL_REGISTRY = {
     // hidden reasoning tokens billed as output — hence `supportsTemperature:
     // false` + `thinksByDefault: true` on each. (gpt-5.2 still accepts
     // temperature; verified the same day.)
+    //
+    // `supportsImages`: every entry still served read a JPEG beside a
+    // jsonSchema in the live probe of 2026-10-29 (test/helpers/llm.ts);
+    // the shut-down gemini-2.5 pair is left unmarked.
     // --- Fast tier ---
     'gemini-3.5-flash-lite': {
         provider: 'gemini',
         apiModelId: 'gemini-3.5-flash-lite',
+        supportsImages: true,
         fallbacks: ['gpt-5.6-luna', 'claude-haiku-4-5'],
         // Default thinking_level is `minimal` — reasoning overhead is negligible,
         // so no `thinksByDefault` headroom warning.
@@ -41,6 +46,7 @@ export const MODEL_REGISTRY = {
     'gemini-3.6-flash': {
         provider: 'gemini',
         apiModelId: 'gemini-3.6-flash',
+        supportsImages: true,
         fallbacks: ['gpt-5.6-luna', 'claude-haiku-4-5'],
         // Thinks by default (thinking_level defaults to `medium`); reasoning
         // tokens are billed as output and count against maxOutputTokens.
@@ -56,6 +62,7 @@ export const MODEL_REGISTRY = {
     'gpt-5.6-luna': {
         provider: 'openai',
         apiModelId: 'gpt-5.6-luna',
+        supportsImages: true,
         fallbacks: ['gemini-3.5-flash-lite', 'claude-haiku-4-5'],
         supportsTemperature: false,
         thinksByDefault: true,
@@ -63,6 +70,7 @@ export const MODEL_REGISTRY = {
     'claude-haiku-4-5': {
         provider: 'anthropic',
         apiModelId: 'claude-haiku-4-5-20251001',
+        supportsImages: true,
         fallbacks: ['gemini-3.5-flash-lite', 'gpt-5.6-luna'],
     },
     // Retiring 2026-10-16 — migrate callers to gemini-3.5-flash-lite.
@@ -74,12 +82,14 @@ export const MODEL_REGISTRY = {
     'gemini-3.1-flash-lite': {
         provider: 'gemini',
         apiModelId: 'gemini-3.1-flash-lite',
+        supportsImages: true,
         fallbacks: ['claude-sonnet-4-6'],
         supportsEffort: true,
     },
     'gemini-3-flash-preview': {
         provider: 'gemini',
         apiModelId: 'gemini-3-flash-preview',
+        supportsImages: true,
         fallbacks: ['claude-haiku-4-5', 'gpt-5.6-luna'],
         supportsEffort: true,
         thinkingLevels: ['minimal', 'low', 'medium', 'high'],
@@ -87,6 +97,7 @@ export const MODEL_REGISTRY = {
     'gpt-4o-mini': {
         provider: 'openai',
         apiModelId: 'gpt-4o-mini',
+        supportsImages: true,
         fallbacks: ['gemini-3.5-flash-lite', 'claude-haiku-4-5'],
     },
     // --- Mid tier ---
@@ -94,6 +105,7 @@ export const MODEL_REGISTRY = {
         provider: 'anthropic',
         supportsEffort: true,
         apiModelId: 'claude-sonnet-5',
+        supportsImages: true,
         fallbacks: ['gpt-5.6-terra', 'gemini-3.1-pro-preview'],
         // Sonnet 5 rejects `temperature` (like Opus 4.7+/Fable 5). It supports
         // adaptive thinking but does NOT think when the request omits `thinking`
@@ -103,6 +115,7 @@ export const MODEL_REGISTRY = {
     'gpt-5.6-terra': {
         provider: 'openai',
         apiModelId: 'gpt-5.6-terra',
+        supportsImages: true,
         fallbacks: ['claude-sonnet-5', 'gemini-3.1-pro-preview'],
         supportsTemperature: false,
         thinksByDefault: true,
@@ -111,6 +124,7 @@ export const MODEL_REGISTRY = {
         provider: 'anthropic',
         supportsEffort: true,
         apiModelId: 'claude-sonnet-4-6',
+        supportsImages: true,
         fallbacks: ['gpt-5.6-terra', 'gemini-3.1-pro-preview'],
     },
     // Legacy: consumer-retired 2026-02; API snapshots retire 2026-10 onward.
@@ -118,6 +132,7 @@ export const MODEL_REGISTRY = {
     'gpt-4o': {
         provider: 'openai',
         apiModelId: 'gpt-4o',
+        supportsImages: true,
         fallbacks: ['claude-sonnet-5', 'gemini-3.1-pro-preview'],
     },
     // --- Top tier ---
@@ -125,6 +140,7 @@ export const MODEL_REGISTRY = {
         provider: 'anthropic',
         supportsEffort: true,
         apiModelId: 'claude-opus-5-5',
+        supportsImages: true,
         fallbacks: ['gpt-5.6-sol', 'gemini-3.1-pro-preview'],
         // All verified live 2026-09-22: rejects `temperature` and forced
         // tool_choice (400 each); thinking is always on and its tokens count
@@ -139,6 +155,7 @@ export const MODEL_REGISTRY = {
         provider: 'anthropic',
         supportsEffort: true,
         apiModelId: 'claude-opus-5',
+        supportsImages: true,
         fallbacks: ['gpt-5.6-sol', 'gemini-3.1-pro-preview'],
         // Opus 4.7+ rejects `temperature` outright (400 invalid_request_error).
         supportsTemperature: false,
@@ -152,6 +169,7 @@ export const MODEL_REGISTRY = {
         provider: 'anthropic',
         supportsEffort: true,
         apiModelId: 'claude-opus-4-8',
+        supportsImages: true,
         fallbacks: ['gpt-5.6-sol', 'gemini-3.1-pro-preview'],
         // Opus 4.7+ rejects `temperature` outright (400 invalid_request_error).
         supportsTemperature: false,
@@ -160,6 +178,7 @@ export const MODEL_REGISTRY = {
         provider: 'anthropic',
         supportsEffort: true,
         apiModelId: 'claude-opus-4-6',
+        supportsImages: true,
         fallbacks: ['gpt-5.6-sol', 'gemini-3.1-pro-preview'],
     },
     // Released 2026-09-22; same limits as gpt-5.6-sol (1.05M / 128k). Verified
@@ -169,6 +188,7 @@ export const MODEL_REGISTRY = {
     'gpt-6-sol': {
         provider: 'openai',
         apiModelId: 'gpt-6-sol',
+        supportsImages: true,
         fallbacks: ['claude-opus-5-5', 'gemini-3.1-pro-preview'],
         supportsTemperature: false,
         thinksByDefault: true,
@@ -176,6 +196,7 @@ export const MODEL_REGISTRY = {
     'gpt-5.6-sol': {
         provider: 'openai',
         apiModelId: 'gpt-5.6-sol',
+        supportsImages: true,
         fallbacks: ['claude-opus-5-5', 'gemini-3.1-pro-preview'],
         supportsTemperature: false,
         thinksByDefault: true,
@@ -183,6 +204,7 @@ export const MODEL_REGISTRY = {
     'gpt-5.2': {
         provider: 'openai',
         apiModelId: 'gpt-5.2',
+        supportsImages: true,
         fallbacks: ['claude-opus-5-5', 'gemini-3.1-pro-preview'],
     },
     // Google's best Pro model as of 2026-08 — still Preview-labeled (no GA
@@ -191,6 +213,7 @@ export const MODEL_REGISTRY = {
     'gemini-3.1-pro-preview': {
         provider: 'gemini',
         apiModelId: 'gemini-3.1-pro-preview',
+        supportsImages: true,
         fallbacks: ['claude-opus-5-5', 'gpt-5.6-sol'],
         // Thinks by default (thinking_level defaults to `high`).
         thinksByDefault: true,

package/dist/llm/providers/anthropic.js

@@ -60,6 +60,18 @@ function toAnthropicStrictSchema(node) {
     }
     return out;
 }
+/** The user turn: the bare prompt string, or image blocks then the prompt as a text block. */
+function userContent(request) {
+    if (!request.images)
+        return request.prompt;
+    return [
+        ...request.images.map((image) => ({
+            type: 'image',
+            source: { type: 'base64', media_type: image.mediaType, data: image.data },
+        })),
+        { type: 'text', text: request.prompt },
+    ];
+}
 export const anthropicProvider = {
     name: 'anthropic',
     async complete(request) {
@@ -67,12 +79,13 @@ export const anthropicProvider = {
         request.logger?.info('llm.request', {
             provider: 'anthropic', model: request.apiModelId, endpoint,
             ...(request.callSite ? { callSite: request.callSite } : {}),
+            ...(request.images ? { images: request.images.length } : {}),
         });
         const startTime = Date.now();
         const body = {
             model: request.apiModelId,
             max_tokens: request.maxTokens,
-            messages: [{ role: 'user', content: request.prompt }],
+            messages: [{ role: 'user', content: userContent(request) }],
         };
         // Some models (Opus 4.7+, Sonnet 5, Fable 5, Opus 5.5) reject `temperature`
         // outright with a 400 — omit the field entirely rather than sending it.

package/dist/llm/providers/gemini.js

@@ -64,6 +64,7 @@ export const geminiProvider = {
         request.logger?.info('llm.request', {
             provider: 'gemini', model: request.apiModelId, endpoint,
             ...(request.callSite ? { callSite: request.callSite } : {}),
+            ...(request.images ? { images: request.images.length } : {}),
         });
         const startTime = Date.now();
         const generationConfig = {
@@ -95,7 +96,13 @@ export const geminiProvider = {
             generationConfig.thinkingConfig = { thinkingBudget: request.thinkingBudget };
         }
         const body = {
-            contents: [{ parts: [{ text: request.prompt }] }],
+            // Images go as inline-data parts ahead of the prompt's text part.
+            contents: [{
+                    parts: [
+                        ...(request.images ?? []).map((image) => ({ inlineData: { mimeType: image.mediaType, data: image.data } })),
+                        { text: request.prompt },
+                    ],
+                }],
             generationConfig,
         };
         if (request.systemPrompt) {

package/dist/llm/providers/openai.js

@@ -90,13 +90,26 @@ export const openaiProvider = {
         request.logger?.info('llm.request', {
             provider: 'openai', model: request.apiModelId, endpoint,
             ...(request.callSite ? { callSite: request.callSite } : {}),
+            ...(request.images ? { images: request.images.length } : {}),
         });
         const startTime = Date.now();
         const messages = [];
         if (request.systemPrompt) {
             messages.push({ role: 'system', content: request.systemPrompt });
         }
-        messages.push({ role: 'user', content: request.prompt });
+        // Images go as data-URL `image_url` parts ahead of the prompt's text part.
+        messages.push({
+            role: 'user',
+            content: request.images
+                ? [
+                    ...request.images.map((image) => ({
+                        type: 'image_url',
+                        image_url: { url: `data:${image.mediaType};base64,${image.data}` },
+                    })),
+                    { type: 'text', text: request.prompt },
+                ]
+                : request.prompt,
+        });
         const body = {
             model: request.apiModelId,
             max_completion_tokens: request.maxTokens,

package/dist/llm/types.d.ts

@@ -14,12 +14,26 @@ export interface JsonSchema {
     /** JSON Schema object. */
     schema: Record<string, unknown>;
 }
+/** Media types every image-capable provider accepts (Anthropic, OpenAI and Gemini alike). */
+export type LLMImageMediaType = 'image/jpeg' | 'image/png' | 'image/webp';
+/** An image sent beside the prompt: raw base64, no `data:` URL prefix. */
+export interface LLMImage {
+    mediaType: LLMImageMediaType;
+    data: string;
+}
 /** Request to llmComplete(). */
 export interface LLMRequest {
     /** Model name from the registry (e.g. 'claude-sonnet-4-6', 'gemini-2.5-flash'). */
     model: string;
     /** The user prompt. */
     prompt: string;
+    /**
+     * Images for the model to look at beside the prompt, placed before the
+     * prompt text in the user turn. Only models the registry marks
+     * `supportsImages` are tried: the requested model must be one (else the
+     * call is rejected up front), and failover skips fallbacks that are not.
+     */
+    images?: LLMImage[];
     /** Optional system prompt. */
     systemPrompt?: string;
     /** Max output tokens. Default: 2048. */
@@ -174,6 +188,8 @@ export interface ProviderAdapter {
 export interface ProviderCallRequest {
     apiModelId: string;
     prompt: string;
+    /** Present and non-empty only for a `supportsImages` model (gated in complete.ts). */
+    images?: LLMImage[];
     systemPrompt?: string;
     maxTokens: number;
     temperature: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.40.1",
+  "version": "3.42.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",