@visorcraft/idlehands 1.1.6 → 1.1.7

package/dist/agent.js

@@ -3,6 +3,7 @@ import { enforceContextBudget, stripThinking, estimateTokensFromMessages, estima
 import * as tools from './tools.js';
 import { selectHarness } from './harnesses.js';
 import { BASE_MAX_TOKENS, deriveContextWindow, deriveGenerationParams, supportsVisionModel } from './model-customization.js';
+import { HookManager, loadHookPlugins } from './hooks/index.js';
 import { checkExecSafety, checkPathSafety } from './safety.js';
 import { loadProjectContext } from './context.js';
 import { loadGitContext, isGitDirty, stashWorkingTree } from './git.js';
@@ -989,6 +990,15 @@ export async function createSession(opts) {
     if (typeof cfg.response_timeout === 'number' && cfg.response_timeout > 0) {
         client.setResponseTimeout(cfg.response_timeout);
     }
+    if (typeof client.setConnectionTimeout === 'function' && typeof cfg.connection_timeout === 'number' && cfg.connection_timeout > 0) {
+        client.setConnectionTimeout(cfg.connection_timeout);
+    }
+    if (typeof client.setInitialConnectionCheck === 'function' && typeof cfg.initial_connection_check === 'boolean') {
+        client.setInitialConnectionCheck(cfg.initial_connection_check);
+    }
+    if (typeof client.setInitialConnectionProbeTimeout === 'function' && typeof cfg.initial_connection_timeout === 'number' && cfg.initial_connection_timeout > 0) {
+        client.setInitialConnectionProbeTimeout(cfg.initial_connection_timeout);
+    }
     // Health check + model list (cheap, avoids wasting GPU on chat warmups if unreachable)
     let modelsList = normalizeModelsResponse(await client.models().catch(() => null));
     let model = cfg.model && cfg.model.trim().length
@@ -1004,6 +1014,44 @@ export async function createSession(opts) {
         modelMeta,
     });
     let supportsVision = supportsVisionModel(model, modelMeta, harness);
+    const sessionId = `session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    const hookCfg = cfg.hooks ?? {};
+    const hookManager = opts.runtime?.hookManager ?? new HookManager({
+        enabled: hookCfg.enabled !== false,
+        strict: hookCfg.strict === true,
+        warnMs: hookCfg.warn_ms,
+        allowedCapabilities: Array.isArray(hookCfg.allow_capabilities) ? hookCfg.allow_capabilities : undefined,
+        context: () => ({
+            sessionId,
+            cwd: cfg.dir ?? process.cwd(),
+            model,
+            harness: harness.id,
+            endpoint: cfg.endpoint,
+        }),
+    });
+    const emitDetached = (promise, eventName) => {
+        void promise.catch((error) => {
+            if (!process.env.IDLEHANDS_QUIET_WARNINGS) {
+                console.warn(`[hooks] async ${eventName} dispatch failed: ${error?.message ?? String(error)}`);
+            }
+        });
+    };
+    if (!opts.runtime?.hookManager && hookManager.isEnabled()) {
+        const loadedPlugins = await loadHookPlugins({
+            pluginPaths: Array.isArray(hookCfg.plugin_paths) ? hookCfg.plugin_paths : [],
+            cwd: cfg.dir ?? process.cwd(),
+            strict: hookCfg.strict === true,
+        });
+        for (const loaded of loadedPlugins) {
+            await hookManager.registerPlugin(loaded.plugin, loaded.path);
+        }
+    }
+    await hookManager.emit('session_start', {
+        model,
+        harness: harness.id,
+        endpoint: cfg.endpoint,
+        cwd: cfg.dir ?? process.cwd(),
+    });
     if (!cfg.i_know_what_im_doing && contextWindow > 131072) {
         console.warn('[warn] context_window is above 131072; this can increase memory usage and hurt throughput. Use --i-know-what-im-doing to proceed.');
     }
@@ -1276,6 +1324,7 @@ export async function createSession(opts) {
         ];
         sessionMetaPending = sessionMeta;
         lastEditedPath = undefined;
+        initialConnectionProbeDone = false;
         mcpToolsLoaded = !mcpLazySchemaMode;
     };
     const restore = (next) => {
@@ -1298,6 +1347,7 @@ export async function createSession(opts) {
     };
     let reqCounter = 0;
     let inFlight = null;
+    let initialConnectionProbeDone = false;
     let lastEditedPath;
     // Plan mode state (Phase 8)
     let planSteps = [];
@@ -1798,6 +1848,7 @@ export async function createSession(opts) {
         return fresh.data.map((m) => m.id).filter(Boolean);
     };
     const setModel = (name) => {
+        const previousModel = model;
         model = name;
         harness = selectHarness(model, cfg.harness && cfg.harness.trim() ? cfg.harness.trim() : undefined);
         const nextMeta = modelsList?.data?.find((m) => m.id === model);
@@ -1815,6 +1866,11 @@ export async function createSession(opts) {
             configuredTopP: cfg.top_p,
             baseMaxTokens: BASE_MAX_TOKENS,
         }));
+        emitDetached(hookManager.emit('model_changed', {
+            previousModel,
+            nextModel: model,
+            harness: harness.id,
+        }), 'model_changed');
     };
     const setEndpoint = async (endpoint, modelName) => {
         const normalized = endpoint.replace(/\/+$/, '');
@@ -2002,11 +2058,35 @@ export async function createSession(opts) {
         const hookObj = typeof hooks === 'function' ? { onToken: hooks } : hooks ?? {};
         let turns = 0;
         let toolCalls = 0;
+        const askId = `ask-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        const emitToolCall = async (call) => {
+            hookObj.onToolCall?.(call);
+            await hookManager.emit('tool_call', { askId, turn: turns, call });
+        };
+        const emitToolResult = async (result) => {
+            await hookObj.onToolResult?.(result);
+            await hookManager.emit('tool_result', { askId, turn: turns, result });
+        };
+        const emitTurnEnd = async (stats) => {
+            await hookObj.onTurnEnd?.(stats);
+            await hookManager.emit('turn_end', { askId, stats });
+        };
+        const finalizeAsk = async (text) => {
+            await hookManager.emit('ask_end', { askId, text, turns, toolCalls });
+            return { text, turns, toolCalls };
+        };
         const rawInstructionText = userContentToText(instruction).trim();
+        await hookManager.emit('ask_start', { askId, instruction: rawInstructionText });
         const projectDir = cfg.dir ?? process.cwd();
         const reviewKeys = reviewArtifactKeys(projectDir);
         const retrievalRequested = looksLikeReviewRetrievalRequest(rawInstructionText);
         const shouldPersistReviewArtifact = looksLikeCodeReviewRequest(rawInstructionText) && !retrievalRequested;
+        if (!retrievalRequested && cfg.initial_connection_check !== false && !initialConnectionProbeDone) {
+            if (typeof client.probeConnection === 'function') {
+                await client.probeConnection();
+                initialConnectionProbeDone = true;
+            }
+        }
         if (retrievalRequested) {
             const latest = vault
                 ? await vault.getLatestByKey(reviewKeys.latestKey, 'system').catch(() => null)
@@ -2023,37 +2103,37 @@ export async function createSession(opts) {
                         'Reply with "print stale review anyway" to override, or request a fresh review.';
                     messages.push({ role: 'assistant', content: blocked });
                     hookObj.onToken?.(blocked);
-                    await hookObj.onTurnEnd?.({
+                    await emitTurnEnd({
                         turn: turns,
                         toolCalls,
                         promptTokens: cumulativeUsage.prompt,
                         completionTokens: cumulativeUsage.completion,
                     });
-                    return { text: blocked, turns, toolCalls };
+                    return await finalizeAsk(blocked);
                 }
                 const text = stale
                     ? `${artifact.content}\n\n[artifact note] ${stale}`
                     : artifact.content;
                 messages.push({ role: 'assistant', content: text });
                 hookObj.onToken?.(text);
-                await hookObj.onTurnEnd?.({
+                await emitTurnEnd({
                     turn: turns,
                     toolCalls,
                     promptTokens: cumulativeUsage.prompt,
                     completionTokens: cumulativeUsage.completion,
                 });
-                return { text, turns, toolCalls };
+                return await finalizeAsk(text);
             }
             const miss = 'No stored full code review found yet. Ask me to run a code review first, then I can replay it verbatim.';
             messages.push({ role: 'assistant', content: miss });
             hookObj.onToken?.(miss);
-            await hookObj.onTurnEnd?.({
+            await emitTurnEnd({
                 turn: turns,
                 toolCalls,
                 promptTokens: cumulativeUsage.prompt,
                 completionTokens: cumulativeUsage.completion,
             });
-            return { text: miss, turns, toolCalls };
+            return await finalizeAsk(miss);
         }
         const persistReviewArtifact = async (finalText) => {
             if (!vault || !shouldPersistReviewArtifact)
@@ -2193,6 +2273,7 @@ export async function createSession(opts) {
                 if (inFlight?.signal?.aborted)
                     break;
                 turns++;
+                await hookManager.emit('turn_start', { askId, turn: turns });
                 const wallElapsed = (Date.now() - wallStart) / 1000;
                 if (wallElapsed > cfg.timeout) {
                     throw new Error(`session timeout exceeded (${cfg.timeout}s) after ${wallElapsed.toFixed(1)}s`);
@@ -2233,9 +2314,9 @@ export async function createSession(opts) {
                 const callerSignal = hookObj.signal;
                 const onCallerAbort = () => ac.abort();
                 callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
-                // Per-request timeout: the lesser of response_timeout (default 300s) or the remaining session wall time.
+                // Per-request timeout: the lesser of response_timeout (default 600s) or the remaining session wall time.
                 // This prevents a single slow request from consuming the entire session budget.
-                const perReqCap = cfg.response_timeout && cfg.response_timeout > 0 ? cfg.response_timeout : 300;
+                const perReqCap = cfg.response_timeout && cfg.response_timeout > 0 ? cfg.response_timeout : 600;
                 const wallRemaining = Math.max(0, cfg.timeout - (Date.now() - wallStart) / 1000);
                 const reqTimeout = Math.min(perReqCap, Math.max(10, wallRemaining));
                 const timer = setTimeout(() => ac.abort(), reqTimeout * 1000);
@@ -2389,7 +2470,7 @@ export async function createSession(opts) {
                         role: 'user',
                         content: '[system] Your previous response was empty (no text, no tool calls). Continue by either calling a tool with valid JSON arguments or giving a final answer.',
                     });
-                    await hookObj.onTurnEnd?.({
+                    await emitTurnEnd({
                         turn: turns,
                         toolCalls,
                         promptTokens: cumulativeUsage.prompt,
@@ -2638,8 +2719,8 @@ export async function createSession(opts) {
                             const searchTerm = typeof args.search === 'string' ? args.search : '';
                             // Fix 1: Hard cumulative budget — refuse reads past hard cap
                             if (cumulativeReadOnlyCalls > READ_BUDGET_HARD) {
-                                hookObj.onToolCall?.({ id: callId, name, args });
-                                hookObj.onToolResult?.({ id: callId, name, success: false, summary: 'read budget exhausted', result: '' });
+                                await emitToolCall({ id: callId, name, args });
+                                await emitToolResult({ id: callId, name, success: false, summary: 'read budget exhausted', result: '' });
                                 return { id: callId, content: `STOP: Read budget exhausted (${cumulativeReadOnlyCalls}/${READ_BUDGET_HARD} calls). Do NOT read more files. Use search_files or exec: grep -rn "pattern" path/ to find what you need.` };
                             }
                             // Fix 2: Directory scan detection — counts unique files per dir (re-reads are OK)
@@ -2654,8 +2735,8 @@ export async function createSession(opts) {
                                     blockedDirs.add(parentDir);
                                 }
                                 if (blockedDirs.has(parentDir) && uniqueCount > 8) {
-                                    hookObj.onToolCall?.({ id: callId, name, args });
-                                    hookObj.onToolResult?.({ id: callId, name, success: false, summary: 'dir scan blocked', result: '' });
+                                    await emitToolCall({ id: callId, name, args });
+                                    await emitToolResult({ id: callId, name, success: false, summary: 'dir scan blocked', result: '' });
                                     return { id: callId, content: `STOP: Directory scan detected — you've read ${uniqueCount} unique files from ${parentDir}/. Use search_files(pattern, '${parentDir}') or exec: grep -rn "pattern" ${parentDir}/ instead of reading files individually.` };
                                 }
                             }
@@ -2666,8 +2747,8 @@ export async function createSession(opts) {
                                     searchTermFiles.set(key, new Set());
                                 searchTermFiles.get(key).add(filePath);
                                 if (searchTermFiles.get(key).size >= 3) {
-                                    hookObj.onToolCall?.({ id: callId, name, args });
-                                    hookObj.onToolResult?.({ id: callId, name, success: false, summary: 'use search_files', result: '' });
+                                    await emitToolCall({ id: callId, name, args });
+                                    await emitToolResult({ id: callId, name, success: false, summary: 'use search_files', result: '' });
                                     return { id: callId, content: `STOP: You've searched ${searchTermFiles.get(key).size} files for "${searchTerm}" one at a time. This is what search_files does in one call. Use: search_files(pattern="${searchTerm}", path=".") or exec: grep -rn "${searchTerm}" .` };
                                 }
                             }
@@ -2689,12 +2770,12 @@ export async function createSession(opts) {
                             // Notify via confirmProvider.showBlocked if available
                             opts.confirmProvider?.showBlocked?.({ tool: name, args, reason: `plan mode: ${summary}` });
                             // Hook: onToolCall + onToolResult for plan-blocked actions
-                            hookObj.onToolCall?.({ id: callId, name, args });
-                            hookObj.onToolResult?.({ id: callId, name, success: true, summary: `⏸ ${summary} (blocked)`, result: blockedMsg });
+                            await emitToolCall({ id: callId, name, args });
+                            await emitToolResult({ id: callId, name, success: true, summary: `⏸ ${summary} (blocked)`, result: blockedMsg });
                             return { id: callId, content: blockedMsg };
                         }
                         // Hook: onToolCall (Phase 8.5)
-                        hookObj.onToolCall?.({ id: callId, name, args });
+                        await emitToolCall({ id: callId, name, args });
                         if (cfg.step_mode) {
                             const stepPrompt = `Step mode: execute ${name}(${JSON.stringify(args).slice(0, 200)}) ? [Y/n]`;
                             const ok = confirmBridge ? await confirmBridge(stepPrompt, { tool: name, args }) : true;
@@ -2815,7 +2896,7 @@ export async function createSession(opts) {
                             }
                             catch { }
                         }
-                        hookObj.onToolResult?.(resultEvent);
+                        await emitToolResult(resultEvent);
                         // Proactive LSP diagnostics after file mutations
                         if (lspManager?.hasServers() && lspCfg?.proactive_diagnostics !== false) {
                             if (FILE_MUTATION_TOOL_SET.has(name)) {
@@ -2843,7 +2924,7 @@ export async function createSession(opts) {
                     };
                     const results = [];
                     // Helper: catch tool errors but re-throw AgentLoopBreak (those must break the outer loop)
-                    const catchToolError = (e, tc) => {
+                    const catchToolError = async (e, tc) => {
                         if (e instanceof AgentLoopBreak)
                             throw e;
                         const msg = e?.message ?? String(e);
@@ -2877,7 +2958,7 @@ export async function createSession(opts) {
                         }
                         // Hook: onToolResult for errors (Phase 8.5)
                         const callId = resolveCallId(tc);
-                        hookObj.onToolResult?.({ id: callId, name: tc.function.name, success: false, summary: msg || 'unknown error', result: `ERROR: ${msg || 'unknown error'}` });
+                        await emitToolResult({ id: callId, name: tc.function.name, success: false, summary: msg || 'unknown error', result: `ERROR: ${msg || 'unknown error'}` });
                         // Never return undefined error text; it makes bench failures impossible to debug.
                         return { id: callId, content: `ERROR: ${msg || 'unknown tool error'}` };
                     };
@@ -2916,7 +2997,7 @@ export async function createSession(opts) {
                                 results.push(await runOne(tc));
                             }
                             catch (e) {
-                                results.push(catchToolError(e, tc));
+                                results.push(await catchToolError(e, tc));
                             }
                         }
                     }
@@ -2930,7 +3011,7 @@ export async function createSession(opts) {
                                 results.push(await runOne(tc));
                             }
                             catch (e) {
-                                results.push(catchToolError(e, tc));
+                                results.push(await catchToolError(e, tc));
                             }
                         }
                     }
@@ -2972,7 +3053,7 @@ export async function createSession(opts) {
                         });
                     }
                     // Hook: onTurnEnd (Phase 8.5)
-                    await hookObj.onTurnEnd?.({
+                    await emitTurnEnd({
                         turn: turns,
                         toolCalls,
                         promptTokens: cumulativeUsage.prompt,
@@ -3015,7 +3096,7 @@ export async function createSession(opts) {
                                     `Original task:\n${clippedReminder}\n\n` +
                                     `Call the needed tools directly. If everything is truly complete, provide the final answer.`
                             });
-                            await hookObj.onTurnEnd?.({
+                            await emitTurnEnd({
                                 turn: turns,
                                 toolCalls,
                                 promptTokens: cumulativeUsage.prompt,
@@ -3035,7 +3116,7 @@ export async function createSession(opts) {
                         role: 'user',
                         content: '[system] Continue executing the task. Use tools now (do not just narrate plans). If complete, give the final answer.'
                     });
-                    await hookObj.onTurnEnd?.({
+                    await emitTurnEnd({
                         turn: turns,
                         toolCalls,
                         promptTokens: cumulativeUsage.prompt,
@@ -3053,7 +3134,7 @@ export async function createSession(opts) {
                 // final assistant message
                 messages.push({ role: 'assistant', content: assistantText });
                 await persistReviewArtifact(assistantText).catch(() => { });
-                await hookObj.onTurnEnd?.({
+                await emitTurnEnd({
                     turn: turns,
                     toolCalls,
                     promptTokens: cumulativeUsage.prompt,
@@ -3065,7 +3146,7 @@ export async function createSession(opts) {
                     ppTps,
                     tgTps,
                 });
-                return { text: assistantText, turns, toolCalls };
+                return await finalizeAsk(assistantText);
             }
             const reason = `max iterations exceeded (${maxIters})`;
             const diag = lastSuccessfulTestRun
@@ -3091,6 +3172,12 @@ export async function createSession(opts) {
                 })();
                 const err = new Error(`BUG: threw undefined in agent.ask() (turn=${turns}). lastMsg=${lastMsg?.role ?? 'unknown'}:${lastMsgPreview}`);
                 await persistFailure(err, `ask turn ${turns}`);
+                await hookManager.emit('ask_error', {
+                    askId,
+                    error: err.message,
+                    turns,
+                    toolCalls,
+                });
                 throw err;
             }
             await persistFailure(e, `ask turn ${turns}`);
@@ -3100,8 +3187,21 @@ export async function createSession(opts) {
             }
             // Never rethrow undefined; normalize to Error for debuggability.
             if (e === undefined) {
-                throw new Error('BUG: threw undefined (normalized at ask() boundary)');
+                const normalized = new Error('BUG: threw undefined (normalized at ask() boundary)');
+                await hookManager.emit('ask_error', {
+                    askId,
+                    error: normalized.message,
+                    turns,
+                    toolCalls,
+                });
+                throw normalized;
             }
+            await hookManager.emit('ask_error', {
+                askId,
+                error: e instanceof Error ? e.message : String(e),
+                turns,
+                toolCalls,
+            });
             throw e;
         }
     };
@@ -3148,6 +3248,7 @@ export async function createSession(opts) {
         replay,
         vault,
         lens,
+        hookManager,
         get lastEditedPath() {
             return lastEditedPath;
         },