@visorcraft/idlehands 1.1.3 → 1.1.5

package/dist/agent.js

@@ -14,7 +14,8 @@ import { MCPManager } from './mcp.js';
 import { LspManager, detectInstalledLspServers } from './lsp.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { stateDir } from './utils.js';
+import { spawnSync } from 'node:child_process';
+import { stateDir, BASH_PATH as BASH } from './utils.js';
 function makeAbortController() {
     // Node 24: AbortController is global.
     return new AbortController();
@@ -115,6 +116,66 @@ function toolResultSummary(name, args, content, success) {
             return content.slice(0, 80);
     }
 }
+const CACHED_EXEC_OBSERVATION_HINT = '[idlehands hint] Reused cached output for repeated read-only exec call (unchanged observation).';
+function execCommandFromSig(sig) {
+    if (!sig.startsWith('exec:'))
+        return '';
+    const raw = sig.slice('exec:'.length);
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed?.command === 'string' ? parsed.command : '';
+    }
+    catch {
+        return '';
+    }
+}
+function looksLikeReadOnlyExecCommand(command) {
+    const cmd = String(command || '').trim().toLowerCase();
+    if (!cmd)
+        return false;
+    // Shell redirects are likely writes.
+    if (/(^|\s)(?:>>?|<<?)\s*/.test(cmd))
+        return false;
+    // Obvious mutators.
+    if (/\b(?:rm|mv|cp|touch|mkdir|rmdir|chmod|chown|truncate|dd)\b/.test(cmd))
+        return false;
+    if (/\b(?:sed|perl)\b[^\n]*\s-i\b/.test(cmd))
+        return false;
+    if (/\btee\b/.test(cmd))
+        return false;
+    // Git: allow common read-only subcommands, block mutating verbs.
+    if (/\bgit\b/.test(cmd)) {
+        if (/\bgit\b[^\n|;&]*\b(?:add|am|apply|bisect|checkout|switch|clean|clone|commit|fetch|merge|pull|push|rebase|reset|revert|stash)\b/.test(cmd)) {
+            return false;
+        }
+        if (/\bgit\b[^\n|;&]*\b(?:log|show|status|diff|rev-parse|branch(?:\s+--list)?|tag(?:\s+--list)?|ls-files|grep)\b/.test(cmd)) {
+            return true;
+        }
+    }
+    if (/^\s*(?:grep|rg|ag|ack|find|ls|cat|head|tail|wc|stat)\b/.test(cmd))
+        return true;
+    if (/\|\s*(?:grep|rg|ag|ack)\b/.test(cmd))
+        return true;
+    return false;
+}
+function withCachedExecObservationHint(content) {
+    if (!content)
+        return content;
+    try {
+        const parsed = JSON.parse(content);
+        const out = typeof parsed?.out === 'string' ? parsed.out : '';
+        if (out.includes(CACHED_EXEC_OBSERVATION_HINT))
+            return content;
+        parsed.out = out ? `${out}\n${CACHED_EXEC_OBSERVATION_HINT}` : CACHED_EXEC_OBSERVATION_HINT;
+        parsed.cached_observation = true;
+        return JSON.stringify(parsed);
+    }
+    catch {
+        if (content.includes(CACHED_EXEC_OBSERVATION_HINT))
+            return content;
+        return `${content}\n${CACHED_EXEC_OBSERVATION_HINT}`;
+    }
+}
 /** Errors that should break the outer agent loop, not be caught by per-tool handlers */
 class AgentLoopBreak extends Error {
     constructor(message) {
@@ -766,6 +827,123 @@ function userDisallowsDelegation(content) {
         /\b(?:spawn[_\-\s]?task|sub[\-\s]?agents?|delegate|delegation)\b[^\n.]{0,50}\b(?:do not|don't|dont|not allowed|forbidden|no)\b/.test(text);
     return negationNearDelegation;
 }
+function reviewArtifactKeys(projectDir) {
+    const { projectId } = projectIndexKeys(projectDir);
+    return {
+        projectId,
+        latestKey: `artifact:review:latest:${projectId}`,
+        byIdPrefix: `artifact:review:item:${projectId}:`,
+    };
+}
+function looksLikeCodeReviewRequest(text) {
+    const t = text.toLowerCase();
+    if (!t.trim())
+        return false;
+    if (/^\s*\/review\b/.test(t))
+        return true;
+    if (/\b(?:code\s+review|security\s+review|review\s+the\s+(?:code|diff|changes|repo|repository|pr)|audit\s+the\s+code)\b/.test(t))
+        return true;
+    return /\breview\b/.test(t) && /\b(?:code|repo|repository|diff|changes|pull\s*request|pr)\b/.test(t);
+}
+function looksLikeReviewRetrievalRequest(text) {
+    const t = text.toLowerCase();
+    if (!t.trim())
+        return false;
+    if (/^\s*\/review\s+(?:print|show|replay|latest|last|full)\b/.test(t))
+        return true;
+    if (!/\breview\b/.test(t))
+        return false;
+    if (/\bprint\s+stale\s+review\s+anyway\b/.test(t))
+        return true;
+    if (/\b(?:print|show|display|repeat|paste|send|output|give)\b[^\n.]{0,80}\breview\b[^\n.]{0,40}\b(?:again|back)\b/.test(t))
+        return true;
+    if (/\b(?:print|show|display|repeat|paste|send|output|give)\b[^\n.]{0,80}\b(?:full|entire|complete|whole)\b[^\n.]{0,80}\breview\b/.test(t))
+        return true;
+    if (/\b(?:full|entire|complete|whole)\b[^\n.]{0,30}\bcode\s+review\b/.test(t) && /\b(?:print|show|display|repeat|paste|send|output|give)\b/.test(t))
+        return true;
+    if (/\b(?:print|show|display|repeat|paste|send|output|give)\b[^\n.]{0,80}\b(?:last|latest|previous)\b[^\n.]{0,40}\breview\b/.test(t))
+        return true;
+    return false;
+}
+function retrievalAllowsStaleArtifact(text) {
+    const t = text.toLowerCase();
+    if (!t.trim())
+        return false;
+    if (/\bprint\s+stale\s+review\s+anyway\b/.test(t))
+        return true;
+    if (/\b(?:force|override|ignore)\b[^\n.]{0,80}\b(?:stale|old|previous)\b[^\n.]{0,80}\breview\b/.test(t))
+        return true;
+    if (/\b(?:stale|old|previous)\b[^\n.]{0,80}\breview\b[^\n.]{0,80}\b(?:anyway|still|force|override|ignore)\b/.test(t))
+        return true;
+    return false;
+}
+function parseReviewArtifactStalePolicy(raw) {
+    const v = typeof raw === 'string' ? raw.toLowerCase().trim() : '';
+    if (v === 'block')
+        return 'block';
+    return 'warn';
+}
+function parseReviewArtifact(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (parsed.kind !== 'code_review')
+            return null;
+        if (typeof parsed.id !== 'string' || !parsed.id)
+            return null;
+        if (typeof parsed.createdAt !== 'string' || !parsed.createdAt)
+            return null;
+        if (typeof parsed.model !== 'string')
+            return null;
+        if (typeof parsed.projectId !== 'string' || !parsed.projectId)
+            return null;
+        if (typeof parsed.projectDir !== 'string' || !parsed.projectDir)
+            return null;
+        if (typeof parsed.prompt !== 'string')
+            return null;
+        if (typeof parsed.content !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function gitHead(cwd) {
+    const inside = spawnSync(BASH, ['-lc', 'git rev-parse --is-inside-work-tree'], {
+        cwd,
+        encoding: 'utf8',
+        timeout: 1000,
+    });
+    if (inside.status !== 0 || !String(inside.stdout || '').trim().startsWith('true'))
+        return undefined;
+    const head = spawnSync(BASH, ['-lc', 'git rev-parse HEAD'], {
+        cwd,
+        encoding: 'utf8',
+        timeout: 1000,
+    });
+    if (head.status !== 0)
+        return undefined;
+    const sha = String(head.stdout || '').trim();
+    return sha || undefined;
+}
+function shortSha(sha) {
+    if (!sha)
+        return 'unknown';
+    return sha.slice(0, 8);
+}
+function reviewArtifactStaleReason(artifact, cwd) {
+    const currentHead = gitHead(cwd);
+    const currentDirty = isGitDirty(cwd);
+    if (artifact.gitHead && currentHead && artifact.gitHead !== currentHead) {
+        return `Stored review was generated at commit ${shortSha(artifact.gitHead)}; repository is now at ${shortSha(currentHead)}.`;
+    }
+    if (artifact.gitDirty === false && currentDirty) {
+        return 'Stored review was generated on a clean tree; working tree now has uncommitted changes.';
+    }
+    return '';
+}
 function supportsVisionModel(model, modelMeta, harness) {
     if (typeof harness.supportsVision === 'boolean')
         return harness.supportsVision;
@@ -917,7 +1095,11 @@ export async function createSession(opts) {
         mcpTools: mcpToolsLoaded ? (mcpManager?.getEnabledToolSchemas() ?? []) : [],
         allowSpawnTask: spawnTaskEnabled,
     });
-    const vault = vaultEnabled ? (opts.runtime?.vault ?? new VaultStore()) : undefined;
+    const vault = vaultEnabled
+        ? (opts.runtime?.vault ?? new VaultStore({
+            immutableReviewArtifactsPerProject: cfg?.trifecta?.vault?.immutable_review_artifacts_per_project,
+        }))
+        : undefined;
     if (vault) {
         // Scope vault entries by project directory to prevent cross-project context leaks
         vault.setProjectDir(cfg.dir ?? process.cwd());
@@ -1825,6 +2007,88 @@ export async function createSession(opts) {
         const hookObj = typeof hooks === 'function' ? { onToken: hooks } : hooks ?? {};
         let turns = 0;
         let toolCalls = 0;
+        const rawInstructionText = userContentToText(instruction).trim();
+        const projectDir = cfg.dir ?? process.cwd();
+        const reviewKeys = reviewArtifactKeys(projectDir);
+        const retrievalRequested = looksLikeReviewRetrievalRequest(rawInstructionText);
+        const shouldPersistReviewArtifact = looksLikeCodeReviewRequest(rawInstructionText) && !retrievalRequested;
+        if (retrievalRequested) {
+            const latest = vault
+                ? await vault.getLatestByKey(reviewKeys.latestKey, 'system').catch(() => null)
+                : null;
+            const parsedArtifact = latest?.value ? parseReviewArtifact(latest.value) : null;
+            const artifact = parsedArtifact && parsedArtifact.projectId === reviewKeys.projectId
+                ? parsedArtifact
+                : null;
+            if (artifact?.content?.trim()) {
+                const stale = reviewArtifactStaleReason(artifact, projectDir);
+                const stalePolicy = parseReviewArtifactStalePolicy(cfg?.trifecta?.vault?.stale_policy);
+                if (stale && stalePolicy === 'block' && !retrievalAllowsStaleArtifact(rawInstructionText)) {
+                    const blocked = `Stored review is stale and retrieval policy is set to block. ${stale}\n` +
+                        '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?.({
+                        turn: turns,
+                        toolCalls,
+                        promptTokens: cumulativeUsage.prompt,
+                        completionTokens: cumulativeUsage.completion,
+                    });
+                    return { text: blocked, turns, toolCalls };
+                }
+                const text = stale
+                    ? `${artifact.content}\n\n[artifact note] ${stale}`
+                    : artifact.content;
+                messages.push({ role: 'assistant', content: text });
+                hookObj.onToken?.(text);
+                await hookObj.onTurnEnd?.({
+                    turn: turns,
+                    toolCalls,
+                    promptTokens: cumulativeUsage.prompt,
+                    completionTokens: cumulativeUsage.completion,
+                });
+                return { text, turns, toolCalls };
+            }
+            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?.({
+                turn: turns,
+                toolCalls,
+                promptTokens: cumulativeUsage.prompt,
+                completionTokens: cumulativeUsage.completion,
+            });
+            return { text: miss, turns, toolCalls };
+        }
+        const persistReviewArtifact = async (finalText) => {
+            if (!vault || !shouldPersistReviewArtifact)
+                return;
+            const clean = finalText.trim();
+            if (!clean)
+                return;
+            const createdAt = new Date().toISOString();
+            const id = `review-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+            const artifact = {
+                id,
+                kind: 'code_review',
+                createdAt,
+                model,
+                projectId: reviewKeys.projectId,
+                projectDir,
+                prompt: rawInstructionText.slice(0, 2000),
+                content: clean,
+                gitHead: gitHead(projectDir),
+                gitDirty: isGitDirty(projectDir),
+            };
+            try {
+                const raw = JSON.stringify(artifact);
+                await vault.upsertNote(reviewKeys.latestKey, raw, 'system');
+                await vault.upsertNote(`${reviewKeys.byIdPrefix}${artifact.id}`, raw, 'system');
+            }
+            catch {
+                // best effort only
+            }
+        };
         // Read-only tool call budgets (§ anti-scan guardrails)
         const READ_ONLY_PER_TURN_CAP = 6;
         const READ_BUDGET_WARN = 15;
@@ -1855,6 +2119,10 @@ export async function createSession(opts) {
         let repromptUsed = false;
         // Track blocked command loops by exact reason+command signature.
         const blockedExecAttemptsBySig = new Map();
+        // Cache successful read-only exec observations by exact signature.
+        const execObservationCacheBySig = new Map();
+        // Prevent repeating the same "stop rerunning" reminder every turn.
+        const readOnlyExecHintedSigs = new Set();
         // Keep a lightweight breadcrumb for diagnostics on partial failures.
         let lastSuccessfulTestRun = null;
         // One-time nudge to prevent post-success churn after green test runs.
@@ -2236,6 +2504,9 @@ export async function createSession(opts) {
                         const sig = `${tc.function.name}:${tc.function.arguments ?? '{}'}`;
                         turnSigs.add(sig);
                     }
+                    // Repeated read-only exec calls can be served from cache instead of hard-breaking.
+                    const repeatedReadOnlyExecSigs = new Set();
+                    const readOnlyExecTurnHints = [];
                     // Track whether a mutation happened since a given signature was last seen.
                     // (Tool-loop is single-threaded across turns; this is safe to keep in-memory.)
                     for (const sig of turnSigs) {
@@ -2257,6 +2528,17 @@ export async function createSession(opts) {
                                     await injectVaultContext().catch(() => { });
                                 }
                                 if (count >= loopThreshold) {
+                                    const command = execCommandFromSig(sig);
+                                    const canReuseReadOnlyObservation = looksLikeReadOnlyExecCommand(command) &&
+                                        execObservationCacheBySig.has(sig);
+                                    if (canReuseReadOnlyObservation) {
+                                        repeatedReadOnlyExecSigs.add(sig);
+                                        if (!readOnlyExecHintedSigs.has(sig)) {
+                                            readOnlyExecHintedSigs.add(sig);
+                                            readOnlyExecTurnHints.push(command || 'exec command');
+                                        }
+                                        continue;
+                                    }
                                     const args = sig.slice(toolName.length + 1);
                                     const argsPreview = args.length > 220 ? args.slice(0, 220) + '…' : args;
                                     throw new Error(`tool ${toolName}: identical call repeated ${loopThreshold}x across turns; breaking loop. ` +
@@ -2425,72 +2707,88 @@ export async function createSession(opts) {
                                 return { id: callId, content: '[skipped by user: step mode]' };
                             }
                         }
+                        const sig = `${name}:${rawArgs || '{}'}`;
                         let content = '';
-                        if (isSpawnTask) {
-                            content = await runSpawnTask(args);
+                        let reusedCachedReadOnlyExec = false;
+                        if (name === 'exec' && repeatedReadOnlyExecSigs.has(sig)) {
+                            const cached = execObservationCacheBySig.get(sig);
+                            if (cached) {
+                                content = withCachedExecObservationHint(cached);
+                                reusedCachedReadOnlyExec = true;
+                            }
                         }
-                        else if (builtInFn) {
-                            const value = await builtInFn(ctx, args);
-                            content = typeof value === 'string' ? value : JSON.stringify(value);
-                            if (name === 'exec') {
-                                // Successful exec clears blocked-loop counters.
-                                blockedExecAttemptsBySig.clear();
-                                // Capture successful test runs for better partial-failure diagnostics.
-                                try {
-                                    const parsed = JSON.parse(content);
+                        if (!reusedCachedReadOnlyExec) {
+                            if (isSpawnTask) {
+                                content = await runSpawnTask(args);
+                            }
+                            else if (builtInFn) {
+                                const value = await builtInFn(ctx, args);
+                                content = typeof value === 'string' ? value : JSON.stringify(value);
+                                if (name === 'exec') {
+                                    // Successful exec clears blocked-loop counters.
+                                    blockedExecAttemptsBySig.clear();
                                     const cmd = String(args?.command ?? '');
-                                    const out = String(parsed?.out ?? '');
-                                    const rc = Number(parsed?.rc ?? NaN);
-                                    const looksLikeTest = /(^|\s)(node\s+--test|npm\s+test|pnpm\s+test|yarn\s+test|pytest|go\s+test|cargo\s+test|ctest)(\s|$)/i.test(cmd);
-                                    if (looksLikeTest && Number.isFinite(rc) && rc === 0) {
-                                        lastSuccessfulTestRun = {
-                                            command: cmd,
-                                            outputPreview: out.slice(0, 400),
-                                        };
+                                    if (looksLikeReadOnlyExecCommand(cmd)) {
+                                        execObservationCacheBySig.set(sig, content);
+                                    }
+                                    // Capture successful test runs for better partial-failure diagnostics.
+                                    try {
+                                        const parsed = JSON.parse(content);
+                                        const out = String(parsed?.out ?? '');
+                                        const rc = Number(parsed?.rc ?? NaN);
+                                        const looksLikeTest = /(^|\s)(node\s+--test|npm\s+test|pnpm\s+test|yarn\s+test|pytest|go\s+test|cargo\s+test|ctest)(\s|$)/i.test(cmd);
+                                        if (looksLikeTest && Number.isFinite(rc) && rc === 0) {
+                                            lastSuccessfulTestRun = {
+                                                command: cmd,
+                                                outputPreview: out.slice(0, 400),
+                                            };
+                                        }
+                                    }
+                                    catch {
+                                        // Ignore parse issues; non-JSON exec output is tolerated.
                                     }
                                 }
-                                catch {
-                                    // Ignore parse issues; non-JSON exec output is tolerated.
-                                }
-                            }
-                        }
-                        else if (isLspTool && lspManager) {
-                            // LSP tool dispatch
-                            if (name === 'lsp_diagnostics') {
-                                content = await lspManager.getDiagnostics(typeof args.path === 'string' ? args.path : undefined, typeof args.severity === 'number' ? args.severity : undefined);
-                            }
-                            else if (name === 'lsp_symbols') {
-                                content = await buildLspLensSymbolOutput(String(args.path ?? ''));
                             }
-                            else if (name === 'lsp_hover') {
-                                content = await lspManager.getHover(String(args.path ?? ''), Number(args.line ?? 0), Number(args.character ?? 0));
-                            }
-                            else if (name === 'lsp_definition') {
-                                content = await lspManager.getDefinition(String(args.path ?? ''), Number(args.line ?? 0), Number(args.character ?? 0));
-                            }
-                            else if (name === 'lsp_references') {
-                                content = await lspManager.getReferences(String(args.path ?? ''), Number(args.line ?? 0), Number(args.character ?? 0), typeof args.max_results === 'number' ? args.max_results : 50);
-                            }
-                        }
-                        else {
-                            if (mcpManager == null) {
-                                throw new Error(`unknown tool: ${name}`);
+                            else if (isLspTool && lspManager) {
+                                // LSP tool dispatch
+                                if (name === 'lsp_diagnostics') {
+                                    content = await lspManager.getDiagnostics(typeof args.path === 'string' ? args.path : undefined, typeof args.severity === 'number' ? args.severity : undefined);
+                                }
+                                else if (name === 'lsp_symbols') {
+                                    content = await buildLspLensSymbolOutput(String(args.path ?? ''));
+                                }
+                                else if (name === 'lsp_hover') {
+                                    content = await lspManager.getHover(String(args.path ?? ''), Number(args.line ?? 0), Number(args.character ?? 0));
+                                }
+                                else if (name === 'lsp_definition') {
+                                    content = await lspManager.getDefinition(String(args.path ?? ''), Number(args.line ?? 0), Number(args.character ?? 0));
+                                }
+                                else if (name === 'lsp_references') {
+                                    content = await lspManager.getReferences(String(args.path ?? ''), Number(args.line ?? 0), Number(args.character ?? 0), typeof args.max_results === 'number' ? args.max_results : 50);
+                                }
                             }
-                            const mcpReadOnly = isReadOnlyToolDynamic(name);
-                            if (!cfg.step_mode && !ctx.noConfirm && !mcpReadOnly) {
-                                const prompt = `Execute MCP tool '${name}'? [Y/n]`;
-                                const ok = confirmBridge ? await confirmBridge(prompt, { tool: name, args }) : true;
-                                if (!ok) {
-                                    return { id: callId, content: '[skipped by user: approval]' };
+                            else {
+                                if (mcpManager == null) {
+                                    throw new Error(`unknown tool: ${name}`);
+                                }
+                                const mcpReadOnly = isReadOnlyToolDynamic(name);
+                                if (!cfg.step_mode && !ctx.noConfirm && !mcpReadOnly) {
+                                    const prompt = `Execute MCP tool '${name}'? [Y/n]`;
+                                    const ok = confirmBridge ? await confirmBridge(prompt, { tool: name, args }) : true;
+                                    if (!ok) {
+                                        return { id: callId, content: '[skipped by user: approval]' };
+                                    }
                                 }
+                                const callArgs = args && typeof args === 'object' && !Array.isArray(args)
+                                    ? args
+                                    : {};
+                                content = await mcpManager.callTool(name, callArgs);
                             }
-                            const callArgs = args && typeof args === 'object' && !Array.isArray(args)
-                                ? args
-                                : {};
-                            content = await mcpManager.callTool(name, callArgs);
                         }
                         // Hook: onToolResult (Phase 8.5 + Phase 7 rich display)
-                        const summary = toolResultSummary(name, args, content, true);
+                        const summary = reusedCachedReadOnlyExec
+                            ? 'cached read-only exec observation (unchanged)'
+                            : toolResultSummary(name, args, content, true);
                         const resultEvent = { id: callId, name, success: true, summary, result: content };
                         // Phase 7: populate rich display fields
                         if (name === 'exec') {
@@ -2647,6 +2945,18 @@ export async function createSession(opts) {
                     for (const r of results) {
                         messages.push({ role: 'tool', tool_call_id: r.id, content: r.content });
                     }
+                    if (readOnlyExecTurnHints.length) {
+                        const previews = readOnlyExecTurnHints
+                            .slice(0, 2)
+                            .map((cmd) => cmd.length > 140 ? `${cmd.slice(0, 140)}…` : cmd)
+                            .join(' | ');
+                        messages.push({
+                            role: 'user',
+                            content: '[system] You repeated an identical read-only exec command with unchanged arguments. ' +
+                                `Idle Hands reused cached observation output instead of rerunning it (${previews}). ` +
+                                'Do not call the same read-only command again unless files/history changed; proceed with analysis or final answer.',
+                        });
+                    }
                     // If tests are green and we've already made edits, nudge for final summary
                     // once to avoid extra non-essential demo/cleanup turns.
                     if (!finalizeAfterTestsNudgeUsed && lastSuccessfulTestRun && mutationVersion > 0) {
@@ -2747,6 +3057,7 @@ export async function createSession(opts) {
                 noToolTurns = 0;
                 // final assistant message
                 messages.push({ role: 'assistant', content: assistantText });
+                await persistReviewArtifact(assistantText).catch(() => { });
                 await hookObj.onTurnEnd?.({
                     turn: turns,
                     toolCalls,