@steve31415/baselib 3.27.0 → 3.29.0

package/README.md

@@ -5,7 +5,7 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `docs/IMPL.md`. Full design rationale with alternatives:
 `~/migration/research/base-services-design.md`.
 
-Server subpath exports: `config`, `log`, `auth`, `oauth-resource`, `s2s`, `db`, `http`, `sync`,
+Server subpath exports: `config`, `log`, `auth`, `oauth-resource`, `connector`, `s2s`, `db`, `http`, `sync`,
 `app-update`, `llm`, `email`, and `twitter`. Browser exports: `log-browser`, `rum`,
 `slow-fetch`, `sync-browser`, and `app-update-browser`.
 

package/dist/connector.d.ts

@@ -0,0 +1,149 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Hono, MiddlewareHandler } from 'hono';
+import type { z } from 'zod';
+import type { UserAccessPolicy } from './auth.js';
+import type { Logger } from './log-core.js';
+import type { ConnectorUser } from './oauth-resource.js';
+import type { Grants } from './s2s.js';
+export type { ConnectorUser } from './oauth-resource.js';
+/** The headers the front door asserts a user with. */
+export declare const CONNECTOR_HEADERS: {
+    readonly user: "x-connector-user";
+    readonly role: "x-connector-role";
+    readonly scope: "x-connector-scope";
+    readonly client: "x-connector-client";
+    readonly grant: "x-connector-grant";
+    readonly name: "x-connector-name";
+};
+/** The headers that carry `user` to an app (the front door's side). */
+export declare function connectorIdentityHeaders(user: ConnectorUser): Record<string, string>;
+/** The identity the headers assert, or null when any required one is
+ *  missing or malformed. Header values are what the front door set; an
+ *  attacker who can set them has already passed the s2s check. */
+export declare function parseConnectorIdentityHeaders(header: (name: string) => string | undefined): ConnectorUser | null;
+export interface ForwardedConnectorOptions {
+    /** This app's canonical URL: the audience the front door mints its OIDC
+     *  token for. */
+    audience: string;
+    /** The app's checked-in grants; the front door's identity needs `POST /mcp`. */
+    grants: Grants;
+    /** Which users this app admits — copied from its requireIdentity call. */
+    userAccess: UserAccessPolicy;
+    logger?: Logger;
+    /** Per-caller ceiling for the forwarding service (default 6000/min: one
+     *  identity carries every user's traffic). */
+    rateLimitPerMin?: number;
+}
+/**
+ * Admits the front door on an app's `/mcp` and nothing else: the s2s caller
+ * must verify and be granted the route (the coding agent always is), then
+ * the `X-Connector-*` headers name the user, whose role the app's own access
+ * policy is applied to. Sets `c.var.connector`; never `identity`/`user`.
+ */
+export declare function requireForwardedConnectorUser(opts: ForwardedConnectorOptions): MiddlewareHandler;
+/** A tool error the model can read and act on. Anything else thrown by a
+ *  tool is an internal failure: logged at ERROR, answered generically. */
+export declare class ConnectorError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Content-free facts about one call, for its log line. */
+export type CallFacts = Record<string, string | number | boolean | null>;
+export interface ToolOutcome {
+    result: unknown;
+    facts: CallFacts;
+}
+export interface ConnectorToolDefinition<Deps, Shape extends z.ZodRawShape = z.ZodRawShape> {
+    title: string;
+    description: string;
+    inputSchema: Shape;
+    /** Reads only; needs `<app>:read`. Otherwise `<app>:write`. */
+    readOnly: boolean;
+    /** A write that overwrites or discards existing content. */
+    destructive?: boolean;
+    run(deps: Deps, user: ConnectorUser, args: z.infer<z.ZodObject<Shape>>): Promise<ToolOutcome>;
+}
+export interface ConnectorToolTable<Deps> {
+    /** The tool-name and scope prefix: `todo` → `todo_*`, `todo:read`. */
+    app: string;
+    scopes: readonly [read: string, write: string];
+    tools: Readonly<Record<string, ConnectorToolDefinition<Deps>>>;
+}
+export declare function connectorScopes(app: string): readonly [string, string];
+/**
+ * A typed tool table for one app: `tool()` captures each tool's argument
+ * shape; `table()` checks the names and fixes the scopes.
+ *
+ *   const { tool, table } = connectorToolkit<TodoDeps>('todo')
+ *   export const TOOLS = table({ todo_add_item: tool({ … }) })
+ */
+export declare function connectorToolkit<Deps>(app: string): {
+    tool<Shape extends z.ZodRawShape>(definition: ConnectorToolDefinition<Deps, Shape>): ConnectorToolDefinition<Deps, Shape>;
+    table(tools: Record<string, ConnectorToolDefinition<Deps>>): ConnectorToolTable<Deps>;
+};
+/** The scope a tool needs, or null for a name that is not a tool. */
+export declare function connectorToolScope<Deps>(table: ConnectorToolTable<Deps>, name: unknown): string | null;
+/**
+ * The scopes the `tools/call` messages in a JSON-RPC body need. Checked by
+ * the route before the SDK runs, because only an HTTP 403 with a challenge —
+ * never a tool result — makes the client ask the user for more access.
+ */
+export declare function requiredConnectorScopes<Deps>(table: ConnectorToolTable<Deps>, body: unknown): Set<string>;
+export interface ConnectorServerInfo {
+    name: string;
+    title: string;
+    version?: string;
+}
+/**
+ * One MCP server per request, bound to the caller: the endpoint is stateless,
+ * so nothing is shared between calls or users.
+ */
+export declare function buildConnectorServer<Deps>(table: ConnectorToolTable<Deps>, deps: Deps, user: ConnectorUser, logger: Logger, info: ConnectorServerInfo, instructions?: string): McpServer;
+/** Answer one already-parsed JSON-RPC POST for this caller. */
+export declare function handleConnectorRequest(server: McpServer, request: Request, parsedBody: unknown): Promise<Response>;
+/**
+ * The table's tool definitions exactly as `tools/list` returns them (the
+ * SDK's own JSON Schema rendering), obtained by listing them over an
+ * in-memory transport once. Served publicly: definitions are not secret, and
+ * the front door merges them into its own `tools/list`.
+ */
+export declare function connectorToolDefinitions<Deps>(table: ConnectorToolTable<Deps>, info: ConnectorServerInfo): Promise<Tool[]>;
+/** JSON-RPC bodies are small except for a page of Markdown (apps cap their
+ *  own content at 1 MiB). */
+export declare const MAX_CONNECTOR_REQUEST_BYTES: number;
+export interface MountConnectorOptions<Deps> extends ForwardedConnectorOptions {
+    table: ConnectorToolTable<Deps>;
+    deps: Deps;
+    logger: Logger;
+    serverInfo: ConnectorServerInfo;
+    instructions?: string;
+    maxRequestBytes?: number;
+    /** Replaces the forwarded-identity middleware (a transition hook: Notes
+     *  admits its old bearer tokens through it for one deploy). Must set
+     *  `c.var.connector` or answer. */
+    admit?: MiddlewareHandler;
+}
+export interface MountedConnector {
+    /** The public tool-definition document, as `GET /mcp/tools` serves it. */
+    definitions: () => Promise<Tool[]>;
+}
+/**
+ * Serve the table at `/mcp` (POST only, forwarded identity, size cap, strict
+ * JSON, the scope gate, one server per request) and its definitions at
+ * `GET /mcp/tools` (public). Mount before the app's own identity middleware:
+ * a connector must never be looked at by `requireIdentity`, and vice versa.
+ */
+export declare function mountConnector<Deps>(app: Hono, opts: MountConnectorOptions<Deps>): MountedConnector;
+/**
+ * A real MCP client whose HTTP goes straight into a Hono app, for app tests:
+ * `headers` carry the caller (`X-Test-S2S-Caller` plus the X-Connector-*
+ * identity, or whatever the route's `admit` expects).
+ */
+export declare function connectorTestClient(request: (path: string, init: RequestInit) => Response | Promise<Response>, headers: Record<string, string>, path?: string): Promise<Client>;
+/** Call a tool and unpack the JSON text result the kit produces. */
+export declare function callConnectorTool(client: Client, name: string, args: Record<string, unknown>): Promise<{
+    isError: boolean;
+    value: Record<string, unknown>;
+}>;

package/dist/connector.js

@@ -0,0 +1,371 @@
+// The app side of the fleet's AI connector (PW docs/SECURITY.md "Connector
+// access"): everything an app needs to serve its MCP tool table at /mcp,
+// minus the tools themselves.
+//
+// claude.ai talks to one URL, the auth service's front door. The front door
+// verifies the user's OAuth token and relays each tool call to the owning app
+// over the ordinary service-to-service hop: a Google-signed OIDC token for
+// the app's audience, minted as auth's own service account, plus the user's
+// identity in X-Connector-* headers. The user's bearer never reaches an app.
+// So an app's /mcp admits exactly one kind of caller — a granted service
+// asserting a user — and the identity it yields is a `connector`, never
+// `identity`/`user`: a connector cannot reach an app's ordinary routes.
+//
+// Tool names carry the app's prefix (`todo_add_item`): in claude.ai the name
+// is the only thing the model reliably sees, and the front door routes by it.
+// A tool's scope follows from `readOnly`: `<app>:read` or `<app>:write`.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { createMiddleware } from 'hono/factory';
+import { ACCESS_DENIED_CODE, userAllowed } from './auth.js';
+import { serializeError } from './log-core.js';
+import { insufficientScope } from './oauth-resource.js';
+import { RateLimiter, resolveS2sCaller } from './s2s.js';
+// ---------------------------------------------------------------------------
+// The forwarded identity
+/** The headers the front door asserts a user with. */
+export const CONNECTOR_HEADERS = {
+    user: 'x-connector-user',
+    role: 'x-connector-role',
+    scope: 'x-connector-scope',
+    client: 'x-connector-client',
+    grant: 'x-connector-grant',
+    name: 'x-connector-name',
+};
+/** The headers that carry `user` to an app (the front door's side). */
+export function connectorIdentityHeaders(user) {
+    return {
+        [CONNECTOR_HEADERS.user]: user.email,
+        [CONNECTOR_HEADERS.role]: user.role,
+        [CONNECTOR_HEADERS.scope]: [...user.scopes].join(' '),
+        [CONNECTOR_HEADERS.client]: user.clientId,
+        [CONNECTOR_HEADERS.grant]: user.grantId,
+        ...(user.name ? { [CONNECTOR_HEADERS.name]: user.name } : {}),
+    };
+}
+function parseRole(value) {
+    return value === 'owner' || value === 'invited' ? value : undefined;
+}
+/** The identity the headers assert, or null when any required one is
+ *  missing or malformed. Header values are what the front door set; an
+ *  attacker who can set them has already passed the s2s check. */
+export function parseConnectorIdentityHeaders(header) {
+    const email = header(CONNECTOR_HEADERS.user);
+    const role = parseRole(header(CONNECTOR_HEADERS.role));
+    const clientId = header(CONNECTOR_HEADERS.client);
+    const grantId = header(CONNECTOR_HEADERS.grant);
+    const scope = header(CONNECTOR_HEADERS.scope);
+    if (!email || !role || !clientId || !grantId || scope === undefined)
+        return null;
+    const name = header(CONNECTOR_HEADERS.name);
+    return {
+        type: 'connector',
+        email,
+        role,
+        scopes: new Set(scope.split(' ').filter(Boolean)),
+        clientId,
+        grantId,
+        ...(name ? { name } : {}),
+    };
+}
+/**
+ * Admits the front door on an app's `/mcp` and nothing else: the s2s caller
+ * must verify and be granted the route (the coding agent always is), then
+ * the `X-Connector-*` headers name the user, whose role the app's own access
+ * policy is applied to. Sets `c.var.connector`; never `identity`/`user`.
+ */
+export function requireForwardedConnectorUser(opts) {
+    const limiter = new RateLimiter(opts.rateLimitPerMin ?? 6000);
+    return createMiddleware(async (c, next) => {
+        c.header('cache-control', 'no-store');
+        const resolved = await resolveS2sCaller({ audience: opts.audience, grants: opts.grants, logger: opts.logger, limiter }, { authorization: c.req.header('authorization'), testCaller: c.req.header('x-test-s2s-caller') }, c.req.method, c.req.path);
+        if (!resolved.caller) {
+            const failure = resolved.failure;
+            return c.json({ error: failure.error }, failure.status);
+        }
+        const user = parseConnectorIdentityHeaders((name) => c.req.header(name));
+        if (!user) {
+            opts.logger?.warn('connector identity headers missing or malformed', {
+                caller: resolved.caller.email,
+                path: c.req.path,
+            });
+            return c.json({ error: 'connector identity headers missing' }, 400);
+        }
+        if (!userAllowed(opts.userAccess, user)) {
+            opts.logger?.warn('connector user access denied', {
+                email: user.email,
+                policy: opts.userAccess,
+                path: c.req.path,
+            });
+            return c.json({ error: 'not enabled for this account', code: ACCESS_DENIED_CODE, email: user.email }, 403);
+        }
+        c.set('connector', user);
+        await next();
+    });
+}
+// ---------------------------------------------------------------------------
+// Tool tables
+/** A tool error the model can read and act on. Anything else thrown by a
+ *  tool is an internal failure: logged at ERROR, answered generically. */
+export class ConnectorError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ConnectorError';
+    }
+}
+export function connectorScopes(app) {
+    return [`${app}:read`, `${app}:write`];
+}
+const APP_NAME = /^[a-z][a-z0-9]*$/;
+const TOOL_NAME = /^[a-z][a-z0-9_]*$/;
+/**
+ * A typed tool table for one app: `tool()` captures each tool's argument
+ * shape; `table()` checks the names and fixes the scopes.
+ *
+ *   const { tool, table } = connectorToolkit<TodoDeps>('todo')
+ *   export const TOOLS = table({ todo_add_item: tool({ … }) })
+ */
+export function connectorToolkit(app) {
+    if (!APP_NAME.test(app))
+        throw new Error(`connector app name must be lowercase alphanumeric: ${app}`);
+    return {
+        tool(definition) {
+            return definition;
+        },
+        table(tools) {
+            for (const name of Object.keys(tools)) {
+                if (!TOOL_NAME.test(name) || !name.startsWith(`${app}_`)) {
+                    throw new Error(`connector tool name must be ${app}_<name>: ${name}`);
+                }
+            }
+            return { app, scopes: connectorScopes(app), tools };
+        },
+    };
+}
+/** The scope a tool needs, or null for a name that is not a tool. */
+export function connectorToolScope(table, name) {
+    if (typeof name !== 'string' || !Object.hasOwn(table.tools, name))
+        return null;
+    return table.tools[name].readOnly ? table.scopes[0] : table.scopes[1];
+}
+/**
+ * The scopes the `tools/call` messages in a JSON-RPC body need. Checked by
+ * the route before the SDK runs, because only an HTTP 403 with a challenge —
+ * never a tool result — makes the client ask the user for more access.
+ */
+export function requiredConnectorScopes(table, body) {
+    const needed = new Set();
+    for (const message of Array.isArray(body) ? body : [body]) {
+        if (message === null || typeof message !== 'object')
+            continue;
+        const { method, params } = message;
+        if (method !== 'tools/call')
+            continue;
+        const scope = connectorToolScope(table, params?.name);
+        if (scope !== null)
+            needed.add(scope);
+    }
+    return needed;
+}
+function textResult(value, isError = false) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+/**
+ * One MCP server per request, bound to the caller: the endpoint is stateless,
+ * so nothing is shared between calls or users.
+ */
+export function buildConnectorServer(table, deps, user, logger, info, instructions) {
+    const server = new McpServer({ name: info.name, title: info.title, version: info.version ?? '1.0.0' }, instructions ? { instructions } : {});
+    for (const [name, definition] of Object.entries(table.tools)) {
+        const scope = definition.readOnly ? table.scopes[0] : table.scopes[1];
+        server.registerTool(name, {
+            title: definition.title,
+            description: definition.description,
+            inputSchema: definition.inputSchema,
+            annotations: {
+                readOnlyHint: definition.readOnly,
+                ...(definition.readOnly ? {} : { destructiveHint: definition.destructive === true }),
+                openWorldHint: false,
+            },
+        }, async (args) => {
+            const started = Date.now();
+            // Identifiers, counts and the outcome only — never arguments or
+            // results, which are the user's content.
+            const log = (outcome, facts) => logger.info('connector tool call', {
+                tool: name,
+                user: user.email,
+                clientId: user.clientId,
+                grantId: user.grantId,
+                outcome,
+                elapsed_ms: Date.now() - started,
+                ...facts,
+            });
+            // The route's scope gate answers 403 first; this holds if it is bypassed.
+            if (!user.scopes.has(scope)) {
+                log('insufficient_scope', {});
+                return textResult({ error: 'insufficient_scope' }, true);
+            }
+            try {
+                const { result, facts } = await definition.run(deps, user, args);
+                log('ok', facts);
+                return textResult(result);
+            }
+            catch (error) {
+                if (error instanceof ConnectorError) {
+                    log(error.code, {});
+                    return textResult({ error: error.code, message: error.message }, true);
+                }
+                log('internal', {});
+                logger.error('connector tool failed', { tool: name, user: user.email, error: serializeError(error) });
+                return textResult({ error: 'internal', message: `the ${info.title} server failed to complete this call` }, true);
+            }
+        });
+    }
+    return server;
+}
+/** Answer one already-parsed JSON-RPC POST for this caller. */
+export async function handleConnectorRequest(server, request, parsedBody) {
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    try {
+        await server.connect(transport);
+        return await transport.handleRequest(request, { parsedBody });
+    }
+    finally {
+        await server.close();
+    }
+}
+const NO_USER = {
+    type: 'connector',
+    email: 'definitions@invalid',
+    role: 'owner',
+    scopes: new Set(),
+    clientId: 'definitions',
+    grantId: 'definitions',
+};
+const silentLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    with: () => silentLogger,
+    flush: async () => { },
+};
+/**
+ * The table's tool definitions exactly as `tools/list` returns them (the
+ * SDK's own JSON Schema rendering), obtained by listing them over an
+ * in-memory transport once. Served publicly: definitions are not secret, and
+ * the front door merges them into its own `tools/list`.
+ */
+export async function connectorToolDefinitions(table, info) {
+    const server = buildConnectorServer(table, undefined, NO_USER, silentLogger, info);
+    const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'definitions', version: '0.0.0' });
+    try {
+        await server.connect(serverSide);
+        await client.connect(clientSide);
+        return (await client.listTools()).tools;
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// The route
+/** JSON-RPC bodies are small except for a page of Markdown (apps cap their
+ *  own content at 1 MiB). */
+export const MAX_CONNECTOR_REQUEST_BYTES = 2 * 1024 * 1024;
+/**
+ * Serve the table at `/mcp` (POST only, forwarded identity, size cap, strict
+ * JSON, the scope gate, one server per request) and its definitions at
+ * `GET /mcp/tools` (public). Mount before the app's own identity middleware:
+ * a connector must never be looked at by `requireIdentity`, and vice versa.
+ */
+export function mountConnector(app, opts) {
+    const maxBytes = opts.maxRequestBytes ?? MAX_CONNECTOR_REQUEST_BYTES;
+    const admit = opts.admit ?? requireForwardedConnectorUser(opts);
+    let definitions;
+    const listDefinitions = () => (definitions ??= connectorToolDefinitions(opts.table, opts.serverInfo));
+    app.get('/mcp/tools', async (c) => {
+        c.header('cache-control', 'no-store');
+        return c.json({ tools: await listDefinitions() });
+    });
+    // Stateless JSON-RPC over POST: no server-initiated stream, no session.
+    // Answered before admission, so the SDK client's probe for a stream (a
+    // GET) is a plain 405 and not a grants refusal logged at ERROR.
+    const postOnly = createMiddleware(async (c, next) => {
+        if (c.req.method !== 'POST') {
+            c.header('cache-control', 'no-store');
+            return c.json({ error: 'method_not_allowed' }, 405, { allow: 'POST' });
+        }
+        await next();
+    });
+    app.all('/mcp', postOnly, admit, async (c) => {
+        c.header('cache-control', 'no-store');
+        const declared = Number(c.req.header('content-length') ?? '0');
+        if (!Number.isFinite(declared) || declared > maxBytes) {
+            return c.json({ error: 'request_too_large' }, 413);
+        }
+        const raw = await c.req.arrayBuffer();
+        if (raw.byteLength > maxBytes)
+            return c.json({ error: 'request_too_large' }, 413);
+        let body;
+        try {
+            body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
+        }
+        catch {
+            return c.json({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' }, id: null }, 400);
+        }
+        const user = c.get('connector');
+        for (const scope of requiredConnectorScopes(opts.table, body)) {
+            if (!user.scopes.has(scope)) {
+                // The front door rewrites this challenge to its own resource and the
+                // scopes it offers; what matters here is the error code.
+                return insufficientScope(c, { resource: `${opts.audience}/mcp`, scopes: opts.table.scopes });
+            }
+        }
+        const server = buildConnectorServer(opts.table, opts.deps, user, opts.logger, opts.serverInfo, opts.instructions);
+        return handleConnectorRequest(server, c.req.raw, body);
+    });
+    return { definitions: listDefinitions };
+}
+// ---------------------------------------------------------------------------
+// Test support
+/**
+ * A real MCP client whose HTTP goes straight into a Hono app, for app tests:
+ * `headers` carry the caller (`X-Test-S2S-Caller` plus the X-Connector-*
+ * identity, or whatever the route's `admit` expects).
+ */
+export async function connectorTestClient(request, headers, path = '/mcp') {
+    const client = new Client({ name: 'connector-test', version: '0.0.0' });
+    const transport = new StreamableHTTPClientTransport(new URL(`http://connector.test${path}`), {
+        fetch: async (input, init) => {
+            const merged = new Headers(init?.headers);
+            for (const [name, value] of Object.entries(headers))
+                merged.set(name, value);
+            return request(new URL(String(input)).pathname, { ...init, headers: merged });
+        },
+    });
+    await client.connect(transport);
+    return client;
+}
+/** Call a tool and unpack the JSON text result the kit produces. */
+export async function callConnectorTool(client, name, args) {
+    const result = await client.callTool({ name, arguments: args });
+    const content = result.content;
+    if (content.length !== 1 || content[0].type !== 'text') {
+        throw new Error(`unexpected tool result shape for ${name}`);
+    }
+    return { isError: result.isError === true, value: JSON.parse(content[0].text) };
+}

package/dist/llm/complete.d.ts

@@ -1,4 +1,11 @@
-import type { LLMRequest, LLMResponse } from './types.js';
+import type { LLMRequest, LLMResponse, Effort } from './types.js';
+import type { ModelEntry } from './models.js';
+/**
+ * The effort level to send a model: none when the model has no effort
+ * control, otherwise the requested level clamped to the nearest one the
+ * model accepts (e.g. `minimal` → `low` on models without a `minimal`).
+ */
+export declare function resolveEffort(entry: ModelEntry, effort: Effort | undefined): Effort | undefined;
 /**
  * Call an LLM with automatic failover to alternative providers.
  *

package/dist/llm/complete.js

@@ -1,9 +1,25 @@
-import { LLMError } from './types.js';
+import { LLMError, EFFORT_LEVELS } from './types.js';
 import { MODEL_REGISTRY, THINKING_HEADROOM_WARN_TOKENS } from './models.js';
 import { providers } from './providers/index.js';
 const DEFAULT_MAX_TOKENS = 2048;
 const DEFAULT_TEMPERATURE = 0.3;
 const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_THINKING_LEVELS = ['low', 'medium', 'high'];
+/**
+ * The effort level to send a model: none when the model has no effort
+ * control, otherwise the requested level clamped to the nearest one the
+ * model accepts (e.g. `minimal` → `low` on models without a `minimal`).
+ */
+export function resolveEffort(entry, effort) {
+    if (!entry.supportsEffort || effort === undefined)
+        return undefined;
+    const levels = entry.thinkingLevels ?? DEFAULT_THINKING_LEVELS;
+    if (levels.includes(effort))
+        return effort;
+    const rank = (level) => EFFORT_LEVELS.indexOf(level);
+    const wanted = rank(effort);
+    return [...levels].sort((a, b) => Math.abs(rank(a) - wanted) - Math.abs(rank(b) - wanted))[0];
+}
 /**
  * Call an LLM with automatic failover to alternative providers.
  *
@@ -42,6 +58,16 @@ export async function llmComplete(request) {
             ...(request.callSite ? { callSite: request.callSite } : {}),
         });
     }
+    // Google is retiring the Gemini thinking budget in favor of levels (see
+    // LLMRequest.thinkingBudget). Flag every caller still passing one so the
+    // migration to `effort` is visible in the logs, not discovered by a 400.
+    if (request.thinkingBudget !== undefined) {
+        request.logger?.warn('llm.thinking_budget_deprecated', {
+            model: request.model,
+            thinkingBudget: request.thinkingBudget,
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+    }
     // Build the ordered list of models to try: primary + fallbacks
     const modelsToTry = [request.model, ...entry.fallbacks];
     const failedAttempts = [];
@@ -67,7 +93,7 @@ export async function llmComplete(request) {
                 supportsTemperature: modelEntry.supportsTemperature ?? true,
                 supportsThinkingBudgetZero: modelEntry.supportsThinkingBudgetZero ?? true,
                 supportsForcedToolChoice: modelEntry.supportsForcedToolChoice ?? true,
-                effort: modelEntry.supportsEffort ? request.effort : undefined,
+                effort: resolveEffort(modelEntry, request.effort),
                 jsonSchema: request.jsonSchema,
                 apiKey,
                 logger: request.logger,

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, 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, } from './types.js';

package/dist/llm/index.js

@@ -7,4 +7,4 @@
 // Public API
 export { llmComplete } from './complete.js';
 export { MODEL_REGISTRY } from './models.js';
-export { LLMError, } from './types.js';
+export { LLMError, EFFORT_LEVELS, } from './types.js';

package/dist/llm/models.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderName } from './types.js';
+import type { ProviderName, Effort } from './types.js';
 export interface ModelEntry {
     /** Provider that serves this model. */
     provider: ProviderName;
@@ -22,12 +22,22 @@ export interface ModelEntry {
      */
     supportsThinkingBudgetZero?: boolean;
     /**
-     * Whether this model accepts Anthropic's `output_config.effort` parameter
-     * (verified on Sonnet 5 / Sonnet 4.6 2026-08-10; documented GA on Opus
-     * 4.6+/5). Defaults to `false`; the effort option is dropped for models
-     * without it.
+     * Whether this model accepts a reasoning-effort level: Anthropic's
+     * `output_config.effort` (verified on Sonnet 5 / Sonnet 4.6 2026-08-10;
+     * documented GA on Opus 4.6+/5) or Gemini's `thinkingConfig.thinkingLevel`
+     * (every Gemini 3.x model; verified live 2026-10-06). Defaults to `false`;
+     * the effort option is dropped for models without it.
      */
     supportsEffort?: boolean;
+    /**
+     * The effort levels this model accepts, for `supportsEffort` models whose
+     * set differs from the default `low | medium | high`. A requested level
+     * outside the set is clamped to the nearest one in it (`minimal` → `low`).
+     * Gemini 3.5 Flash-Lite, 3.6 Flash and 3 Flash preview also take `minimal`
+     * ("no hidden reasoning"); 3.1 Pro preview does not (Google's per-model
+     * table, 2026-10-06).
+     */
+    thinkingLevels?: readonly Effort[];
     /**
      * Whether this model performs hidden reasoning when the request omits any
      * thinking configuration (which this library always does). Defaults to

package/dist/llm/models.js

@@ -11,7 +11,12 @@ export const THINKING_HEADROOM_WARN_TOKENS = 4096;
 export const MODEL_REGISTRY = {
     // 2026-08 suite refresh: current models are claude-sonnet-5 / claude-opus-5
     // (Anthropic; claude-opus-5-5 succeeded claude-opus-5 on 2026-09-22), the gpt-5.6 sol/terra/luna family (OpenAI), and the Gemini
-    // 3.5/3.6 GA line plus gemini-3.1-pro-preview (Google). Older names stay
+    // 3.5/3.6 GA line plus gemini-3.1-pro-preview (Google). Google's 2026-10
+    // deprecation notice: `temperature`/`topP`/`topK` have had no effect since
+    // 3.6 Flash and, like `thinkingBudget`, will 400 on models after 3.8 Flash
+    // — hence `supportsTemperature: false` from 3.6 Flash on and `effort`
+    // (thinking level) as the reasoning control on every Gemini 3.x entry.
+    // Older names stay
     // registered so existing callers keep working, but no fallback chain routes
     // through a retiring model: gemini-2.5-pro and gemini-2.5-flash shut down
     // 2026-10-16, and the gpt-4o snapshots retire from 2026-10 onward.
@@ -30,6 +35,8 @@ export const MODEL_REGISTRY = {
         // so no `thinksByDefault` headroom warning.
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
         supportsThinkingBudgetZero: false,
+        supportsEffort: true,
+        thinkingLevels: ['minimal', 'low', 'medium', 'high'],
     },
     'gemini-3.6-flash': {
         provider: 'gemini',
@@ -40,6 +47,11 @@ export const MODEL_REGISTRY = {
         thinksByDefault: true,
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
         supportsThinkingBudgetZero: false,
+        supportsEffort: true,
+        thinkingLevels: ['minimal', 'low', 'medium', 'high'],
+        // Sampling parameters are fixed at their defaults from this model on
+        // (Google, 2026-10); still accepted today, so omitting changes nothing.
+        supportsTemperature: false,
     },
     'gpt-5.6-luna': {
         provider: 'openai',
@@ -63,11 +75,14 @@ export const MODEL_REGISTRY = {
         provider: 'gemini',
         apiModelId: 'gemini-3.1-flash-lite',
         fallbacks: ['claude-sonnet-4-6'],
+        supportsEffort: true,
     },
     'gemini-3-flash-preview': {
         provider: 'gemini',
         apiModelId: 'gemini-3-flash-preview',
         fallbacks: ['claude-haiku-4-5', 'gpt-5.6-luna'],
+        supportsEffort: true,
+        thinkingLevels: ['minimal', 'low', 'medium', 'high'],
     },
     'gpt-4o-mini': {
         provider: 'openai',
@@ -181,6 +196,8 @@ export const MODEL_REGISTRY = {
         thinksByDefault: true,
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
         supportsThinkingBudgetZero: false,
+        // Levels low|medium|high only (no `minimal`) — the default set.
+        supportsEffort: true,
     },
     // Retiring 2026-10-16 — migrate callers to gemini-3.1-pro-preview.
     'gemini-2.5-pro': {

package/dist/llm/providers/gemini.js

@@ -53,13 +53,18 @@ export const geminiProvider = {
             generationConfig.responseSchema = stripUnsupportedSchemaFields(request.jsonSchema.schema);
         }
         // Gemini thinking models reason before answering; the reasoning tokens
-        // count against maxOutputTokens. Capping the thinking budget reserves
-        // headroom for the visible response so a long reasoning pass can't
-        // truncate it. Models with a thinking floor (registry
+        // count against maxOutputTokens. `effort` (pre-gated and clamped in
+        // complete.ts) is the current control, sent as a thinking level — not a
+        // token cap, so callers size maxOutputTokens for it. The deprecated
+        // thinkingBudget is still forwarded when no level is set (the API rejects
+        // both together). Models with a thinking floor (registry
         // `supportsThinkingBudgetZero: false`) reject an explicit 0 budget with a
         // 400 — for those a 0 means "as little thinking as possible", which their
         // default already is, so the config is omitted entirely.
-        if (request.thinkingBudget !== undefined
+        if (request.effort) {
+            generationConfig.thinkingConfig = { thinkingLevel: request.effort };
+        }
+        else if (request.thinkingBudget !== undefined
             && (request.thinkingBudget !== 0 || request.supportsThinkingBudgetZero)) {
             generationConfig.thinkingConfig = { thinkingBudget: request.thinkingBudget };
         }

package/dist/llm/types.d.ts

@@ -35,21 +35,25 @@ export interface LLMRequest {
     /** Timeout per provider attempt, including response body download, in ms. Default: 60000. */
     timeoutMs?: number;
     /**
-     * Cap on reasoning/thinking tokens for models that support hidden reasoning
-     * (currently Gemini 2.5 family). Reasoning tokens are charged against the
-     * same budget as output tokens, so when thinking is unbounded it can starve
-     * the visible response and cause mid-string truncation. Setting this
-     * reserves headroom for the response. Ignored by providers that don't
-     * expose a thinking budget.
+     * @deprecated Use `effort`. Gemini's token cap on hidden reasoning. Gemini
+     * 3.x already remaps a budget to a thinking *level* (so it is no longer a
+     * cap), and Google has announced that models after 3.8 Flash reject it
+     * outright (400). Still forwarded to Gemini when `effort` is absent, with
+     * WARN `llm.thinking_budget_deprecated` per call; ignored by Anthropic and
+     * OpenAI, and ignored by Gemini when `effort` is also set.
      */
     thinkingBudget?: number;
     /**
-     * Output-effort level for models that support Anthropic's `output_config.
-     * effort` (registry `supportsEffort`). Lower effort trades thoroughness for
-     * latency/cost. Currently honored on Anthropic models only; when a call
-     * fails over to another provider the fallback runs at its own defaults.
+     * Reasoning-effort level for models that expose one (registry
+     * `supportsEffort`): Anthropic `output_config.effort`, Gemini
+     * `thinkingConfig.thinkingLevel`. Lower effort trades thoroughness for
+     * latency and cost. A level the target model lacks is clamped to its
+     * nearest supported level (registry `thinkingLevels`; `minimal` → `low` on
+     * Anthropic). Dropped for models without the control, so a failed-over
+     * call runs at the fallback's defaults. Levels are not token caps: size
+     * `maxTokens` for the reasoning the level will do.
      */
-    effort?: 'low' | 'medium' | 'high';
+    effort?: Effort;
     /**
      * Optional short identifier for the calling feature (e.g. 'video_classify',
      * 'message_prioritize', 'log_summary'). Included in llm.request and
@@ -80,6 +84,14 @@ export interface LLMRequest {
  * provider-specific vocabulary local to the adapter that owns it.
  */
 export type FinishCategory = 'complete' | 'truncated' | 'declined' | 'other';
+/**
+ * Reasoning-effort levels, ordered from least to most. Each provider adapter
+ * maps a level to its native control (Anthropic `output_config.effort`,
+ * Gemini `thinkingConfig.thinkingLevel`); `minimal` exists only on some
+ * Gemini models and means "no hidden reasoning".
+ */
+export declare const EFFORT_LEVELS: readonly ["minimal", "low", "medium", "high"];
+export type Effort = (typeof EFFORT_LEVELS)[number];
 /** Successful response from llmComplete(). */
 export interface LLMResponse {
     /** The text output (or JSON stringified if jsonSchema was used). */
@@ -188,8 +200,11 @@ export interface ProviderCallRequest {
     logger?: Logger;
     timeoutMs: number;
     thinkingBudget?: number;
-    /** Effort level, pre-gated by the registry's `supportsEffort` (absent when unsupported). */
-    effort?: 'low' | 'medium' | 'high';
+    /**
+     * Effort level, pre-gated by the registry's `supportsEffort` (absent when
+     * unsupported) and clamped to the model's `thinkingLevels`.
+     */
+    effort?: Effort;
     callSite?: string;
     cacheSystemPrompt?: boolean;
 }

package/dist/llm/types.js

@@ -1,3 +1,10 @@
+/**
+ * Reasoning-effort levels, ordered from least to most. Each provider adapter
+ * maps a level to its native control (Anthropic `output_config.effort`,
+ * Gemini `thinkingConfig.thinkingLevel`); `minimal` exists only on some
+ * Gemini models and means "no hidden reasoning".
+ */
+export const EFFORT_LEVELS = ['minimal', 'low', 'medium', 'high'];
 /** Error thrown when an LLM provider call fails. Its message may contain private input; do not log verbatim. */
 export class LLMError extends Error {
     provider;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.27.0",
+  "version": "3.29.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -80,6 +80,10 @@
     "./email": {
       "types": "./dist/email.d.ts",
       "default": "./dist/email.js"
+    },
+    "./connector": {
+      "types": "./dist/connector.d.ts",
+      "default": "./dist/connector.js"
     }
   },
   "bin": {
@@ -104,10 +108,12 @@
   "dependencies": {
     "@google-cloud/cloud-sql-connector": "^1.8.2",
     "@hono/node-server": "^1.14.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "google-auth-library": "^10.5.0",
     "hono": "^4.7.0",
     "pg": "^8.14.0",
-    "web-vitals": "^6.1.1"
+    "web-vitals": "^6.1.1",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",