<?php
/**
 * The transcript line format.
 *
 * @package MazeAi
 * @since   0.1.0
 */

declare(strict_types=1);

namespace MazeAi\Chat;

defined('ABSPATH') || exit;

use MazeAi\I18n\StoredMessage;
use MazeAi\Kernel\Support\ToolOutcome;
use MazeAi\Support\Redactor;

/**
 * A session is an append-only list of JSON lines, the way desktop AI tools keep their transcripts. Version 1:
 *
 * ```jsonl
 * {"v":1,"type":"message","role":"user","parts":[{"type":"text","text":"What PHP version is this?"}],"ts":"…"}
 * {"v":1,"type":"message","role":"assistant","parts":[{"type":"tool_call","id":"c1","name":"core/get-environment-info","args":{}}],"run":"…","step":0,"model":"openai:gpt-…","usage":{"in":812,"out":19},"duration_ms":842,"finish":"tool_calls","ts":"…"}
 * {"v":1,"type":"message","role":"tool","parts":[{"type":"tool_result","id":"c1","name":"core/get-environment-info","status":"ok","data":{…},"ui":{"summary":"7 fields"}}],"run":"…","step":0,"ts":"…"}
 * {"v":1,"type":"message","role":"assistant","parts":[{"type":"text","text":"PHP 8.3.35."}],"run":"…","step":1,…}
 * {"v":1,"type":"event","event":"run_finished","reason":"stop","run":"…","ts":"…"}
 * ```
 *
 * Parts: `text` {text}; `tool_call` {id, name, args, state?}; `tool_result` {id, name, status ok|blocked|error, data?,
 * content?, ui {summary, change?}, code?, error?, tainted?} (lines written before decision 036 have `result` instead
 * of `data`; `MazeAi\Kernel\Support\ToolOutcome::fromPart()` reads both).
 * Events: `run_finished` {reason stop|max_steps|length|cancelled|error|…}, `error` {code, message}, `notice` {code, message},
 * `retry` {step, attempt, retry_after, code, message}, `approval_requested` {id, step, calls [{id, name, preview, code}],
 * tainted}, `approval_resolved` {id, step, approved, refused}, `auto_approved` {run, step, call, tool, mode},
 * `permission_mode_changed` {from, to}, `delegated` {step, call, agent, child | denied, message},
 * `compaction` {upto, summary, usage}, `change_undone` {change, tool},
 * `rewind` {to}: every line after `to` up to this one is superseded (regenerate, edit-and-resend). Nothing is ever
 * removed from the log; readers apply rewinds in order (`visible()`), and the export keeps the full history.
 * `state` is opaque provider continuation state (Gemini's thought signature): only the model adapter reads or writes it,
 * and it is sent back unchanged on later turns. New part and event types may be added; readers skip what they do not know. `seq` is added by the store.
 *
 * @since 0.1.0
 */
final class Transcript
{
    public const VERSION = 1;

    /**
     * @param list<array<string, mixed>> $parts
     * @param array<string, mixed>       $extra
     * @return array<string, mixed>
     */
    public static function message(string $role, array $parts, array $extra = []): array
    {
        return ['v' => self::VERSION, 'type' => 'message', 'role' => $role, 'parts' => $parts] + $extra + ['ts' => self::now()];
    }

    /**
     * @param array<string, mixed> $data
     * @return array<string, mixed>
     */
    public static function event(string $event, array $data = []): array
    {
        return ['v' => self::VERSION, 'type' => 'event', 'event' => $event] + $data + ['ts' => self::now()];
    }

    /**
     * The conversation the model sees: messages only, with any tool call that never got a result (a cancelled or
     * crashed step) removed, because providers reject a call without its answer.
     *
     * @param list<array<string, mixed>> $entries
     * @return list<array{role: string, parts: list<array<string, mixed>>}>
     */
    public static function conversation(array $entries): array
    {
        $messages = array_values(array_filter(self::visible($entries), static fn (array $e): bool => ($e['type'] ?? '') === 'message'));
        $answered = [];
        foreach ($messages as $message) {
            foreach ($message['parts'] as $part) {
                if (($part['type'] ?? '') === 'tool_result') {
                    $answered[(string) $part['id']] = true;
                }
            }
        }

        $out = [];
        foreach ($messages as $message) {
            $parts = array_values(array_filter(
                $message['parts'],
                static fn (array $part): bool => in_array($part['type'] ?? '', ['text', 'tool_call', 'tool_result'], true)
                    && (($part['type'] !== 'tool_call') || isset($answered[(string) $part['id']]))
                    && ($part['type'] !== 'text' || trim((string) $part['text']) !== ''),
            ));
            if ($parts !== []) {
                $out[] = ['role' => (string) $message['role'], 'parts' => $parts];
            }
        }

        return $out;
    }

    /**
     * The transcript as it now reads: each `rewind` drops the lines after its `to`, and is dropped itself.
     *
     * @param list<array<string, mixed>> $entries In `seq` order.
     * @return list<array<string, mixed>>
     */
    public static function visible(array $entries): array
    {
        $kept = [];
        foreach ($entries as $entry) {
            if (($entry['type'] ?? '') === 'event' && ($entry['event'] ?? '') === 'rewind') {
                $to   = (int) ($entry['to'] ?? 0);
                $kept = array_values(array_filter($kept, static fn (array $e): bool => (int) ($e['seq'] ?? 0) <= $to));
                continue;
            }
            $kept[] = $entry;
        }

        return $kept;
    }

    /**
     * The last user message of the visible transcript, or null.
     *
     * @param list<array<string, mixed>> $entries
     * @return array<string, mixed>|null
     */
    public static function lastUserMessage(array $entries): ?array
    {
        $visible = self::visible($entries);
        for ($i = count($visible) - 1; $i >= 0; $i--) {
            if (($visible[$i]['type'] ?? '') === 'message' && ($visible[$i]['role'] ?? '') === 'user') {
                return $visible[$i];
            }
        }

        return null;
    }

    /**
     * The plain text of a message entry.
     *
     * @param array<string, mixed> $entry
     */
    public static function text(array $entry): string
    {
        $texts = [];
        foreach ($entry['parts'] ?? [] as $part) {
            if (($part['type'] ?? '') === 'text') {
                $texts[] = (string) $part['text'];
            }
        }

        return Redactor::mask(trim(implode("\n\n", $texts)));
    }

    /**
     * Remove key-shaped secrets before a transcript line reaches durable storage. Opaque provider continuation state
     * is excluded because the model adapter must return it unchanged.
     *
     * @since 0.1.0
     * @param array<string, mixed> $entry
     * @return array<string, mixed>
     */
    public static function redactSensitive(array $entry): array
    {
        $hasState = array_key_exists('state', $entry);
        $state    = $entry['state'] ?? null;
        unset($entry['state']);

        $partStates = [];
        if (isset($entry['parts']) && is_array($entry['parts'])) {
            foreach ($entry['parts'] as $index => &$part) {
                if (is_array($part) && ($part['type'] ?? '') === 'tool_call' && array_key_exists('state', $part)) {
                    $partStates[$index] = $part['state'];
                    unset($part['state']);
                }
            }
            unset($part);
        }

        $entry = Redactor::maskDeep($entry);
        if (($entry['type'] ?? '') === 'message' && in_array($entry['role'] ?? '', ['user', 'assistant'], true) && isset($entry['parts']) && is_array($entry['parts'])) {
            foreach ($entry['parts'] as &$part) {
                if (is_array($part) && ($part['type'] ?? '') === 'text' && is_string($part['text'] ?? null)) {
                    // Human chat can contain a key from a provider whose format we do not know yet. Apply the
                    // generic long-token matcher to this text only; site data can contain hashes and IDs.
                    $part['text'] = Redactor::mask($part['text']);
                }
            }
            unset($part);
        }
        if ($hasState) {
            $entry['state'] = $state;
        }
        foreach ($partStates as $index => $partState) {
            if (isset($entry['parts'][$index]) && is_array($entry['parts'][$index])) {
                $entry['parts'][$index]['state'] = $partState;
            }
        }

        return $entry;
    }

    /**
     * A title from the first words of the first message (no model call, nothing extra sent anywhere).
     *
     * @since 0.1.0
     */
    public static function title(string $text): string
    {
        $text = Redactor::mask(trim((string) preg_replace('/\s+/u', ' ', wp_strip_all_tags($text))));
        if (mb_strlen($text) <= 60) {
            return $text;
        }
        $cut   = mb_substr($text, 0, 60);
        $space = mb_strrpos($cut, ' ');

        return rtrim($space !== false && $space > 30 ? mb_substr($cut, 0, $space) : $cut, " ,.;:-") . '…';
    }

    /**
     * Entries as the browser and the export see them: only what a person or the app uses. The model adapter's
     * opaque `state`, the model-facing `content` of tool results, client ids, compaction summaries and the ids of
     * sub-agent sessions stay in the database. A tool result is sent as its status, its trace-card `ui` and, for
     * the person to inspect, the site data the assistant read (`detail`).
     *
     * @since 0.1.0
     * @param list<array<string, mixed>> $entries
     * @return list<array<string, mixed>>
     */
    public static function forClient(array $entries): array
    {
        return array_map(static function (array $entry): array {
            $entry = self::redactSensitive($entry);
            unset($entry['client_id']);
            if (isset($entry['parts']) && is_array($entry['parts'])) {
                $entry['parts'] = array_map([self::class, 'partForClient'], $entry['parts']);
            }
            if (($entry['type'] ?? '') === 'event') {
                unset($entry['summary'], $entry['usage'], $entry['child']);
                $entry = self::renderMessages($entry);
            }

            return $entry;
        }, $entries);
    }

    /**
     * Turn the stored messages of an event (an "undone" line, an approval's previews) into sentences in the viewer's
     * language. Older entries hold finished prose and pass through.
     *
     * @param array<string, mixed> $entry
     * @return array<string, mixed>
     */
    private static function renderMessages(array $entry): array
    {
        if (is_string($entry['message'] ?? null)) {
            $entry['message'] = StoredMessage::render($entry['message']);
        }
        if (is_array($entry['calls'] ?? null)) {
            $entry['calls'] = array_map(static function ($call) {
                if (is_array($call) && is_string($call['preview'] ?? null)) {
                    $call['preview'] = StoredMessage::render($call['preview']);
                }

                return $call;
            }, $entry['calls']);
        }

        return $entry;
    }

    /**
     * @since 0.1.0
     */
    public static function partForClient(mixed $part): mixed
    {
        if (!is_array($part)) {
            return $part;
        }
        unset($part['state']);
        if (($part['type'] ?? '') !== 'tool_result') {
            return $part;
        }

        $outcome = ToolOutcome::fromPart($part);
        $client  = ['type' => 'tool_result', 'id' => (string) ($part['id'] ?? ''), 'name' => (string) ($part['name'] ?? ''), 'status' => $outcome->status];
        if ($outcome->code !== '') {
            $client['code'] = $outcome->code;
        }
        if ($outcome->error !== '') {
            $client['error'] = $outcome->error;
        }
        $client['ui'] = $outcome->ui + ['summary' => $outcome->error];
        if (is_string($client['ui']['summary'] ?? null)) {
            $client['ui']['summary'] = StoredMessage::render($client['ui']['summary']);
        }
        if ($outcome->ok()) {
            $client['detail'] = $outcome->data;
        }

        return $client;
    }

    /**
     * The entries as JSONL, one line each.
     *
     * @param list<array<string, mixed>> $entries
     */
    public static function jsonl(array $entries): string
    {
        $lines = array_map(static fn (array $entry): string => (string) wp_json_encode($entry, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE), $entries);

        return $lines === [] ? '' : implode("\n", $lines) . "\n";
    }

    private static function now(): string
    {
        return gmdate('Y-m-d\TH:i:s\Z');
    }
}