packages/frontend/lib/features/agent/models/agent_tool_event.dart

import 'agent_tool_id.dart';
import 'agent_tool_metadata.dart';

/// Summary of a single tool invocation performed during an agent turn.
enum ToolStatus { running, success, error }

enum WriteFileChangeKind { created, updated }

class AgentToolEvent {
  const AgentToolEvent({
    required this.toolId,
    required this.summary,
    required this.status,
    this.skipped = false,
    this.subAction,
    this.targetPath,
    this.startLine,
    this.endLine,
    this.writeFileChangeKind,
    this.requiresPreviewRebuild = false,
    this.patchReplacementCount,
    this.errorMessage,
    this.callId,
    this.screenshotBase64,
  });

  /// Stable identifier of the invoked tool.
  final AgentToolId toolId;

  /// The execution status of this tool invocation.
  final ToolStatus status;

  /// Short human-readable description of what the tool did.
  final String summary;

  /// Whether the tool invocation completed as a non-mutating no-op.
  final bool skipped;

  /// Normalized sub-action identifier for tools with multiple modes
  /// (e.g. 'clean', 'pub_get', 'full_rebuild' for workspace maintenance).
  final String? subAction;

  /// Workspace-relative path targeted by the tool, when applicable.
  final String? targetPath;

  /// First affected line for ranged file reads, when applicable.
  final int? startLine;

  /// Last affected line for ranged file reads, when applicable.
  final int? endLine;

  /// Whether a file write created a new file or updated an existing one.
  final WriteFileChangeKind? writeFileChangeKind;

  /// Whether this mutation should rebuild the preview instead of hot reloading.
  final bool requiresPreviewRebuild;

  /// Number of replacements applied by a patch-style tool, when applicable.
  final int? patchReplacementCount;

  /// Failure message captured from the tool call, if any.
  final String? errorMessage;

  /// Unique identifier of the tool invocation call (used to update UI in-place).
  final String? callId;

  /// Base64-encoded PNG screenshot captured by the tool, if applicable.
  ///
  /// Present only for screenshot tool calls. Displayed as a thumbnail
  /// in the tool event row.
  final String? screenshotBase64;

  /// Whether the tool call completed successfully.
  bool get success => status == ToolStatus.success;

  /// Category for UI styling and accessibility grouping.
  AgentToolUiKind get uiKind => toolId.uiKind;

  /// Capabilities required or declared by the tool.
  Set<AgentToolCapability> get capabilities => toolId.capabilities;

  /// The tool's wire name used for UI display and tool registration.
  String get toolName => toolId.name;

  /// Check whether this tool provides a specific capability.
  bool hasCapability(AgentToolCapability capability) => capabilities.contains(capability);

  /// Whether this event represents a successful workspace file mutation.
  bool get changedFileInWorkspace =>
      success && targetPath != null && hasCapability(AgentToolCapability.workspaceMutate);
}