@luckydraw/cumulus 0.27.41 → 0.28.0

package/dist/lib/gateway.js

@@ -10,27 +10,64 @@ import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { getToolDefinitions as getMcpToolDefinitions, handleToolCall, } from '../mcp/tool-handler.js';
 import { loadAdaptiveState } from './adaptive-context-budget.js';
-import { loadGlobalConfig, loadThreadConfig, mergeConfigs, readAlwaysIncludeFiles, resolveRagBudget, } from './config.js';
+import { runAgenticLoop } from './agentic-loop.js';
+import { loadGlobalConfig, loadThreadConfig, mergeConfigs, readAlwaysIncludeFiles, } from './config.js';
 import { saveThreadConfig } from './config.js';
 import { ContentStore } from './content-store.js';
 import { ContextBudget, estimateTokens } from './context-budget.js';
 import { HistoryStore } from './history.js';
+import { HuggingFaceProvider, getModelContextLimit, getModelMaxOutput, } from './huggingface-provider.js';
 import { retrieve } from './retriever.js';
 import { SessionManager } from './session.js';
 import { StreamProcessor, shouldExternalizeUserInput, externalizeUserInput, } from './stream-processor.js';
 import { scaffoldFromTemplate } from './templates.js';
+import { getEagerTools } from './tools/index.js';
 // ─── Constants ───────────────────────────────────────────────────────────────
 const CUMULUS_DIR = path.join(os.homedir(), '.cumulus');
 const THREADS_DIR = path.join(CUMULUS_DIR, 'threads');
+// ─── Active subprocess tracking (for graceful shutdown) ──────────────────────
+const _activeSubprocesses = new Set();
+/** Promises that resolve when each subprocess has fully persisted its response */
+const _completionPromises = new Map();
+/** Map subprocess → thread name (for auto-resume after restart) */
+const _activeThreadNames = new Map();
+/** Read-only view of active Claude subprocesses (for health/shutdown) */
+export function getActiveSubprocessCount() {
+    return _activeSubprocesses.size;
+}
+/** Register a completion promise for a subprocess (resolves after persistence) */
+export function registerCompletionPromise(child, promise) {
+    _completionPromises.set(child, promise);
+}
+/** Get thread names of all currently active (in-flight) subprocesses */
+export function getActiveThreadNames() {
+    return Array.from(_activeThreadNames.values());
+}
+/** Wait for all active subprocesses to complete AND persist their responses (with timeout) */
+export async function drainActiveSubprocesses(timeoutMs = 120_000) {
+    const promises = Array.from(_completionPromises.values());
+    if (promises.length === 0 && _activeSubprocesses.size === 0)
+        return 0;
+    const startCount = Math.max(_activeSubprocesses.size, promises.length);
+    // Wait for all completion promises (which include persistence) with timeout
+    const timeout = new Promise(resolve => setTimeout(resolve, timeoutMs));
+    await Promise.race([Promise.allSettled(promises), timeout]);
+    // Force-kill any remaining after timeout
+    for (const child of _activeSubprocesses) {
+        child.kill('SIGTERM');
+    }
+    return startCount - _activeSubprocesses.size;
+}
 export const RECENT_CONTEXT_COUNT = 10;
 export const RECENT_MSG_MAX_TOKENS = 500;
 export const RECENT_CONTEXT_BUDGET = 6_000;
 export const SYSTEM_PROMPT_TEMPLATE = `You have NO memory of this conversation. There are {count} prior messages (~{tokens} tokens) in the history.
 
 CURRENT SESSION: {sessionId}
-{alwaysIncludeContext}{recentContext}
-{retrievedContext}
+{alwaysIncludeContext}{retrievedContext}
+{recentContext}
 CONTEXT MANAGEMENT:
 - RECENT CONVERSATION: The last few messages, always included for continuity.
 - RETRIEVED CONTEXT: Automatically retrieved based on the user's current message using semantic + keyword search.
@@ -105,6 +142,146 @@ function getContentStorePath(threadPath) {
 function getSessionsPath(threadPath) {
     return threadPath.replace(/\.jsonl$/, '.sessions');
 }
+function getStreamingTmpPath(threadName) {
+    return path.join(THREADS_DIR, `${threadName}.streaming.tmp`);
+}
+/**
+ * Create a write-through streaming buffer for a thread.
+ * Writes partial response to disk every 5 seconds so it survives restarts.
+ */
+function createStreamingBuffer(threadName, userMessageId) {
+    const tmpPath = getStreamingTmpPath(threadName);
+    const header = JSON.stringify({
+        threadName,
+        startedAt: new Date().toISOString(),
+        userMessageId: userMessageId || '',
+    });
+    try {
+        fs.writeFileSync(tmpPath, header + '\n---\n', 'utf-8');
+    }
+    catch (err) {
+        console.error(`[streaming-buffer] Failed to create ${tmpPath}:`, err);
+    }
+    return { tmpPath, flushedLength: 0, interval: null };
+}
+/**
+ * Flush accumulated response text to the streaming tmp file.
+ */
+function flushStreamingBuffer(state, fullResponse) {
+    if (fullResponse.length <= state.flushedLength)
+        return;
+    const newText = fullResponse.slice(state.flushedLength);
+    try {
+        fs.appendFileSync(state.tmpPath, newText, 'utf-8');
+        state.flushedLength = fullResponse.length;
+    }
+    catch (err) {
+        console.error(`[streaming-buffer] Flush failed for ${state.tmpPath}:`, err);
+    }
+}
+/**
+ * Clean up the streaming tmp file (called on normal completion).
+ */
+function cleanupStreamingBuffer(state) {
+    if (state.interval) {
+        clearInterval(state.interval);
+        state.interval = null;
+    }
+    try {
+        if (fs.existsSync(state.tmpPath)) {
+            fs.unlinkSync(state.tmpPath);
+        }
+    }
+    catch {
+        // Non-critical — stale tmp files are handled by recovery on next startup
+    }
+}
+/**
+ * Start periodic flushing (every 5 seconds).
+ */
+function startStreamingFlush(state, getFullResponse) {
+    state.interval = setInterval(() => {
+        flushStreamingBuffer(state, getFullResponse());
+    }, 5_000);
+}
+/**
+ * Recover partial responses from .streaming.tmp files left by a previous crash/restart.
+ * Called on daemon startup BEFORE auto-resume.
+ * Returns the number of partial responses recovered.
+ */
+export async function recoverStreamingBuffers() {
+    ensureDirectories();
+    let recovered = 0;
+    let files;
+    try {
+        files = fs.readdirSync(THREADS_DIR).filter(f => f.endsWith('.streaming.tmp'));
+    }
+    catch {
+        return 0;
+    }
+    for (const file of files) {
+        const tmpPath = path.join(THREADS_DIR, file);
+        try {
+            const raw = fs.readFileSync(tmpPath, 'utf-8');
+            const separatorIdx = raw.indexOf('\n---\n');
+            if (separatorIdx === -1) {
+                fs.unlinkSync(tmpPath);
+                continue;
+            }
+            const headerStr = raw.slice(0, separatorIdx);
+            const responseText = raw.slice(separatorIdx + 5); // skip '\n---\n'
+            if (!responseText.trim()) {
+                // No actual response content — just delete
+                fs.unlinkSync(tmpPath);
+                continue;
+            }
+            let header;
+            try {
+                header = JSON.parse(headerStr);
+            }
+            catch {
+                fs.unlinkSync(tmpPath);
+                continue;
+            }
+            // Check for stale tmp: if the thread has newer messages, skip
+            const threadPath = getThreadPath(header.threadName);
+            if (fs.existsSync(threadPath)) {
+                const stat = fs.statSync(threadPath);
+                const tmpStat = fs.statSync(tmpPath);
+                if (stat.mtimeMs > tmpStat.mtimeMs) {
+                    // Thread was already updated after the tmp was written — skip
+                    console.error(`[streaming-buffer] Skipping stale tmp for ${header.threadName}`);
+                    fs.unlinkSync(tmpPath);
+                    continue;
+                }
+            }
+            // Persist the partial response to JSONL
+            const thread = await getOrCreateThread(header.threadName);
+            await thread.history.append({
+                role: 'assistant',
+                content: responseText + '\n\n*(response interrupted by gateway restart)*',
+                metadata: {
+                    partial: true,
+                    interruptedAt: header.startedAt,
+                },
+            });
+            console.error(`[streaming-buffer] Recovered partial response for ${header.threadName} (${responseText.length} chars)`);
+            recovered++;
+            fs.unlinkSync(tmpPath);
+        }
+        catch (err) {
+            console.error(`[streaming-buffer] Failed to recover ${file}:`, err);
+            // Try to clean up
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    return recovered;
+}
 /**
  * Resolve the full path to the `claude` CLI binary.
  * When launched from Finder/launchd, PATH is minimal.
@@ -231,15 +408,22 @@ export function generateMcpConfig(threadPath, sessionId, threadName, sharedMcpPo
     let gatewayAgentsEntry = {};
     if (gatewayAgentsConfig) {
         const agentsMcpPath = getGatewayAgentsMcpPathInternal();
+        const agentsEnv = {
+            GATEWAY_API_URL: gatewayAgentsConfig.apiUrl,
+            GATEWAY_API_KEY: gatewayAgentsConfig.apiKey,
+            GATEWAY_AGENT_NAME: threadName,
+        };
+        if (gatewayAgentsConfig.resendApiKey) {
+            agentsEnv.RESEND_API_KEY = gatewayAgentsConfig.resendApiKey;
+            agentsEnv.RESEND_DEFAULT_FROM = gatewayAgentsConfig.resendDefaultFrom || '';
+            agentsEnv.RESEND_REPLY_TO = gatewayAgentsConfig.resendReplyTo || '';
+            agentsEnv.RESEND_RATE_LIMIT = String(gatewayAgentsConfig.resendRateLimit || 10);
+        }
         gatewayAgentsEntry = {
             'gateway-agents': {
                 command: nodePath,
                 args: [agentsMcpPath],
-                env: {
-                    GATEWAY_API_URL: gatewayAgentsConfig.apiUrl,
-                    GATEWAY_API_KEY: gatewayAgentsConfig.apiKey,
-                    GATEWAY_AGENT_NAME: threadName,
-                },
+                env: agentsEnv,
             },
         };
     }
@@ -408,17 +592,12 @@ export function computeAvgRelevance(debug) {
  * Get or create a thread's stores and adaptive budget.
  * Cached in a module-level Map.
  */
-export async function getOrCreateThread(threadName, basePath) {
-    // Use basePath-qualified cache key to prevent cross-environment collisions
-    const cacheKey = basePath ? `${basePath}::${threadName}` : threadName;
-    if (threadCache.has(cacheKey)) {
-        return threadCache.get(cacheKey);
-    }
-    const threadsDir = basePath ? path.join(basePath, 'threads') : THREADS_DIR;
-    if (!fs.existsSync(threadsDir)) {
-        fs.mkdirSync(threadsDir, { recursive: true });
+export async function getOrCreateThread(threadName, _basePath) {
+    if (threadCache.has(threadName)) {
+        return threadCache.get(threadName);
     }
-    const threadPath = path.join(threadsDir, `${threadName}.jsonl`);
+    ensureDirectories();
+    const threadPath = getThreadPath(threadName);
     const contentStorePath = getContentStorePath(threadPath);
     const sessionsPath = getSessionsPath(threadPath);
     const history = new HistoryStore(threadPath);
@@ -427,15 +606,12 @@ export async function getOrCreateThread(threadName, basePath) {
     await session.initialize();
     const adaptive = await loadAdaptiveState(threadPath);
     const thread = { history, content, session, adaptive, threadPath };
-    threadCache.set(cacheKey, thread);
+    threadCache.set(threadName, thread);
     return thread;
 }
 /** Clear a thread from the cache */
-export function clearThreadCache(threadName, basePath) {
+export function clearThreadCache(threadName) {
     if (threadName) {
-        const cacheKey = basePath ? `${basePath}::${threadName}` : threadName;
-        threadCache.delete(cacheKey);
-        // Also try the plain name for backward compat
         threadCache.delete(threadName);
     }
     else {
@@ -450,7 +626,7 @@ export function clearThreadCache(threadName, basePath) {
  * from both Janus (via IPC) and the gateway server (via HTTP/SSE).
  */
 export async function sendMessage(options) {
-    const { threadName, message, images = [], attachments = [], basePath = CUMULUS_DIR, claudePath, sharedMcpPort, systemPromptTemplate, projectDir, projectRoot, extraMcpServers, gatewayAgentsConfig, onToken, onSegment, onError, onSpawn, signal, executorRegistry, } = options;
+    const { threadName, message, images = [], attachments = [], basePath = CUMULUS_DIR, claudePath, sharedMcpPort, systemPromptTemplate, projectDir, projectRoot, extraMcpServers, gatewayAgentsConfig, onToken, onSegment, onError, onSpawn, signal, executorRegistry, hfApiKey, resumeState, onNeedsInput, } = options;
     const thread = await getOrCreateThread(threadName, basePath);
     // ── Build image content blocks ──
     const imageBlocks = [];
@@ -507,7 +683,7 @@ export async function sendMessage(options) {
     else {
         budget.consume(estimateTokens(messageForClaude));
     }
-    // ── Persist user message ──
+    // ── Persist user message (capture ID for streaming buffer header) ──
     const userMessage = await thread.history.append({
         role: 'user',
         content: message,
@@ -521,6 +697,7 @@ export async function sendMessage(options) {
             }))
             : undefined,
     });
+    const userMessageId = userMessage?.id;
     // ── Stats + recent context ──
     const stats = await thread.history.getStats();
     const recentMessages = await thread.history.getRecent(RECENT_CONTEXT_COUNT);
@@ -530,7 +707,7 @@ export async function sendMessage(options) {
     // ── Config + always-include ──
     // Resolve executor and cwd
     const effectiveProjectRoot = projectRoot || path.join(os.homedir(), 'projects');
-    const tc = await loadThreadConfig(threadName, basePath !== CUMULUS_DIR ? basePath : undefined);
+    const tc = await loadThreadConfig(threadName);
     const executor = tc.executor || 'thundercat';
     const isRemoteExecutor = executor !== 'thundercat' && executorRegistry?.isOnline(executor);
     // Resolve cwd: explicit projectDir > executorPaths[executor] > thread config projectDir > default
@@ -573,18 +750,32 @@ export async function sendMessage(options) {
             console.warn(`[Gateway] scaffold failed for ${threadName}:`, err);
         }
         // Persist the resolved path so it survives thread renames
-        await saveThreadConfig(threadName, { projectDir: threadCwd }, basePath !== CUMULUS_DIR ? basePath : undefined);
+        await saveThreadConfig(threadName, { projectDir: threadCwd });
     }
     const globalConfig = await loadGlobalConfig();
-    const threadConfig = await loadThreadConfig(threadName, basePath !== CUMULUS_DIR ? basePath : undefined);
+    const threadConfig = await loadThreadConfig(threadName);
     const mergedConfig = mergeConfigs(globalConfig, threadConfig);
     const alwaysInclude = await readAlwaysIncludeFiles(mergedConfig, threadCwd);
+    // ── Model resolution ──
+    // Thread config `model` field determines the execution path:
+    //   "claude" or absent → existing CLI subprocess (default, zero behavior change)
+    //   any HuggingFace model ID → agentic loop with HuggingFace provider
+    const threadModel = mergedConfig.model || 'claude';
+    const isHuggingFace = threadModel !== 'claude' && !!hfApiKey;
+    console.log(`[Model] thread=${threadName} model=${threadModel} isHuggingFace=${isHuggingFace} hfApiKey=${!!hfApiKey}`);
+    // Clamp adaptive budget to model's actual context window.
+    // For HuggingFace models, subtract max_output to reserve space for generation,
+    // and subtract a safety margin for tool definitions and other overhead.
+    const HF_OVERHEAD_RESERVE = 40_000; // tool defs, deferred list, etc.
+    const rawModelLimit = isHuggingFace ? getModelContextLimit(threadModel) : 1_000_000;
+    const modelContextLimit = isHuggingFace
+        ? rawModelLimit - getModelMaxOutput(threadModel) - HF_OVERHEAD_RESERVE
+        : rawModelLimit;
     // ── RAG budget ──
-    const adaptiveBudget = thread.adaptive.getTotalContextBudget();
+    const rawAdaptiveBudget = thread.adaptive.getTotalContextBudget();
+    const adaptiveBudget = Math.min(rawAdaptiveBudget, modelContextLimit);
     const userQueryTokens = estimateTokens(message);
-    const overhead = userQueryTokens + alwaysInclude.totalTokens + RECENT_CONTEXT_BUDGET;
-    const effectiveBudget = resolveRagBudget(mergedConfig, adaptiveBudget, overhead);
-    const ragBudget = Math.max(0, effectiveBudget - userQueryTokens - alwaysInclude.totalTokens - RECENT_CONTEXT_BUDGET);
+    const ragBudget = Math.max(0, adaptiveBudget - userQueryTokens - alwaysInclude.totalTokens - RECENT_CONTEXT_BUDGET);
     // ── RAG retrieval ──
     let retrievalResult = null;
     try {
@@ -666,6 +857,19 @@ export async function sendMessage(options) {
     const collectedSegments = [];
     const spawnTime = Date.now();
     let ttft = null;
+    let lastTokenTime = Date.now();
+    let activePid = 'n/a'; // set by CLI branch; stays 'n/a' for HF models
+    // Stream heartbeat — log every 30s so we can detect silent hangs
+    const heartbeat = setInterval(() => {
+        const elapsed = Date.now() - spawnTime;
+        const sinceLast = Date.now() - lastTokenTime;
+        console.error(`[subprocess] HEARTBEAT thread=${threadName} pid=${activePid} elapsed=${elapsed}ms sinceLast=${sinceLast}ms chars=${fullResponse.length}`);
+        if (sinceLast > 60_000) {
+            console.error(`[subprocess] STALL thread=${threadName} — no output for ${Math.round(sinceLast / 1000)}s. Last 200 chars: ${fullResponse.slice(-200)}`);
+        }
+    }, 30_000);
+    // ── Persistent streaming buffer (survives gateway restart) ──
+    let streamBuf = null;
     const processLine = async (line) => {
         if (!line.trim())
             return;
@@ -679,8 +883,13 @@ export async function sendMessage(options) {
         // Text extraction
         const text = extractTextFromStreamLine(processed.line);
         if (text) {
+            lastTokenTime = Date.now();
             if (ttft === null) {
                 ttft = Date.now() - spawnTime;
+                console.error(`[subprocess] FIRST_TOKEN thread=${threadName} ttft=${ttft}ms`);
+                // Create persistent streaming buffer on first token
+                streamBuf = createStreamingBuffer(threadName, userMessageId);
+                startStreamingFlush(streamBuf, () => fullResponse);
             }
             if (fullResponse && !fullResponse.endsWith('\n')) {
                 fullResponse += '\n\n';
@@ -698,6 +907,11 @@ export async function sendMessage(options) {
     };
     // ── Persist response and update session/adaptive (shared between local and remote) ──
     const persistResponse = async () => {
+        // Clean up streaming buffer — response is being persisted to JSONL, tmp no longer needed
+        if (streamBuf) {
+            cleanupStreamingBuffer(streamBuf);
+            streamBuf = null;
+        }
         let assistantMessage = null;
         if (fullResponse) {
             assistantMessage = await thread.history.append({
@@ -814,6 +1028,308 @@ export async function sendMessage(options) {
             throw err;
         }
     }
+    // ═══ BRANCH: HuggingFace / agentic loop (non-Claude models) ═══
+    if (isHuggingFace) {
+        const provider = new HuggingFaceProvider(hfApiKey, threadModel);
+        // Build system blocks with cache_control on static parts
+        const systemBlocks = [];
+        // Static instructions (cacheable)
+        const instructions = systemPromptTemplate || SYSTEM_PROMPT_TEMPLATE;
+        const modelIdentity = `You are ${threadModel}. You are NOT Claude, NOT Opus, NOT Sonnet, NOT Haiku. If asked what model you are, say "${threadModel}". `;
+        systemBlocks.push({
+            type: 'text',
+            text: modelIdentity +
+                instructions
+                    .replace('{{messageCount}}', String(stats.count))
+                    .replace('{{totalTokens}}', String(stats.totalTokens))
+                    .replace('{{sessionId}}', thread.session.getSessionId()),
+            cache_control: { type: 'ephemeral' },
+        });
+        // Always-include files
+        if (alwaysInclude.formattedContext) {
+            systemBlocks.push({
+                type: 'text',
+                text: alwaysInclude.formattedContext,
+                cache_control: { type: 'ephemeral' },
+            });
+        }
+        // RAG context (before recent conversation so the model continues naturally)
+        if (retrievedContext) {
+            systemBlocks.push({ type: 'text', text: `\n\n## Retrieved Context\n${retrievedContext}` });
+        }
+        // Recent conversation (last, so the model produces a natural continuation)
+        const recentCtx = formatRecentContext(recentConversation, RECENT_CONTEXT_BUDGET);
+        if (recentCtx) {
+            systemBlocks.push({ type: 'text', text: `\n\n## Recent Conversation\n${recentCtx}` });
+        }
+        // Build core tools + MCP tools as direct function calls
+        const coreTools = getEagerTools();
+        // MCP tools: cumulus-history as direct function calls (namespaced)
+        const mcpToolEntries = [];
+        // Build ToolContext for direct cumulus-history tool dispatch
+        const toolCtx = {
+            historyStore: thread.history,
+            contentStore: thread.content,
+            sessionsPath: path.join(path.dirname(thread.history.threadPath), '..', 'sessions'),
+            currentSessionId: thread.session.getSessionId(),
+        };
+        // Wire all cumulus-history tools as mcp__cumulus_history__* (direct function calls)
+        for (const toolDef of getMcpToolDefinitions()) {
+            const nsName = `mcp__cumulus_history__${toolDef.name}`;
+            mcpToolEntries.push({
+                definition: {
+                    name: nsName,
+                    description: toolDef.description ?? toolDef.name,
+                    input_schema: toolDef.inputSchema,
+                },
+                execute: async (input) => {
+                    const result = await handleToolCall(toolDef.name, input, toolCtx);
+                    return result.content.map((c) => c.text).join('\n');
+                },
+            });
+        }
+        // Wire gateway-agents tools as mcp__gateway_agents__* (HTTP calls to own server)
+        if (gatewayAgentsConfig) {
+            const { apiUrl, apiKey: agentsApiKey } = gatewayAgentsConfig;
+            const agentsHttpCall = async (method, endpoint, body) => {
+                const http = await import('http');
+                const url = new URL(endpoint, apiUrl);
+                return new Promise((resolve, reject) => {
+                    const bodyStr = body ? JSON.stringify(body) : undefined;
+                    const req = http.request({
+                        hostname: url.hostname,
+                        port: url.port,
+                        path: url.pathname + url.search,
+                        method,
+                        headers: {
+                            'Content-Type': 'application/json',
+                            'X-API-Key': agentsApiKey,
+                            ...(bodyStr ? { 'Content-Length': String(Buffer.byteLength(bodyStr)) } : {}),
+                        },
+                    }, res => {
+                        let data = '';
+                        res.on('data', (chunk) => {
+                            data += chunk;
+                        });
+                        res.on('end', () => {
+                            try {
+                                resolve(JSON.parse(data));
+                            }
+                            catch {
+                                resolve({ error: `HTTP ${res.statusCode}: ${data}` });
+                            }
+                        });
+                    });
+                    req.on('error', (err) => reject(err));
+                    if (bodyStr)
+                        req.write(bodyStr);
+                    req.end();
+                });
+            };
+            mcpToolEntries.push({
+                definition: {
+                    name: 'mcp__gateway_agents__list_agents',
+                    description: 'List all active threads (agents) on the gateway.',
+                    input_schema: { type: 'object', properties: {}, required: [] },
+                },
+                execute: async () => {
+                    try {
+                        const result = (await agentsHttpCall('GET', '/api/agents'));
+                        return JSON.stringify({ agents: result.agents || [], self: threadName });
+                    }
+                    catch (err) {
+                        return `Error: ${err.message}`;
+                    }
+                },
+            });
+            mcpToolEntries.push({
+                definition: {
+                    name: 'mcp__gateway_agents__send_to_agent',
+                    description: 'Send a message to another agent by thread name.',
+                    input_schema: {
+                        type: 'object',
+                        properties: {
+                            target: {
+                                description: 'Target thread name or array of names',
+                                oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+                            },
+                            message: { type: 'string', description: 'Message to send' },
+                            visibility: {
+                                description: 'Visibility: "cc" (default), "blind", or { hidden: [...] }',
+                                oneOf: [
+                                    { type: 'string', enum: ['cc', 'blind'] },
+                                    {
+                                        type: 'object',
+                                        properties: { hidden: { type: 'array', items: { type: 'string' } } },
+                                        required: ['hidden'],
+                                    },
+                                ],
+                            },
+                        },
+                        required: ['target', 'message'],
+                    },
+                },
+                execute: async (input) => {
+                    try {
+                        const targets = Array.isArray(input.target) ? input.target : [input.target];
+                        const body = {
+                            targets: targets.filter((t) => t !== threadName),
+                            message: input.message,
+                            sender: threadName,
+                            messageType: 'direct',
+                        };
+                        if (input.visibility)
+                            body.visibility = input.visibility;
+                        return JSON.stringify(await agentsHttpCall('POST', '/api/agents/inject', body));
+                    }
+                    catch (err) {
+                        return `Error: ${err.message}`;
+                    }
+                },
+            });
+            mcpToolEntries.push({
+                definition: {
+                    name: 'mcp__gateway_agents__notify_user',
+                    description: "Send a push notification to the user's phone/device.",
+                    input_schema: {
+                        type: 'object',
+                        properties: {
+                            message: { type: 'string' },
+                            title: { type: 'string' },
+                            priority: { type: 'string', enum: ['low', 'normal', 'high'] },
+                        },
+                        required: ['message'],
+                    },
+                },
+                execute: async (input) => {
+                    try {
+                        return JSON.stringify(await agentsHttpCall('POST', '/api/notify', {
+                            title: input.title || threadName,
+                            body: input.message,
+                            threadName,
+                            priority: input.priority || 'normal',
+                        }));
+                    }
+                    catch (err) {
+                        return `Error: ${err.message}`;
+                    }
+                },
+            });
+            mcpToolEntries.push({
+                definition: {
+                    name: 'mcp__gateway_agents__upload_media',
+                    description: 'Upload a local file to the media directory. Returns the public URL path.',
+                    input_schema: {
+                        type: 'object',
+                        properties: {
+                            source_path: { type: 'string', description: 'Absolute path to the file' },
+                            filename: { type: 'string', description: 'Optional desired filename' },
+                        },
+                        required: ['source_path'],
+                    },
+                },
+                execute: async (input) => {
+                    try {
+                        const fileData = fs.readFileSync(input.source_path);
+                        const filename = input.filename || path.basename(input.source_path);
+                        return JSON.stringify(await agentsHttpCall('POST', '/api/media/upload', {
+                            filename,
+                            data: fileData.toString('base64'),
+                            encoding: 'base64',
+                        }));
+                    }
+                    catch (err) {
+                        return `Error: ${err.message}`;
+                    }
+                },
+            });
+        }
+        // Run the agentic loop
+        const spawnTimeApi = Date.now();
+        let ttftApi = null;
+        let firstToken = true;
+        try {
+            const loopResult = await runAgenticLoop({
+                provider,
+                model: threadModel,
+                system: systemBlocks,
+                userMessage: messageForClaude || '',
+                imageBlocks: hasImages ? imageBlocks : undefined,
+                tools: coreTools,
+                mcpTools: mcpToolEntries,
+                eagerAll: true, // HF models can't use ToolSearch — send all tools upfront
+                onToken: text => {
+                    if (firstToken) {
+                        ttftApi = Date.now() - spawnTimeApi;
+                        firstToken = false;
+                        // Create persistent streaming buffer on first token
+                        streamBuf = createStreamingBuffer(threadName, userMessageId);
+                        startStreamingFlush(streamBuf, () => fullResponse);
+                    }
+                    fullResponse += text;
+                    onToken?.(text);
+                },
+                onToolUse: (name, input) => {
+                    const segment = { type: 'tool_use', tool: name, input };
+                    collectedSegments.push(segment);
+                    onSegment?.(segment);
+                },
+                onToolResult: (_name, output, isError) => {
+                    const segment = {
+                        type: 'tool_result',
+                        content: output.slice(0, 500),
+                        isError,
+                    };
+                    collectedSegments.push(segment);
+                    onSegment?.(segment);
+                },
+                signal,
+                cwd: threadCwd,
+                threadName,
+                resumeState,
+            });
+            ttft = ttftApi;
+            console.log(`[Gateway] HuggingFace API: ${threadModel}, ${loopResult.turns} turns, ` +
+                `${loopResult.usage.totalInputTokens} in / ${loopResult.usage.totalOutputTokens} out`);
+            if (loopResult.usage.totalOutputTokens === 0 && !loopResult.response.trim()) {
+                console.warn(`[Gateway] WARNING: HuggingFace returned empty response for ${threadName}. ` +
+                    `Model context limit: ${rawModelLimit}, effective budget: ${modelContextLimit}, ` +
+                    `system prompt tokens: ${debug.systemPromptLength}`);
+            }
+            // Handle AskUserQuestion pause — stop flush interval but keep tmp file
+            if (loopResult.status === 'needs_input' && loopResult.needsInput) {
+                if (streamBuf?.interval) {
+                    clearInterval(streamBuf.interval);
+                    streamBuf.interval = null;
+                }
+                onNeedsInput?.(loopResult.needsInput);
+                return {
+                    response: fullResponse,
+                    ttft: ttftApi,
+                    userMessage,
+                    assistantMessage: null,
+                    segments: collectedSegments,
+                    debug,
+                    needsInput: loopResult.needsInput,
+                };
+            }
+            const assistantMessage = await persistResponse();
+            return {
+                response: fullResponse,
+                ttft,
+                userMessage,
+                assistantMessage,
+                segments: collectedSegments,
+                debug,
+            };
+        }
+        catch (err) {
+            if (fullResponse) {
+                await persistResponse();
+            }
+            throw err;
+        }
+    }
     // ── Local execution: spawn Claude on this machine ──
     // Build device MCP config if thread has devices configured
     let deviceMcpConfig;
@@ -850,6 +1366,10 @@ export async function sendMessage(options) {
         env: cleanEnv,
         cwd: threadCwd,
     });
+    activePid = claude.pid ?? '?';
+    _activeSubprocesses.add(claude);
+    _activeThreadNames.set(claude, threadName);
+    console.error(`[subprocess] SPAWN thread=${threadName} pid=${claude.pid} cwd=${threadCwd} active=${_activeSubprocesses.size}`);
     // Expose subprocess ref to caller
     onSpawn?.(claude);
     // Wire abort signal to kill subprocess
@@ -915,14 +1435,41 @@ export async function sendMessage(options) {
                 reject(err);
             }
         };
-        claude.on('close', async () => {
-            if (buffer.trim()) {
-                pendingLines.push(processLine(buffer).catch(() => { }));
+        claude.on('close', (code, sig) => {
+            clearInterval(heartbeat);
+            const duration = Date.now() - spawnTime;
+            const responseLen = fullResponse.length;
+            const toolCalls = collectedSegments.filter(s => s.type === 'tool_use').length;
+            const lastOutput = fullResponse.slice(-200);
+            console.error(`[subprocess] CLOSE thread=${threadName} pid=${claude.pid} code=${code} signal=${sig ?? 'none'} duration=${duration}ms responseChars=${responseLen} toolCalls=${toolCalls} active=${_activeSubprocesses.size}`);
+            if (responseLen > 0) {
+                console.error(`[subprocess] LAST_OUTPUT thread=${threadName}: ...${lastOutput}`);
             }
-            await Promise.all(pendingLines);
-            handleCompletion();
+            // Complete async work (pending line processing + persistence) BEFORE
+            // removing from tracking set. This ensures drainActiveSubprocesses()
+            // waits for persistence to finish before allowing process.exit().
+            const completion = (async () => {
+                if (buffer.trim()) {
+                    pendingLines.push(processLine(buffer).catch(() => { }));
+                }
+                await Promise.all(pendingLines);
+                await handleCompletion();
+                _activeSubprocesses.delete(claude);
+                _activeThreadNames.delete(claude);
+                _completionPromises.delete(claude);
+            })();
+            registerCompletionPromise(claude, completion);
         });
         claude.on('error', (err) => {
+            clearInterval(heartbeat);
+            _activeSubprocesses.delete(claude);
+            _activeThreadNames.delete(claude);
+            _completionPromises.delete(claude);
+            if (streamBuf) {
+                cleanupStreamingBuffer(streamBuf);
+                streamBuf = null;
+            }
+            console.error(`[subprocess] ERROR thread=${threadName} pid=${claude.pid} error=${err.message} active=${_activeSubprocesses.size}`);
             cleanupMcpConfig(mcpConfigPath);
             const errorMsg = err.message.includes('ENOENT')
                 ? 'Claude CLI not found. Please install it first.'