@bahulam/code 2.6.0

package/src/core/providers.mjs

@@ -0,0 +1,219 @@
+/**
+ * Multi-Provider — unified provider config and request/response transforms.
+ *
+ * Supports: Anthropic, OpenAI, Google, Bedrock (stub), Vertex (stub).
+ * Each provider defines endpoint, auth headers, and optional transforms.
+ */
+
+const PROVIDERS = {
+    anthropic: {
+        name: 'Anthropic',
+        endpoint: 'https://api.anthropic.com/v1/messages',
+        envKey: 'ANTHROPIC_API_KEY',
+        authHeader(key) {
+            return {
+                'x-api-key': key,
+                'anthropic-version': '2023-06-01',
+                'Content-Type': 'application/json',
+            };
+        },
+        models: ['claude-sonnet-4-6', 'claude-haiku-4-5', 'claude-opus-4-6'],
+    },
+
+    openai: {
+        name: 'OpenAI',
+        endpoint: 'https://api.openai.com/v1/chat/completions',
+        envKey: 'OPENAI_API_KEY',
+        authHeader(key) {
+            return {
+                'Authorization': `Bearer ${key}`,
+                'Content-Type': 'application/json',
+            };
+        },
+        models: ['gpt-4o', 'gpt-4o-mini', 'o1-preview', 'o1-mini', 'o3-mini'],
+        transformRequest(body) {
+            const messages = [];
+            if (body.system) {
+                messages.push({ role: 'system', content: body.system });
+            }
+            for (const msg of body.messages || []) {
+                if (typeof msg.content === 'string') {
+                    messages.push({ role: msg.role, content: msg.content });
+                } else if (Array.isArray(msg.content)) {
+                    for (const block of msg.content) {
+                        if (block.type === 'tool_result') {
+                            messages.push({
+                                role: 'tool',
+                                tool_call_id: block.tool_use_id,
+                                content: block.content,
+                            });
+                        }
+                    }
+                }
+            }
+
+            const tools = (body.tools || []).map(t => ({
+                type: 'function',
+                function: { name: t.name, description: t.description, parameters: t.input_schema },
+            }));
+
+            return {
+                model: body.model,
+                messages,
+                ...(tools.length > 0 && { tools }),
+                ...(body.max_tokens && { max_tokens: body.max_tokens }),
+                ...(body.stream && { stream: true }),
+            };
+        },
+        transformResponse(data) {
+            const choice = data.choices?.[0];
+            if (!choice) throw new Error('No choices in OpenAI response');
+
+            const content = [];
+            if (choice.message?.content) {
+                content.push({ type: 'text', text: choice.message.content });
+            }
+            if (choice.message?.tool_calls) {
+                for (const tc of choice.message.tool_calls) {
+                    content.push({
+                        type: 'tool_use',
+                        id: tc.id,
+                        name: tc.function.name,
+                        input: JSON.parse(tc.function.arguments || '{}'),
+                    });
+                }
+            }
+
+            return {
+                content,
+                stop_reason: choice.finish_reason === 'stop' ? 'end_turn' : choice.finish_reason,
+                usage: {
+                    input_tokens: data.usage?.prompt_tokens || 0,
+                    output_tokens: data.usage?.completion_tokens || 0,
+                },
+            };
+        },
+    },
+
+    google: {
+        name: 'Google',
+        endpoint: 'https://generativelanguage.googleapis.com/v1beta/models',
+        envKey: 'GOOGLE_API_KEY',
+        altEnvKey: 'GEMINI_API_KEY',
+        authHeader(key) {
+            return { 'Content-Type': 'application/json' };
+        },
+        models: ['gemini-2.0-flash', 'gemini-2.0-pro', 'gemini-1.5-flash'],
+        transformRequest(body) {
+            const contents = [];
+            for (const msg of body.messages || []) {
+                const role = msg.role === 'assistant' ? 'model' : 'user';
+                if (typeof msg.content === 'string') {
+                    contents.push({ role, parts: [{ text: msg.content }] });
+                }
+            }
+
+            return {
+                contents,
+                ...(body.system && {
+                    systemInstruction: { parts: [{ text: body.system }] },
+                }),
+            };
+        },
+        transformResponse(data) {
+            const candidate = data.candidates?.[0];
+            if (!candidate) throw new Error('No candidates in Google response');
+
+            const content = [];
+            for (const part of candidate.content?.parts || []) {
+                if (part.text) content.push({ type: 'text', text: part.text });
+            }
+
+            return {
+                content,
+                stop_reason: 'end_turn',
+                usage: {
+                    input_tokens: data.usageMetadata?.promptTokenCount || 0,
+                    output_tokens: data.usageMetadata?.candidatesTokenCount || 0,
+                },
+            };
+        },
+    },
+
+    bedrock: {
+        name: 'AWS Bedrock',
+        endpoint: null, // Dynamic based on region
+        envKey: 'AWS_ACCESS_KEY_ID',
+        models: ['anthropic.claude-3-sonnet', 'anthropic.claude-3-haiku'],
+        authHeader() {
+            // AWS SigV4 signing would go here
+            return { 'Content-Type': 'application/json' };
+        },
+        getEndpoint(model, region = 'us-east-1') {
+            return `https://bedrock-runtime.${region}.amazonaws.com/model/${model}/invoke`;
+        },
+    },
+
+    vertex: {
+        name: 'Google Vertex AI',
+        endpoint: null, // Dynamic based on project/region
+        envKey: 'GOOGLE_APPLICATION_CREDENTIALS',
+        models: ['claude-sonnet-4-6@anthropic'],
+        authHeader() {
+            // GCP bearer token would go here
+            return { 'Content-Type': 'application/json' };
+        },
+        getEndpoint(model, project, region = 'us-central1') {
+            return `https://${region}-aiplatform.googleapis.com/v1/projects/${project}/locations/${region}/publishers/anthropic/models/${model}:rawPredict`;
+        },
+    },
+};
+
+/**
+ * Get the provider configuration for a given model.
+ * @param {string} model - model name
+ * @returns {object} provider config
+ */
+export function getProvider(model) {
+    if (model.startsWith('claude') || model.startsWith('anthropic')) return PROVIDERS.anthropic;
+    if (model.startsWith('gpt') || model.startsWith('o1') || model.startsWith('o3')) return PROVIDERS.openai;
+    if (model.startsWith('gemini')) return PROVIDERS.google;
+    return PROVIDERS.anthropic; // default
+}
+
+/**
+ * Get a provider by name.
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+export function getProviderByName(name) {
+    return PROVIDERS[name];
+}
+
+/**
+ * List all supported providers.
+ * @returns {Array<{ name: string, envKey: string, models: string[] }>}
+ */
+export function listProviders() {
+    return Object.entries(PROVIDERS).map(([key, p]) => ({
+        id: key,
+        name: p.name,
+        envKey: p.envKey,
+        models: p.models || [],
+        hasEndpoint: !!p.endpoint,
+    }));
+}
+
+/**
+ * Check which providers have API keys configured.
+ * @returns {Array<{ id: string, name: string, configured: boolean }>}
+ */
+export function checkProviderKeys() {
+    return Object.entries(PROVIDERS).map(([key, p]) => ({
+        id: key,
+        name: p.name,
+        configured: !!(process.env[p.envKey] || (p.altEnvKey && process.env[p.altEnvKey])),
+    }));
+}
+
+export { PROVIDERS };

package/src/core/rate-limit-display.mjs

@@ -0,0 +1,121 @@
+/**
+ * User-facing helpers for PRD-065 rolling message windows.
+ */
+
+export function normalizeRateLimit(rateLimit) {
+    if (!rateLimit || typeof rateLimit !== 'object') return null;
+
+    const used = numberOrNull(rateLimit.msgs_used_in_window);
+    const limit = numberOrNull(rateLimit.msgs_per_window);
+    const configured = numberOrNull(rateLimit.configured_msgs_per_window);
+    const retryAfter = numberOrNull(rateLimit.retry_after ?? rateLimit.retry_after_seconds);
+
+    return {
+        ...rateLimit,
+        msgs_used_in_window: used,
+        msgs_per_window: limit,
+        configured_msgs_per_window: configured,
+        retry_after: retryAfter,
+        unlimited: Boolean(rateLimit.unlimited),
+        byok: Boolean(rateLimit.byok),
+    };
+}
+
+export function messagesRemaining(rateLimit) {
+    const rl = normalizeRateLimit(rateLimit);
+    if (!rl) return null;
+    if (rl.unlimited || rl.msgs_per_window === -1) return Infinity;
+    if (typeof rl.msgs_used_in_window !== 'number' || typeof rl.msgs_per_window !== 'number') return null;
+    return Math.max(0, rl.msgs_per_window - rl.msgs_used_in_window);
+}
+
+export function formatRetryAfter(seconds) {
+    const secs = Math.max(0, Math.ceil(Number(seconds) || 0));
+    if (secs <= 0) return 'soon';
+    const hours = Math.floor(secs / 3600);
+    const minutes = Math.ceil((secs % 3600) / 60);
+    if (hours > 0 && minutes > 0) return `${hours}h ${minutes}m`;
+    if (hours > 0) return `${hours}h`;
+    if (minutes > 0) return `${minutes}m`;
+    return `${secs}s`;
+}
+
+export function resetLabel(rateLimit, now = Date.now()) {
+    const rl = normalizeRateLimit(rateLimit);
+    if (!rl?.window_reset_at) return null;
+    const resetMs = Date.parse(rl.window_reset_at);
+    if (!Number.isFinite(resetMs)) return null;
+    return formatRetryAfter(Math.max(0, (resetMs - now) / 1000));
+}
+
+export function formatMessageWindow(rateLimit, { includeReset = true } = {}) {
+    const rl = normalizeRateLimit(rateLimit);
+    if (!rl) return null;
+
+    const tier = rl.tier ? String(rl.tier).toUpperCase() : null;
+    if (rl.byok || rl.unlimited || rl.msgs_per_window === -1) {
+        return [tier, 'unlimited messages'].filter(Boolean).join(' · ');
+    }
+
+    if (typeof rl.msgs_used_in_window !== 'number' || typeof rl.msgs_per_window !== 'number') {
+        return tier || null;
+    }
+
+    const remaining = Math.max(0, rl.msgs_per_window - rl.msgs_used_in_window);
+    const parts = [
+        tier,
+        `${remaining} / ${rl.msgs_per_window} messages this window`,
+    ].filter(Boolean);
+
+    const reset = includeReset ? resetLabel(rl) : null;
+    if (reset) parts.push(`resets in ${reset}`);
+    return parts.join(' · ');
+}
+
+export function lowWindowStatus(rateLimit) {
+    const rl = normalizeRateLimit(rateLimit);
+    if (!rl || rl.byok || rl.unlimited || rl.msgs_per_window === -1) return 'ok';
+    const remaining = messagesRemaining(rl);
+    if (typeof remaining !== 'number' || typeof rl.msgs_per_window !== 'number') return 'ok';
+    if (remaining <= 0) return 'exhausted';
+    if (remaining <= Math.max(5, Math.floor(rl.msgs_per_window * 0.2))) return 'low';
+    return 'ok';
+}
+
+export function rateLimitErrorMessage(payload, fallback = 'Message limit reached.') {
+    const detail = quotaErrorDetail(payload);
+    const retryAfter = detail?.retry_after ?? detail?.rate_limit?.retry_after ?? detail?.rate_limit?.retry_after_seconds;
+    const detailMessage = normalizeBillingBrandCopy(detail?.message);
+    if (detail?.code === 'credit_balance_exhausted') {
+        return detailMessage || 'Credit balance exhausted — add credits, upgrade your plan, or switch to BYOK in Settings.';
+    }
+    if (detail?.code === 'message_limit_reached') {
+        if (detailMessage) return detailMessage;
+        if (retryAfter != null) return `Message window exhausted — try again in ${formatRetryAfter(retryAfter)}, or upgrade your plan.`;
+        return 'Message window exhausted — wait for the window to reset or upgrade your plan.';
+    }
+    if (detailMessage) return detailMessage;
+    if (retryAfter != null) return `Message window exhausted — try again in ${formatRetryAfter(retryAfter)}, or upgrade your plan.`;
+    return fallback;
+}
+
+export function normalizeBillingBrandCopy(value) {
+    if (typeof value !== 'string') return value;
+    return value
+        .replace(/codekepler\.ai\/pricing/gi, 'bahulam.ai/pricing')
+        .replace(/Kepler credit charges/g, 'Bahulam credit charges')
+        .replace(/Kepler credits/g, 'Bahulam credits');
+}
+
+export function quotaErrorDetail(payload) {
+    if (!payload || typeof payload !== 'object') return {};
+    if (typeof payload.detail === 'string') return { message: payload.detail };
+    if (payload.detail && typeof payload.detail === 'object') return payload.detail;
+    return payload;
+}
+
+function numberOrNull(value) {
+    if (value == null) return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}

package/src/core/rate-limiter.mjs

@@ -0,0 +1,119 @@
+/**
+ * Rate Limiter — handle 429 and 529 API responses.
+ *
+ * Implements exponential backoff with jitter for rate-limited
+ * and overloaded API responses. Tracks retry state per-instance.
+ */
+
+export class RateLimiter {
+    /**
+     * @param {object} [options]
+     * @param {number} [options.maxRetries] - max number of retries (default: 5)
+     * @param {number} [options.baseDelay] - base delay in ms (default: 1000)
+     * @param {number} [options.maxDelay] - max delay in ms (default: 60000)
+     */
+    constructor(options = {}) {
+        this.maxRetries = options.maxRetries ?? 5;
+        this.baseDelay = options.baseDelay ?? 1000;
+        this.maxDelay = options.maxDelay ?? 60000;
+        this.retryAfter = 0;
+        this.retryCount = 0;
+        this.lastRetryAt = null;
+    }
+
+    /**
+     * Handle an API response and determine whether to retry.
+     * @param {{ status: number, headers: { get: (name: string) => string|null } }} response
+     * @returns {Promise<'ok'|'retry'|'fail'>}
+     */
+    async handleResponse(response) {
+        if (response.status === 429) {
+            // Rate limited
+            if (this.retryCount >= this.maxRetries) return 'fail';
+
+            const retryAfter = parseInt(response.headers?.get?.('retry-after') || '10', 10);
+            const delayMs = Math.min(retryAfter * 1000, this.maxDelay);
+            this.retryAfter = Date.now() + delayMs;
+            this.retryCount++;
+            this.lastRetryAt = new Date().toISOString();
+
+            await this.wait(delayMs);
+            return 'retry';
+        }
+
+        if (response.status === 529) {
+            // API overloaded
+            if (this.retryCount >= this.maxRetries) return 'fail';
+
+            const delay = this.calculateBackoff();
+            this.retryAfter = Date.now() + delay;
+            this.retryCount++;
+            this.lastRetryAt = new Date().toISOString();
+
+            await this.wait(delay);
+            return 'retry';
+        }
+
+        // Success — reset retry count
+        this.retryCount = 0;
+        return 'ok';
+    }
+
+    /**
+     * Calculate exponential backoff with jitter.
+     * @returns {number} delay in milliseconds
+     */
+    calculateBackoff() {
+        const exponential = this.baseDelay * Math.pow(2, this.retryCount);
+        const jitter = Math.random() * this.baseDelay;
+        return Math.min(exponential + jitter, this.maxDelay);
+    }
+
+    /**
+     * Check if we should wait before making a request.
+     * @returns {boolean}
+     */
+    shouldWait() {
+        return Date.now() < this.retryAfter;
+    }
+
+    /**
+     * Get remaining wait time in ms.
+     * @returns {number}
+     */
+    remainingWait() {
+        return Math.max(0, this.retryAfter - Date.now());
+    }
+
+    /**
+     * Reset all retry state.
+     */
+    reset() {
+        this.retryAfter = 0;
+        this.retryCount = 0;
+        this.lastRetryAt = null;
+    }
+
+    /**
+     * Get current limiter status.
+     */
+    status() {
+        return {
+            retryCount: this.retryCount,
+            maxRetries: this.maxRetries,
+            retryAfter: this.retryAfter,
+            lastRetryAt: this.lastRetryAt,
+            isWaiting: this.shouldWait(),
+            remainingMs: this.remainingWait(),
+        };
+    }
+
+    /**
+     * Wait for the specified duration.
+     * @param {number} ms
+     * @returns {Promise<void>}
+     */
+    wait(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}

package/src/core/resume-mode.mjs

@@ -0,0 +1,192 @@
+/**
+ * Resume Mode — decide how much of a transcript to send to the agent (PRD-068 §5.14.3).
+ *
+ * Rule of thumb: if the projected context (transcript + system prompt overhead)
+ * fits comfortably in the current model's window, resume with `full` silently.
+ * Only ask the user when we're above the highWatermark.
+ *
+ * Config lives in .bahulam/settings.json:
+ *   {
+ *     "resume": {
+ *       "highWatermark": 0.50,   // prompt above this (default 50%)
+ *       "hardCap":       0.85    // refuse full above this  (default 85%)
+ *     }
+ *   }
+ */
+
+// System overhead — tools, memory, .bahulam/ context, kepler.md, skills index.
+// Rough constant; individual runs vary. Tuned toward "assume ~4k of overhead".
+const DEFAULT_SYSTEM_OVERHEAD_TOKENS = 4000;
+
+// Model context windows we know about. Fallback used when unknown.
+// Keep this table small — it's a hint, not a source of truth.
+const MODEL_CONTEXT_WINDOWS = {
+  'anthropic/claude-sonnet-4':          200000,
+  'anthropic/claude-4-sonnet-20250522': 200000,
+  'anthropic/claude-opus-4':            200000,
+  'deepseek/deepseek-v4-flash':         128000,
+  'deepseek/deepseek-v4-pro':           128000,
+  'deepseek/deepseek-chat-v3-0324':     128000,
+  'openai/gpt-5':                       400000,
+  'openai/gpt-5-mini':                  400000,
+  'google/gemini-2.5-pro':              1000000,
+  'xiaomi/mimo-v2.5':                   128000,
+};
+const DEFAULT_CONTEXT_WINDOW = 128000;
+
+function contextWindowHintInfo(hint) {
+  const raw = typeof hint === 'number'
+    ? hint
+    : hint?.context_length ?? hint?.contextLength ?? hint?.tokens ?? hint?.windowSize;
+  const tokens = Number(raw);
+  if (Number.isFinite(tokens) && tokens > 0) {
+    return {
+      tokens: Math.trunc(tokens),
+      known: true,
+      source: hint?.source || 'backend_catalog',
+    };
+  }
+  return null;
+}
+
+export function modelContextWindowInfo(model, contextWindowHint = null) {
+  const hinted = contextWindowHintInfo(contextWindowHint);
+  if (hinted) return hinted;
+  if (model && MODEL_CONTEXT_WINDOWS[model]) {
+    return { tokens: MODEL_CONTEXT_WINDOWS[model], known: true, source: 'model_map' };
+  }
+  return { tokens: DEFAULT_CONTEXT_WINDOW, known: false, source: 'fallback' };
+}
+
+export function modelContextWindow(model, contextWindowHint = null) {
+  return modelContextWindowInfo(model, contextWindowHint).tokens;
+}
+
+/**
+ * Decide the resume mode for a session based on projected context usage.
+ *
+ * @param {object} args
+ * @param {number} args.transcriptTokens  — projected transcript size when serialized
+ * @param {string} [args.model]           — current agent model id
+ * @param {object|number} [args.contextWindow] — backend/catalog context-window hint
+ * @param {object} [args.settings]        — .bahulam/settings.json contents (optional)
+ * @param {number} [args.systemOverhead]  — override system overhead (defaults to 4k)
+ * @returns {{
+ *   mode:          'full' | 'ask' | 'no-full-allowed',
+ *   defaultChoice: 'full' | 'tail-20' | 'summary',
+ *   projected:     number,   // total projected tokens
+ *   windowSize:    number,   // model window
+ *   usageRatio:    number,   // projected / windowSize
+ *   highWatermark: number,
+ *   hardCap:       number,
+ * }}
+ *
+ * `mode = 'full'`             — resume immediately in full mode; do not prompt
+ * `mode = 'ask'`              — show the tri-choice overlay
+ * `mode = 'no-full-allowed'`  — above hardCap; user must pick a tail mode or summary
+ */
+export function decideResumeMode({
+  transcriptTokens,
+  model,
+  contextWindow = null,
+  settings,
+  systemOverhead = DEFAULT_SYSTEM_OVERHEAD_TOKENS,
+} = {}) {
+  const cfg = settings?.resume || {};
+  const highWatermark = clampRatio(cfg.highWatermark, 0.50);
+  const hardCap = clampRatio(cfg.hardCap, 0.85);
+
+  const windowInfo = modelContextWindowInfo(model, contextWindow);
+  const windowSize = windowInfo.tokens;
+  const projected = Math.max(0, Number(transcriptTokens) || 0) + systemOverhead;
+  const usageRatio = windowSize > 0 ? projected / windowSize : 0;
+
+  let mode;
+  let defaultChoice;
+  if (usageRatio > hardCap) {
+    mode = 'no-full-allowed';
+    // Above hardCap — last 20 turns is usually the least-lossy fit; user picks.
+    defaultChoice = 'tail-20';
+  } else if (usageRatio > highWatermark) {
+    mode = 'ask';
+    defaultChoice = 'full';
+  } else {
+    mode = 'full';
+    defaultChoice = 'full';
+  }
+
+  return {
+    mode,
+    defaultChoice,
+    projected,
+    windowSize,
+    windowKnown: windowInfo.known,
+    windowSource: windowInfo.source,
+    usageRatio,
+    highWatermark,
+    hardCap,
+  };
+}
+
+/**
+ * Estimate the context tokens for a candidate mode. Used by the tri-choice
+ * overlay to render "62k / 14k / 2k" per option before the user commits.
+ *
+ * @param {'full' | 'checkpoint-full' | 'summary' | 'tail-10' | 'tail-20' | 'recap+tail'} choice
+ * @param {number} fullTokens — projected transcript size in full mode
+ * @param {object} [opts]
+ * @returns {number} projected tokens for the chosen mode
+ */
+export function projectedTokensForChoice(choice, fullTokens, opts = {}) {
+  const {
+    tailTurns = null,
+    // Rough per-turn estimate. Summary block is ~1-2k.
+    tailBaseTokens = 2000,
+    perTailTurnTokens = 500,
+    summaryBaseTokens = 2000,
+    resumeSummary = null,
+  } = opts;
+
+  switch (choice) {
+    case 'full':
+      return Math.max(0, Number(fullTokens) || 0);
+    case 'checkpoint-full': {
+      const full = Math.max(0, Number(fullTokens) || 0);
+      const fullMessages = Math.max(0, Number(resumeSummary?.fullMessageCount) || 0);
+      const covered = Math.max(0, Number(resumeSummary?.sourceMessageCount) || 0);
+      if (!fullMessages || covered <= 0) return full;
+      const remainingMessages = Math.max(0, fullMessages - covered);
+      if (remainingMessages === 0) return summaryBaseTokens;
+      return summaryBaseTokens + (perTailTurnTokens * remainingMessages);
+    }
+    case 'tail-10':
+      return tailBaseTokens + (10 * perTailTurnTokens);
+    case 'tail-20':
+      return tailBaseTokens + (20 * perTailTurnTokens);
+    case 'recap+tail':
+      return tailBaseTokens + ((Number(tailTurns) || 8) * perTailTurnTokens);
+    case 'summary':
+      return summaryBaseTokens;
+    default:
+      return Math.max(0, Number(fullTokens) || 0);
+  }
+}
+
+function clampRatio(value, fallback) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  if (n <= 0) return fallback;
+  if (n > 1) return fallback;
+  return n;
+}
+
+/**
+ * Format tokens with a k/M suffix — "8k", "62k", "1.2M".
+ * Used by the picker + overlay so numbers fit in narrow columns.
+ */
+export function formatTokens(n) {
+  const v = Math.round(Number(n) || 0);
+  if (v < 1000) return `${v}`;
+  if (v < 1_000_000) return `${Math.round(v / 1000)}k`;
+  return `${(v / 1_000_000).toFixed(1)}M`;
+}