@phuetz/code-buddy 2.0.0 → 2.2.0

package/dist/agent/execution/agent-executor.js

@@ -1,3 +1,4 @@
+import { bindFactsMemorySession } from '../../memory/facts-memory.js';
 /**
  * Agent Executor Module
  *
@@ -7,10 +8,12 @@
  *
  * @module agent/execution
  */
+import { BoundedOutput } from '../../utils/bounded-output.js';
 import { resolveFirstTokenStallTimeoutMs, resolveStallTimeoutMs, withStallGuard } from "../../utils/stream-stall-guard.js";
 import { startHeadlessPromptProgress } from "../../cli/headless-prompt-progress.js";
 import { HEADLESS_LOCAL_COMPACT_ALWAYS_INCLUDE, HEADLESS_LOCAL_COMPACT_MAX_TOOLS, isHeadlessLocalPromptCompact, } from "../../config/headless-local-prompt.js";
 import { normalizeHallucinatedLocalToolCall } from "../tool-handler.js";
+import { mergeAlwaysInclude } from "./tool-selection-strategy.js";
 import { ContextCompactionError } from "../../context/context-manager-v2.js";
 import { logger } from "../../utils/logger.js";
 import { getErrorMessage } from "../../errors/index.js";
@@ -27,6 +30,9 @@ import { compress as tokenJuice, isTokenJuiceEnabled, JUICE_MIN_CHARS } from "..
 import { formatToolResultForRecovery, getRestorableCompressor, } from "../../context/restorable-compression.js";
 import { recordCompactionFork } from "../../context/compaction-fork.js";
 import { getActiveRunStore } from "../../observability/run-store.js";
+import { ToolLoopGuard } from "./tool-loop-guard.js";
+import { getGlobalEventBus } from "../../events/event-bus.js";
+import { takeFirstUseHint } from "../../utils/first-use-hints.js";
 import { getTurnMetricsRecorder } from '../../observability/turn-metrics.js';
 import { shouldCompactBeforeToolExec, estimateToolResultTokens } from "../../context/proactive-compaction.js";
 import { formatTokenUsage, estimateCost } from "../../utils/token-display.js";
@@ -35,7 +41,7 @@ import { getModelToolConfig } from "../../config/model-tools.js";
 import { getLatencyOptimizer, getStreamingOptimizer } from "../../optimization/latency-optimizer.js";
 import { buildTextEmotionalPresenceContext } from "../../companion/reply-augment.js";
 import { guardRelationshipReply, SAFE_RELATIONSHIP_REPAIR, } from "../../conversation/relationship-safety.js";
-import { classifyLisaIntrospection, guardLisaOperationalSelfInspectionReply, isLisaEvolutionRequest, renderLisaOperationalSelfResponse, } from '../../identity/lisa-introspection.js';
+import { classifyLisaIntrospection, guardLisaOperationalSelfInspectionReply, isLisaEvolutionRequest, isLisaSubjectiveConsciousnessQuestion, renderLisaOperationalSelfResponse, } from '../../identity/lisa-introspection.js';
 import { withLlmStreamRetry } from '../../codebuddy/llm-retry.js';
 import { getStreamingAdapter } from '../../tools/streaming-adapter.js';
 import { notify } from '../proactive/notification-default-sink.js';
@@ -467,16 +473,28 @@ export class AgentExecutor {
     /** Execute one tool and buffer optional streaming-adapter output. */
     async executeToolForBatch(toolCall, executionExtra, signal, startedAt = Date.now()) {
         const streamChunks = [];
+        const streamPreview = new BoundedOutput(256 * 1024);
+        let collapsed = false;
+        const appendStreamChunk = (chunk) => {
+            if (!chunk || signal?.aborted)
+                return;
+            streamPreview.append(chunk);
+            collapsed ||= streamPreview.omittedBytes > 0 || streamChunks.length >= 1024;
+            if (collapsed)
+                streamChunks.splice(0, streamChunks.length, streamPreview.text());
+            else
+                streamChunks.push(chunk);
+        };
         const extraWithSignal = signal
             ? { ...(executionExtra ?? {}), abortSignal: signal }
             : executionExtra;
         const execute = async () => {
-            const streamingTools = new Set(['bash', 'reason', 'generate_document']);
+            const streamingTools = new Set(['bash', 'reason', 'generate_document', 'code_exec']);
             if (streamingTools.has(toolCall.function.name)) {
                 const generator = this.deps.toolHandler.executeToolStreaming(toolCall, extraWithSignal);
                 let generated = await generator.next();
                 while (!generated.done) {
-                    streamChunks.push(generated.value);
+                    appendStreamChunk(generated.value);
                     generated = await generator.next();
                 }
                 return {
@@ -486,7 +504,7 @@ export class AgentExecutor {
             }
             const streamingAdapter = getStreamingAdapter();
             if (streamingAdapter.supportsStreaming(toolCall.function.name)) {
-                const result = await streamingAdapter.wrapWithStreaming(toolCall.function.name, () => this.executeToolViaLane(toolCall, extraWithSignal), (chunk) => streamChunks.push(chunk));
+                const result = await streamingAdapter.wrapWithStreaming(toolCall.function.name, () => this.executeToolViaLane(toolCall, extraWithSignal), appendStreamChunk);
                 return { result, streamChunks };
             }
             return {
@@ -740,7 +758,7 @@ export class AgentExecutor {
         const operationId = getLatencyOptimizer().startOperation('assistant_turn', startedAt);
         let recordedFirstVisibleResponse = false;
         try {
-            for await (const event of this.runTurnLoop(message, history, messages, abortController, transientContext, relationshipSafety, surface, introspectionText)) {
+            for await (const event of bindFactsMemorySession(this.deps.client, this.runTurnLoop(message, history, messages, abortController, transientContext, relationshipSafety, surface, introspectionText))) {
                 if (!recordedFirstVisibleResponse &&
                     (event.type === 'content' || event.type === 'reasoning' || event.type === 'tool_calls')) {
                     recordedFirstVisibleResponse = true;
@@ -783,7 +801,9 @@ export class AgentExecutor {
         const introspectionIntent = classifyLisaIntrospection(introspectionTextForTurn);
         const readOnlySelfInspection = introspectionIntent === 'describe' || introspectionIntent === 'inspect';
         const guardGenerativeSelfInspection = introspectionIntent === 'improve';
-        const isolatedSharedHost = surface === 'http';
+        const codeResearch = surface === 'cli' && introspectionIntent === 'inspect' &&
+            !isLisaSubjectiveConsciousnessQuestion(introspectionTextForTurn);
+        const isolatedSharedHost = surface === 'http' || codeResearch;
         const turnCwd = typeof this.deps.toolHandler.getWorkingDirectory === 'function'
             ? this.deps.toolHandler.getWorkingDirectory()
             : process.cwd();
@@ -806,8 +826,9 @@ export class AgentExecutor {
         let permissionMode;
         let providerName;
         let operationalRobotName;
-        if (introspectionIntent !== null) {
-            operationalRobotName = await this.getOperationalRobotName();
+        if (introspectionIntent !== null || surface === 'cli') {
+            if (introspectionIntent !== null)
+                operationalRobotName = await this.getOperationalRobotName();
             try {
                 const { getPermissionModeManager } = await import('../../security/permission-modes.js');
                 permissionMode = getPermissionModeManager().getMode();
@@ -822,7 +843,7 @@ export class AgentExecutor {
                 // Legacy/test clients may not expose provider metadata.
             }
         }
-        if (readOnlySelfInspection) {
+        if (readOnlySelfInspection && !codeResearch) {
             if (isLisaEvolutionRequest(introspectionTextForTurn)) {
                 const { formatEvolutionNotesForVoice, queryEvolutionNotes, readEvolutionNotes, } = await import('../../self-model/evolution-notes.js');
                 const since = introspectionTextForTurn.match(/\b20\d{2}-\d{2}-\d{2}\b/)?.[0];
@@ -850,6 +871,8 @@ export class AgentExecutor {
             // every strict describe/inspect turn. No provider, plugin or generic
             // workspace tool participates in this path.
             const { buildOperationalSelfModel } = await import('../../identity/operational-self-model.js');
+            const { getRuntimeSettingsSnapshot } = await import('../../services/runtime-settings-context.js');
+            const activeSettings = getRuntimeSettingsSnapshot({ surface, model: this.deps.client.getCurrentModel(), provider: providerName, maxToolRounds: this.config.maxToolRounds });
             const selfModel = buildOperationalSelfModel({
                 cwd: turnCwd,
                 focus: introspectionTextForTurn,
@@ -859,6 +882,7 @@ export class AgentExecutor {
                     : {}),
                 runtime: {
                     providerInvoked: false,
+                    ...(activeSettings.theme ? { theme: activeSettings.theme.active } : {}),
                     ...(this.deps.client.getCurrentModel()
                         ? { model: this.deps.client.getCurrentModel() }
                         : {}),
@@ -900,6 +924,11 @@ export class AgentExecutor {
         };
         const maxToolRounds = this.config.maxToolRounds;
         let toolRounds = 0;
+        // One guard per task: warnings/stops never leak into the next user turn.
+        const loopGuard = new ToolLoopGuard();
+        let pendingLoopDecision = null;
+        let loopGuardStopped = false;
+        let observationShortened = false;
         let totalOutputTokens = 0;
         let totalInputTokensForCost = 0;
         let providerPromptTokens = 0;
@@ -1042,6 +1071,25 @@ export class AgentExecutor {
                         alwaysInclude: ['view_file', 'bash', 'search'],
                     };
                 }
+                if (!codeResearch) {
+                    const { runtimeInspectionTools, connectedFleetSurfaceTools } = await import('../../services/runtime-settings-context.js');
+                    const inspectionTools = [...new Set([
+                            ...(surface === 'cli' ? runtimeInspectionTools(turnQueryText) : []),
+                            ...connectedFleetSurfaceTools(),
+                        ])];
+                    if (inspectionTools.length) {
+                        // Fleet tools first (Qwen3.6 GGUF otherwise prefers bash and
+                        // shells list_peers) but they are ADDED to the guaranteed
+                        // default list, never substituted for it.
+                        const alwaysInclude = mergeAlwaysInclude(selectionOpts.alwaysInclude, inspectionTools);
+                        if (alwaysInclude) {
+                            selectionOpts = { ...selectionOpts, alwaysInclude };
+                        }
+                    }
+                }
+                if (codeResearch) {
+                    selectionOpts = { ...selectionOpts, alwaysInclude: ['self_describe'] };
+                }
                 const selectionPromise = this.deps.toolSelectionStrategy.selectToolsForQuery(turnQueryText, selectionOpts);
                 // Build context in a scratch array while the prompt and tools are being
                 // prepared. It is appended only after transcript preparation so the
@@ -1094,7 +1142,9 @@ export class AgentExecutor {
                     incrementalTokenCounter.invalidate();
                     logger.debug(`[agent-executor] system prompt rebuilt query-aware (${rebuiltSystemPrompt.length} chars)`);
                 }
-                let tools = selectionResult.tools;
+                let tools = codeResearch
+                    ? selectionResult.tools.filter(tool => tool.function.name === 'self_describe')
+                    : selectionResult.tools;
                 let forcedChatOnlyToolRunModel = null;
                 if (toolRounds === 0) {
                     this.deps.toolSelectionStrategy.cacheTools(tools, activeModelName);
@@ -1109,7 +1159,7 @@ export class AgentExecutor {
                         tools = [];
                     }
                 }
-                const turnExecutionExtra = introspectionIntent
+                const turnExecutionExtra = introspectionIntent || surface === 'cli'
                     ? {
                         ...(activeModelName ? { model: activeModelName } : {}),
                         ...(providerName ? { provider: providerName } : {}),
@@ -1118,6 +1168,7 @@ export class AgentExecutor {
                         ...(operationalRobotName
                             ? { robotName: operationalRobotName }
                             : {}),
+                        maxToolRounds,
                         exposedToolNames: tools.map((tool) => tool.function.name),
                         introspectionIntent,
                     }
@@ -1142,6 +1193,27 @@ export class AgentExecutor {
                     throw error;
                 }
                 preparedMessages.push(...contextBlocks);
+                if (codeResearch) {
+                    preparedMessages.push({ role: 'system', content: 'Research your actual implementation using self_describe: operation=list/read/search, relative src/ paths (source checkout) or dist/ paths (installed package). Search literal symbols, read relevant code, and cite paths and line numbers. Only this confined read-only tool is exposed for this turn. Do not mistake the user project for your implementation. Do not claim a code graph is available without evidence.' });
+                }
+                if (surface === 'cli') {
+                    const { formatRuntimeSettingsContext } = await import('../../services/runtime-settings-context.js');
+                    preparedMessages.push({ role: 'system', content: formatRuntimeSettingsContext({
+                            surface, model: activeModelName, provider: providerName, maxToolRounds,
+                        }) });
+                }
+                else {
+                    // P5: other surfaces have no runtime_settings block; only a non-default
+                    // code_exec policy needs its short guidance.
+                    const { resolveCodeExecPolicy, CODE_EXEC_PREFER_HINT, CODE_EXEC_OFF_NOTICE } = await import('../../config/code-exec-policy.js');
+                    const codeExecPolicy = resolveCodeExecPolicy(activeModelName ?? undefined);
+                    if (codeExecPolicy.policy !== 'offer') {
+                        preparedMessages.push({
+                            role: 'system',
+                            content: `<code_exec_policy policy="${codeExecPolicy.policy}" source="${codeExecPolicy.source}">\n${codeExecPolicy.policy === 'prefer' ? CODE_EXEC_PREFER_HINT : CODE_EXEC_OFF_NOTICE}\n</code_exec_policy>`,
+                        });
+                    }
+                }
                 if (emotionalPresenceContext) {
                     preparedMessages.push({
                         role: 'system',
@@ -1190,6 +1262,9 @@ export class AgentExecutor {
                 const progress = startHeadlessPromptProgress();
                 const streamFactory = () => withStallGuard(this.deps.client.chatStream(preparedMessages, tools, {
                     streamRetry: false,
+                    // An explicit request to inspect implementation needs an observation
+                    // before an answer. Only the confined self_describe reader is exposed.
+                    ...(codeResearch && toolRounds === 0 && tools.length ? { tool_choice: 'required' } : {}),
                     turnMetrics: {
                         recorder: getTurnMetricsRecorder(),
                         inputTokens,
@@ -1297,6 +1372,11 @@ export class AgentExecutor {
                     }
                     toolCalls = filteredToolCalls.length > 0 ? filteredToolCalls : undefined;
                 }
+                if (codeResearch && toolCalls?.some(call => call.function.name !== 'self_describe')) {
+                    yield { type: 'content', content: 'Code inspection is read-only; the requested tool is not available in this inspection turn.' };
+                    yield { type: 'done' };
+                    return;
+                }
                 if (relationshipSafety && Array.isArray(toolCalls)) {
                     toolCalls = toolCalls.map(prepareRelationshipSafeInteractiveToolCall);
                 }
@@ -1471,8 +1551,15 @@ export class AgentExecutor {
                                         estimatedTokens,
                                         contextWindow,
                                     });
+                                    // The results of this round's calls are pushed after execution:
+                                    // name them so repair does not close them with a synthetic
+                                    // '[result lost during compaction]' that would then win over
+                                    // the real output.
                                     const compacted = compactTurnMessagesInPlace(this.deps.contextManager, messages, {
                                         isolatedSharedHost,
+                                        pendingToolCallIds: toolCalls
+                                            .map((call) => call.id)
+                                            .filter((id) => typeof id === 'string' && id.length > 0),
                                     });
                                     if (compacted)
                                         incrementalTokenCounter.invalidate();
@@ -1565,6 +1652,18 @@ export class AgentExecutor {
                                     };
                                 }
                             }
+                            // --- Tool loop guard (P1): observe the native result before any
+                            // optimizer so "same call + same result" means no progress. The
+                            // decision is applied at the batch boundary so tool_call/tool_result
+                            // pairs are never split.
+                            const loopDecision = loopGuard.observe({
+                                name: toolCall.function.name,
+                                argumentsJson: toolCall.function.arguments || '{}',
+                                result,
+                            });
+                            if (loopDecision.action === 'stop' || (loopDecision.action === 'warn' && !pendingLoopDecision)) {
+                                pendingLoopDecision = loopDecision;
+                            }
                             // Expand the current turn's cached schema after discovery or live
                             // authoring. Without this, a newly created tool is dispatchable but
                             // invisible to the model until the next user turn.
@@ -1705,6 +1804,8 @@ export class AgentExecutor {
                                 signal: abortController?.signal,
                             });
                             let modelStreamContent = optimization.content;
+                            if (optimization.optimized)
+                                observationShortened = true;
                             // lm-resizer owns the semantic budget when available. Its absence or
                             // an intentionally raw failure still receives a model-aware hard cap;
                             // the exact observation remains available through restore_context.
@@ -1715,6 +1816,7 @@ export class AgentExecutor {
                                     this.deps.tokenCounter.countTokens(modelStreamContent) > budgetTokens) {
                                     const truncated = semanticTruncate(modelStreamContent, { maxChars: hardLimitChars });
                                     if (truncated.truncated) {
+                                        observationShortened = true;
                                         const recoveryNote = toolCall.id
                                             ? `\n\n[Full exact observation: restore_context({"identifier":${JSON.stringify(toolCall.id)}})]`
                                             : '';
@@ -1850,6 +1952,68 @@ export class AgentExecutor {
                         yield { type: "done" };
                         return;
                     }
+                    // First shortened observation in this profile: one user-facing tip (P4 first-use hints).
+                    if (observationShortened) {
+                        observationShortened = false;
+                        const tip = takeFirstUseHint('restore_context');
+                        if (tip)
+                            yield { type: "content", content: `\n💡 ${tip}\n` };
+                    }
+                    // Tool-call/result pairs are complete here: apply the loop guard.
+                    if (pendingLoopDecision) {
+                        const decision = pendingLoopDecision;
+                        pendingLoopDecision = null;
+                        const loopData = {
+                            action: decision.action,
+                            loopType: decision.kind,
+                            toolNames: decision.toolNames,
+                            repetitions: decision.repetitions,
+                            toolRounds,
+                        };
+                        try {
+                            getGlobalEventBus().emit('agent:loop_detected', {
+                                loopType: decision.kind,
+                                detail: decision.message,
+                                count: decision.repetitions,
+                                turnIndex: toolRounds,
+                            });
+                        }
+                        catch (err) {
+                            logger.debug('[loop-guard] event emission failed', { error: String(err) });
+                        }
+                        if (decision.action === 'warn') {
+                            logger.warn('[loop-guard] loop warning injected', loopData);
+                            yield { type: "content", content: `\n⚠️ ${decision.message}\n` };
+                            messages.push({
+                                role: 'system',
+                                content: `<context type="loop-guard">\n${decision.message}\n</context>`,
+                            });
+                        }
+                        else {
+                            logger.warn('[loop-guard] turn stopped', loopData);
+                            const runId = typeof this.deps.toolHandler.getRunId === 'function'
+                                ? this.deps.toolHandler.getRunId()
+                                : undefined;
+                            if (runId) {
+                                try {
+                                    getActiveRunStore()?.emit(runId, {
+                                        type: 'decision',
+                                        data: { kind: 'loop_guard_stopped', ...loopData },
+                                    });
+                                }
+                                catch { /* observability is optional */ }
+                            }
+                            yield {
+                                type: 'run_event',
+                                runEvent: { runId: runId ?? '', eventType: 'loop_guard_stopped', data: loopData },
+                            };
+                            history.push({ type: 'assistant', content: decision.message, timestamp: new Date() });
+                            messages.push({ role: 'assistant', content: decision.message });
+                            yield { type: "content", content: `\n\n${decision.message}` };
+                            loopGuardStopped = true;
+                            break;
+                        }
+                    }
                     // Tool-call/result pairs are complete at this boundary, so a steer
                     // that arrived while tools were running can now be injected safely.
                     const deferredSteering = this.deps.messageQueue?.hasSteeringMessage()
@@ -1956,7 +2120,7 @@ export class AgentExecutor {
                     break;
                 }
             }
-            if (toolRounds >= maxToolRounds && !terminateDetectedStreaming) {
+            if (toolRounds >= maxToolRounds && !terminateDetectedStreaming && !loopGuardStopped) {
                 const limitMessage = 'Maximum tool execution rounds reached.';
                 history.push({ type: 'assistant', content: limitMessage, timestamp: new Date() });
                 messages.push({ role: 'assistant', content: limitMessage });

package/dist/agent/execution/context-pipeline.d.ts

@@ -59,9 +59,18 @@ export declare function prepareIsolatedTurnMessages(messages: CodeBuddyMessage[]
  * transcript never shrank, the middleware 'compact' action did nothing, and
  * proactive compaction re-fired forever while the provider limit approached.
  * Returns true when the transcript actually changed.
+ *
+ * `pendingToolCallIds` names the calls of the round being executed. Their
+ * results are pushed AFTER this compaction, so repairing them here injected
+ * `[result lost during compaction]`; the real result then lost the first-wins
+ * duplicate arbitration and the model never saw the tool output. Those
+ * placeholders are removed while every other repair — historical orphans,
+ * id-less calls, duplicates, ordering — is kept. The provider frontier stays
+ * `prepareTurnMessages`, which still closes any call left unanswered.
  */
 export declare function compactTurnMessagesInPlace(contextManager: ContextManagerV2, messages: CodeBuddyMessage[], options?: {
     isolatedSharedHost?: boolean;
+    pendingToolCallIds?: Iterable<string>;
 }): boolean;
 export interface InitialContextDeps {
     message: string;

package/dist/agent/execution/context-pipeline.js

@@ -151,6 +151,52 @@ export function prepareIsolatedTurnMessages(messages) {
         ? repairToolCallPairs(messages)
         : [...messages];
 }
+/** Tool calls of the in-flight round that have no result in `messages` yet. */
+function unansweredPendingCalls(messages, pendingToolCallIds) {
+    const pending = new Set();
+    for (const id of pendingToolCallIds ?? [])
+        if (id)
+            pending.add(id);
+    if (pending.size === 0)
+        return pending;
+    for (const message of messages) {
+        if (message.role !== 'tool')
+            continue;
+        const callId = message.tool_call_id;
+        if (callId)
+            pending.delete(callId);
+    }
+    return pending;
+}
+/**
+ * Drop the synthetic `[result lost during compaction]` placeholders that
+ * transcript repair injected for calls that are merely still running.
+ *
+ * Returns null when a pending call did not survive compaction at all: the
+ * caller then keeps the transcript untouched rather than leaving a call whose
+ * real result would become an unpairable orphan.
+ */
+function withoutPendingPlaceholders(compacted, pending) {
+    const survivingCallIds = new Set();
+    for (const message of compacted) {
+        const calls = message.tool_calls;
+        if (Array.isArray(calls))
+            for (const call of calls)
+                if (call?.id)
+                    survivingCallIds.add(call.id);
+    }
+    for (const id of pending)
+        if (!survivingCallIds.has(id))
+            return null;
+    // `pending` only holds ids with no result in `original`, so every tool
+    // message carrying one of them was invented by repair just now.
+    return compacted.filter((message) => {
+        if (message.role !== 'tool')
+            return true;
+        const callId = message.tool_call_id;
+        return !(callId && pending.has(callId));
+    });
+}
 /**
  * Compact + repair IN PLACE — for mid-loop compaction sites where `messages`
  * is a SHARED reference (the turn loop and its helpers keep pushing into it).
@@ -159,11 +205,27 @@ export function prepareIsolatedTurnMessages(messages) {
  * transcript never shrank, the middleware 'compact' action did nothing, and
  * proactive compaction re-fired forever while the provider limit approached.
  * Returns true when the transcript actually changed.
+ *
+ * `pendingToolCallIds` names the calls of the round being executed. Their
+ * results are pushed AFTER this compaction, so repairing them here injected
+ * `[result lost during compaction]`; the real result then lost the first-wins
+ * duplicate arbitration and the model never saw the tool output. Those
+ * placeholders are removed while every other repair — historical orphans,
+ * id-less calls, duplicates, ordering — is kept. The provider frontier stays
+ * `prepareTurnMessages`, which still closes any call left unanswered.
  */
 export function compactTurnMessagesInPlace(contextManager, messages, options = {}) {
-    const compacted = prepareTurnMessages(contextManager, messages, options);
-    if (compacted === messages)
+    const pending = unansweredPendingCalls(messages, options.pendingToolCallIds);
+    const prepared = prepareTurnMessages(contextManager, messages, options);
+    if (prepared === messages)
         return false;
+    let compacted = prepared;
+    if (pending.size > 0) {
+        const protectedMessages = withoutPendingPlaceholders(prepared, pending);
+        if (!protectedMessages)
+            return false; // pending call dropped: never risk its real result
+        compacted = protectedMessages;
+    }
     const changed = compacted.length !== messages.length || compacted.some((m, i) => m !== messages[i]);
     if (!changed)
         return false;

package/dist/agent/execution/tool-loop-guard.d.ts

@@ -0,0 +1,76 @@
+/**
+ * ToolLoopGuard — stops unproductive tool-call loops inside one agent task.
+ *
+ * New code written for Buddy (comparatif plan P1); nothing was copied from
+ * another project. It does not wire the older, unwired
+ * `src/agent/loop-detection-service.ts` for technical reasons: that service
+ * keys a loop on tool name + arguments only, so a polling call whose output
+ * changes (process status, job progress) is flagged as a loop; it has no
+ * per-tool exemption and no warn → stop escalation. This guard adds the result
+ * fingerprint, `repeatSafe` metadata and a one-warning-then-stop contract, and
+ * emits the same `agent:loop_detected` event, so the domain-event bridge and
+ * the `agent-loop-alert` rule template keep working unchanged.
+ *
+ * Contract:
+ * - "No progress" means the SAME tool, SAME canonical arguments AND the SAME
+ *   result fingerprint. A polling call whose output changes is progress.
+ * - Tools whose metadata declares `repeatSafe: true` are never observed.
+ * - First detection in a task → `warn` (exactly once per task). Any loop
+ *   pattern that persists for `stopAfterWarning` more observations after the
+ *   warning → `stop`.
+ * - The guard is a validation, not a confirmation: nothing in the autonomy /
+ *   YOLO configuration disables it. A new guard instance is created per task.
+ */
+import type { ToolResult } from '../../types/index.js';
+export type ToolLoopKind = 'repeated_call' | 'repeated_cycle';
+export interface ToolLoopObservation {
+    name: string;
+    /** Raw JSON arguments string as sent by the model. */
+    argumentsJson: string;
+    result?: Pick<ToolResult, 'success' | 'output' | 'error'> | null;
+}
+export type ToolLoopDecision = {
+    action: 'none';
+} | {
+    action: 'warn' | 'stop';
+    kind: ToolLoopKind;
+    toolNames: string[];
+    repetitions: number;
+    message: string;
+};
+export interface ToolLoopGuardOptions {
+    /** Identical no-progress observations (or cycle repetitions) before warning. Default 5. */
+    threshold?: number;
+    /** Additional looping observations after the warning before stopping. Default 3. */
+    stopAfterWarning?: number;
+    /** Longest cycle period inspected (A→B→A→B is period 2). Default 3. */
+    maxCyclePeriod?: number;
+    /** Override for tests; defaults to the `repeatSafe` flag in tool metadata. */
+    isRepeatSafe?: (toolName: string) => boolean;
+}
+export declare function isRepeatSafeTool(toolName: string): boolean;
+/**
+ * Loop fingerprint of a successful `a2a_call`: every SendMessage creates a new remote task,
+ * so `taskId` / `contextId` change even when the peer returns the same text. For that tool
+ * only, and only when the output has exactly the task shape, those two technical ids are
+ * dropped; peer, state, text and instruction stay. Anything else (another tool, invalid JSON,
+ * another shape such as a message result) is fingerprinted raw, so changing output is progress.
+ */
+export declare function loopFingerprintOutput(toolName: string, output: string): string;
+export declare class ToolLoopGuard {
+    private readonly threshold;
+    private readonly stopAfterWarning;
+    private readonly maxCyclePeriod;
+    private readonly isRepeatSafe;
+    private history;
+    private warned;
+    private stopped;
+    constructor(options?: ToolLoopGuardOptions);
+    get hasWarned(): boolean;
+    get hasStopped(): boolean;
+    observe(observation: ToolLoopObservation): ToolLoopDecision;
+    /** Detect a repeated call or cycle repeated at least `repeats` times at the tail of history. */
+    private detect;
+    private warnMessage;
+    private stopMessage;
+}