kollabor 0.4.9__py3-none-any.whl → 0.4.15__py3-none-any.whl

agents/kollabor/inspect-llm-conversation.md

@@ -0,0 +1,148 @@
+Inspect and debug LLM conversation history and message flow
+
+skill name: inspect-llm-conversation
+
+purpose:
+  examine conversation state, message history, pending tools queue, and
+  question gate state to diagnose conversation flow issues in kollabor-cli
+
+when to use:
+  - messages not appearing in conversation history
+  - question gate appears stuck (agent asks question but doesn't continue)
+  - tools not executing after user response
+  - need to verify message threading or parent uuids
+  - debugging context window or history truncation
+  - investigating duplicate or missing messages
+
+methodology:
+  1. check current session state (session id, message count, queue status)
+  2. inspect conversation history in memory
+  3. check pending tools queue and question gate state
+  4. review persisted conversation logs if needed
+  5. trace message flow from user input through processing
+
+tools and commands:
+
+  files to read:
+    - core/llm/llm_service.py
+      conversation state: conversation_history, conversation_manager, pending_tools
+      question gate: question_gate_active, question_gate_enabled
+      queue: processing_queue, is_processing, turn_completed
+
+    - core/llm/conversation_manager.py
+      session tracking: current_session_id, messages list, message_index
+      context: context_window, max_history
+      storage: conversations_dir
+
+    - core/llm/response_parser.py
+      question detection: question_pattern, parse_response()
+      tool extraction: tool_call_pattern, terminal_pattern
+
+  terminal commands:
+    python3 -c "
+import sys
+sys.path.insert(0, '.')
+from core.config.loader import ConfigLoader
+from core.llm.conversation_manager import ConversationManager
+config = ConfigLoader().load()
+cm = ConversationManager(config)
+print('Session:', cm.current_session_id)
+print('Messages:', len(cm.messages))
+print('Context window:', len(cm.context_window), '/', cm.max_history)
+"
+
+    python3 -c "
+import sys, json
+sys.path.insert(0, '.')
+from core.storage.state_manager import StateManager
+sm = StateManager()
+history = sm.get('llm.conversation_history', [])
+print('Total messages in state:', len(history))
+for i, msg in enumerate(history[-5:]):
+    print(f'  [{i}] {msg.get(\"role\", \"unknown\")}: {msg.get(\"content\", \"\")[:50]}...')
+"
+
+    ls -la ~/.kollabor-cli/conversations/
+    ls -la .kollabor-cli/conversations/
+
+  grep patterns for debugging:
+    grep -r "question_gate_active" core/llm/
+    grep -r "pending_tools" core/llm/
+    grep -r "add_message\|log_user_message\|log_assistant_message" core/llm/
+
+example workflow:
+
+  scenario: agent asked a question but isn't continuing after user response
+
+  1. check question gate state:
+     read core/llm/llm_service.py lines 195-202
+     look for: self.question_gate_active, self.pending_tools
+
+  2. check response parser for question detection:
+     read core/llm/response_parser.py lines 439-443, 548-563
+     look for: question_pattern regex, _extract_question method
+
+  3. check conversation manager for message threading:
+     read core/llm/conversation_manager.py lines 66-123
+     look for: add_message method, parent_uuid handling
+
+  4. view raw conversation logs:
+     terminal: tail -20 ~/.kollabor-cli/conversations/*.jsonl
+     terminal: jq . ~/.kollabor-cli/conversations/session_*.json 2>/dev/null | tail -50
+
+  5. trace question gate flow in llm_service:
+     read core/llm/llm_service.py lines 1068-1105, 1474-1481, 1667-1677
+     look for: question gate handling in process_user_input and message processing
+
+expected output:
+
+  [ok] session state
+    session_id: frost-blade-1234
+    messages in memory: 42
+    context window: 42 / 90
+    queue size: 0 / 10
+
+  [ok] question gate state
+    question_gate_enabled: true
+    question_gate_active: false
+    pending_tools: 0
+
+  [ok] message threading
+    current_parent_uuid: abc-123-def
+    last message role: assistant
+    thread depth: 3
+
+  or if issue detected:
+
+  [error] question gate stuck
+    question_gate_active: true (should be false)
+    pending_tools: 2 tools suspended
+    last assistant message contains: <question>...</question>
+    recommendation: check question gate reset logic in process_user_input
+
+troubleshooting tips:
+
+  issue: messages not appearing in history
+    - verify _add_conversation_message is being called (llm_service.py:38)
+    - check conversation_manager.add_message is syncing (llm_service.py:66-71)
+    - look for exceptions in conversation_logger.log_user_message
+
+  issue: question gate not clearing
+    - check llm_service.py lines 1103-1105 (question gate reset)
+    - verify question_gate_enabled is true in config
+    - check for <question> tag in last assistant response
+
+  issue: pending tools not executing
+    - verify pending_tools queue is populated (llm_service.py:200)
+    - check tool_executor.execute_all_tools is being called
+    - look for exceptions during tool execution in logs
+
+  issue: context window truncation
+    - check max_history config (default 90 in llm_service.py:120)
+    - verify conversation_manager._update_context_window (lines 138-148)
+    - look for system message being dropped from context
+
+  issue: duplicate messages
+    - check message flow through message_display.display_user_message
+    - verify message_coordinator is not double-displaying
+    - look for multiple display_message_sequence calls

agents/kollabor/monitor-event-bus.md

@@ -0,0 +1,558 @@
+<!-- Monitor event bus activity in real-time -->
+
+skill name: monitor-event-bus
+
+purpose:
+  watch event bus activity in real-time to understand system behavior.
+  helps visualize event flow, track active listeners, measure processing
+  times, and diagnose performance bottlenecks in the event system.
+
+
+when to use:
+  [ ] need to see what events are firing in real-time
+  [ ] investigating event propagation issues
+  [ ] measuring event processing performance
+  [ ] identifying which plugins are listening to which events
+  [ ] debugging event-related race conditions
+  [ ] understanding event flow for a specific user action
+
+
+methodology:
+
+phase 1: event bus discovery
+  understand event bus architecture
+  identify all registered event listeners
+  check event type mappings
+
+phase 2: real-time monitoring
+  set up live event watching
+  trace event propagation through pre/main/post phases
+  capture event context and timing data
+
+phase 3: analysis
+  identify slow events/hooks
+  find event bottlenecks
+  visualize event flow patterns
+
+
+tools and commands:
+
+core files to read:
+  <read>file>core/events/bus.py</file>
+  <read>file>core/events/models.py</read>
+  <read>file>core/events/processor.py</read>
+  <read>file>core/events/registry.py</read>
+  <read>file>core/events/executor.py</read>
+
+grep patterns for event discovery:
+  <terminal>grep -r "emit_with_hooks\|emit(" core/ --include="*.py"</terminal>
+  <terminal>grep -r "EventType\." core/ --include="*.py" | head -50</terminal>
+  <terminal>grep -r "process_event_with_phases" core/ --include="*.py"</terminal>
+
+find all event emission points:
+  <terminal>grep -r "await.*event_bus" core/ --include="*.py" -B 2</terminal>
+
+view event bus in logs:
+  <terminal>grep -i "event.*emitted\|event.*processed" .kollabor-cli/logs/kollabor.log | tail -50</terminal>
+
+check event processing times:
+  <terminal>grep -i "duration_ms\|processing.*time" .kollabor-cli/logs/kollabor.log | tail -30</terminal>
+
+monitor live events:
+  <terminal>tail -f .kollabor-cli/logs/kollabor.log | grep -i "event"</terminal>
+
+
+event bus architecture:
+
+eventbus (core/events/bus.py)
+  central coordinator for all event activity
+  combines three specialized components:
+
+key attributes:
+  - hook_registry: manages hook registration and lookup
+  - hook_executor: executes individual hooks with timeout/error handling
+  - event_processor: coordinates pre/main/post phase processing
+
+key methods for monitoring:
+  - get_hook_status(): get current status of all registered hooks
+  - get_registry_stats(): comprehensive statistics (counts, distributions)
+  - get_hooks_for_event(event_type): count hooks for specific event
+  - emit_with_hooks(event_type, data, source): main event emission point
+
+
+eventprocessor (core/events/processor.py)
+  handles event flow through pre/main/post phases
+
+pre/post event mappings:
+  - USER_INPUT -> USER_INPUT_PRE + USER_INPUT_POST
+  - KEY_PRESS -> KEY_PRESS_PRE + KEY_PRESS_POST
+  - LLM_REQUEST -> LLM_REQUEST_PRE + LLM_REQUEST_POST
+  - LLM_RESPONSE -> LLM_RESPONSE_PRE + LLM_RESPONSE_POST
+  - TOOL_CALL -> TOOL_CALL_PRE + TOOL_CALL_POST
+
+key methods:
+  - process_event_with_phases(): main event processing pipeline
+  - get_supported_event_types(): show all pre/post mappings
+
+
+hookregistry (core/events/registry.py)
+  tracks all hooks by event type and priority
+
+key methods:
+  - get_hooks_for_event(event_type): get enabled hooks sorted by priority
+  - get_hook_status_summary(): get all hook statuses with details
+  - get_registry_stats(): comprehensive statistics
+
+return data includes:
+  - total_hooks: total number of registered hooks
+  - hooks_per_event_type: count per event type
+  - priority_distribution: hooks by priority level
+  - hooks_per_plugin: hooks by plugin name
+
+
+hookexecutor (core/events/executor.py)
+  executes hooks and tracks performance
+
+key methods:
+  - execute_hook(hook, event): execute single hook with timeout
+  - get_execution_stats(results): calculate timing and success stats
+
+return data includes:
+  - successful: count of successful executions
+  - failed: count of failed executions
+  - timed_out: count of timeouts
+  - total_duration_ms: total processing time
+  - avg_duration_ms: average processing time
+
+
+event types (core/events/models.py)
+
+user input events:
+  USER_INPUT_PRE, USER_INPUT, USER_INPUT_POST
+  KEY_PRESS_PRE, KEY_PRESS, KEY_PRESS_POST
+  PASTE_DETECTED
+
+llm events:
+  LLM_REQUEST_PRE, LLM_REQUEST, LLM_REQUEST_POST
+  LLM_RESPONSE_PRE, LLM_RESPONSE, LLM_RESPONSE_POST
+  LLM_THINKING, CANCEL_REQUEST
+
+tool events:
+  TOOL_CALL_PRE, TOOL_CALL, TOOL_CALL_POST
+
+system events:
+  SYSTEM_STARTUP, SYSTEM_SHUTDOWN, RENDER_FRAME
+
+rendering events:
+  INPUT_RENDER_PRE, INPUT_RENDER, INPUT_RENDER_POST
+  STATUS_VIEW_CHANGED, STATUS_CONTENT_UPDATE
+  PAUSE_RENDERING, RESUME_RENDERING
+
+command events:
+  SLASH_COMMAND_DETECTED, SLASH_COMMAND_EXECUTE, SLASH_COMMAND_COMPLETE
+  COMMAND_MENU_SHOW, COMMAND_MENU_NAVIGATE, COMMAND_MENU_SELECT
+  COMMAND_MENU_HIDE, COMMAND_MENU_FILTER
+
+modal events:
+  MODAL_TRIGGER, MODAL_SHOW, MODAL_HIDE, MODAL_SAVE
+  STATUS_MODAL_TRIGGER, LIVE_MODAL_TRIGGER
+
+
+phase 1: discover event bus state
+
+step 1: query registry for hook statistics
+
+check total hook count:
+  <terminal>grep -i "total.*hook\|registered.*hook" .kollabor-cli/logs/kollabor.log | tail -5</terminal>
+
+check hooks per event type:
+  <terminal>grep -i "hook.*for.*event\|event.*type" .kollabor-cli/logs/kollabor.log | tail -20</terminal>
+
+check plugin hook distribution:
+  <terminal>grep -i "plugin.*hook" .kollabor-cli/logs/kollabor.log | tail -20</terminal>
+
+
+step 2: find all event emission points in code
+
+search for emit_with_hooks calls:
+  <terminal>grep -rn "emit_with_hooks" core/ --include="*.py"</terminal>
+
+sample output shows:
+  - where events are emitted
+  - which event types are used
+  - what data is passed with events
+
+
+step 3: identify active listeners for specific event
+
+for a given event type (e.g., USER_INPUT):
+  <terminal>grep -rn "USER_INPUT" plugins/ --include="*.py" | grep "Hook("</terminal>
+
+this shows all hooks listening to USER_INPUT events.
+
+
+phase 2: real-time event monitoring
+
+step 1: enable event bus logging
+
+check if debug logging is enabled:
+  <read>file>.kollabor-cli/config.json</file>
+
+look for logging configuration:
+  {
+    "logging": {
+      "level": "DEBUG"
+    }
+  }
+
+if not set, add and restart application.
+
+
+step 2: monitor all events in real-time
+
+watch all event emissions:
+  <terminal>tail -f .kollabor-cli/logs/kollabor.log | grep "event"</terminal>
+
+filter for specific event type:
+  <terminal>tail -f .kollabor-cli/logs/kollabor.log | grep "USER_INPUT"</terminal>
+
+filter for phase information:
+  <terminal>tail -f .kollabor-cli/logs/kollabor.log | grep "PRE\|MAIN\|POST"</terminal>
+
+watch for event cancellations:
+  <terminal>tail -f .kollabor-cli/logs/kollabor.log | grep "cancel"</terminal>
+
+
+step 3: create event monitoring helper
+
+add this function to track events:
+
+  # in core/events/bus.py (for debugging)
+  _event_log = []
+
+  async def emit_with_hooks(self, event_type, data, source):
+      entry = {
+          "timestamp": datetime.now().isoformat(),
+          "event_type": event_type.value,
+          "source": source,
+          "data_keys": list(data.keys()) if isinstance(data, dict) else str(type(data))
+      }
+      self._event_log.append(entry)
+      logger.debug(f"[EVENT] {event_type.value} from {source}")
+      return await self.event_processor.process_event_with_phases(event_type, data, source)
+
+  def get_event_log(self, limit=100):
+      return self._event_log[-limit:]
+
+
+step 4: trace event flow through phases
+
+enable verbose phase logging in processor:
+  <terminal>grep -A 5 "process_event_with_phases" core/events/processor.py</terminal>
+
+look for phase logging:
+  - "event {event_type} cancelled during pre phase"
+  - "processing {phase_name} phase"
+
+this shows the complete flow: pre -> main -> post
+
+
+phase 3: performance measurement
+
+step 1: measure event processing time
+
+check hook execution times in logs:
+  <terminal>grep -i "duration_ms\|executed.*hook" .kollabor-cli/logs/kollabor.log | tail -50</terminal>
+
+sort by slowest hooks:
+  <terminal>grep -i "duration_ms" .kollabor-cli/logs/kollabor.log | sort -t: -k2 -rn | head -20</terminal>
+
+
+step 2: identify bottleneck hooks
+
+find hooks taking longer than threshold:
+  <terminal>awk '/duration_ms/ {if ($2 > 50) print}' .kollabor-cli/logs/kollabor.log</terminal>
+
+adjust threshold as needed (50ms in example).
+
+
+step 3: create performance summary
+
+run this command to aggregate timing:
+  <terminal>grep "duration_ms" .kollabor-cli/logs/kollabor.log | awk '{sum+=$2; count++} END {print "avg:", sum/count, "ms total:", sum, "ms count:", count}'</terminal>
+
+
+step 4: trace slow event flows
+
+when you find a slow event, trace its hooks:
+  1. identify event type from logs
+  2. find all hooks for that event type
+  3. check each hook's callback implementation
+  4. profile slow callbacks
+
+
+example workflow:
+
+scenario: "what events fire when i press enter?"
+
+step 1: start real-time monitoring
+  <terminal>tail -f .kollabor-cli/logs/kollabor.log | grep -i "event\|hook"</terminal>
+
+step 2: trigger the action
+  press enter in the application
+
+step 3: observe event sequence
+
+typical sequence for enter key:
+  [event] KEY_PRESS_PRE
+  [hook] enhanced_input.key_press_pre_handler
+  [event] KEY_PRESS
+  [hook] input_handler.process_key
+  [event] USER_INPUT_PRE
+  [hook] workflow_enforcement.validate_input
+  [event] USER_INPUT
+  [hook] llm_service.process_user_message
+  [event] LLM_REQUEST_PRE
+  [hook] api_communication.prepare_request
+
+step 4: analyze the flow
+  - identify which hooks modified data
+  - check for any cancelled events
+  - note timing for each phase
+
+
+example workflow 2:
+
+scenario: "why is my command slow?"
+
+step 1: measure timing
+  <terminal>grep "SLASH_COMMAND" .kollabor-cli/logs/kollabor.log | grep "duration_ms" | tail -10</terminal>
+
+step 2: identify slow hook
+  look for duration_ms values > 100
+
+step 3: inspect hook implementation
+  find the plugin with the slow hook:
+    <terminal>grep -r "hook_name" plugins/ --include="*.py" -l</terminal>
+
+  read the hook callback to find bottleneck.
+
+step 4: optimize or report
+  - optimize slow code if you own it
+  - report performance issue if in core library
+
+
+example workflow 3:
+
+scenario: "which plugins are listening to RENDER_FRAME?"
+
+step 1: find hooks for event type
+  <terminal>grep -rn "RENDER_FRAME" plugins/ --include="*.py" | grep -E "Hook|EventType"</terminal>
+
+step 2: list all listeners
+  expected output shows:
+    - plugin names
+    - hook names
+    - priority levels
+
+step 3: understand execution order
+  higher priority hooks execute first.
+  system (1000) > security (900) > preprocessing (500) >
+  llm (100) > postprocessing (50) > display (10)
+
+step 4: verify expected behavior
+  check if each listener is needed for render_frame.
+  remove unused hooks to improve performance.
+
+
+advanced: event tracing decorator
+
+create a tracing decorator in core/events/tracer.py:
+
+  import functools
+  import time
+  import logging
+
+  logger = logging.getLogger(__name__)
+
+  def trace_event(event_type):
+      def decorator(func):
+          @functools.wraps(func)
+          async def wrapper(self, *args, **kwargs):
+              start = time.time()
+              logger.debug(f"[TRACE] {event_type} starting")
+              try:
+                  result = await func(self, *args, **kwargs)
+                  duration = (time.time() - start) * 1000
+                  logger.debug(f"[TRACE] {event_type} complete in {duration:.2f}ms")
+                  return result
+              except Exception as e:
+                  duration = (time.time() - start) * 1000
+                  logger.error(f"[TRACE] {event_type} failed after {duration:.2f}ms: {e}")
+                  raise
+          return wrapper
+      return decorator
+
+apply to event emission points for detailed tracing.
+
+
+advanced: custom event monitor script
+
+create monitor_events.py:
+
+  import asyncio
+  from pathlib import Path
+  import sys
+
+  sys.path.insert(0, str(Path(__file__).parent))
+
+  from core.events.bus import EventBus
+  from core.events.models import EventType, Hook, HookPriority
+
+  class EventMonitor:
+      def __init__(self):
+          self.event_count = {}
+          self.last_events = []
+
+      async def track_event(self, event_type, data, source):
+          key = event_type.value
+          self.event_count[key] = self.event_count.get(key, 0) + 1
+          self.last_events.append({
+              "type": key,
+              "source": source,
+              "timestamp": asyncio.get_event_loop().time()
+          })
+          if len(self.last_events) > 100:
+              self.last_events.pop(0)
+          print(f"[EVENT] {key} from {source}")
+
+      def print_summary(self):
+          print("\nevent count summary:")
+          for event, count in sorted(self.event_count.items(), key=lambda x: -x[1]):
+              print(f"  {event}: {count}")
+
+          print("\nrecent events:")
+          for event in self.last_events[-10:]:
+              print(f"  {event}")
+
+  async def main():
+      bus = EventBus()
+      monitor = EventMonitor()
+
+      # register monitor hooks for all event types
+      for event_type in EventType:
+          hook = Hook(
+              name="monitor",
+              plugin_name="event_monitor",
+              event_type=event_type,
+              priority=HookPriority.SYSTEM.value,
+              callback=lambda d, e, et=event_type: monitor.track_event(et, d, e.source)
+          )
+          await bus.register_hook(hook)
+
+      print("event monitor running. press ctrl+c to stop.")
+      print("trigger events in the application...\n")
+
+      try:
+          while True:
+              await asyncio.sleep(1)
+      except KeyboardInterrupt:
+          monitor.print_summary()
+
+  asyncio.run(main())
+
+
+advanced: event flow visualization
+
+create a text-based event flow diagram:
+
+  1. enable event logging
+  2. trigger a user action
+  3. extract event sequence from logs:
+     <terminal>grep "event.*from\|phase" .kollabor-cli/logs/kollabor.log | grep "USER_INPUT" > event_flow.txt</terminal>
+  4. format as flow diagram:
+
+  USER_INPUT_PRE
+    |-- enhanced_input.validate_format [2ms]
+    +-- workflow_enforcement.check_rules [1ms]
+  USER_INPUT
+    |-- llm_service.prepare_request [5ms]
+    +-- conversation_manager.add_to_history [1ms]
+  USER_INPUT_POST
+    +-- display.update_status [1ms]
+
+  total: 10ms
+
+
+troubleshooting tips:
+
+tip 1: no events appearing in logs
+  - verify logging level is set to DEBUG
+  - check event_bus is properly initialized
+  - verify emit_with_hooks is being called
+  - add print statement at emit_with_hooks entry
+
+tip 2: events firing but hooks not executing
+  - check hook status: "hook_enabled: false"
+  - verify hook.event_type matches emitted event
+  - check for event cancellation by earlier hooks
+  - verify hook priority (lower than expected?)
+
+tip 3: performance degradation over time
+  - monitor event_count for unexpected growth
+  - check for memory leaks in event data
+  - look for hooks that don't clean up resources
+  - profile hook callback functions
+
+tip 4: missing pre/post phases
+  - verify event type is in pre_post_map
+  - check eventprocessor.add_event_type_mapping for custom events
+  - some events don't have pre/post phases (by design)
+
+tip 5: event storms (too many events)
+  - identify source of high-frequency events
+  - check render_frame events (can fire 60x/second)
+  - look for loops where hooks emit same event
+  - consider debouncing high-frequency events
+
+
+expected output:
+
+when this skill executes successfully, you should be able to:
+
+  [ ] list all event types and their listener counts
+  [ ] see real-time event flow in logs
+  [ ] identify which hooks are slow
+  [ ] trace complete event flow for any action
+  [ ] understand pre/main/post phase execution
+  [ ] measure event processing performance
+  [ ] visualize event flow patterns
+
+
+status tags reference:
+
+  [ok]   event system working normally
+  [warn] high event volume or slow processing
+  [error] event failures or system broken
+  [todo]  optimization needed
+
+
+quick reference commands:
+
+show all event emission points:
+  grep -rn "emit_with_hooks" core/ --include="*.py"
+
+show all registered hooks by plugin:
+  grep -rn "Hook(" plugins/ --include="*.py" | grep -v "^.*:#"
+
+monitor live events:
+  tail -f .kollabor-cli/logs/kollabor.log | grep -i "event"
+
+find slow hooks (>50ms):
+  grep "duration_ms" .kollabor-cli/logs/kollabor.log | awk -F: '$2 > 50'
+
+show hooks for specific event:
+  grep -rn "USER_INPUT" plugins/ --include="*.py" | grep "Hook("
+
+check event cancellations:
+  grep -i "cancel" .kollabor-cli/logs/kollabor.log