//
//  AgentEvent.swift
//  Zyquo Agent
//
//  Author: Simon-Pierre Boucher
//  Mail: contact@spboucher.ai
//
//  The engine→UI event stream. AgentLoop emits these while a run executes;
//  the CLI renderer (Phase 3) and the full UI (Phase 6) render EXCLUSIVELY
//  from this stream plus the persisted Transcript — nothing about a run is
//  observable any other way.
//

import Foundation

/// Coarse run state, for status pills and the sidebar activity indicator.
enum AgentRunStatus: Sendable, Equatable {
    /// Workspace/memory/system prompt being prepared.
    case preparing
    /// A model turn is streaming.
    case running
    /// Tool calls from the current turn are executing.
    case executingTools
    /// Context compaction in progress.
    case compacting
    /// A LoopGuard trip paused the run; waiting for resume/stop.
    case awaitingUser
    /// The run ended (see the accompanying `runFinished` outcome).
    case finished
}

/// How a run ended. Persisted in the Transcript.
enum AgentRunOutcome: Codable, Sendable {
    /// The model produced a final answer (its user-facing result summary).
    case completed(finalAnswer: String)
    /// The run failed with a human-readable reason (provider error, refusal,
    /// repeated truncation, model without tool support…).
    case failed(reason: String)
    /// The surrounding task was cancelled (user pressed Stop / ⌘.).
    case cancelled
    /// A LoopGuard trip was answered with "stop".
    case stoppedByUser(reason: String)
}

/// One event in the live run stream.
enum AgentEvent: Sendable {
    case statusChanged(AgentRunStatus)

    /// A new loop iteration began (step has its index + id; content follows).
    case stepStarted(AgentStep)
    /// Reasoning-model thinking text for the step, as it streams.
    case thinkingDelta(stepID: UUID, String)
    /// Assistant-visible text for the step, as it streams.
    case textDelta(stepID: UUID, String)

    /// The model opened a tool-call block — show the live chip immediately,
    /// before the arguments finish streaming.
    case toolCallStreaming(stepID: UUID, index: Int, id: String, name: String)
    /// Raw tool-call argument JSON fragments for the call at `index`
    /// (concatenate to render the command as it streams; may be partial JSON).
    case toolCallArgumentsDelta(stepID: UUID, index: Int, delta: String)

    /// A finalized tool call is about to execute (arguments complete,
    /// heading into the policy gate).
    case toolCallStarted(stepID: UUID, AgentToolInvocation)
    /// Live stdout/stderr/note chunks from the executing tool.
    case toolOutput(stepID: UUID, callID: String, ToolOutputChunk)
    /// The tool call finished; the invocation carries its ToolResult.
    case toolCallFinished(stepID: UUID, AgentToolInvocation)

    /// The step is complete (final AgentStep snapshot, with invocations).
    case stepCompleted(AgentStep)

    /// The plan/todo list changed (created or updated via `update_plan`).
    case planUpdated(TaskPlan)
    /// A LoopGuard limit tripped; the run is pausing (answer with
    /// `AgentLoop.resume(raisingBudget:)` or `AgentLoop.stop()`).
    case guardTripped(LoopGuardTrip)
    /// The MemoryManager compacted older history.
    case compactionPerformed(CompactionRecord)

    /// Terminal event — always the last one emitted.
    case runFinished(AgentRunOutcome)
}