agent-world 0.11.1 → 0.12.0

package/dist/core/events/tool-bridge-logging.js

@@ -0,0 +1,94 @@
+/**
+ * Tool Bridge Logging Utilities
+ *
+ * Purpose:
+ * Shared LLM↔tool debug logging helpers used by both orchestrator and
+ * memory-manager to trace request/result/error handoff payloads.
+ *
+ * Key Features:
+ * - Console-level bridge logs gated by `LOG_LLM_TOOL_BRIDGE` env var
+ * - Simplified output showing only type, tool name, and truncated content (100-200 chars)
+ * - Safe JSON serialization with fallback to `String()`
+ *
+ * Implementation Notes:
+ * - Extracted from orchestrator.ts and memory-manager.ts to eliminate duplication
+ * - Filters verbose metadata, keeps only essential debugging fields
+ *
+ * Changes:
+ * - 2026-02-16: Extracted shared tool-bridge logging utilities from orchestrator
+ *   and memory-manager into a dedicated module.
+ * - 2026-02-17: Simplified logToolBridge to show only type, tool name, and truncated
+ *   content/args/result (100-300 chars max) for better debugging ergonomics. Removed
+ *   worldId, agentId, chatId, hopCount, retryCount and other verbose metadata.
+ */
+const TOOL_DEBUG_RESULT_PREVIEW_LIMIT = 200;
+export function safeSerializeForConsole(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+export function isToolBridgeLoggingEnabled() {
+    const rawValue = typeof process !== 'undefined' && process.env
+        ? process.env.LOG_LLM_TOOL_BRIDGE
+        : undefined;
+    if (!rawValue)
+        return false;
+    const normalized = rawValue.toLowerCase().trim();
+    return normalized === '1' || normalized === 'true' || normalized === 'debug' || normalized === 'on';
+}
+function truncateContent(value, maxLength = TOOL_DEBUG_RESULT_PREVIEW_LIMIT) {
+    const str = typeof value === 'string'
+        ? value
+        : JSON.stringify(value);
+    if (str.length <= maxLength) {
+        return str;
+    }
+    return `${str.slice(0, maxLength)}...[${str.length - maxLength} more]`;
+}
+export function logToolBridge(direction, payload) {
+    if (!isToolBridgeLoggingEnabled()) {
+        return;
+    }
+    // Extract only essential fields: type and shortened content
+    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        const obj = payload;
+        const essential = {};
+        // Keep type fields
+        if ('type' in obj)
+            essential.type = obj.type;
+        if ('responseType' in obj)
+            essential.type = obj.responseType;
+        // Keep tool name/ID (essential for tracing)
+        if ('toolName' in obj)
+            essential.tool = obj.toolName;
+        if ('toolCallId' in obj)
+            essential.id = String(obj.toolCallId).slice(0, 8);
+        // Truncate content/result fields
+        if ('content' in obj)
+            essential.content = truncateContent(obj.content, 100);
+        if ('contentPreview' in obj)
+            essential.content = truncateContent(obj.contentPreview, 100);
+        if ('resultPreview' in obj)
+            essential.result = truncateContent(obj.resultPreview, 150);
+        if ('args' in obj)
+            essential.args = truncateContent(obj.args, 100);
+        console.log(`[LLM↔TOOLS] ${direction}`, essential);
+    }
+    else {
+        // Raw responses (LLM RAW -> CONTINUE)
+        console.log(`[LLM↔TOOLS] ${direction}`, truncateContent(payload, 300));
+    }
+}
+export function getToolResultPreview(value) {
+    const serialized = typeof value === 'string'
+        ? value
+        : safeSerializeForConsole(value);
+    if (serialized.length <= TOOL_DEBUG_RESULT_PREVIEW_LIMIT) {
+        return serialized;
+    }
+    return `${serialized.slice(0, TOOL_DEBUG_RESULT_PREVIEW_LIMIT)}... [truncated ${serialized.length - TOOL_DEBUG_RESULT_PREVIEW_LIMIT} chars]`;
+}
+//# sourceMappingURL=tool-bridge-logging.js.map

package/dist/core/events/tool-bridge-logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-bridge-logging.js","sourceRoot":"","sources":["../../../core/events/tool-bridge-logging.ts"],"names":[],"mappings":"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"}

package/dist/core/events-metadata.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Event Metadata Calculation Helpers
+ *
+ * Pure functions that calculate enhanced metadata for message and tool events.
+ * These functions analyze the world state, message content, and agent configurations
+ * to determine ownership, recipients, threading, and message classification.
+ *
+ * Features:
+ * - calculateOwnerAgentIds: Determine which agents should have message in memory
+ * - calculateRecipientAgentId: Identify intended recipient from @mentions
+ * - calculateMessageDirection: Classify as outgoing/incoming/broadcast
+ * - calculateIsMemoryOnly: Detect cross-agent messages (saved but no response)
+ * - calculateIsCrossAgentMessage: Identify agent-to-agent communication
+ * - calculateThreadMetadata: Compute thread depth and root with cycle detection
+ *
+ * All functions are pure - no side effects, deterministic output, easy to test.
+ *
+ * Implementation: 2025-11-07
+ * - Clean build approach with complete metadata from creation
+ * - Supports human broadcasts, @mention targeting, and cross-agent messaging
+ * - Thread depth calculation with circular reference protection
+ */
+import type { World, WorldMessageEvent, AgentMessage } from './types.js';
+/**
+ * Calculate which agents should have this message in their memory
+ *
+ * Rules:
+ * - Human messages: All agents receive (broadcast)
+ * - Agent messages with @mention: Only recipient gets it
+ * - Agent messages without @mention: All agents get it (broadcast)
+ * - Cross-agent messages: Both sender and recipient
+ */
+export declare function calculateOwnerAgentIds(world: World, message: WorldMessageEvent): string[];
+/**
+ * Calculate the intended recipient from @mentions
+ * Returns agentId if found, null for broadcast
+ */
+export declare function calculateRecipientAgentId(world: World, message: WorldMessageEvent): string | null;
+/**
+ * Calculate message direction from agent's perspective
+ *
+ * - outgoing: Agent is sender
+ * - incoming: Agent is recipient (has @mention)
+ * - broadcast: No specific recipient
+ */
+export declare function calculateMessageDirection(world: World, message: WorldMessageEvent): 'outgoing' | 'incoming' | 'broadcast';
+/**
+ * Calculate if message is memory-only (cross-agent, no response expected)
+ *
+ * Memory-only messages:
+ * - Agent messages with @mention (cross-agent communication)
+ * - Saved to recipient's memory but doesn't trigger response
+ */
+export declare function calculateIsMemoryOnly(world: World, message: WorldMessageEvent): boolean;
+/**
+ * Calculate if message is agent-to-agent communication
+ */
+export declare function calculateIsCrossAgentMessage(world: World, message: WorldMessageEvent): boolean;
+/**
+ * Calculate thread metadata: root ID, depth, and circular reference detection
+ *
+ * Returns:
+ * - threadRootId: ID of root message (null if this is root)
+ * - threadDepth: 0 for root, 1 for reply, 2 for reply-to-reply, etc.
+ * - isReply: true if replyToMessageId is set
+ */
+export declare function calculateThreadMetadata(message: WorldMessageEvent, allMessages: AgentMessage[]): {
+    threadRootId: string | null;
+    threadDepth: number;
+    isReply: boolean;
+};
+//# sourceMappingURL=events-metadata.d.ts.map

package/dist/core/events-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-metadata.d.ts","sourceRoot":"","sources":["../../core/events-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAmBzE;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,GACzB,MAAM,EAAE,CAiBV;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,GACzB,MAAM,GAAG,IAAI,CAEf;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,UAAU,GAAG,WAAW,CAavC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAMT;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAMT;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,YAAY,EAAE,GAC1B;IACD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB,CA2DA"}

package/dist/core/events-metadata.js

@@ -0,0 +1,167 @@
+/**
+ * Event Metadata Calculation Helpers
+ *
+ * Pure functions that calculate enhanced metadata for message and tool events.
+ * These functions analyze the world state, message content, and agent configurations
+ * to determine ownership, recipients, threading, and message classification.
+ *
+ * Features:
+ * - calculateOwnerAgentIds: Determine which agents should have message in memory
+ * - calculateRecipientAgentId: Identify intended recipient from @mentions
+ * - calculateMessageDirection: Classify as outgoing/incoming/broadcast
+ * - calculateIsMemoryOnly: Detect cross-agent messages (saved but no response)
+ * - calculateIsCrossAgentMessage: Identify agent-to-agent communication
+ * - calculateThreadMetadata: Compute thread depth and root with cycle detection
+ *
+ * All functions are pure - no side effects, deterministic output, easy to test.
+ *
+ * Implementation: 2025-11-07
+ * - Clean build approach with complete metadata from creation
+ * - Supports human broadcasts, @mention targeting, and cross-agent messaging
+ * - Thread depth calculation with circular reference protection
+ */
+import { extractParagraphBeginningMentions } from './utils.js';
+function resolveRecipientAgentId(world, message) {
+    const mentions = extractParagraphBeginningMentions(message.content || '');
+    if (mentions.length === 0) {
+        return null;
+    }
+    const targetMention = mentions[0];
+    const targetAgent = Array.from(world.agents.values()).find((agent) => agent.id.toLowerCase() === targetMention ||
+        agent.name.toLowerCase() === targetMention);
+    return targetAgent?.id ?? null;
+}
+/**
+ * Calculate which agents should have this message in their memory
+ *
+ * Rules:
+ * - Human messages: All agents receive (broadcast)
+ * - Agent messages with @mention: Only recipient gets it
+ * - Agent messages without @mention: All agents get it (broadcast)
+ * - Cross-agent messages: Both sender and recipient
+ */
+export function calculateOwnerAgentIds(world, message) {
+    const isHuman = message.sender === 'human' || message.sender === 'user';
+    // Human messages go to all agents
+    if (isHuman) {
+        return Array.from(world.agents.keys());
+    }
+    // Agent message - check for paragraph-beginning direct mention
+    const recipientAgentId = resolveRecipientAgentId(world, message);
+    if (recipientAgentId) {
+        // Cross-agent message: both sender and recipient
+        return [message.sender, recipientAgentId];
+    }
+    // Agent broadcast - all agents
+    return Array.from(world.agents.keys());
+}
+/**
+ * Calculate the intended recipient from @mentions
+ * Returns agentId if found, null for broadcast
+ */
+export function calculateRecipientAgentId(world, message) {
+    return resolveRecipientAgentId(world, message);
+}
+/**
+ * Calculate message direction from agent's perspective
+ *
+ * - outgoing: Agent is sender
+ * - incoming: Agent is recipient (has @mention)
+ * - broadcast: No specific recipient
+ */
+export function calculateMessageDirection(world, message) {
+    const isHuman = message.sender === 'human' || message.sender === 'user';
+    if (isHuman) {
+        return 'broadcast'; // Human messages are always broadcast
+    }
+    const recipientId = calculateRecipientAgentId(world, message);
+    if (recipientId) {
+        return 'incoming'; // Has specific recipient
+    }
+    return 'broadcast'; // Agent broadcast to all
+}
+/**
+ * Calculate if message is memory-only (cross-agent, no response expected)
+ *
+ * Memory-only messages:
+ * - Agent messages with @mention (cross-agent communication)
+ * - Saved to recipient's memory but doesn't trigger response
+ */
+export function calculateIsMemoryOnly(world, message) {
+    const isHuman = message.sender === 'human' || message.sender === 'user';
+    if (isHuman)
+        return false; // Human messages always trigger responses
+    const recipientId = calculateRecipientAgentId(world, message);
+    return recipientId !== null; // Has @mention = memory-only
+}
+/**
+ * Calculate if message is agent-to-agent communication
+ */
+export function calculateIsCrossAgentMessage(world, message) {
+    const isHuman = message.sender === 'human' || message.sender === 'user';
+    if (isHuman)
+        return false;
+    const recipientId = calculateRecipientAgentId(world, message);
+    return recipientId !== null;
+}
+/**
+ * Calculate thread metadata: root ID, depth, and circular reference detection
+ *
+ * Returns:
+ * - threadRootId: ID of root message (null if this is root)
+ * - threadDepth: 0 for root, 1 for reply, 2 for reply-to-reply, etc.
+ * - isReply: true if replyToMessageId is set
+ */
+export function calculateThreadMetadata(message, allMessages) {
+    const isReply = !!message.replyToMessageId;
+    if (!isReply) {
+        return {
+            threadRootId: null,
+            threadDepth: 0,
+            isReply: false
+        };
+    }
+    // Traverse up the reply chain to find root
+    const visited = new Set([message.messageId]);
+    let currentId = message.replyToMessageId;
+    let depth = 1;
+    while (currentId) {
+        // Circular reference detection
+        if (visited.has(currentId)) {
+            console.warn(`Circular thread reference detected: ${Array.from(visited).join(' -> ')} -> ${currentId}`);
+            return {
+                threadRootId: message.replyToMessageId ?? null, // Treat immediate parent as root
+                threadDepth: 1,
+                isReply: true
+            };
+        }
+        visited.add(currentId);
+        // Find parent message
+        const parent = allMessages.find(m => m.messageId === currentId);
+        if (!parent || !parent.replyToMessageId) {
+            // Found root or missing parent
+            return {
+                threadRootId: currentId,
+                threadDepth: depth,
+                isReply: true
+            };
+        }
+        currentId = parent.replyToMessageId;
+        depth++;
+        // Safety limit to prevent infinite loops
+        if (depth > 100) {
+            console.warn(`Thread depth exceeds 100 levels, stopping traversal`);
+            return {
+                threadRootId: currentId,
+                threadDepth: depth,
+                isReply: true
+            };
+        }
+    }
+    return {
+        threadRootId: currentId ?? message.replyToMessageId ?? null,
+        threadDepth: depth,
+        isReply: true
+    };
+}
+//# sourceMappingURL=events-metadata.js.map

package/dist/core/events-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-metadata.js","sourceRoot":"","sources":["../../core/events-metadata.ts"],"names":[],"mappings":"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"}

package/dist/core/events.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Unified Events Module - World and Agent Event Functions
+ *
+ * Purpose: Event-driven message publishing, agent response processing, and memory persistence
+ *
+ * Logging: Enable with LOG_EVENTS=debug or specific categories:
+ * - LOG_EVENTS_PUBLISH, LOG_EVENTS_AGENT, LOG_EVENTS_RESPONSE, LOG_EVENTS_MEMORY
+ * - LOG_EVENTS_AUTOMENTION, LOG_EVENTS_TURNLIMIT, LOG_EVENTS_CHATTITLE
+ *
+ * Core Features:
+ * - Event publishing/subscription via World.eventEmitter with type safety
+ * - Agent message filtering with mention detection and turn limits
+ * - Auto-mention logic with loop prevention and world tags (<world>STOP|TO:a,b</world>)
+ * - Message threading with replyToMessageId preservation
+ * - Event persistence with automatic chatId defaulting to world.currentChatId
+ * - Tool approval system with session/one-time approval tracking
+ * - Chat title generation on world idle events
+ *
+ * Recent Changes (2025-11):
+ * - Fixed tool event metadata validation errors: Added required ownerAgentId and
+ *   triggeredByMessageId fields to toolHandler, added validation guards to reject
+ *   tool events missing messageId or agentName
+ * - Removed unnecessary 'info' event emission from tool-utils.ts to prevent validation errors
+ * - Fixed approval response broadcast bug: Removed HUMAN check from shouldAutoMention to ensure
+ *   agent responses to HUMAN approval messages include proper targeting mentions (@HUMAN),
+ *   preventing unintended broadcast to all agents
+ * - Consolidated redundant logging and streamlined approval checking
+ * - Added tool_calls/tool_call_id persistence for approval messages
+ * - Pre-generate message IDs for agent responses
+ * - Fixed activity tracking to prevent premature idle signals
+ */
+import { World, Agent, WorldMessageEvent, WorldSSEEvent, WorldToolEvent, AgentMessage } from './types.js';
+export declare function enableStreaming(): void;
+export declare function disableStreaming(): void;
+/**
+ * Publish CRUD event for agent, chat, or world configuration changes
+ * Allows subscribed clients to receive real-time updates for all CRUD operations
+ */
+export declare function publishCRUDEvent(world: World, operation: 'create' | 'update' | 'delete', entityType: 'agent' | 'chat' | 'world', entityId: string, entityData?: any): void;
+/**
+ * Setup automatic event persistence listeners on World event emitter.
+ * Should be called once during World initialization.
+ *
+ * Events are persisted synchronously/awaitable for reliability.
+ * Failures are logged but don't block event emission.
+ * Returns a cleanup function to remove listeners.
+ *
+ * Environment variables:
+ * - DISABLE_EVENT_PERSISTENCE=true: Skip all persistence
+ */
+export declare function setupEventPersistence(world: World): () => void;
+/**
+ * Publish event to a specific channel using World.eventEmitter
+ */
+export declare function publishEvent(world: World, type: string, content: any): void;
+/**
+ * Message publishing using World.eventEmitter with chat session management
+ * Parses enhanced string protocol and automatically prepends @mention if agentId detected
+ * Returns the messageEvent so callers can access the generated messageId
+ *
+ * @param chatId - Optional chat ID. If not provided, uses world.currentChatId
+ * @param replyToMessageId - Optional parent message ID for threading
+ */
+export declare function publishMessage(world: World, content: string, sender: string, chatId?: string | null, replyToMessageId?: string): WorldMessageEvent;
+/**
+ * Message publishing with pre-generated messageId
+ * Used when messageId needs to be known before publishing (e.g., for agent responses)
+ *
+ * @param chatId - Optional chat ID. If not provided, uses world.currentChatId
+ * @param replyToMessageId - Optional parent message ID for threading
+ */
+export declare function publishMessageWithId(world: World, content: string, sender: string, messageId: string, chatId?: string | null, replyToMessageId?: string): WorldMessageEvent;
+export declare function subscribeToMessages(world: World, handler: (event: WorldMessageEvent) => void): () => void;
+/**
+ * SSE events using World.eventEmitter (for LLM streaming)
+ */
+export declare function publishSSE(world: World, data: Partial<WorldSSEEvent>): void;
+/**
+ * Tool events using World.eventEmitter (for agent behavioral events)
+ */
+export declare function publishToolEvent(world: World, data: Partial<WorldToolEvent>): void;
+/**
+ * Publish approval request event
+ * Used when a tool requires approval before execution
+ * Note: This function is legacy - approval requests now use direct message events
+ * with OpenAI tool call protocol (see tool-utils.ts)
+ */
+export declare function publishApprovalRequest(world: World, approvalRequest: any, agentId: string, messageId: string): void;
+/**
+ * SSE subscription using World.eventEmitter
+ */
+export declare function subscribeToSSE(world: World, handler: (event: WorldSSEEvent) => void): () => void;
+export declare function hasAnyMentionAtBeginning(response: string): boolean;
+export declare function removeMentionsFromParagraphBeginnings(text: string, specificMention?: string): string;
+export declare function addAutoMention(response: string, sender: string): string;
+export declare function getValidMentions(response: string, agentId: string): string[];
+export declare function shouldAutoMention(response: string, sender: string, agentId: string): boolean;
+export declare function removeSelfMentions(response: string, agentId: string): string; /**
+ * Agent subscription with automatic message processing
+ */
+export declare function subscribeAgentToMessages(world: World, agent: Agent): () => void;
+/**
+ * Save incoming message to agent memory with auto-save
+ */
+export declare function saveIncomingMessageToMemory(world: World, agent: Agent, messageEvent: WorldMessageEvent): Promise<void>;
+/**
+ * Agent message processing with LLM response generation and auto-mention logic
+ */
+export declare function processAgentMessage(world: World, agent: Agent, messageEvent: WorldMessageEvent): Promise<void>;
+/**
+ * Reset LLM call count for human/world messages with persistence
+ */
+export declare function resetLLMCallCountIfNeeded(world: World, agent: Agent, messageEvent: WorldMessageEvent): Promise<void>;
+/**
+ * Enhanced message filtering logic with turn limits and mention detection
+ */
+export declare function shouldAgentRespond(world: World, agent: Agent, messageEvent: WorldMessageEvent): Promise<boolean>;
+/**
+ * Subscribe world to messages with cleanup function
+ */
+export declare function subscribeWorldToMessages(world: World): () => void;
+/**
+ * Setup world activity listener for chat title updates
+ * Triggers title generation when world becomes idle (pendingOperations === 0)
+ */
+export declare function setupWorldActivityListener(world: World): () => void;
+/**
+ * Check if a specific tool requires approval based on message history
+ * Simplified: Only checks for session-wide approval, not one-time or denials
+ *
+ * Logic:
+ * 1. Search for session approval → Execute immediately
+ * 2. No session approval → Request approval
+ *
+ * @param context - Execution context with workingDirectory (CRITICAL FIX: AR Issue #1)
+ */
+export declare function checkToolApproval(world: World, toolName: string, toolArgs: any, message: string, messages: AgentMessage[], context?: {
+    workingDirectory?: string;
+    [key: string]: any;
+}): Promise<{
+    needsApproval: boolean;
+    canExecute: boolean;
+    approvalRequest?: any;
+    reason?: string;
+}>;
+/**
+ * Find session-wide approval for a tool in message history
+ * Supports both enhanced string protocol (JSON) and legacy text parsing
+ *
+ * Session approval matches on:
+ * - Tool name (required)
+ * - Working directory (if provided)
+ * - Parameters (exact match)
+ *
+ * Enhanced protocol format:
+ * {
+ *   role: 'tool',
+ *   tool_call_id: 'approval_...',
+ *   content: '{"__type":"tool_result","content":"{\"decision\":\"approve\",\"scope\":\"session\",\"toolName\":\"...\",\"toolArgs\":{...},\"workingDirectory\":\"...\"}"}'
+ * }
+ */
+export declare function findSessionApproval(messages: AgentMessage[], toolName: string, toolArgs?: any, workingDirectory?: string): {
+    decision: 'approve';
+    scope: 'session';
+    toolName: string;
+} | undefined;
+/**
+ * @deprecated This function is no longer used in approval checking logic.
+ * One-time approvals are consumed after tool execution, checking for them is redundant.
+ * Kept for backwards compatibility only.
+ */
+export declare function findRecentApproval(messages: AgentMessage[], toolName: string): {
+    decision: 'approve' | 'deny';
+    scope: 'once';
+    toolName: string;
+} | undefined;
+/**
+ * @deprecated This function is no longer used in approval checking logic.
+ * Users should be allowed to change their mind about denials.
+ * Kept for backwards compatibility only.
+ */
+export declare function findRecentDenial(messages: AgentMessage[], toolName: string): {
+    decision: 'deny';
+    toolName: string;
+} | undefined;
+//# sourceMappingURL=events.d.ts.map

package/dist/core/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../core/events.ts"],"names":[],"mappings":"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"}