iranti 0.3.21 → 0.3.23

package/dist/src/attendant/AttendantInstance.js

@@ -7,8 +7,10 @@ exports.extractRuleTriggers = extractRuleTriggers;
 exports.matchesRuleTriggers = matchesRuleTriggers;
 exports.formatMatchedUserRules = formatMatchedUserRules;
 exports.extractFilePathEntityHints = extractFilePathEntityHints;
+exports.derivePendingToolCallEntityHints = derivePendingToolCallEntityHints;
 exports.readPersistedSessionState = readPersistedSessionState;
 exports.summarizeSessionState = summarizeSessionState;
+exports.injectedFactsAreTaskRelevant = injectedFactsAreTaskRelevant;
 const crypto_1 = require("crypto");
 const router_1 = require("../lib/router");
 const staffEventRegistry_1 = require("../lib/staffEventRegistry");
@@ -59,6 +61,11 @@ const SESSION_INTERRUPTION_TTL_MS = 5 * 60 * 1000;
 const PERSISTENCE_WARNING_THRESHOLD = 3;
 const PERSISTENCE_NON_COMPLIANT_THRESHOLD = 5;
 const ENTITY_DETECTION_WINDOW_CHARS = 1500;
+// A1: mid-turn attends default to a smaller fact budget than pre-response.
+// The agent is already deep in the task with a working memory frame; the point
+// of a mid-turn attend is to surface 1-3 NEW facts on a topic shift, not to
+// re-dump the whole briefing.
+const MID_TURN_DEFAULT_MAX_FACTS = 3;
 const MIN_ENTITY_CONFIDENCE = 0.75;
 const MEMORY_DECISION_CONTEXT_WINDOW_CHARS = 2000;
 const LEDGER_WORKING_MEMORY_PREFIX = 'system/session_ledger/recent_learning_';
@@ -446,6 +453,174 @@ function extractFilePathEntityHints(text, projectEntity) {
     }
     return hints;
 }
+// ─── A2: Pending Tool-Call Entity Hints ─────────────────────────────────────
+//
+// Derive entity hints from a structured tool call that the agent is about to
+// make. This lets attend() preempt redundant read-only tool calls by surfacing
+// stored facts keyed to the target of the tool call (a file, a URL, a query).
+//
+// We deliberately keep this a PURE function so it is trivially unit-testable
+// and so the caller can exercise different tool shapes without spinning up an
+// attendant. It returns entity hints in `entityType/entityId` form.
+function normalizeWebToken(value, maxLen = 48) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, maxLen);
+}
+function deriveFileEntityFromPath(rawPath, projectId, seen, hints) {
+    const trimmed = rawPath.trim();
+    if (!trimmed)
+        return;
+    const basename = trimmed.replace(/\\/g, '/').split('/').pop() ?? '';
+    // Strip trailing args like "foo.ts:42" or "foo.ts,bar.ts"
+    const stripped = basename.split(/[,:()]/)[0] ?? basename;
+    const nameWithoutExt = stripped
+        .replace(/\.\w+$/, '')
+        .replace(/[^a-zA-Z0-9]/g, '_')
+        .toLowerCase();
+    if (!nameWithoutExt || nameWithoutExt.length < 2)
+        return;
+    const hint = `project/${projectId}/file/${nameWithoutExt}`;
+    if (!seen.has(hint)) {
+        seen.add(hint);
+        hints.push(hint);
+    }
+}
+function scanStringForPathEntities(text, projectId, seen, hints) {
+    if (!text)
+        return;
+    FILE_PATH_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = FILE_PATH_PATTERN.exec(text)) !== null) {
+        deriveFileEntityFromPath(match[1], projectId, seen, hints);
+    }
+}
+function extractBasenameFromGlobPattern(pattern) {
+    // A glob like "src/**/*.ts" has no meaningful basename; one like
+    // "tests/attendant/run_mid_turn_attend_tests.ts" does. We only derive a
+    // file entity from the last segment if it looks like a literal filename.
+    const segments = pattern.replace(/\\/g, '/').split('/');
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const seg = segments[i];
+        if (!seg || seg.includes('*') || seg.includes('?') || seg === '.' || seg === '..')
+            continue;
+        if (/\.\w+$/.test(seg))
+            return seg;
+    }
+    return null;
+}
+/**
+ * Derive entity hints from a pending tool call. Pure, stateless, safe to call
+ * from tests. Callers should merge the result into `effectiveEntityHints`
+ * *after* text-derived hints so text signals still take precedence when a hint
+ * appears in both places.
+ */
+function derivePendingToolCallEntityHints(toolCall, projectEntity) {
+    if (!toolCall || !projectEntity)
+        return [];
+    const parsed = (0, entity_resolution_1.parseEntityString)(projectEntity);
+    const projectId = parsed.entityId;
+    if (!projectId)
+        return [];
+    const args = (toolCall.args ?? {});
+    const seen = new Set();
+    const hints = [];
+    switch (toolCall.name) {
+        case 'Read': {
+            const filePath = typeof args.file_path === 'string' ? args.file_path : '';
+            if (filePath) {
+                deriveFileEntityFromPath(filePath, projectId, seen, hints);
+            }
+            break;
+        }
+        case 'Grep': {
+            // Grep has pattern + optional path + optional glob. Only path/glob
+            // can yield file-level entities; the regex pattern itself is
+            // content-level and gets surfaced via the existing text hints from
+            // latestMessage/currentContext.
+            if (typeof args.path === 'string') {
+                deriveFileEntityFromPath(args.path, projectId, seen, hints);
+            }
+            if (typeof args.glob === 'string') {
+                const base = extractBasenameFromGlobPattern(args.glob);
+                if (base)
+                    deriveFileEntityFromPath(base, projectId, seen, hints);
+            }
+            break;
+        }
+        case 'Glob': {
+            if (typeof args.pattern === 'string') {
+                const base = extractBasenameFromGlobPattern(args.pattern);
+                if (base)
+                    deriveFileEntityFromPath(base, projectId, seen, hints);
+                // If the pattern has no literal basename, fall through to the
+                // project entity so stored project-level facts still surface.
+            }
+            if (typeof args.path === 'string') {
+                deriveFileEntityFromPath(args.path, projectId, seen, hints);
+            }
+            break;
+        }
+        case 'Bash': {
+            // Scan the command string for embedded paths. This covers
+            // `cat src/foo.ts`, `rm ./dist/bar.js`, `node scripts/baz.ts`, etc.
+            const command = typeof args.command === 'string' ? args.command : '';
+            scanStringForPathEntities(command, projectId, seen, hints);
+            break;
+        }
+        case 'WebSearch': {
+            const query = typeof args.query === 'string' ? args.query : '';
+            const token = normalizeWebToken(query);
+            if (token) {
+                const hint = `web/search_${token}`;
+                if (!seen.has(hint)) {
+                    seen.add(hint);
+                    hints.push(hint);
+                }
+            }
+            break;
+        }
+        case 'WebFetch': {
+            const url = typeof args.url === 'string' ? args.url : '';
+            if (url) {
+                try {
+                    const parsedUrl = new URL(url);
+                    const host = normalizeWebToken(parsedUrl.hostname);
+                    if (host) {
+                        const hostHint = `web/${host}`;
+                        if (!seen.has(hostHint)) {
+                            seen.add(hostHint);
+                            hints.push(hostHint);
+                        }
+                    }
+                    const path = normalizeWebToken(parsedUrl.pathname);
+                    if (host && path && path.length >= 2) {
+                        const pathHint = `web/${host}_${path}`;
+                        if (!seen.has(pathHint)) {
+                            seen.add(pathHint);
+                            hints.push(pathHint);
+                        }
+                    }
+                }
+                catch {
+                    // Non-URL string — fall back to a normalized token entity.
+                    const token = normalizeWebToken(url);
+                    if (token) {
+                        const hint = `web/${token}`;
+                        if (!seen.has(hint)) {
+                            seen.add(hint);
+                            hints.push(hint);
+                        }
+                    }
+                }
+            }
+            break;
+        }
+    }
+    return hints;
+}
 function advisoryTaskTokens(taskType) {
     if (!taskType)
         return [];
@@ -931,6 +1106,38 @@ function tokenize(text) {
         .map((part) => part.trim())
         .filter((part) => part.length > 2);
 }
+/**
+ * Determine whether injected facts are relevant to the current task context.
+ * Uses token overlap between the task description and fact keys/summaries.
+ * Exported for unit testing.
+ */
+function injectedFactsAreTaskRelevant(taskContext, injectedKeys, injectedSummaries) {
+    if (!taskContext)
+        return true;
+    const taskTokens = new Set(tokenize(taskContext));
+    if (taskTokens.size === 0)
+        return true;
+    for (const entityKey of injectedKeys) {
+        const key = entityKey.split('/').slice(2).join('/');
+        for (const token of tokenize(key.replace(/[_/.-]+/g, ' '))) {
+            if (taskTokens.has(token))
+                return true;
+        }
+    }
+    if (injectedSummaries && injectedSummaries.length > 0) {
+        const contentTokens = injectedSummaries
+            .flatMap((s) => tokenize(s).filter((t) => t.length > 5));
+        let contentMatches = 0;
+        for (const token of contentTokens) {
+            if (taskTokens.has(token)) {
+                contentMatches++;
+                if (contentMatches >= 2)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
 function tokenizeForSearch(text) {
     return tokenize(text).filter((token) => !SEARCH_SUGGESTION_STOPWORDS.has(token));
 }
@@ -1512,6 +1719,7 @@ class AttendantInstance {
             injectedEntryIds: [...input.injectedEntryIds],
             injectedSummaries: input.injectedSummaries ? [...input.injectedSummaries] : undefined,
             evidenceKinds: [],
+            taskContext: input.taskContext,
         };
         this.pendingMemoryAttributions.push(attribution);
         this.updateBriefPendingMemoryAttributions();
@@ -1582,6 +1790,9 @@ class AttendantInstance {
                 && /\b(next_step|current_step|open_risks|status|checkpoint_summary|recent_file_changes|recent_actions|implementation_status|blockers?)\b/i.test(key));
         });
     }
+    checkInjectedFactsTaskRelevant(attribution) {
+        return injectedFactsAreTaskRelevant(attribution.taskContext, attribution.injectedKeys, attribution.injectedSummaries);
+    }
     scorePendingMemoryAttributions(response) {
         if (this.pendingMemoryAttributions.length === 0) {
             return [];
@@ -1596,18 +1807,27 @@ class AttendantInstance {
             if (!rediscoveredManually && this.responseShowsRecoveryValue(response, entry) && !evidenceKinds.includes('response_recovery')) {
                 evidenceKinds.push('response_recovery');
             }
+            // Check task-relevance: if facts are not relevant to the current task,
+            // mark as task_irrelevant so the compliance scorer does not penalize.
+            const taskRelevant = this.checkInjectedFactsTaskRelevant(entry);
+            if (!taskRelevant && !evidenceKinds.includes('task_irrelevant')) {
+                evidenceKinds.push('task_irrelevant');
+            }
             const used = evidenceKinds.includes('write')
                 || evidenceKinds.includes('checkpoint')
                 || evidenceKinds.includes('response_reference')
-                || evidenceKinds.includes('response_recovery');
+                || evidenceKinds.includes('response_recovery')
+                || evidenceKinds.includes('task_irrelevant');
             const helpful = evidenceKinds.includes('checkpoint')
                 || evidenceKinds.includes('write')
                 || evidenceKinds.includes('response_recovery');
             const reason = helpful
                 ? 'response_or_action_confirmed_memory_helpfulness'
-                : used
-                    ? 'response_referenced_injected_memory'
-                    : 'memory_was_only_surfaced';
+                : evidenceKinds.includes('task_irrelevant')
+                    ? 'injected_facts_not_relevant_to_current_task'
+                    : used
+                        ? 'response_referenced_injected_memory'
+                        : 'memory_was_only_surfaced';
             const scoredEntry = {
                 ...entry,
                 used,
@@ -2277,11 +2497,22 @@ class AttendantInstance {
         const baseEntityHints = this.resolveAttendEntityHints(input.entityHints, latestMessage);
         // File-change demand-driven recall: extract file path mentions and add as entity hints
         const filePathHints = extractFilePathEntityHints(`${latestMessage}\n${currentContext}`, (0, autoRemember_1.getProjectMemoryEntity)() ?? null);
-        const effectiveEntityHints = filePathHints.length > 0
-            ? [...new Set([...baseEntityHints, ...filePathHints])]
-            : baseEntityHints;
-        // User operating rules: load rules whose triggers match the current context
-        const matchedUserRules = phase !== 'post-response'
+        // A2: tool-call triggered retrieval. If the caller says "I'm about to
+        // run Read(file_path=X) / Grep / Bash / WebFetch / WebSearch", derive
+        // structured entity hints from the tool arguments BEFORE the tool
+        // runs, so stored facts can preempt the lookup.
+        const toolCallHints = derivePendingToolCallEntityHints(input.pendingToolCall, (0, autoRemember_1.getProjectMemoryEntity)() ?? null);
+        const allExtraHints = filePathHints.length === 0 && toolCallHints.length === 0
+            ? null
+            : [...filePathHints, ...toolCallHints];
+        const effectiveEntityHints = allExtraHints === null
+            ? baseEntityHints
+            : [...new Set([...baseEntityHints, ...allExtraHints])];
+        // User operating rules: load rules whose triggers match the current context.
+        // Mid-turn attends skip this — rules were already surfaced at pre-response,
+        // and reloading them on every mid-turn call would duplicate context and burn
+        // an LLM call on the trigger match.
+        const matchedUserRules = (phase !== 'post-response' && phase !== 'mid-turn')
             ? await this.loadMatchingUserRules(`${latestMessage}\n${currentContext}`)
             : [];
         let watchedEntitiesChanged = this.updateWatchedEntities(effectiveEntityHints);
@@ -2401,6 +2632,17 @@ class AttendantInstance {
                 await this.persistState();
             }
             (0, metrics_1.timeEnd)('attendant.attend_ms', t0);
+            // A2: even on the "memory not needed" early return, if the caller
+            // passed pendingToolCall, echo the derived entities so the agent
+            // can see that attend() was tool-call-aware on this call.
+            const skipGuidance = input.pendingToolCall
+                ? {
+                    toolName: input.pendingToolCall.name,
+                    derivedEntities: toolCallHints,
+                    factCount: 0,
+                    note: `Memory was not deemed necessary for this ${input.pendingToolCall.name} call. Proceed.`,
+                }
+                : undefined;
             return {
                 shouldInject: matchedUserRules.length > 0,
                 reason: 'memory_not_needed',
@@ -2426,21 +2668,28 @@ class AttendantInstance {
                     hintsResolved: 0,
                     dropped: [{ name: latestMessage || '(none)', reason: 'memory_not_needed' }],
                 },
+                toolCallGuidance: skipGuidance,
             };
         }
         // Post-compaction recovery: re-surface facts that were recently injected (likely in context
         // just before the compact) without blocking them on the already-in-context filter.
         // The flag is set by handshake(postCompaction:true) and consumed exactly once here.
         const postCompactionRecoveryKeys = [];
-        let postCompactionMaxFacts = input.maxFacts;
+        let effectiveMaxFacts = input.maxFacts;
         if (this.postCompactionPending) {
             const recentInjections = this.pendingMemoryAttributions.slice(-5);
             for (const attr of recentInjections) {
                 postCompactionRecoveryKeys.push(...attr.injectedKeys);
             }
-            postCompactionMaxFacts = Math.min((input.maxFacts ?? 5) * 2, 10);
+            effectiveMaxFacts = Math.min((input.maxFacts ?? 5) * 2, 10);
             this.postCompactionPending = false;
         }
+        else if (phase === 'mid-turn' && input.maxFacts === undefined) {
+            // A1: mid-turn attends default to a smaller fact budget than pre-response.
+            // The agent already has a working-memory frame from the pre-response attend;
+            // mid-turn is about surfacing 1-3 NEW facts on a topic shift, not re-dumping briefs.
+            effectiveMaxFacts = MID_TURN_DEFAULT_MAX_FACTS;
+        }
         const observeEntityHints = effectiveEntityHints.length > 0 ? effectiveEntityHints : freshState.entities;
         const allObserveEntityHints = postCompactionRecoveryKeys.length > 0
             ? [...new Set([
@@ -2453,7 +2702,7 @@ class AttendantInstance {
             : observeEntityHints;
         const observed = await this.observe({
             currentContext: observationContext,
-            maxFacts: postCompactionMaxFacts,
+            maxFacts: effectiveMaxFacts,
             entityHints: allObserveEntityHints,
             priorityKeys: expandContinuityPriorityKeys(Array.from(new Set([
                 ...(mandatoryRecall.key ? [mandatoryRecall.key] : []),
@@ -2477,7 +2726,31 @@ class AttendantInstance {
             const remainder = slashIdx2 === -1 ? '' : fact.entityKey.slice(slashIdx2);
             return { ...fact, entityKey: `${canonicalPersonalType}/${canonicalPersonalId}${remainder}` };
         });
-        const structuredFacts = (0, hostMemoryFormatting_1.assignStructuredFactIds)(remappedFacts);
+        // A1: mid-turn dedup — drop facts whose entityKey was already injected earlier
+        // in the SAME turn. pendingMemoryAttributions is reset at post-response, so any
+        // entry in that list belongs to the current turn. This prevents mid-turn attends
+        // from spamming the agent with facts it already has in working memory from a
+        // previous pre-response or mid-turn attend call.
+        const midTurnFilteredKeys = [];
+        let factsAfterDedup = remappedFacts;
+        if (phase === 'mid-turn' && this.pendingMemoryAttributions.length > 0) {
+            const alreadyInjectedThisTurn = new Set();
+            for (const attr of this.pendingMemoryAttributions) {
+                for (const key of attr.injectedKeys) {
+                    alreadyInjectedThisTurn.add(key);
+                }
+            }
+            if (alreadyInjectedThisTurn.size > 0) {
+                factsAfterDedup = remappedFacts.filter((fact) => {
+                    if (alreadyInjectedThisTurn.has(fact.entityKey)) {
+                        midTurnFilteredKeys.push(fact.entityKey);
+                        return false;
+                    }
+                    return true;
+                });
+            }
+        }
+        const structuredFacts = (0, hostMemoryFormatting_1.assignStructuredFactIds)(factsAfterDedup);
         watchedEntitiesChanged = this.updateWatchedEntities(observed.entitiesResolved?.map((entry) => entry.canonicalEntity) ?? []) || watchedEntitiesChanged;
         this.markSharedStateObserved(observeEntityHints.length > 0 ? observeEntityHints : freshState.entities);
         let reason = 'memory_needed_injected';
@@ -2486,8 +2759,14 @@ class AttendantInstance {
         const memoryResultsConsidered = observed.totalFound;
         let searchSuggestion;
         if (!shouldInject) {
+            // A1: if mid-turn dedup ate everything observe returned, treat it as
+            // "already in context" — the agent has these facts from an earlier attend.
+            const allDroppedByMidTurnDedup = phase === 'mid-turn'
+                && midTurnFilteredKeys.length > 0
+                && remappedFacts.length > 0
+                && factsAfterDedup.length === 0;
             const allAlreadyInContext = observed.totalFound > 0 && observed.alreadyPresent >= observed.totalFound;
-            reason = allAlreadyInContext ? 'memory_needed_but_in_context' : 'memory_checked_no_match';
+            reason = (allAlreadyInContext || allDroppedByMidTurnDedup) ? 'memory_needed_but_in_context' : 'memory_checked_no_match';
             if (reason === 'memory_checked_no_match') {
                 const terms = tokenizeForSearch(latestMessage).slice(0, 6);
                 const alternativeEntities = (observed.entitiesResolved ?? [])
@@ -2514,11 +2793,34 @@ class AttendantInstance {
                         .map((fact) => fact.knowledgeEntryId)
                         .filter((value) => typeof value === 'number'),
                     injectedSummaries: structuredFacts.map((fact) => fact.summary).filter(Boolean),
+                    taskContext: this.brief?.inferredTaskType,
                 }),
             ]
             : [];
+        // A1: when mid-turn dedup filtered keys, surface them in debug so the
+        // caller (and tests) can reason about which facts were suppressed.
+        const debugWithMidTurn = (midTurnFilteredKeys.length > 0 && observed.debug)
+            ? { ...observed.debug, midTurnFilteredKeys: [...midTurnFilteredKeys] }
+            : observed.debug;
+        // A2: if the caller supplied pendingToolCall, surface a guidance block
+        // so the agent can see what entities were derived and how many stored
+        // facts preempted the lookup. Only populated when a tool call was
+        // actually passed — no allocation overhead for the common path.
+        const toolCallGuidance = input.pendingToolCall
+            ? {
+                toolName: input.pendingToolCall.name,
+                derivedEntities: toolCallHints,
+                factCount: structuredFacts.length,
+                note: toolCallHints.length === 0
+                    ? `No entity hints derived from ${input.pendingToolCall.name} args. Memory check ran on message/context only.`
+                    : structuredFacts.length > 0
+                        ? `Iranti surfaced ${structuredFacts.length} stored fact(s) for this ${input.pendingToolCall.name} call. Read them before running the tool — you may not need to run it.`
+                        : `No stored facts matched the ${input.pendingToolCall.name} target. Proceed with the tool call.`,
+            }
+            : undefined;
         const attendResult = {
             ...observed,
+            debug: debugWithMidTurn,
             facts: structuredFacts,
             shouldInject: structuredFacts.length > 0 || matchedUserRules.length > 0,
             reason,
@@ -2532,6 +2834,7 @@ class AttendantInstance {
             memoryResultsConsidered,
             matchedUserRules: matchedUserRules.length > 0 ? matchedUserRules : undefined,
             usageGuidance: buildUsageGuidance('attend', this.turnsWithoutWrite),
+            toolCallGuidance,
         };
         if (input.suppressEvents !== true) {
             (0, staffEventRegistry_1.getStaffEventEmitter)().emit({