@axplusb/kepler 2.3.2 → 2.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axplusb/kepler",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "description": "Kepler — AI coding agent with operating brief, preflight planning, and sub-agents. SWE-bench Lite evaluated.",
   "type": "module",
   "bin": {

package/src/core/error-guidance.mjs

@@ -221,6 +221,7 @@ export function formatAgentErrorGuidance(data = {}) {
   const providerMeta = provider || compact(data.provider || data.gateway || data.gateway_type);
   const taskId = compact(data.task_id);
   const retryAfter = data.retry_after != null ? compact(data.retry_after) : '';
+  const retryLabel = retryAfter ? formatRetryAfterLabel(retryAfter) : '';
   const retryable = data.retryable === true;
 
   if (isBedrockMissingCredentials(data)) {
@@ -237,7 +238,16 @@ export function formatAgentErrorGuidance(data = {}) {
 
   const lines = [];
   const providerGuidance = PROVIDER_GUIDANCE[provider];
-  if (phase === 'gateway' || code.includes('gateway')) {
+  if (code === 'credit_balance_exhausted') {
+    lines.push('Add credits or upgrade your plan to continue using platform-hosted models.');
+    lines.push('If you have your own provider key, switch to BYOK in Settings to keep working without Kepler credit charges.');
+    if (data.pricing_url) lines.push(`Open ${data.pricing_url} to top up or compare plans.`);
+  } else if (code === 'message_limit_reached') {
+    const retry = retryLabel ? ` Wait ${retryLabel} for the rolling window to recover.` : ' Wait for the rolling message window to reset.';
+    lines.push(`You reached the message limit for this plan.${retry}`);
+    lines.push('Upgrade your plan for a larger 5-hour message window, or switch to BYOK if available.');
+    if (data.pricing_url) lines.push(`Open ${data.pricing_url} to upgrade.`);
+  } else if (phase === 'gateway' || code.includes('gateway')) {
     const label = providerGuidance?.label || 'provider';
     lines.push(`The ${label} gateway failed before the agent could respond.`);
     if (providerGuidance) {
@@ -266,6 +276,17 @@ export function formatAgentErrorGuidance(data = {}) {
   };
 }
 
+function formatRetryAfterLabel(value) {
+  const secs = Math.max(0, Math.ceil(Number(value) || 0));
+  if (!secs) return '';
+  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`;
+}
+
 function normalizeProviderToken(value) {
   const raw = lower(value);
   if (!raw) return '';

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

@@ -83,13 +83,28 @@ export function lowWindowStatus(rateLimit) {
 }
 
 export function rateLimitErrorMessage(payload, fallback = 'Message limit reached.') {
-    const detail = payload?.detail && typeof payload.detail === 'object' ? payload.detail : payload;
+    const detail = quotaErrorDetail(payload);
     const retryAfter = detail?.retry_after ?? detail?.rate_limit?.retry_after ?? detail?.rate_limit?.retry_after_seconds;
+    if (detail?.code === 'credit_balance_exhausted') {
+        return detail.message || 'Credit balance exhausted — add credits, upgrade your plan, or switch to BYOK in Settings.';
+    }
+    if (detail?.code === 'message_limit_reached') {
+        if (detail.message) return detail.message;
+        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 (detail?.message) return detail.message;
-    if (retryAfter != null) return `Message limit reached — try again in ${formatRetryAfter(retryAfter)}.`;
+    if (retryAfter != null) return `Message window exhausted — try again in ${formatRetryAfter(retryAfter)}, or upgrade your plan.`;
     return fallback;
 }
 
+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);

package/src/core/stream-client.mjs

@@ -11,7 +11,7 @@
 
 import { sendCallback, sendSkippedCallback, sendApprovalDecision } from './callback-client.mjs';
 import { ApprovalManager } from './approval.mjs';
-import { rateLimitErrorMessage } from './rate-limit-display.mjs';
+import { quotaErrorDetail, rateLimitErrorMessage } from './rate-limit-display.mjs';
 
 export const EVENT_TYPES = Object.freeze({
     // Phase 1 — handled
@@ -134,7 +134,7 @@ export class TarangStreamClient {
             } catch {
                 payload = { detail: { message: text } };
             }
-            const detail = payload?.detail && typeof payload.detail === 'object' ? payload.detail : payload;
+            const detail = quotaErrorDetail(payload);
             yield {
                 type: EVENT_TYPES.ERROR,
                 data: {
@@ -142,6 +142,8 @@ export class TarangStreamClient {
                     code: detail?.code || 'rate_limited',
                     retry_after: detail?.retry_after ?? detail?.rate_limit?.retry_after,
                     rate_limit: detail?.rate_limit || null,
+                    action: detail?.action || null,
+                    pricing_url: detail?.pricing_url || null,
                     fatal: true,
                 },
             };