@flatfile/improv/docs/events.md

A powerful TypeScript library for building AI agents with multi-threaded conversations, tool execution, and event handling capabilities

# Improv Events Reference

This document provides a complete reference of all events emitted throughout the Improv library. For usage examples and patterns, see the [Event System Guide](./events-guide.md).

## Quick Reference

```typescript
import { 
  MESSAGE_EVENTS, 
  THREAD_EVENTS, 
  AGENT_EVENTS, 
  TOOL_EVENTS, 
  GIG_EVENTS, 
  PIECE_EVENTS 
} from '@flatfile/improv';
```

## Event Naming Analysis

### Current Naming Patterns

- **Dot-separated**: `namespace.action` (e.g., `thread.response`, `agent.tool-added`)
- **Underscore in actions**: `thread.max_steps_reached`, `thread.message-added`
- **Hyphen in actions**: `agent.tool-added`, `agent.thread-added`

### Inconsistencies Identified

1. **Mixed separators**: Some use hyphens (`tool-added`) while others use underscores (`max_steps_reached`)
2. **Action tense**: Mix of past tense (`tool-added`) and present tense (`starting`)
3. **Namespace variations**: Some events use full words (`thread`, `agent`) while others use abbreviations

## Complete Event Registry

### Message Events - Managing individual messages

| Event Name | Source | Payload | Description |
|------------|--------|---------|-------------|
| `message.added` | Thread | `{ thread: Thread, message: Message }` | Message added to thread |
| `message.removed` | Thread | `{ thread: Thread, message: Message }` | Message removed from thread |
| `message.sent` | Thread | `{ thread: Thread, message?: Message }` | Message sent to LLM |
| `message.received` | Thread | `{ thread: Thread, message: Message }` | Message received from LLM |
| `messages.cleared` | Thread | `{ thread: Thread, removedMessages: Message[] }` | Messages cleared from thread |

### Thread Events - Managing conversation threads

| Event Name | Source | Payload | Description |
|------------|--------|---------|-------------|
| `thread.max-steps-reached` | Thread | `{ thread: Thread, steps: number }` | Maximum steps exceeded |
| `thread.error-occurred` | Thread | `{ thread: Thread, error: Error }` | Error occurred in thread |
| `thread.tool-added` | Thread | `{ thread: Thread, tool: Tool }` | Tool added to thread |

### Agent Events - Managing AI agents

| Event Name | Source | Payload | Description |
|------------|--------|---------|-------------|
| `agent.tool-added` | Agent | `{ agent: Agent, tool: Tool }` | Tool added to agent |
| `agent.thread-created` | Agent | `{ agent: Agent, thread: Thread }` | Thread created in agent |
| `agent.thread-closed` | Agent | `{ agent: Agent, thread: Thread }` | Thread closed in agent |
| `agent.knowledge-added` | Agent | `{ agent: Agent, knowledge: AgentKnowledge }` | Knowledge added to agent |
| `agent.instruction-added` | Agent | `{ agent: Agent, instruction: AgentInstruction }` | Instruction added to agent |

### Tool Events - Tool execution lifecycle

| Event Name | Source | Payload | Description |
|------------|--------|---------|-------------|
| `tool.started` | Tool | `{ tool: Tool, name: string, args: any }` | Tool execution started |
| `tool.completed` | Tool | `{ tool: Tool, name: string, args: any, result: any }` | Tool execution completed |
| `tool.failed` | Tool | `{ tool: Tool, name: string, args: any, toolCall: ToolCall, error: string }` | Tool execution failed |
| `tool.followup-added` | Tool | `{ tool: Tool, message: string }` | Follow-up message added to tool |
| `tool.messages-generated` | Tool | `{ tool: Tool, messages: Message[] }` | Messages generated from tool |

### Gig Events - Workflow orchestration

| Event Name | Source | Payload | Description |
|------------|--------|---------|-------------|
| `gig.performance-completed` | Gig | `{ gig: Gig, results: GigResults }` | Gig performance completed successfully |
| `gig.performance-failed` | Gig | `{ gig: Gig, error: Error, results: GigResults }` | Gig performance failed |

### Piece Events - Individual workflow pieces

| Event Name | Source | Payload | Description |
|------------|--------|---------|-------------|
| `piece.execution-completed` | Gig | `{ gig: Gig, piece: string, recording: any }` | Piece execution completed |
| `piece.execution-failed` | Gig | `{ gig: Gig, piece: string, error: Error }` | Piece execution failed |
| `piece.execution-skipped` | Gig | `{ gig: Gig, piece: string }` | Piece execution skipped |
| `piece.execution-started` | Gig | `{ gig: Gig, piece: string }` | Piece execution started |
| `piece.retry-attempted` | Gig | `{ gig: Gig, piece: string, attempt: number, error: Error }` | Piece retry attempted |

### Debug Events

| Event Name | Source | Payload | Description |
|------------|--------|---------|-------------|
| `debug` | Model Drivers | `string, object` | Debug information from drivers |

## ✅ Standardization Applied

### Implemented Naming Conventions

1. **Namespace**: Use full descriptive names (`thread`, `agent`, `tool`, `gig`, `piece`)
2. **Action separator**: Use hyphens consistently for multi-word actions
3. **Action tense**: Use past tense for completed actions (`started`, `completed`, `failed`)
4. **Descriptive names**: Make event names clear and descriptive
5. **Hierarchical namespacing**: Use dots for sub-categories (`tool.execution.started`)

### Changes Applied

| Old Name | New Name | Improvement |
|----------|----------|-------------|
| `thread.response` | `thread.response-received` | More descriptive |
| `thread.sent` | `thread.message-sent` | More specific |
| `thread.error` | `thread.error-occurred` | More descriptive |
| `agent.thread-added` | `agent.thread-created` | More accurate action |
| `agent.thread-removed` | `agent.thread-closed` | More accurate action |
| `tool.execution.started` | `tool.started` | Simpler and cleaner |
| `tool.execution.completed` | `tool.completed` | Simpler and cleaner |
| `tool.execution.failed` | `tool.failed` | Simpler and cleaner |
| `tool.followup.set` | `tool.followup-added` | Consistent with other actions |
| `tool.messages.generated` | `tool.messages-generated` | Consistent separator |
| `gig.complete` | `gig.performance-completed` | More descriptive |
| `gig.failed` | `gig.performance-failed` | More descriptive |
| `piece.complete` | `piece.execution-completed` | More descriptive and consistent |
| `piece.failed` | `piece.execution-failed` | More descriptive and consistent |
| `piece.skipped` | `piece.execution-skipped` | More descriptive and consistent |
| `piece.starting` | `piece.execution-started` | Consistent tense and descriptive |
| `piece.retry` | `piece.retry-attempted` | More descriptive |

### Event Payload Standardization

All events should consistently include:

- **Source object**: The originating instance (`thread`, `agent`, `tool`, `gig`)
- **Context data**: Relevant data for the event
- **Consistent naming**: Use consistent field names across similar events

## Future Considerations

1. **Event versioning**: Consider adding version info for breaking changes
2. **Event filtering**: Support for event filtering/subscription patterns
3. **Event metadata**: Add timestamps, correlation IDs, etc.
4. **Performance events**: Add performance metrics for debugging
5. **Lifecycle events**: Add creation/destruction events for major objects