@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/gateway/handlers/turn.js

@@ -0,0 +1,100 @@
+/**
+ * Command handlers for `agent.turn.submit` / `agent.turn.cancel` /
+ * `turn.approve`.
+ *
+ * Registered on the coordinator-owned command registry; each handler
+ * receives the service context (which carries the started turn service),
+ * the validated command payload, and the request meta.
+ *
+ * Response shapes: the protocol response schemas require
+ * `{ turnId, status }`. The handlers return a superset —
+ * `{ turnId, sessionId, status }` for submit (so the client learns the
+ * created session id) and `{ turnId, ok, status }` for cancel —
+ * which stays schema-valid (zod strips unknown fields) while carrying
+ * the fields callers need.
+ */
+import { ProtocolError } from '@boombot/protocol';
+export function registerTurnHandlers(registry) {
+    registry.register('agent.turn.submit', async (ctx, payload) => {
+        const service = ctx.turnService;
+        if (service === undefined) {
+            throw new Error('turn service is not running: agent.turn.submit is unavailable');
+        }
+        const { sessionId, message } = readSubmitPayload(payload);
+        const result = await service.submit({ sessionId, input: message });
+        return { turnId: result.turnId, sessionId: result.sessionId, status: 'running' };
+    });
+    registry.register('agent.turn.cancel', async (ctx, payload) => {
+        const service = ctx.turnService;
+        if (service === undefined) {
+            throw new Error('turn service is not running: agent.turn.cancel is unavailable');
+        }
+        const { turnId } = readCancelPayload(payload);
+        const ok = await service.cancel(turnId);
+        const status = ok ? 'cancelled' : 'completed';
+        return { turnId, ok, status };
+    });
+    registry.register('turn.approve', async (ctx, payload) => {
+        const service = ctx.turnService;
+        if (service === undefined) {
+            throw new Error('turn service is not running: turn.approve is unavailable');
+        }
+        if (service.approveTurn === undefined) {
+            throw new Error('turn.approve is not supported by this turn service');
+        }
+        const { runId, approved, editedArgs } = readApprovePayload(payload);
+        const { found, resumed } = await service.approveTurn(runId, approved, editedArgs);
+        if (!found) {
+            // Client error (400 via the server's ProtocolError mapping), not a
+            // 500: the runId is well-formed, it is just not awaiting approval
+            // (timed out, already answered, or never existed).
+            throw new ProtocolError('INVALID_PAYLOAD', `no pending approval for runId: ${runId}`, { runId });
+        }
+        return { runId, approved, resumed };
+    });
+}
+function readSubmitPayload(payload) {
+    if (typeof payload !== 'object' || payload === null) {
+        throw new Error('agent.turn.submit: payload must be an object');
+    }
+    const record = payload;
+    const { sessionId, message } = record;
+    if (typeof message !== 'string' || message.trim() === '') {
+        throw new Error('agent.turn.submit: message must be a non-empty string');
+    }
+    if (sessionId !== undefined && typeof sessionId !== 'string') {
+        throw new Error('agent.turn.submit: sessionId must be a string when provided');
+    }
+    return sessionId === undefined ? { message } : { sessionId, message };
+}
+function readCancelPayload(payload) {
+    if (typeof payload !== 'object' || payload === null) {
+        throw new Error('agent.turn.cancel: payload must be an object');
+    }
+    const { turnId } = payload;
+    if (typeof turnId !== 'string' || turnId === '') {
+        throw new Error('agent.turn.cancel: turnId must be a non-empty string');
+    }
+    return { turnId };
+}
+function readApprovePayload(payload) {
+    if (typeof payload !== 'object' || payload === null) {
+        throw new Error('turn.approve: payload must be an object');
+    }
+    const record = payload;
+    const { runId, approved, editedArgs } = record;
+    if (typeof runId !== 'string' || runId === '') {
+        throw new Error('turn.approve: runId must be a non-empty string');
+    }
+    if (typeof approved !== 'boolean') {
+        throw new Error('turn.approve: approved must be a boolean');
+    }
+    if (editedArgs !== undefined && (typeof editedArgs !== 'object' || editedArgs === null)) {
+        throw new Error('turn.approve: editedArgs must be an object when provided');
+    }
+    return {
+        runId,
+        approved,
+        editedArgs: editedArgs,
+    };
+}

package/dist/gateway/index.js

@@ -0,0 +1,126 @@
+/**
+ * BoomBot gateway entry point (coordinator-owned).
+ *
+ * `startGateway()` boots the full runtime: config → context (sessions,
+ * registry, event bus) → handlers → services → HTTP server. Exported for
+ * the `boombot gateway` CLI command (`apps/cli`), which dynamic-imports
+ * this module and calls `startGateway()`.
+ */
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { describeResearchConfig, loadResearchConfig } from '@boombot/core';
+import { loadConfig } from './config.js';
+import { defaultEnvPath, loadEnvFile } from './env-file.js';
+import { handleSSE, publishEvent } from './events.js';
+import { registerAllHandlers } from './handlers/index.js';
+import { HandlerRegistry } from './handlers/registry.js';
+import { createGatewayServer } from './server.js';
+import { startServices } from './services.js';
+import { SqliteSessionStore } from './sessions.js';
+import { isWebUiEnabled } from './static.js';
+export { handleSSE, publishEvent };
+/** Build the service context: config, durable sessions, registry, event bus. */
+function createContext() {
+    /*
+     * Load `.env` BEFORE `loadConfig()`, and load it here rather than in `main.ts`:
+     * the real entry path is `boombot gateway`, i.e. the CLI dynamic-imports this
+     * module and calls `startGateway()` — `main.ts` is not involved. `createContext`
+     * is where every config value flows through, so it's also the one place that
+     * must be certain.
+     *
+     * Print the count of loaded values with the path, NEVER the values: this is
+     * the line that answers "was the token I just pasted into `.env` picked up"
+     * without leaking anything.
+     */
+    const envKeys = loadEnvFile();
+    const config = loadConfig();
+    if (envKeys > 0) {
+        console.log(`[gateway] [info] env: loaded ${envKeys} value(s) from ${defaultEnvPath()}`);
+    }
+    mkdirSync(config.dataDir, { recursive: true });
+    const sessions = SqliteSessionStore.open(join(config.dataDir, 'sessions.sqlite'));
+    const registry = new HandlerRegistry();
+    const ctx = {
+        config,
+        dataDir: config.dataDir,
+        log: (level, msg, meta) => {
+            const extra = meta !== undefined && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';
+            console.log(`[gateway] [${level}] ${msg}${extra}`);
+        },
+        events: { publish: publishEvent },
+        sessions,
+        registry,
+    };
+    return ctx;
+}
+function createShutdown(stop, sessions) {
+    let stopping = false;
+    const shutdown = async () => {
+        if (stopping)
+            return;
+        stopping = true;
+        process.off('SIGINT', signalShutdown);
+        process.off('SIGTERM', signalShutdown);
+        console.log('[gateway] shutting down…');
+        try {
+            await stop();
+        }
+        finally {
+            sessions.close();
+        }
+        console.log('[gateway] stopped');
+    };
+    const signalShutdown = () => void shutdown().then(() => process.exit(0));
+    process.on('SIGINT', signalShutdown);
+    process.on('SIGTERM', signalShutdown);
+    return shutdown;
+}
+/**
+ * Boot the gateway and start listening. Resolves when the server is
+ * listening; the process keeps running until SIGINT/SIGTERM.
+ */
+export async function startGatewayManaged() {
+    const ctx = createContext();
+    // Services first: some handlers capture services at registration time
+    // (providers), others read them per-call (turn/schedule/memory/channels).
+    const stopServices = await startServices(ctx);
+    registerAllHandlers(ctx, ctx.registry);
+    const server = createGatewayServer(ctx);
+    const stop = async () => {
+        await stopServices();
+        await new Promise((resolve) => server.close(() => resolve()));
+    };
+    try {
+        await new Promise((resolve, reject) => {
+            const onError = (error) => reject(error);
+            server.once('error', onError);
+            server.listen(ctx.config.port, ctx.config.host, () => {
+                server.off('error', onError);
+                resolve();
+            });
+        });
+    }
+    catch (error) {
+        await stopServices();
+        ctx.sessions.close();
+        throw error;
+    }
+    const shutdown = createShutdown(stop, ctx.sessions);
+    console.log(`[gateway] listening on http://${ctx.config.host}:${ctx.config.port} (wire v1)`);
+    // Provider summary reads from the same env source as the turn service (the
+    // gateway config has no `research` field yet) — list ids only, NEVER print keys.
+    const research = describeResearchConfig(loadResearchConfig());
+    console.log(`[gateway] research: search ${research.search.join(', ')} | extract ${research.extract}`);
+    if (isWebUiEnabled()) {
+        console.log(`[gateway] web UI: http://${ctx.config.host}:${ctx.config.port}/`);
+    }
+    else {
+        console.log('[gateway] web UI assets not found — API-only mode ' +
+            '(dev: run the web UI with `pnpm --filter @boombot/web dev`)');
+    }
+    return shutdown;
+}
+/** Boot for callers that only need the process kept alive. */
+export async function startGateway() {
+    await startGatewayManaged();
+}

package/dist/gateway/main.js

@@ -0,0 +1,23 @@
+/**
+ * BoomBot gateway — process entry point.
+ *
+ * Boots the full phase-2 runtime (HTTP server, command dispatch, SSE,
+ * scheduler, memory, channels).
+ *
+ * There is no plain-`node` way to run this file from the source tree: the
+ * workspace packages export `./src/index.ts`, and Node's type stripping does
+ * NOT rewrite the relative `./x.js` specifiers inside them, so the import of
+ * `./index.js` here fails with ERR_MODULE_NOT_FOUND. Run the published bundle
+ * instead:
+ *
+ *   pnpm dist && node apps/cli/dist/bin/boombot.js gateway --no-browser
+ *
+ * or in-process via the CLI: `boombot gateway` (also `boombot serve`).
+ * For a source-tree entry, set BOOMBOT_GATEWAY_ENTRY=<path> to a loadable
+ * bundle — that override is the only supported escape hatch.
+ */
+import { startGateway } from './index.js';
+void startGateway().catch((error) => {
+    console.error('[gateway] fatal boot error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/gateway/server.js

@@ -0,0 +1,354 @@
+import { readFileSync } from 'node:fs';
+import { createServer as createHttpServer, } from 'node:http';
+import { createEnvelope, parseEnvelope, ProtocolError, WIRE_VERSION, } from '@boombot/protocol';
+import { checkAuth } from './auth.js';
+import { handleSSE, handleTurnSSE } from './events.js';
+import { serveStatic } from './static.js';
+/**
+ * Gateway HTTP server (node:http, no framework).
+ *
+ * Routes:
+ * - `GET /` and other non-API paths — the bundled web UI (`dist/web/`) when
+ *   present, with SPA fallback to `index.html` (see `static.ts`). Falls
+ *   through to 404 in API-only dev mode.
+ * - `GET /healthz` — liveness, no auth: `{ ok, version, wireVersion }`.
+ * - `GET /v1/events` — SSE stream of `StreamEvent`s. Auth required.
+ * - `GET /v1/turns/:turnId/events` — per-turn SSE stream (web chat). Auth required.
+ * - `POST /v1/commands` — command envelope dispatch. Auth required,
+ *   body limited to 1 MiB.
+ *
+ * Errors use the flat error body the web client parses:
+ * `{ error: { code, message, requestId?, details? } }` with the matching
+ * HTTP status (400 protocol errors, 401 auth, 404/405 routing, 413 body too
+ * large, 500 unexpected). Request logs never include headers or bodies.
+ */
+/** Max JSON body accepted on `POST /v1/commands` (1 MiB). */
+export const MAX_BODY_BYTES = 1_048_576;
+function readGatewayVersion() {
+    try {
+        const raw = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            'version' in parsed &&
+            typeof parsed.version === 'string') {
+            return parsed.version;
+        }
+    }
+    catch {
+        // Fall through to the fallback below.
+    }
+    return '0.0.0';
+}
+/** Gateway package version, surfaced on `GET /healthz`. */
+export const GATEWAY_VERSION = readGatewayVersion();
+class BodyTooLargeError extends Error {
+    constructor() {
+        super(`Request body exceeds ${MAX_BODY_BYTES} bytes`);
+        this.name = 'BodyTooLargeError';
+    }
+}
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(text),
+    });
+    res.end(text);
+}
+function sendOAuthPage(res, status, success) {
+    const title = success ? 'Zalo connected' : 'Zalo connection failed';
+    const body = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${title}</title><style>body{font:16px system-ui;margin:3rem;color:#172033}main{max-width:32rem;margin:auto}h1{font-size:1.4rem}</style></head><body><main><h1>${title}</h1><p>${success ? 'You can close this window and return to BoomBot.' : 'Return to BoomBot and start the connection again.'}</p></main>${success ? '<script>setTimeout(()=>window.close(),800)</script>' : ''}</body></html>`;
+    res.writeHead(status, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Content-Length': Buffer.byteLength(body),
+        'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'",
+        'Referrer-Policy': 'no-referrer',
+        'X-Content-Type-Options': 'nosniff',
+    });
+    res.end(body);
+}
+function sendError(res, status, code, message, options) {
+    const error = {
+        code,
+        message,
+    };
+    if (options?.requestId !== undefined)
+        error.requestId = options.requestId;
+    if (options?.details !== undefined)
+        error.details = options.details;
+    sendJson(res, status, { error });
+}
+function protocolStatus(code) {
+    switch (code) {
+        case 'INVALID_ENVELOPE':
+        case 'VERSION_MISMATCH':
+        case 'UNKNOWN_COMMAND':
+        case 'INVALID_PAYLOAD':
+        case 'INVALID_EVENT':
+            return 400;
+        case 'SESSION_NOT_FOUND':
+            return 404;
+        case 'NOT_CONFIGURED':
+            return 503;
+    }
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let settled = false;
+        req.on('data', (chunk) => {
+            if (settled)
+                return;
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                settled = true;
+                reject(new BodyTooLargeError());
+                // Pause the upload; the 413 response is sent by the caller, and the
+                // stream is destroyed only after the response has been flushed
+                // (destroying here would kill the socket before the client reads it).
+                req.pause();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            if (!settled) {
+                settled = true;
+                resolve(Buffer.concat(chunks));
+            }
+        });
+        req.on('error', (err) => {
+            if (!settled) {
+                settled = true;
+                reject(err);
+            }
+        });
+    });
+}
+function methodNotAllowed(ctx, res, method, path) {
+    ctx.log('warn', 'request', { method, path, status: 405 });
+    sendError(res, 405, 'METHOD_NOT_ALLOWED', `Method ${method} not allowed for ${path}`);
+}
+async function handleCommand(req, res, ctx) {
+    let requestId;
+    try {
+        const raw = (await readBody(req)).toString('utf8');
+        let json;
+        try {
+            json = raw.length === 0 ? undefined : JSON.parse(raw);
+        }
+        catch {
+            throw new ProtocolError('INVALID_ENVELOPE', 'Request body is not valid JSON');
+        }
+        const envelope = parseEnvelope(json);
+        requestId = envelope.requestId;
+        const result = await ctx.registry.dispatch(envelope.type, ctx, envelope.payload, {
+            requestId,
+        });
+        sendJson(res, 200, createEnvelope(envelope.type, result, requestId));
+        ctx.log('debug', 'request', {
+            method: 'POST',
+            path: '/v1/commands',
+            status: 200,
+            type: envelope.type,
+            requestId,
+        });
+    }
+    catch (error) {
+        if (error instanceof BodyTooLargeError) {
+            ctx.log('warn', 'request', { method: 'POST', path: '/v1/commands', status: 413 });
+            sendError(res, 413, 'PAYLOAD_TOO_LARGE', error.message, { requestId });
+            // Tear down the (paused) upload stream only after the 413 has flushed.
+            res.on('finish', () => req.destroy());
+            return;
+        }
+        if (error instanceof ProtocolError) {
+            const status = protocolStatus(error.code);
+            ctx.log('warn', 'request', {
+                method: 'POST',
+                path: '/v1/commands',
+                status,
+                code: error.code,
+                requestId,
+            });
+            sendError(res, status, error.code, error.message, {
+                requestId,
+                details: error.details,
+            });
+            return;
+        }
+        // Unexpected handler failure: generic message on the wire, details in the log only.
+        ctx.log('error', 'command handler failed', {
+            requestId,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        sendError(res, 500, 'INTERNAL_ERROR', 'Internal server error', { requestId });
+    }
+}
+async function handleChannelWebhook(req, res, ctx, channel, method, query) {
+    if (ctx.channelService === undefined) {
+        sendError(res, 503, 'NOT_CONFIGURED', 'Channel service is unavailable');
+        return;
+    }
+    try {
+        const response = await ctx.channelService.handleWebhook(channel, {
+            method,
+            rawBody: method === 'POST' ? await readBody(req) : Buffer.alloc(0),
+            headers: req.headers,
+            query,
+        });
+        const body = response.body ?? '';
+        res.writeHead(response.status, {
+            'Content-Type': response.contentType ?? 'text/plain; charset=utf-8',
+            'Content-Length': Buffer.byteLength(body),
+        });
+        res.end(body);
+        ctx.log('debug', 'channel webhook', { channel, method, status: response.status });
+    }
+    catch (error) {
+        if (error instanceof BodyTooLargeError) {
+            sendError(res, 413, 'PAYLOAD_TOO_LARGE', error.message);
+            res.on('finish', () => req.destroy());
+            return;
+        }
+        ctx.log('error', 'channel webhook failed', {
+            channel,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        sendError(res, 500, 'INTERNAL_ERROR', 'Internal server error');
+    }
+}
+async function handleRequest(req, res, ctx) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const path = url.pathname;
+    const method = (req.method ?? 'GET').toUpperCase();
+    if (path === '/healthz') {
+        if (method !== 'GET') {
+            methodNotAllowed(ctx, res, method, path);
+            return;
+        }
+        sendJson(res, 200, { ok: true, version: GATEWAY_VERSION, wireVersion: WIRE_VERSION });
+        ctx.log('debug', 'request', { method, path, status: 200 });
+        return;
+    }
+    if (path === '/v1/channels/zalo/oauth/callback') {
+        if (method !== 'GET') {
+            methodNotAllowed(ctx, res, method, path);
+            return;
+        }
+        if (ctx.channelService === undefined) {
+            sendOAuthPage(res, 503, false);
+            return;
+        }
+        try {
+            await ctx.channelService.completeZaloOAuth(url.searchParams);
+            sendOAuthPage(res, 200, true);
+            ctx.log('info', 'zalo OAuth callback completed', { path });
+        }
+        catch (error) {
+            ctx.log('warn', 'zalo OAuth callback failed', {
+                path,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            sendOAuthPage(res, 400, false);
+        }
+        return;
+    }
+    const webhookMatch = /^\/v1\/channels\/(slack|discord|whatsapp|messenger)\/webhook$/.exec(path);
+    if (webhookMatch !== null) {
+        if (method !== 'POST' && !(method === 'GET' && (webhookMatch[1] === 'whatsapp' || webhookMatch[1] === 'messenger'))) {
+            methodNotAllowed(ctx, res, method, path);
+            return;
+        }
+        await handleChannelWebhook(req, res, ctx, webhookMatch[1] ?? '', method, url.searchParams);
+        return;
+    }
+    if (path === '/v1/events') {
+        if (method !== 'GET') {
+            methodNotAllowed(ctx, res, method, path);
+            return;
+        }
+        const auth = checkAuth(req, ctx.config);
+        if (!auth.ok) {
+            ctx.log('warn', 'request', { method, path, status: 401, code: auth.code });
+            sendError(res, 401, auth.code, auth.message);
+            return;
+        }
+        handleSSE(req, res);
+        ctx.log('info', 'sse connected', { path });
+        return;
+    }
+    // Per-turn SSE stream for the web chat view: GET /v1/turns/:turnId/events.
+    const turnEventsMatch = /^\/v1\/turns\/([^/]+)\/events$/.exec(path);
+    if (turnEventsMatch !== null) {
+        if (method !== 'GET') {
+            methodNotAllowed(ctx, res, method, path);
+            return;
+        }
+        const auth = checkAuth(req, ctx.config);
+        if (!auth.ok) {
+            ctx.log('warn', 'request', { method, path, status: 401, code: auth.code });
+            sendError(res, 401, auth.code, auth.message);
+            return;
+        }
+        const turnId = decodeURIComponent(turnEventsMatch[1] ?? '');
+        if (turnId.length === 0) {
+            sendError(res, 400, 'INVALID_PAYLOAD', 'Missing turn id');
+            return;
+        }
+        handleTurnSSE(req, res, turnId, () => ctx.turnService?.getTerminalEvent?.(turnId), () => ctx.turnService?.getProgressEvents?.(turnId) ?? []);
+        ctx.log('info', 'sse connected', { path: '/v1/turns/:turnId/events', turnId });
+        return;
+    }
+    if (path === '/v1/commands') {
+        if (method !== 'POST') {
+            methodNotAllowed(ctx, res, method, path);
+            return;
+        }
+        const auth = checkAuth(req, ctx.config);
+        if (!auth.ok) {
+            ctx.log('warn', 'request', { method, path, status: 401, code: auth.code });
+            sendError(res, 401, auth.code, auth.message);
+            return;
+        }
+        await handleCommand(req, res, ctx);
+        return;
+    }
+    // Bundled web UI (`dist/web/`, zero-dependency static serving with SPA
+    // fallback). Falls through when the assets are absent (API-only dev mode),
+    // so the dev workflow is untouched.
+    if (await serveStatic(req, res, ctx.log)) {
+        return;
+    }
+    ctx.log('warn', 'request', { method, path, status: 404 });
+    sendError(res, 404, 'NOT_FOUND', `Unknown path: ${path}`);
+}
+/**
+ * Create (but do not listen on) the gateway HTTP server. The caller owns
+ * `listen()` / `close()`; `main.ts` wires the `ServiceContext` and starts it.
+ */
+export function createGatewayServer(ctx) {
+    // P1-2: re-announce HITL approvals still `pending` from the previous
+    // process, before the server starts listening. The turn service retains
+    // them in its per-turn progress replay, so a client opening
+    // `GET /v1/turns/:turnId/events` after boot still sees the pending
+    // approval instead of a silent timeout. No turn service (tests, API-only
+    // boot) → no-op.
+    ctx.turnService?.reannouncePendingApprovals?.();
+    const server = createHttpServer((req, res) => {
+        void handleRequest(req, res, ctx).catch((error) => {
+            ctx.log('error', 'unhandled request error', {
+                message: error instanceof Error ? error.message : String(error),
+            });
+            if (!res.headersSent) {
+                sendError(res, 500, 'INTERNAL_ERROR', 'Internal server error');
+            }
+            else {
+                res.destroy();
+            }
+        });
+    });
+    return server;
+}

package/dist/gateway/services/context-limits.js

@@ -0,0 +1,75 @@
+/**
+ * Dynamic Provider Context Limit Resolver.
+ *
+ * Resolves the accurate token context window and character bounds for any active
+ * provider and model dynamically. Eliminates hardcoded limits so providers with
+ * large contexts (e.g. 257k for CommandCode/anti, 200k for Claude, 1M for Gemini)
+ * utilize their full capacity while preventing overflow on smaller models.
+ */
+export function resolveProviderContextLimits(provider, modelName) {
+    // 1. Explicit environment variable override
+    const envLimit = process.env['BOOMBOT_MAX_CONTEXT_TOKENS'];
+    if (envLimit && !isNaN(Number(envLimit))) {
+        const tokens = Math.max(4_000, Number(envLimit));
+        return {
+            maxContextTokens: tokens,
+            maxContextChars: tokens * 4,
+            triggerThreshold: 0.75,
+            hotZoneRounds: 4,
+        };
+    }
+    // 2. Explicit provider extra configurations
+    if (typeof provider?.extra?.['contextWindow'] === 'number') {
+        const tokens = Math.max(4_000, provider.extra['contextWindow']);
+        return {
+            maxContextTokens: tokens,
+            maxContextChars: tokens * 4,
+            triggerThreshold: 0.75,
+            hotZoneRounds: 4,
+        };
+    }
+    if (typeof provider?.extra?.['maxTokens'] === 'number' && provider.extra['maxTokens'] > 16_000) {
+        const tokens = provider.extra['maxTokens'];
+        return {
+            maxContextTokens: tokens,
+            maxContextChars: tokens * 4,
+            triggerThreshold: 0.75,
+            hotZoneRounds: 4,
+        };
+    }
+    const model = (modelName || provider?.model || '').toLowerCase();
+    const kind = (provider?.kind || '').toLowerCase();
+    // 3. Model & Provider heuristic mapping
+    let tokens = 128_000;
+    if (model.includes('anti')) {
+        // CommandCode 9Router anti instance
+        tokens = 257_000;
+    }
+    else if (model.includes('gemini') || kind === 'google') {
+        tokens = 1_000_000;
+    }
+    else if (model.includes('claude') || kind === 'anthropic') {
+        tokens = 200_000;
+    }
+    else if (model.includes('deepseek') || kind === 'deepseek') {
+        tokens = 128_000;
+    }
+    else if (model.includes('gpt-4o') || model.includes('o1') || model.includes('o3') || kind === 'openai') {
+        tokens = 128_000;
+    }
+    else if (model.includes('qwen') || kind === 'qwen') {
+        tokens = 128_000;
+    }
+    else if (model.includes('mistral') || model.includes('codestral') || kind === 'mistral') {
+        tokens = 128_000;
+    }
+    else if (kind === 'ollama') {
+        tokens = 32_768;
+    }
+    return {
+        maxContextTokens: tokens,
+        maxContextChars: tokens * 4,
+        triggerThreshold: 0.75,
+        hotZoneRounds: 4,
+    };
+}