events

Class info

Classes

Name	Children	Inherits
ChatMessage llmling_agent.messaging.messages Common message format for all UI types.		Generic
CommandCompleteEvent llmling_agent.agent.events Event indicating slash command execution is complete.		object
CommandOutputEvent llmling_agent.agent.events Event for slash command output.		object
CustomEvent llmling_agent.agent.events Generic custom event that can be emitted during tool execution.		Generic
DiffContentItem llmling_agent.agent.events File modification shown as a diff.		object
FileEditProgressEvent llmling_agent.agent.events Event for file edit progress with diff information.		object
FileOperationEvent llmling_agent.agent.events Event for filesystem operations.		object
LocationContentItem llmling_agent.agent.events A file location being accessed or modified.		object
PlanUpdateEvent llmling_agent.agent.events Event indicating plan state has changed.		object
ProcessExitEvent llmling_agent.agent.events Event for process completion.		object
ProcessKillEvent llmling_agent.agent.events Event for process termination.		object
ProcessOutputEvent llmling_agent.agent.events Event for process output updates.		object
ProcessReleaseEvent llmling_agent.agent.events Event for process resource cleanup.		object
ProcessStartEvent llmling_agent.agent.events Event for process start operations.		object
RunErrorEvent llmling_agent.agent.events Signals an error during an agent run.		object
RunStartedEvent llmling_agent.agent.events Signals the start of an agent run.		object
StreamCompleteEvent llmling_agent.agent.events Event indicating streaming is complete with final message.		Generic
TerminalContentItem llmling_agent.agent.events Embed a terminal for live output display.		object
TextContentItem llmling_agent.agent.events Simple text content.		object
ToolCallCompleteEvent llmling_agent.agent.events Event indicating tool call is complete with both input and output.		object
ToolCallProgressEvent llmling_agent.agent.events Enhanced tool call progress event with rich content support.		object
ToolCallStartEvent llmling_agent.agent.events Event indicating a tool call has started with rich ACP metadata.		object

🛈 DocStrings

Event stream events.

TODO: The specialized process and file events (ProcessStartEvent, ProcessExitEvent, FileOperationEvent, etc.) are essentially domain-specific versions of ToolCallProgressEvent. These could potentially be merged into a single, more flexible ToolCallProgressEvent that carries rich content (terminals, diffs, locations) and domain metadata. This would align better with the ACP protocol's tool call structure and reduce event type proliferation.

CommandCompleteEvent dataclass

Event indicating slash command execution is complete.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class CommandCompleteEvent:
    """Event indicating slash command execution is complete."""

    command: str
    """The command name that was completed."""
    success: bool
    """Whether the command executed successfully."""
    event_kind: Literal["command_complete"] = "command_complete"
    """Event type identifier."""

command instance-attribute

command: str

The command name that was completed.

event_kind class-attribute instance-attribute

event_kind: Literal['command_complete'] = 'command_complete'

Event type identifier.

success instance-attribute

success: bool

Whether the command executed successfully.

CommandOutputEvent dataclass

Event for slash command output.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class CommandOutputEvent:
    """Event for slash command output."""

    command: str
    """The command name that was executed."""
    output: str
    """The output text from the command."""
    event_kind: Literal["command_output"] = "command_output"
    """Event type identifier."""

command instance-attribute

command: str

The command name that was executed.

event_kind class-attribute instance-attribute

event_kind: Literal['command_output'] = 'command_output'

Event type identifier.

output instance-attribute

output: str

The output text from the command.

CustomEvent dataclass

Generic custom event that can be emitted during tool execution.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class CustomEvent[T]:
    """Generic custom event that can be emitted during tool execution."""

    event_data: T
    """The custom event data of any type."""
    event_type: str = "custom"
    """Type identifier for the custom event."""
    source: str | None = None
    """Optional source identifier (tool name, etc.)."""
    event_kind: Literal["custom"] = "custom"
    """Event type identifier."""

event_data instance-attribute

event_data: T

The custom event data of any type.

event_kind class-attribute instance-attribute

event_kind: Literal['custom'] = 'custom'

Event type identifier.

event_type class-attribute instance-attribute

event_type: str = 'custom'

Type identifier for the custom event.

source class-attribute instance-attribute

source: str | None = None

Optional source identifier (tool name, etc.).

DiffContentItem dataclass

File modification shown as a diff.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class DiffContentItem:
    """File modification shown as a diff."""

    type: Literal["diff"] = "diff"
    """Content type identifier."""
    path: str
    """The file path being modified."""
    old_text: str | None = None
    """The original content (None for new files)."""
    new_text: str
    """The new content after modification."""

new_text instance-attribute

new_text: str

The new content after modification.

old_text class-attribute instance-attribute

old_text: str | None = None

The original content (None for new files).

path instance-attribute

path: str

The file path being modified.

type class-attribute instance-attribute

type: Literal['diff'] = 'diff'

Content type identifier.

FileEditProgressEvent dataclass

Event for file edit progress with diff information.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class FileEditProgressEvent:
    """Event for file edit progress with diff information."""

    path: str
    """The file path being edited."""
    old_text: str
    """Original file content."""
    new_text: str
    """New file content."""
    status: Literal["in_progress", "completed", "failed"]
    """Current status of the edit operation."""
    changed_lines: list[int] = field(default_factory=list)
    """Line numbers that were changed."""
    tool_call_id: str | None = None
    """Tool call ID for ACP notifications."""
    event_kind: Literal["file_edit_progress"] = "file_edit_progress"
    """Event type identifier."""

changed_lines class-attribute instance-attribute

changed_lines: list[int] = field(default_factory=list)

Line numbers that were changed.

event_kind class-attribute instance-attribute

event_kind: Literal['file_edit_progress'] = 'file_edit_progress'

Event type identifier.

new_text instance-attribute

new_text: str

New file content.

old_text instance-attribute

old_text: str

Original file content.

path instance-attribute

path: str

The file path being edited.

status instance-attribute

status: Literal['in_progress', 'completed', 'failed']

Current status of the edit operation.

tool_call_id class-attribute instance-attribute

tool_call_id: str | None = None

Tool call ID for ACP notifications.

FileOperationEvent dataclass

Event for filesystem operations.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class FileOperationEvent:
    """Event for filesystem operations."""

    operation: Literal["read", "write", "delete", "list", "edit"]
    """The filesystem operation performed."""
    path: str
    """The file/directory path that was operated on."""
    success: bool
    """Whether the operation completed successfully."""
    error: str | None = None
    """Error message if operation failed."""
    size: int | None = None
    """Size of file in bytes (for successful operations)."""
    tool_call_id: str | None = None
    """Tool call ID for ACP notifications."""

    # Rich ACP metadata
    title: str | None = None
    """Display title for the operation."""
    kind: str | None = None
    """Tool operation kind (edit, read, write, etc.)."""
    locations: list[str] = field(default_factory=list)
    """File paths affected by the operation."""
    raw_input: dict[str, Any] = field(default_factory=dict)
    """Original tool input arguments."""
    raw_output: Any = None
    """Tool result data for failed operations."""

    event_kind: Literal["file_operation"] = "file_operation"
    """Event type identifier."""

error class-attribute instance-attribute

error: str | None = None

Error message if operation failed.

event_kind class-attribute instance-attribute

event_kind: Literal['file_operation'] = 'file_operation'

Event type identifier.

kind class-attribute instance-attribute

kind: str | None = None

Tool operation kind (edit, read, write, etc.).

locations class-attribute instance-attribute

locations: list[str] = field(default_factory=list)

File paths affected by the operation.

operation instance-attribute

operation: Literal['read', 'write', 'delete', 'list', 'edit']

The filesystem operation performed.

path instance-attribute

path: str

The file/directory path that was operated on.

raw_input class-attribute instance-attribute

raw_input: dict[str, Any] = field(default_factory=dict)

Original tool input arguments.

raw_output class-attribute instance-attribute

raw_output: Any = None

Tool result data for failed operations.

size class-attribute instance-attribute

size: int | None = None

Size of file in bytes (for successful operations).

success instance-attribute

success: bool

Whether the operation completed successfully.

title class-attribute instance-attribute

title: str | None = None

Display title for the operation.

tool_call_id class-attribute instance-attribute

tool_call_id: str | None = None

Tool call ID for ACP notifications.

LocationContentItem dataclass

A file location being accessed or modified.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class LocationContentItem:
    """A file location being accessed or modified."""

    type: Literal["location"] = "location"
    """Content type identifier."""
    path: str
    """The file path being accessed or modified."""
    line: int | None = None
    """Optional line number within the file."""

line class-attribute instance-attribute

line: int | None = None

Optional line number within the file.

path instance-attribute

path: str

The file path being accessed or modified.

type class-attribute instance-attribute

type: Literal['location'] = 'location'

Content type identifier.

PlanUpdateEvent dataclass

Event indicating plan state has changed.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class PlanUpdateEvent:
    """Event indicating plan state has changed."""

    entries: list[PlanEntry]
    """Current plan entries."""
    tool_call_id: str | None = None
    """Tool call ID for ACP notifications."""
    event_kind: Literal["plan_update"] = "plan_update"
    """Event type identifier."""

entries instance-attribute

entries: list[PlanEntry]

Current plan entries.

event_kind class-attribute instance-attribute

event_kind: Literal['plan_update'] = 'plan_update'

Event type identifier.

tool_call_id class-attribute instance-attribute

tool_call_id: str | None = None

Tool call ID for ACP notifications.

ProcessExitEvent dataclass

Event for process completion.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class ProcessExitEvent:
    """Event for process completion."""

    process_id: str
    """Process identifier."""
    exit_code: int
    """Process exit code."""
    success: bool
    """Whether the process completed successfully (exit_code == 0)."""
    final_output: str | None = None
    """Final process output."""
    truncated: bool = False
    """Whether output was truncated due to limits."""
    tool_call_id: str | None = None
    """Tool call ID for notifications."""

    event_kind: Literal["process_exit"] = "process_exit"
    """Event type identifier."""

event_kind class-attribute instance-attribute

event_kind: Literal['process_exit'] = 'process_exit'

Event type identifier.

exit_code instance-attribute

exit_code: int

Process exit code.

final_output class-attribute instance-attribute

final_output: str | None = None

Final process output.

process_id instance-attribute

process_id: str

Process identifier.

success instance-attribute

success: bool

Whether the process completed successfully (exit_code == 0).

tool_call_id class-attribute instance-attribute

tool_call_id: str | None = None

Tool call ID for notifications.

truncated class-attribute instance-attribute

truncated: bool = False

Whether output was truncated due to limits.

ProcessKillEvent dataclass

Event for process termination.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class ProcessKillEvent:
    """Event for process termination."""

    process_id: str
    """Process identifier."""
    success: bool
    """Whether the process was successfully killed."""
    error: str | None = None
    """Error message if kill failed."""
    tool_call_id: str | None = None
    """Tool call ID for notifications."""

    event_kind: Literal["process_kill"] = "process_kill"
    """Event type identifier."""

error class-attribute instance-attribute

error: str | None = None

Error message if kill failed.

event_kind class-attribute instance-attribute

event_kind: Literal['process_kill'] = 'process_kill'

Event type identifier.

process_id instance-attribute

process_id: str

Process identifier.

success instance-attribute

success: bool

Whether the process was successfully killed.

tool_call_id class-attribute instance-attribute

tool_call_id: str | None = None

Tool call ID for notifications.

ProcessOutputEvent dataclass

Event for process output updates.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class ProcessOutputEvent:
    """Event for process output updates."""

    process_id: str
    """Process identifier."""
    output: str
    """Process output (stdout/stderr combined)."""
    stdout: str | None = None
    """Standard output (if separated)."""
    stderr: str | None = None
    """Standard error (if separated)."""
    truncated: bool = False
    """Whether output was truncated due to limits."""
    tool_call_id: str | None = None
    """Tool call ID for notifications."""

    event_kind: Literal["process_output"] = "process_output"
    """Event type identifier."""

event_kind class-attribute instance-attribute

event_kind: Literal['process_output'] = 'process_output'

Event type identifier.

output instance-attribute

output: str

Process output (stdout/stderr combined).

process_id instance-attribute

process_id: str

Process identifier.

stderr class-attribute instance-attribute

stderr: str | None = None

Standard error (if separated).

stdout class-attribute instance-attribute

stdout: str | None = None

Standard output (if separated).

tool_call_id class-attribute instance-attribute

tool_call_id: str | None = None

Tool call ID for notifications.

truncated class-attribute instance-attribute

truncated: bool = False

Whether output was truncated due to limits.

ProcessReleaseEvent dataclass

Event for process resource cleanup.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class ProcessReleaseEvent:
    """Event for process resource cleanup."""

    process_id: str
    """Process identifier."""
    success: bool
    """Whether resources were successfully released."""
    error: str | None = None
    """Error message if release failed."""
    tool_call_id: str | None = None
    """Tool call ID for notifications."""

    event_kind: Literal["process_release"] = "process_release"
    """Event type identifier."""

error class-attribute instance-attribute

error: str | None = None

Error message if release failed.

event_kind class-attribute instance-attribute

event_kind: Literal['process_release'] = 'process_release'

Event type identifier.

process_id instance-attribute

process_id: str

Process identifier.

success instance-attribute

success: bool

Whether resources were successfully released.

tool_call_id class-attribute instance-attribute

tool_call_id: str | None = None

Tool call ID for notifications.

ProcessStartEvent dataclass

Event for process start operations.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class ProcessStartEvent:
    """Event for process start operations."""

    process_id: str
    """Unique process identifier."""
    command: str
    """Command being executed."""
    args: list[str] = field(default_factory=list)
    """Command arguments."""
    cwd: str | None = None
    """Working directory."""
    env: dict[str, str] = field(default_factory=dict)
    """Environment variables."""
    output_limit: int | None = None
    """Maximum bytes of output to retain."""
    success: bool = True
    """Whether the process started successfully."""
    error: str | None = None
    """Error message if start failed."""
    tool_call_id: str | None = None
    """Tool call ID for notifications."""

    event_kind: Literal["process_start"] = "process_start"
    """Event type identifier."""

args class-attribute instance-attribute

args: list[str] = field(default_factory=list)

Command arguments.

command instance-attribute

command: str

Command being executed.

cwd class-attribute instance-attribute

cwd: str | None = None

Working directory.

env class-attribute instance-attribute

env: dict[str, str] = field(default_factory=dict)

Environment variables.

error class-attribute instance-attribute

error: str | None = None

Error message if start failed.

event_kind class-attribute instance-attribute

event_kind: Literal['process_start'] = 'process_start'

Event type identifier.

output_limit class-attribute instance-attribute

output_limit: int | None = None

Maximum bytes of output to retain.

process_id instance-attribute

process_id: str

Unique process identifier.

success class-attribute instance-attribute

success: bool = True

Whether the process started successfully.

tool_call_id class-attribute instance-attribute

tool_call_id: str | None = None

Tool call ID for notifications.

RunErrorEvent dataclass

Signals an error during an agent run.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class RunErrorEvent:
    """Signals an error during an agent run."""

    message: str
    """Error message."""
    code: str | None = None
    """Error code."""
    run_id: str | None = None
    """ID of the agent run that failed."""
    agent_name: str | None = None
    """Name of the agent that errored."""
    event_kind: Literal["run_error"] = "run_error"
    """Event type identifier."""

agent_name class-attribute instance-attribute

agent_name: str | None = None

Name of the agent that errored.

code class-attribute instance-attribute

code: str | None = None

Error code.

event_kind class-attribute instance-attribute

event_kind: Literal['run_error'] = 'run_error'

Event type identifier.

message instance-attribute

message: str

Error message.

run_id class-attribute instance-attribute

run_id: str | None = None

ID of the agent run that failed.

RunStartedEvent dataclass

Signals the start of an agent run.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class RunStartedEvent:
    """Signals the start of an agent run."""

    thread_id: str
    """ID of the conversation thread (conversation_id)."""
    run_id: str
    """ID of the agent run (unique per request/response cycle)."""
    agent_name: str | None = None
    """Name of the agent starting the run."""
    event_kind: Literal["run_started"] = "run_started"
    """Event type identifier."""

agent_name class-attribute instance-attribute

agent_name: str | None = None

Name of the agent starting the run.

event_kind class-attribute instance-attribute

event_kind: Literal['run_started'] = 'run_started'

Event type identifier.

run_id instance-attribute

run_id: str

ID of the agent run (unique per request/response cycle).

thread_id instance-attribute

thread_id: str

ID of the conversation thread (conversation_id).

StreamCompleteEvent dataclass

Event indicating streaming is complete with final message.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class StreamCompleteEvent[TContent]:
    """Event indicating streaming is complete with final message."""

    message: ChatMessage[TContent]
    """The final chat message with all metadata."""
    event_kind: Literal["stream_complete"] = "stream_complete"
    """Event type identifier."""

event_kind class-attribute instance-attribute

event_kind: Literal['stream_complete'] = 'stream_complete'

Event type identifier.

message instance-attribute

message: ChatMessage[TContent]

The final chat message with all metadata.

TerminalContentItem dataclass

Embed a terminal for live output display.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class TerminalContentItem:
    """Embed a terminal for live output display."""

    type: Literal["terminal"] = "terminal"
    """Content type identifier."""
    terminal_id: str
    """The ID of the terminal being embedded."""

terminal_id instance-attribute

terminal_id: str

The ID of the terminal being embedded.

type class-attribute instance-attribute

type: Literal['terminal'] = 'terminal'

Content type identifier.

TextContentItem dataclass

Simple text content.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class TextContentItem:
    """Simple text content."""

    type: Literal["text"] = "text"
    """Content type identifier."""
    text: str
    """The text content."""

text instance-attribute

text: str

The text content.

type class-attribute instance-attribute

type: Literal['text'] = 'text'

Content type identifier.

ToolCallCompleteEvent dataclass

Event indicating tool call is complete with both input and output.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class ToolCallCompleteEvent:
    """Event indicating tool call is complete with both input and output."""

    tool_name: str
    """The name of the tool that was called."""
    tool_call_id: str
    """The ID of the tool call."""
    tool_input: dict[str, Any]
    """The input provided to the tool."""
    tool_result: Any
    """The result returned by the tool."""
    agent_name: str
    """The name of the agent that made the tool call."""
    message_id: str
    """The message ID associated with this tool call."""
    event_kind: Literal["tool_call_complete"] = "tool_call_complete"
    """Event type identifier."""

agent_name instance-attribute

agent_name: str

The name of the agent that made the tool call.

event_kind class-attribute instance-attribute

event_kind: Literal['tool_call_complete'] = 'tool_call_complete'

Event type identifier.

message_id instance-attribute

message_id: str

The message ID associated with this tool call.

tool_call_id instance-attribute

tool_call_id: str

The ID of the tool call.

tool_input instance-attribute

tool_input: dict[str, Any]

The input provided to the tool.

tool_name instance-attribute

tool_name: str

The name of the tool that was called.

tool_result instance-attribute

tool_result: Any

The result returned by the tool.

ToolCallProgressEvent dataclass

Enhanced tool call progress event with rich content support.

This event can carry various types of rich content (terminals, diffs, locations, text) and maps directly to ACP tool call notifications. It serves as a unified replacement for specialized events like ProcessStartEvent, FileOperationEvent, etc.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class ToolCallProgressEvent:
    """Enhanced tool call progress event with rich content support.

    This event can carry various types of rich content (terminals, diffs, locations, text)
    and maps directly to ACP tool call notifications. It serves as a unified replacement
    for specialized events like ProcessStartEvent, FileOperationEvent, etc.
    """

    tool_call_id: str
    """The ID of the tool call."""
    status: Literal["pending", "in_progress", "completed", "failed"] = "in_progress"
    """Current execution status."""
    title: str | None = None
    """Human-readable title describing the operation."""

    # Rich content items (unified content + locations)
    items: list[ToolCallContentItem] = field(default_factory=list)
    """Rich content items (terminals, diffs, locations, text)."""

    # Legacy fields for backwards compatibility
    progress: int | None = None
    """The current progress of the tool call."""
    total: int | None = None
    """The total progress of the tool call."""
    message: str | None = None
    """Progress message (falls back to TextContentItem)."""
    tool_name: str | None = None
    """The name of the tool being called."""
    tool_input: dict[str, Any] | None = None
    """The input provided to the tool."""

    event_kind: Literal["tool_call_progress"] = "tool_call_progress"
    """Event type identifier."""

event_kind class-attribute instance-attribute

event_kind: Literal['tool_call_progress'] = 'tool_call_progress'

Event type identifier.

items class-attribute instance-attribute

items: list[ToolCallContentItem] = field(default_factory=list)

Rich content items (terminals, diffs, locations, text).

message class-attribute instance-attribute

message: str | None = None

Progress message (falls back to TextContentItem).

progress class-attribute instance-attribute

progress: int | None = None

The current progress of the tool call.

status class-attribute instance-attribute

status: Literal['pending', 'in_progress', 'completed', 'failed'] = 'in_progress'

Current execution status.

title class-attribute instance-attribute

title: str | None = None

Human-readable title describing the operation.

tool_call_id instance-attribute

tool_call_id: str

The ID of the tool call.

tool_input class-attribute instance-attribute

tool_input: dict[str, Any] | None = None

The input provided to the tool.

tool_name class-attribute instance-attribute

tool_name: str | None = None

The name of the tool being called.

total class-attribute instance-attribute

total: int | None = None

The total progress of the tool call.

ToolCallStartEvent dataclass

Event indicating a tool call has started with rich ACP metadata.

Source code in src/llmling_agent/agent/events.py

@dataclass(kw_only=True)
class ToolCallStartEvent:
    """Event indicating a tool call has started with rich ACP metadata."""

    tool_call_id: str
    """The ID of the tool call."""
    tool_name: str
    """The name of the tool being called."""
    title: str
    """Human-readable title describing what the tool is doing."""
    kind: ToolKind = "other"
    """Tool kind (read, edit, delete, move, search, execute, think, fetch, other)."""
    content: list[ToolCallContentItem] = field(default_factory=list)
    """Content produced by the tool call."""
    locations: list[LocationContentItem] = field(default_factory=list)
    """File locations affected by this tool call."""
    raw_input: dict[str, Any] = field(default_factory=dict)
    """The raw input parameters sent to the tool."""

    event_kind: Literal["tool_call_start"] = "tool_call_start"
    """Event type identifier."""

content class-attribute instance-attribute

content: list[ToolCallContentItem] = field(default_factory=list)

Content produced by the tool call.

event_kind class-attribute instance-attribute

event_kind: Literal['tool_call_start'] = 'tool_call_start'

Event type identifier.

kind class-attribute instance-attribute

kind: ToolKind = 'other'

Tool kind (read, edit, delete, move, search, execute, think, fetch, other).

locations class-attribute instance-attribute

locations: list[LocationContentItem] = field(default_factory=list)

File locations affected by this tool call.

raw_input class-attribute instance-attribute

raw_input: dict[str, Any] = field(default_factory=dict)

The raw input parameters sent to the tool.

title instance-attribute

title: str

Human-readable title describing what the tool is doing.

tool_call_id instance-attribute

tool_call_id: str

The ID of the tool call.

tool_name instance-attribute

tool_name: str

The name of the tool being called.