clementine-agent 1.18.176 → 1.18.178

package/dist/agent/assistant.js

@@ -2343,6 +2343,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                             ...process.env,
                             CLEMENTINE_HOME: BASE_DIR,
                             CLEMENTINE_TEAM_AGENT: profile?.slug ?? 'clementine',
+                            ...(sessionKey ? { CLEMENTINE_SESSION_KEY: sessionKey } : {}),
                             CLEMENTINE_INTERACTION_SOURCE: sourceOverride ?? inferInteractionSource(sessionKey),
                             CLEMENTINE_TOOL_ALLOWLIST: clementineToolAllowlist,
                             CLEMENTINE_1M_CONTEXT_MODE: oneMillionModeValue,

package/dist/agent/complex-task-detector.d.ts

@@ -1,9 +1,26 @@
+/**
+ * Explicit background-intent detector.
+ *
+ * Returns a recommendation ONLY when the user explicitly asks for background
+ * / autonomous / overnight execution. We deliberately do not classify "this
+ * looks complex" anymore — chat now stays in the live SDK loop, with
+ * automatic compaction and inline subagent delegation (Agent → planner /
+ * researcher / etc.) for context isolation, just like Claude Code itself.
+ * Big work that genuinely blows past the SDK's auto-compact is caught by the
+ * gateway's overflow → retry → promote-to-background fallback, which is the
+ * *real* escape hatch instead of a regex pre-classifier.
+ *
+ * The narrow detection here is what lets a user say "go research this
+ * overnight" and have it actually queue as a durable background task.
+ */
 export interface ComplexTaskRecommendation {
-    score: number;
     reasons: string[];
     suggestedMaxMinutes: number;
     plan: string[];
-    queueImmediately: boolean;
+    /** Always true when this function returns a recommendation — the only
+     *  trigger is the user explicitly asking for background execution. Kept
+     *  on the type for back-compat with the post-overflow rescue path. */
+    queueImmediately: true;
 }
 export declare function detectComplexTaskForBackground(text: string): ComplexTaskRecommendation | null;
 //# sourceMappingURL=complex-task-detector.d.ts.map

package/dist/agent/complex-task-detector.js

@@ -1,32 +1,18 @@
+// Skill authoring is an interactive build-with-the-user flow; never auto-queue.
 const SKILL_AUTHORING_RE = /\b(create|make|build|draft|write|teach|save|update)\b.{0,40}\b(skill|SKILL\.md)\b|\bskill[- ]creator\b/i;
-const EXPLICIT_BACKGROUND_RE = /\b(background|deep mode|keep working|don't stop|dont stop|autonomous|long[- ]running|run overnight|take your time)\b/i;
-const COMPLEX_WORK_RE = /\b(audit|research|analy[sz]e|review|scrape|crawl|extract|enrich|compile|compare|verify|cross[- ]check|triage|reconcile|draft|generate|update|sync|report back|write back)\b/i;
-const BATCH_RE = /\b(all|every|each|bulk|batch|list of|contacts?|leads?|accounts?|tasks?|tickets?|records?|rows?|pages?|repos?|projects?)\b/i;
-const SIDE_EFFECT_RE = /\b(update|write|create|draft|send|post|comment|reply|upload|append|sync|mark|close|move)\b/i;
-const MULTI_STEP_RE = /\b(and then|then|after that|finally|from .* to |against .* and |across|compile .* into|check .* then)\b/i;
+// The ONLY trigger. Matches "in the background", "overnight", "keep working",
+// "don't stop", "autonomous", "long-running", "take your time", "deep mode".
+const EXPLICIT_BACKGROUND_RE = /\b(background|deep mode|keep working|don't stop|dont stop|autonomous|long[- ]running|run overnight|overnight|take your time)\b/i;
+// Light scope hints used only for the duration estimate + plan text. None of
+// these alter whether the function fires — they shape the recommendation
+// once the explicit-intent gate has already opened.
+const BATCH_RE = /\b(all|every|each|bulk|batch|list of|contacts?|leads?|accounts?|tasks?|tickets?|records?|rows?|pages?|repos?|projects?|firms?|metros?|prospects?)\b/i;
+const SIDE_EFFECT_RE = /\b(update|write|create|draft|send|post|comment|reply|upload|append|sync|mark|close|move|deploy|host|publish)\b/i;
 const SYSTEM_KEYWORDS = [
-    'asana',
-    'salesforce',
-    'google sheet',
-    'google sheets',
-    'sheet',
-    'sheets',
-    'dataforseo',
-    'hubspot',
-    'notion',
-    'github',
-    'gmail',
-    'outlook',
-    'slack',
-    'discord',
-    'website',
-    'websites',
-    'crm',
-    'spreadsheet',
-    'csv',
-    'airtable',
-    'linear',
-    'jira',
+    'asana', 'salesforce', 'google sheet', 'google sheets', 'sheet', 'sheets',
+    'dataforseo', 'hubspot', 'notion', 'github', 'gmail', 'outlook', 'slack',
+    'discord', 'website', 'websites', 'crm', 'spreadsheet', 'csv', 'netlify',
+    'vercel', 'airtable', 'linear', 'jira',
 ];
 function countSystemMentions(text) {
     const lower = text.toLowerCase();
@@ -37,10 +23,10 @@ function countSystemMentions(text) {
     }
     return count;
 }
-function estimatedMinutes(score, systemCount) {
-    if (score >= 8 || systemCount >= 4)
+function estimatedMinutes(systemCount, textLength) {
+    if (systemCount >= 4 || textLength > 800)
         return 90;
-    if (score >= 6 || systemCount >= 3)
+    if (systemCount >= 2 || textLength > 400)
         return 60;
     return 30;
 }
@@ -72,47 +58,17 @@ export function detectComplexTaskForBackground(text) {
         return null;
     if (SKILL_AUTHORING_RE.test(trimmed))
         return null;
-    const systemCount = countSystemMentions(trimmed);
-    const reasons = [];
-    let score = 0;
-    if (EXPLICIT_BACKGROUND_RE.test(trimmed)) {
-        score += 4;
-        reasons.push('explicit background/deep-work wording');
-    }
-    if (COMPLEX_WORK_RE.test(trimmed)) {
-        score += 2;
-        reasons.push('multi-step work verb');
-    }
-    if (BATCH_RE.test(trimmed)) {
-        score += 2;
-        reasons.push('batch or many-record scope');
-    }
-    if (SIDE_EFFECT_RE.test(trimmed)) {
-        score += 1;
-        reasons.push('write/draft/update side effects');
-    }
-    if (MULTI_STEP_RE.test(trimmed)) {
-        score += 1;
-        reasons.push('multi-step sequencing');
-    }
-    if (systemCount >= 2) {
-        score += Math.min(4, systemCount);
-        reasons.push(`${systemCount} named systems or data surfaces`);
-    }
-    if (trimmed.length > 450) {
-        score += 1;
-        reasons.push('long detailed request');
-    }
-    const queueImmediately = EXPLICIT_BACKGROUND_RE.test(trimmed) && score >= 5;
-    const shouldOffer = queueImmediately || score >= 5 || (systemCount >= 2 && (BATCH_RE.test(trimmed) || SIDE_EFFECT_RE.test(trimmed)));
-    if (!shouldOffer)
+    if (!EXPLICIT_BACKGROUND_RE.test(trimmed))
         return null;
+    const systemCount = countSystemMentions(trimmed);
+    const reasons = ['explicit background/deep-work wording'];
+    if (systemCount >= 2)
+        reasons.push(`${systemCount} named systems`);
     return {
-        score,
         reasons,
-        suggestedMaxMinutes: estimatedMinutes(score, systemCount),
+        suggestedMaxMinutes: estimatedMinutes(systemCount, trimmed.length),
         plan: buildPlan(trimmed, systemCount),
-        queueImmediately,
+        queueImmediately: true,
     };
 }
 //# sourceMappingURL=complex-task-detector.js.map

package/dist/agent/run-agent-cron.js

@@ -26,6 +26,31 @@ const CRON_PROGRESS_PENDING_MAX_ITEMS = 20;
 const CRON_PROGRESS_NOTES_MAX_CHARS = 2000;
 const logger = pino({ name: 'clementine.run-agent-cron' });
 const CRON_CONTEXT_ITEM_MAX = 80;
+const CLEMENTINE_TOOLS_SERVER = `${(process.env.ASSISTANT_NAME ?? 'Clementine').toLowerCase()}-tools`;
+const BACKGROUND_TASK_WORKER_NAME = 'background-task-worker';
+const DEFAULT_BACKGROUND_WORKER_TOOLS = [
+    'Agent',
+    'Read',
+    'Write',
+    'Edit',
+    'Glob',
+    'Grep',
+    'Bash',
+    'WebSearch',
+    'WebFetch',
+    'TodoWrite',
+];
+const BACKGROUND_TASK_WORKER_PROMPT = [
+    'You are Clementine\'s background task worker for long-running user requests.',
+    '',
+    'Run the assigned task to completion using the available tools. Keep raw API responses, scraped pages, and large file contents out of the final answer; extract the fields you need and continue.',
+    '',
+    'Use TodoWrite for multi-step state. Process batch work in bounded chunks, checkpoint meaningful progress in durable artifacts when useful, and avoid repeating the same expensive read or tool call.',
+    '',
+    'If credentials, missing scope, human approval, or an irreversible action blocks completion, stop with one concise blocker/question and the exact next action needed. Do not keep retrying blindly.',
+    '',
+    'Return only the final user-facing result: links or changed locations, counts, skipped/error records, and the next recommended action.',
+].join('\n');
 /** Total number of skill blocks injected into a cron prompt — pinned + auto. */
 const MAX_INJECTED_SKILLS = 4;
 /**
@@ -172,6 +197,27 @@ function capContextBlock(s, max) {
         return '';
     return s.length <= max ? s : s.slice(0, max - 3) + '...';
 }
+function backgroundWorkerTools(effectiveAllowedTools, mcpServersApplied) {
+    if (effectiveAllowedTools)
+        return [...new Set(['Agent', ...effectiveAllowedTools])];
+    const mcpWildcards = [CLEMENTINE_TOOLS_SERVER, ...mcpServersApplied]
+        .filter(Boolean)
+        .map((server) => `mcp__${server}__*`);
+    return [...new Set([...DEFAULT_BACKGROUND_WORKER_TOOLS, ...mcpWildcards])];
+}
+function buildBackgroundTaskWorker(tools, model, maxTurns) {
+    return {
+        description: [
+            'Use for background tasks queued from chat, especially multi-step work, batch data collection, project builds, deployments, and external-system writebacks.',
+            'This agent owns the heavy tool loop so the parent task context stays small.',
+        ].join(' '),
+        prompt: BACKGROUND_TASK_WORKER_PROMPT,
+        tools,
+        ...(model ? { model } : { model: 'sonnet' }),
+        effort: 'medium',
+        maxTurns: typeof maxTurns === 'number' && maxTurns > 0 ? maxTurns : 40,
+    };
+}
 /**
  * Build the previous-progress block from the cron progress JSON file.
  * Lets the agent continue where the prior run left off without re-doing
@@ -749,10 +795,18 @@ export async function runAgentCron(opts) {
         skillsMissing: plan.skillsMissing.length,
         trickAllowedTools: effectiveAllowedTools?.length,
         trickAllowedMcp: opts.allowedMcpServers?.length,
+        forcedBackgroundWorker: opts.jobName.startsWith('bg:'),
         widenedFromSkills: plan.widenedFromSkills,
         ...(promptOversized ? { warning: 'prompt > 50KB; risk of "Prompt is too long" failure' } : {}),
     }, 'runAgentCron: dispatching to runAgent');
     const startedAt = Date.now();
+    const forceBackgroundWorker = opts.jobName.startsWith('bg:');
+    const workerTools = forceBackgroundWorker
+        ? backgroundWorkerTools(effectiveAllowedTools, mcpServersApplied)
+        : [];
+    const workerDef = forceBackgroundWorker
+        ? buildBackgroundTaskWorker(workerTools, opts.model, opts.maxTurns)
+        : null;
     const result = await runAgent(builtPrompt, {
         sessionKey: `cron:${opts.jobName}`,
         source: 'cron',
@@ -762,9 +816,16 @@ export async function runAgentCron(opts) {
         model: opts.model,
         effort,
         ...(maxBudget !== undefined ? { maxBudgetUsd: maxBudget } : {}),
-        maxTurns: opts.maxTurns,
+        maxTurns: forceBackgroundWorker ? 5 : opts.maxTurns,
         abortSignal: opts.abortSignal,
-        ...(effectiveAllowedTools ? { allowedTools: effectiveAllowedTools } : {}),
+        ...(forceBackgroundWorker
+            ? {
+                allowedTools: ['Agent'],
+                permissionTools: workerTools,
+                forceSubagent: BACKGROUND_TASK_WORKER_NAME,
+                agents: { [BACKGROUND_TASK_WORKER_NAME]: workerDef },
+            }
+            : (effectiveAllowedTools ? { allowedTools: effectiveAllowedTools } : {})),
         extraMcpServers: mcpServerMap,
         // 1.18.121 — pipe the merged addDirs+pinned-skill folders to the SDK
         // so a skill's bundled scripts/templates are reachable via Bash/Read

package/dist/agent/run-agent.d.ts

@@ -16,6 +16,7 @@
  *    long-task preflight, NO mode=unleashed wrapper.
  */
 import { type AgentDefinition } from '@anthropic-ai/claude-agent-sdk';
+import type { TerminalReason } from '../types.js';
 /** Read the latest MCP status snapshot. Safe to call from any module. */
 export declare function getLatestMcpStatusSnapshot(): {
     servers: Array<{
@@ -26,6 +27,10 @@ export declare function getLatestMcpStatusSnapshot(): {
 };
 /** Write a fresh snapshot. Called from system/init handlers. */
 export declare function recordMcpStatusFromSystemInit(rawMcpServers: unknown): void;
+/** True when the SDK emits an internal context-pressure diagnostic as an
+ * assistant text block. These are operational warnings, not useful user
+ * output, and they can appear while the run is still recovering/continuing. */
+export declare function isSdkContextDiagnosticText(text: string): boolean;
 /** Drop one server from the cache so the next query repopulates it. */
 export declare function invalidateMcpStatusEntry(name: string): {
     cleared: boolean;
@@ -133,6 +138,8 @@ export interface RunAgentResult {
     sessionId: string;
     /** Final stop reason from the SDK (success, error_max_turns, error_max_budget_usd, etc). */
     subtype: string;
+    /** Precise SDK loop terminal reason, when available. */
+    terminalReason?: TerminalReason;
     /** Token usage breakdown (input, output, cache). */
     usage?: {
         input_tokens?: number;

package/dist/agent/run-agent.js

@@ -75,6 +75,16 @@ function truncateForLog(value, maxBytes) {
         return { _unstringifiable: true };
     }
 }
+/** True when the SDK emits an internal context-pressure diagnostic as an
+ * assistant text block. These are operational warnings, not useful user
+ * output, and they can appear while the run is still recovering/continuing. */
+export function isSdkContextDiagnosticText(text) {
+    const t = text.trim();
+    if (!t)
+        return false;
+    return /^Autocompact is thrashing:\s*the context refilled to the limit/i.test(t)
+        || /^rapid_refill_breaker\b/i.test(t);
+}
 /** Drop one server from the cache so the next query repopulates it. */
 export function invalidateMcpStatusEntry(name) {
     const before = _lastMcpStatusSnapshot.servers.length;
@@ -287,6 +297,7 @@ export async function runAgent(prompt, opts) {
                 ...subprocessEnv,
                 CLEMENTINE_HOME: BASE_DIR,
                 ...(opts.profile?.slug ? { CLEMENTINE_TEAM_AGENT: opts.profile.slug } : {}),
+                CLEMENTINE_SESSION_KEY: opts.sessionKey,
                 CLEMENTINE_INTERACTION_SOURCE: interactionSourceForSession(opts.sessionKey, source),
                 CLEMENTINE_TOOL_ALLOWLIST: clementineToolAllowlist,
             },
@@ -482,6 +493,7 @@ export async function runAgent(prompt, opts) {
     let totalCostUsd = 0;
     let numTurns = 0;
     let subtype = 'unknown';
+    let terminalReason;
     let usage;
     const stream = query({ prompt: effectivePrompt, options: sdkOptions });
     try {
@@ -537,6 +549,15 @@ export async function runAgent(prompt, opts) {
                 const blocks = (am.message?.content ?? []);
                 for (const block of blocks) {
                     if (block.type === 'text' && typeof block.text === 'string') {
+                        if (isSdkContextDiagnosticText(block.text)) {
+                            logger.warn({
+                                sessionKey: opts.sessionKey,
+                                source,
+                                subtype,
+                                preview: block.text.slice(0, 240),
+                            }, 'runAgent: suppressed SDK context diagnostic text');
+                            continue;
+                        }
                         finalText += block.text;
                         // PRD Phase 4a / 1.18.85: llm_text Event. Truncate at 8KB to keep
                         // the JSONL light — full text is reachable via the SDK transcript.
@@ -610,6 +631,7 @@ export async function runAgent(prompt, opts) {
                 const result = message;
                 sessionId = sessionId || (result.session_id ?? '');
                 subtype = result.subtype ?? 'unknown';
+                terminalReason = result.terminal_reason;
                 numTurns = result.num_turns ?? numTurns;
                 totalCostUsd = result.total_cost_usd ?? 0;
                 const u = result.usage;
@@ -628,7 +650,7 @@ export async function runAgent(prompt, opts) {
                     ts: new Date().toISOString(),
                     sessionId,
                     costUsd: totalCostUsd,
-                    stopReason: subtype,
+                    stopReason: terminalReason && terminalReason !== 'completed' ? `${subtype}:${terminalReason}` : subtype,
                 });
                 // PRD Phase 4d / 1.18.101: unregister from the hook-session registry.
                 // Late-arriving hook events for this sessionId silently drop after this.
@@ -757,6 +779,7 @@ export async function runAgent(prompt, opts) {
         numTurns,
         sessionId,
         subtype,
+        ...(terminalReason ? { terminalReason } : {}),
         ...(usage ? { usage } : {}),
         runId,
         permissionMode: toolPolicy.permissionMode,

package/dist/gateway/router.d.ts

@@ -13,6 +13,16 @@ import type { NotificationDispatcher } from './notifications.js';
 import { type ProactiveNotificationInput } from './notification-context.js';
 import { type ToolsetName } from '../agent/toolsets.js';
 export { isLiveUnleashedStatus } from './unleashed-status.js';
+export declare function buildContextOverflowRetryPrompt(opts: {
+    chatPrompt: string;
+    turnContextPrefix?: string;
+    project?: ProjectMeta | null;
+}): string;
+export declare function runAgentResultIndicatesContextOverflow(result: {
+    subtype?: string;
+    terminalReason?: string;
+    text?: string;
+}): boolean;
 export type ChatErrorKind = 'rate_limit' | 'one_million_context' | 'context_overflow' | 'auth' | 'billing' | 'transient' | 'unknown';
 export declare function classifyChatError(err: unknown): ChatErrorKind;
 /** Detect auth-like errors in response text that the SDK returned as "successful" results. */
@@ -59,13 +69,14 @@ export declare class Gateway {
     private extractBackgroundTaskId;
     private makeBackgroundOfferId;
     private backgroundAgentForSession;
+    private buildBackgroundTaskPrompt;
     private pruneExpiredBackgroundOffers;
     private latestBackgroundOfferForSession;
     private getBackgroundOfferForSession;
     private createBackgroundOffer;
     private queueBackgroundOffer;
     private formatBackgroundQueuedResponse;
-    private formatBackgroundOfferResponse;
+    private queueBackgroundTaskAfterContextOverflow;
     acceptBackgroundOffer(sessionKey: string, id: string): {
         ok: boolean;
         response: string;

package/dist/gateway/router.js

@@ -49,6 +49,8 @@ const CHAT_TIMEOUT_MS = 10 * 60 * 1000;
  *  Safety net so no session runs forever, even if active.
  *  Primary guardrail is cost budget (maxBudgetUsd), not this timer. */
 const CHAT_MAX_WALL_MS = 30 * 60 * 1000;
+const CHAT_CONTEXT_RETRY_CONTEXT_MAX_CHARS = 6_000;
+const CHAT_CONTEXT_RETRY_SYSTEM_MAX_CHARS = 16_000;
 const BACKGROUND_TASK_ID_RE = /\bbg-[a-z0-9]+-[a-f0-9]{6}\b/i;
 function collectRunToolNames(runId) {
     if (!runId)
@@ -74,6 +76,37 @@ function compactToolNames(names) {
     }
     return out;
 }
+function trimContextRecoveryText(text, maxChars) {
+    if (!text || text.length <= maxChars)
+        return text;
+    return `${text.slice(0, maxChars - 80).trimEnd()}\n\n[context recovery: trimmed oversized carry-over context]`;
+}
+export function buildContextOverflowRetryPrompt(opts) {
+    const parts = [
+        '[Context recovery: the previous SDK session was too large, so this is a fresh session. Continue with the current user request. Do not ask the user to resend it.]',
+    ];
+    if (opts.project?.path) {
+        const description = opts.project.description ? ` (${opts.project.description})` : '';
+        parts.push(`[Active project: ${opts.project.path}${description}]`);
+    }
+    const compactContext = trimContextRecoveryText((opts.turnContextPrefix ?? '').trim(), CHAT_CONTEXT_RETRY_CONTEXT_MAX_CHARS);
+    if (compactContext) {
+        parts.push(compactContext);
+    }
+    parts.push(opts.chatPrompt);
+    return parts.filter(Boolean).join('\n\n');
+}
+export function runAgentResultIndicatesContextOverflow(result) {
+    const terminalReason = (result.terminalReason ?? '').trim();
+    if (terminalReason && classifyChatError(terminalReason) === 'context_overflow')
+        return true;
+    const subtype = (result.subtype ?? '').trim();
+    if (subtype && subtype !== 'success' && classifyChatError(subtype) === 'context_overflow')
+        return true;
+    const text = (result.text ?? '').trim();
+    return /^Autocompact is thrashing:\s*the context refilled to the limit/i.test(text)
+        || /^rapid_refill_breaker\b/i.test(text);
+}
 export function classifyChatError(err) {
     const msg = String(err);
     if (isCreditBalanceError(msg))
@@ -82,7 +115,7 @@ export function classifyChatError(err) {
         return 'rate_limit';
     if (looksLikeClaudeOneMillionContextError(msg))
         return 'one_million_context';
-    if (/context.?length|token.?limit|maximum.?context|prompt.?too.?long|rapid_refill_breaker|autocompact|context.?refilled/i.test(msg))
+    if (/context.?length|token.?limit|maximum.?context|prompt(?:\s+is)?.?too.?long|input.?too.?long|rapid_refill_breaker|autocompact|context.?refilled/i.test(msg))
         return 'context_overflow';
     if (/\b401\b|\b403\b|auth|forbidden|invalid.?api.?key|permission|does not have access|please run \/login/i.test(msg))
         return 'auth';
@@ -277,6 +310,18 @@ export class Gateway {
     backgroundAgentForSession(sessionKey) {
         return this._agentSlugFromSessionKey(sessionKey) ?? this.getSessionProfile(sessionKey) ?? 'clementine';
     }
+    buildBackgroundTaskPrompt(sessionKey, prompt) {
+        const sess = this.sessions.get(sessionKey);
+        const parts = [
+            '[Background task from chat: run this in a fresh task execution. Do not rely on the live chat transcript being resumed; use the self-contained request below.]',
+        ];
+        if (sess?.project?.path) {
+            const description = sess.project.description ? ` (${sess.project.description})` : '';
+            parts.push(`[Active project: ${sess.project.path}${description}]`);
+        }
+        parts.push(prompt.trim());
+        return parts.filter(Boolean).join('\n\n');
+    }
     pruneExpiredBackgroundOffers() {
         const now = Date.now();
         for (const [id, offer] of this.pendingBackgroundOffers) {
@@ -305,6 +350,7 @@ export class Gateway {
             sessionKey,
             fromAgent: this.backgroundAgentForSession(sessionKey),
             prompt,
+            taskPrompt: this.buildBackgroundTaskPrompt(sessionKey, prompt),
             recommendation,
             createdAt: Date.now(),
             expiresAt: Date.now() + 30 * 60_000,
@@ -315,7 +361,7 @@ export class Gateway {
     queueBackgroundOffer(offer) {
         const task = createBackgroundTask({
             fromAgent: offer.fromAgent,
-            prompt: offer.prompt,
+            prompt: offer.taskPrompt,
             maxMinutes: offer.recommendation.suggestedMaxMinutes,
             sessionKey: offer.sessionKey,
         });
@@ -333,25 +379,37 @@ export class Gateway {
         return [
             `Queued background task **${task.id}**.`,
             '',
-            `It will run as **${task.fromAgent}** with a ${task.maxMinutes} minute cap.`,
+            `It will run as **${task.fromAgent}** in a fresh task session with a ${task.maxMinutes} minute cap.`,
             `Use \`status ${task.id}\` or check the dashboard Background Tasks panel for progress.`,
         ].join('\n');
     }
-    formatBackgroundOfferResponse(offer) {
-        const lines = [
-            'This looks like long-running, multi-tool work. I recommend running it in the background so chat does not go stale.',
-            '',
-            '**Plan**',
-            ...offer.recommendation.plan.map((step, idx) => `${idx + 1}. ${step}`),
-            '',
-            `**Why background:** ${offer.recommendation.reasons.join('; ')}.`,
-            `**Estimated cap:** ${offer.recommendation.suggestedMaxMinutes} minutes.`,
-            `**Background offer:** ${offer.id}`,
-            '',
-            `Reply \`run background ${offer.id}\` to queue it, \`run inline ${offer.id}\` to run it in this chat, or \`save skill ${offer.id}\` to make it reusable first.`,
-        ];
-        return lines.join('\n');
+    queueBackgroundTaskAfterContextOverflow(sessionKey, prompt) {
+        const recommendation = detectComplexTaskForBackground(prompt);
+        const task = createBackgroundTask({
+            fromAgent: this.backgroundAgentForSession(sessionKey),
+            prompt,
+            maxMinutes: recommendation?.suggestedMaxMinutes ?? 60,
+            sessionKey,
+        });
+        logger.warn({
+            taskId: task.id,
+            sessionKey,
+            fromAgent: task.fromAgent,
+            maxMinutes: task.maxMinutes,
+        }, 'Queued background task after repeated chat context overflow');
+        return {
+            task,
+            response: [
+                `The live chat context hit the limit, so I moved this into background task **${task.id}** and kept your request attached.`,
+                '',
+                `It will run as **${task.fromAgent}** in a fresh task session with a ${task.maxMinutes} minute cap.`,
+                `Use \`status ${task.id}\` or check the dashboard Background Tasks panel for progress.`,
+            ].join('\n'),
+        };
     }
+    // Offer-message formatter was removed in the Saturday-feel restoration —
+    // the chat path no longer asks "want me to run this in the background?".
+    // Auto-queue on explicit user intent is silent; everything else just runs.
     acceptBackgroundOffer(sessionKey, id) {
         const offer = this.getBackgroundOfferForSession(sessionKey, id);
         if (!offer) {
@@ -1896,45 +1954,38 @@ export class Gateway {
                     || text.startsWith('[Approval:')
                     || text.startsWith('[Reaction:')
                     || text.startsWith('[System:');
+                // ── Explicit background-intent shortcut ────────────────────────
+                // Chat normally runs in-place — the SDK auto-compacts and the model
+                // can spawn `planner` / `researcher` subagents for context-heavy
+                // sub-steps, just like Claude Code. We only auto-queue a durable
+                // background task when the user *explicitly* says "in the
+                // background", "overnight", "keep working", "don't stop", etc. The
+                // post-overflow rescue path below still catches the rare case
+                // where chat actually drowns despite all that.
                 if (!skipBackgroundOffer && !isBuilderSession && !isInternalMsg && this.isTrustedPersonalSession(sessionKey)) {
                     const recommendation = detectComplexTaskForBackground(text);
                     if (recommendation) {
                         const offer = this.createBackgroundOffer(sessionKey, text, recommendation);
-                        if (recommendation.queueImmediately) {
-                            const task = this.queueBackgroundOffer(offer);
-                            const queued = this.formatBackgroundQueuedResponse(task);
-                            if (ledgerRunMetadata) {
-                                ledgerRunMetadata.executionMode = 'background_queued';
-                                ledgerRunMetadata.backgroundTaskId = task.id;
-                            }
-                            if (onText) {
-                                try {
-                                    await onText(queued);
-                                }
-                                catch { /* channel streaming is best-effort */ }
-                            }
-                            this.mirrorChatExchange(sessionKey, originalText, queued, { model: 'chat-control' });
-                            return queued;
-                        }
-                        const offerText = this.formatBackgroundOfferResponse(offer);
+                        const task = this.queueBackgroundOffer(offer);
+                        const queued = this.formatBackgroundQueuedResponse(task);
                         if (ledgerRunMetadata) {
-                            ledgerRunMetadata.executionMode = 'background_offer';
+                            ledgerRunMetadata.executionMode = 'background_queued';
+                            ledgerRunMetadata.backgroundTaskId = task.id;
                         }
                         logger.info({
                             sessionKey,
-                            offerId: offer.id,
-                            score: recommendation.score,
+                            taskId: task.id,
                             reasons: recommendation.reasons,
                             maxMinutes: recommendation.suggestedMaxMinutes,
-                        }, 'Offering background execution for complex chat request');
+                        }, 'Auto-queued background task on explicit user intent');
                         if (onText) {
                             try {
-                                await onText(offerText);
+                                await onText(queued);
                             }
                             catch { /* channel streaming is best-effort */ }
                         }
-                        this.mirrorChatExchange(sessionKey, originalText, offerText, { model: 'chat-control' });
-                        return offerText;
+                        this.mirrorChatExchange(sessionKey, originalText, queued, { model: 'chat-control' });
+                        return queued;
                     }
                 }
                 if (!isInternalMsg && !sess?.profile && !text.startsWith('!') && !isStructuredWorkflowMsg && onProgress) {
@@ -2058,6 +2109,7 @@ export class Gateway {
                     // Interrupt flag was set but no useful partial text — just clear it.
                     delete sessState.pendingInterrupt;
                 }
+                let contextOverflowRecoveryPrompt = '';
                 try {
                     // ── Canonical SDK chat path (Phase 5) ────────────────────────
                     // runAgent() owns chat. No legacy fallback — errors propagate
@@ -2117,6 +2169,7 @@ export class Gateway {
                     const chatSystemAppend = resolvedSkills && resolvedSkills.promptBlock
                         ? (baseSystemAppend ? `${baseSystemAppend}\n\n${resolvedSkills.promptBlock}` : resolvedSkills.promptBlock)
                         : baseSystemAppend;
+                    const retrySystemAppend = trimContextRecoveryText(chatSystemAppend, CHAT_CONTEXT_RETRY_SYSTEM_MAX_CHARS);
                     // Per-turn context (recall + persistent learnings + silent
                     // blocks + security/toolset directives) — real chat only.
                     // Builder doesn't need recall of unrelated transcripts.
@@ -2156,7 +2209,7 @@ export class Gateway {
                         skillMatchNames: resolvedSkills?.matches.map(m => m.name) ?? [],
                         skillHintedMcpServers: resolvedSkills?.hintedMcpServers ?? [],
                     }, 'Routing chat through runAgent');
-                    const runAgentResult = await runAgent(finalPrompt, {
+                    const buildRunAgentChatOptions = (opts) => ({
                         sessionKey: effectiveSessionKey,
                         source: 'chat',
                         profile: resolvedProfile,
@@ -2166,8 +2219,8 @@ export class Gateway {
                         ...(maxTurns ? { maxTurns } : {}),
                         ...(chatBudget !== undefined ? { maxBudgetUsd: chatBudget } : {}),
                         ...(builderAllowedTools ? { allowedTools: builderAllowedTools } : {}),
-                        ...(chatSystemAppend ? { systemPromptAppend: chatSystemAppend } : {}),
-                        ...(priorSdkSessionId ? { resumeSessionId: priorSdkSessionId } : {}),
+                        ...(opts.systemPromptAppend ? { systemPromptAppend: opts.systemPromptAppend } : {}),
+                        ...(opts.resumeSessionId ? { resumeSessionId: opts.resumeSessionId } : {}),
                         ...(chatMcp ? { extraMcpServers: chatMcp.servers } : {}),
                         onText: wrappedOnText,
                         onToolActivity: ({ tool, input }) => {
@@ -2178,6 +2231,74 @@ export class Gateway {
                         },
                         abortSignal: chatAc.signal,
                     });
+                    let didContextOverflowRetry = false;
+                    const contextOverflowAfterRetryError = () => new Error('rapid_refill_breaker after context overflow retry');
+                    const retryAfterContextOverflow = async () => {
+                        if (didContextOverflowRetry)
+                            throw contextOverflowAfterRetryError();
+                        didContextOverflowRetry = true;
+                        const retryPrompt = buildContextOverflowRetryPrompt({
+                            chatPrompt,
+                            turnContextPrefix,
+                            project: sess?.project ?? null,
+                        });
+                        contextOverflowRecoveryPrompt = retryPrompt;
+                        logger.info({
+                            sessionKey: effectiveSessionKey,
+                            hadResume: !!priorSdkSessionId,
+                            promptChars: finalPrompt.length,
+                            retryPromptChars: retryPrompt.length,
+                            systemAppendChars: chatSystemAppend.length,
+                            retrySystemAppendChars: retrySystemAppend.length,
+                        }, 'Context overflow — retrying current message in fresh SDK session');
+                        if (onProgress) {
+                            await onProgress('refreshing conversation context...').catch(() => { });
+                        }
+                        this.assistant.clearSession(effectiveSessionKey);
+                        return runAgent(retryPrompt, buildRunAgentChatOptions({
+                            ...(retrySystemAppend ? { systemPromptAppend: retrySystemAppend } : {}),
+                        }));
+                    };
+                    let runAgentResult;
+                    try {
+                        runAgentResult = await runAgent(finalPrompt, buildRunAgentChatOptions({
+                            ...(priorSdkSessionId ? { resumeSessionId: priorSdkSessionId } : {}),
+                            ...(chatSystemAppend ? { systemPromptAppend: chatSystemAppend } : {}),
+                        }));
+                    }
+                    catch (err) {
+                        if (chatAc.signal.aborted || classifyChatError(err) !== 'context_overflow') {
+                            throw err;
+                        }
+                        runAgentResult = await retryAfterContextOverflow();
+                    }
+                    if (!chatAc.signal.aborted && runAgentResultIndicatesContextOverflow(runAgentResult)) {
+                        if (didContextOverflowRetry) {
+                            logger.info({
+                                sessionKey: effectiveSessionKey,
+                                subtype: runAgentResult.subtype,
+                                terminalReason: runAgentResult.terminalReason,
+                                textPreview: runAgentResult.text?.slice(0, 240),
+                            }, 'Context overflow result after retry — queueing background task');
+                            throw contextOverflowAfterRetryError();
+                        }
+                        logger.info({
+                            sessionKey: effectiveSessionKey,
+                            subtype: runAgentResult.subtype,
+                            terminalReason: runAgentResult.terminalReason,
+                            textPreview: runAgentResult.text?.slice(0, 240),
+                        }, 'Context overflow result — retrying current message in fresh SDK session');
+                        runAgentResult = await retryAfterContextOverflow();
+                        if (runAgentResultIndicatesContextOverflow(runAgentResult)) {
+                            logger.info({
+                                sessionKey: effectiveSessionKey,
+                                subtype: runAgentResult.subtype,
+                                terminalReason: runAgentResult.terminalReason,
+                                textPreview: runAgentResult.text?.slice(0, 240),
+                            }, 'Context overflow result after retry — queueing background task');
+                            throw contextOverflowAfterRetryError();
+                        }
+                    }
                     if (ledgerRunMetadata) {
                         ledgerRunMetadata.runId = runAgentResult.runId;
                         ledgerRunMetadata.executionMode = ledgerRunMetadata.executionMode ?? 'inline';
@@ -2254,9 +2375,18 @@ export class Gateway {
                             this.clearSession(effectiveSessionKey);
                             return oneMillionContextRecoveryMessage();
                         case 'context_overflow':
-                            logger.info({ sessionKey }, 'Context overflow — rotating session');
+                            logger.info({ sessionKey }, 'Context overflow after retry — queueing background task');
                             this.assistant.clearSession(effectiveSessionKey);
-                            return "That conversation got too long — I've started a fresh session. Please resend your message.";
+                            {
+                                const promptForBackground = contextOverflowRecoveryPrompt || chatPrompt;
+                                const { response, task } = this.queueBackgroundTaskAfterContextOverflow(sessionKey, promptForBackground);
+                                if (ledgerRunMetadata) {
+                                    ledgerRunMetadata.executionMode = 'background_queued';
+                                    ledgerRunMetadata.backgroundTaskId = task.id;
+                                }
+                                this.mirrorChatExchange(sessionKey, originalText, response, { model: 'chat-control' });
+                                return response;
+                            }
                         case 'auth':
                             this.recordAuthFailure();
                             return "I'm temporarily offline due to an authentication issue. The owner needs to re-authenticate — I'll recover automatically once it's resolved.";

package/dist/integrations/composio/client.d.ts

@@ -32,6 +32,12 @@ export declare function isComposioEnabled(): boolean;
  * the dashboard PUT /api/settings/COMPOSIO_API_KEY handler.
  */
 export declare function resetComposioClient(): void;
+/**
+ * Drop the per-process connection-list cache so the next call to
+ * `listConnectedToolkits()` hits Composio fresh. Used after authorize /
+ * disconnect / rename so the dashboard and agent see the change immediately.
+ */
+export declare function clearConnectedToolkitsCache(): void;
 export declare function getPreferredUserId(): Promise<string>;
 export declare function clementineUserId(): string;
 export declare function displayNameFor(slug: string): string;

package/dist/integrations/composio/client.js

@@ -83,6 +83,30 @@ export function resetComposioClient() {
     identityCache.clear();
     catalogCache = null;
     detectedPreferredUserId = null;
+    connectionsCache = null;
+    void busComposioMcpCache();
+}
+/**
+ * Drop the per-process connection-list cache so the next call to
+ * `listConnectedToolkits()` hits Composio fresh. Used after authorize /
+ * disconnect / rename so the dashboard and agent see the change immediately.
+ */
+export function clearConnectedToolkitsCache() {
+    connectionsCache = null;
+}
+/**
+ * Fire-and-forget MCP-server cache bust. Imported lazily to avoid the
+ * client → mcp-bridge → client cycle that an `import { ... }` at the top
+ * would create.
+ */
+async function busComposioMcpCache() {
+    try {
+        const mod = await import('./mcp-bridge.js');
+        mod.clearComposioMcpCache?.();
+    }
+    catch {
+        /* mcp-bridge optional at boot; safe to ignore */
+    }
 }
 // Public: same logic as the internal detector, exposed for the MCP bridge so
 // agent sessions land on the right user_id.
@@ -310,10 +334,22 @@ async function getIdentityFor(composio, id, slug, seed) {
     identityCache.set(id, { at: Date.now(), identity });
     return identity;
 }
+// Short-lived per-process cache + stale-while-revalidate. Composio API hiccups
+// between turns used to make tools "vanish" from the chat; with this, a single
+// failed list call falls back to the prior good snapshot. TTL is short enough
+// (60s) that legit reconnects / disconnects show up quickly, and the dashboard
+// auth/disconnect handlers explicitly bust the cache via
+// `clearConnectedToolkitsCache()` for instant reflection.
+let connectionsCache = null;
+const CONNECTIONS_TTL_MS = 60_000;
 export async function listConnectedToolkits() {
     const composio = getComposio();
     if (!composio)
         return [];
+    const now = Date.now();
+    if (connectionsCache && now - connectionsCache.at < CONNECTIONS_TTL_MS) {
+        return connectionsCache.data;
+    }
     try {
         // No userIds filter: a Composio API key is account-scoped, and a personal
         // agent should see every connection on the account regardless of which
@@ -337,10 +373,15 @@ export async function listConnectedToolkits() {
                 createdAt: it.createdAt,
             };
         }));
+        connectionsCache = { at: now, data: enriched };
         return enriched;
     }
     catch (err) {
-        logger.error({ err }, 'listConnectedToolkits failed');
+        if (connectionsCache) {
+            logger.warn({ err, staleAgeMs: now - connectionsCache.at, items: connectionsCache.data.length }, 'listConnectedToolkits failed — returning stale cache');
+            return connectionsCache.data;
+        }
+        logger.error({ err }, 'listConnectedToolkits failed (no cache to fall back to)');
         return [];
     }
 }
@@ -481,6 +522,8 @@ _opts) {
         // others created in parallel via Composio's web UI) get picked up
         // immediately, even within the 60s TTL window.
         detectedPreferredUserId = null;
+        connectionsCache = null;
+        void busComposioMcpCache();
         return { redirectUrl: conn.redirectUrl ?? null, connectionId: conn.id };
     }
     catch (err) {
@@ -509,6 +552,8 @@ export async function disconnectToolkit(connectionId) {
         throw new Error('COMPOSIO_API_KEY not set');
     await composio.connectedAccounts.delete(connectionId);
     identityCache.delete(connectionId);
+    connectionsCache = null;
+    void busComposioMcpCache();
 }
 export async function renameConnection(connectionId, alias) {
     const composio = getComposio();
@@ -520,5 +565,6 @@ export async function renameConnection(connectionId, alias) {
     // hatch and the alternative (bypassing the wrapper entirely) loses retry
     // and auth handling.
     await composio.client.connectedAccounts.patch(connectionId, { alias });
+    connectionsCache = null;
 }
 //# sourceMappingURL=client.js.map

package/dist/integrations/composio/mcp-bridge.d.ts

@@ -16,6 +16,7 @@
  * always works — Composio is purely additive.
  */
 import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+export declare function clearComposioMcpCache(slug?: string): void;
 /**
  * Build SDK MCP server configs for the given toolkit slugs (or all active
  * connected toolkits when omitted). Each toolkit becomes one MCP server.

package/dist/integrations/composio/mcp-bridge.js

@@ -19,6 +19,15 @@ import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
 import pino from 'pino';
 import { getComposio, getPreferredUserId, listConnectedToolkits, } from './client.js';
 const logger = pino({ name: 'clementine.composio.mcp' });
+const serverCache = new Map();
+const SERVER_CACHE_TTL_MS = 5 * 60_000;
+export function clearComposioMcpCache(slug) {
+    if (slug) {
+        serverCache.delete(slug);
+        return;
+    }
+    serverCache.clear();
+}
 /**
  * Build SDK MCP server configs for the given toolkit slugs (or all active
  * connected toolkits when omitted). Each toolkit becomes one MCP server.
@@ -70,6 +79,11 @@ export async function listComposioToolkitTools(slugs) {
     return out;
 }
 async function buildOne(composio, slug, _connected) {
+    const now = Date.now();
+    const cached = serverCache.get(slug);
+    if (cached && now - cached.at < SERVER_CACHE_TTL_MS) {
+        return cached.server;
+    }
     // composio.tools.get() returns the FLAT toolkit tools (OUTLOOK_LIST_MESSAGES,
     // GMAIL_SEND_EMAIL, …) — exactly the namespacing the agent expects as
     // mcp__outlook__OUTLOOK_LIST_MESSAGES. The alternative, composio.create()
@@ -83,11 +97,13 @@ async function buildOne(composio, slug, _connected) {
     // alphabetically come after OUTLOOK_LIST_CALENDAR_GROUP_*. GitHub has
     // 800+. Set 1000 — comfortable headroom for any single toolkit.
     const tools = await fetchToolkitTools(composio, slug);
-    return createSdkMcpServer({
+    const server = createSdkMcpServer({
         name: slug,
         version: '0.1.0',
         tools: tools,
     });
+    serverCache.set(slug, { at: now, server });
+    return server;
 }
 async function fetchToolkitTools(composio, slug) {
     const userId = await getPreferredUserId();

package/dist/tools/background-task-tools.js

@@ -13,7 +13,7 @@
  */
 import { z } from 'zod';
 import { createBackgroundTask, listBackgroundTasks, loadBackgroundTask, } from '../agent/background-tasks.js';
-import { ACTIVE_AGENT_SLUG, logger, textResult } from './shared.js';
+import { ACTIVE_AGENT_SLUG, ACTIVE_SESSION_KEY, logger, textResult } from './shared.js';
 const DEFAULT_MAX_MINUTES = 30;
 export function registerBackgroundTaskTools(server) {
     server.tool('start_background_task', 'Kick off a long-running autonomous task in the background. Use when the work would burn the chat context (deep research, multi-page extraction, batch processing) or take longer than a chat turn. Returns a task id immediately. The daemon picks the task up within seconds, runs it with your profile + tools, and posts the deliverable to your Discord channel when done.', {
@@ -30,8 +30,9 @@ export function registerBackgroundTaskTools(server) {
             fromAgent,
             prompt: trimmed,
             maxMinutes: cap,
+            ...(ACTIVE_SESSION_KEY ? { sessionKey: ACTIVE_SESSION_KEY } : {}),
         });
-        logger.info({ id: task.id, fromAgent, maxMinutes: task.maxMinutes }, 'Background task queued');
+        logger.info({ id: task.id, fromAgent, sessionKey: task.sessionKey, maxMinutes: task.maxMinutes }, 'Background task queued');
         return textResult(`Queued **${task.id}** (max ${task.maxMinutes} min). The daemon will pick it up within a few seconds and run it in the background. You'll get a notification in your channel when the deliverable lands. Use \`get_background_task\` to check status.`);
     });
     server.tool('get_background_task', 'Check the status of a background task. Returns its lifecycle state (pending|running|done|failed|aborted|interrupted), how long it has been running, and the result/error if terminal.', {

package/dist/tools/mcp-server.d.ts

@@ -8,6 +8,6 @@
  * Usage:
  *   npx tsx src/tools/mcp-server.ts
  */
-export { getStore, textResult, externalResult, incrementalSync, ACTIVE_AGENT_SLUG } from './shared.js';
+export { getStore, textResult, externalResult, incrementalSync, ACTIVE_AGENT_SLUG, ACTIVE_SESSION_KEY } from './shared.js';
 export type { MemoryStoreType } from './shared.js';
 //# sourceMappingURL=mcp-server.d.ts.map

package/dist/tools/mcp-server.js

@@ -15,7 +15,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { BASE_DIR, VAULT_DIR, env, getStore, getStoreSync, logger, textResult, externalResult, } from './shared.js';
 // Re-export for any code that imports from mcp-server.ts directly
-export { getStore, textResult, externalResult, incrementalSync, ACTIVE_AGENT_SLUG } from './shared.js';
+export { getStore, textResult, externalResult, incrementalSync, ACTIVE_AGENT_SLUG, ACTIVE_SESSION_KEY } from './shared.js';
 // ── Tool modules ────────────────────────────────────────────────────────
 import { registerMemoryTools } from './memory-tools.js';
 import { registerVaultTools } from './vault-tools.js';

package/dist/tools/shared.d.ts

@@ -671,6 +671,7 @@ export type MemoryStoreType = {
 export declare function getStore(): Promise<MemoryStoreType>;
 export declare function getStoreSync(): MemoryStoreType | null;
 export declare const ACTIVE_AGENT_SLUG: string | null;
+export declare const ACTIVE_SESSION_KEY: string | null;
 export declare const GOALS_DIR: string;
 export declare function agentTasksFile(slug: string | null): string;
 export declare function agentWorkingMemoryFile(slug: string | null): string;

package/dist/tools/shared.js

@@ -59,6 +59,8 @@ export function getStoreSync() {
 // ── Active Agent Slug ──────────────────────────────────────────────────
 const _rawAgentSlug = process.env.CLEMENTINE_TEAM_AGENT || null;
 export const ACTIVE_AGENT_SLUG = _rawAgentSlug === 'clementine' ? null : _rawAgentSlug;
+const _rawSessionKey = process.env.CLEMENTINE_SESSION_KEY || null;
+export const ACTIVE_SESSION_KEY = _rawSessionKey?.trim() || null;
 // ── Agent-aware path helpers ───────────────────────────────────────────
 // GOALS_DIR is defined in config.ts but not in shared.ts — define it here
 export const GOALS_DIR = path.join(BASE_DIR, 'goals');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.176",
+  "version": "1.18.178",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",