<?php
/**
 * What one tool call produced.
 *
 * @package MazeAi
 * @since   0.1.0
 */

declare(strict_types=1);

namespace MazeAi\Kernel\Support;

defined('ABSPATH') || exit;

/**
 * The three-part tool result (decision 036): `data` is the structured value (masked and bounded) that code and evals
 * read, `content` is model-facing text when a tool has something better to say than its data (otherwise the model
 * reads `data`), and `ui` is what the person sees on the trace card: a one-line `summary` plus, for writes, the
 * `change` that can be undone. `status` is `ok`, `blocked` (policy refused), `error` (the tool failed or was
 * interrupted) or `ask` (waiting for a person); `code` is a stable reason for anything but `ok`.
 *
 * Stored as a transcript `tool_result` part. Lines written before this shape have only `result`, read as `data`.
 *
 * @since 0.1.0
 */
final class ToolOutcome
{
    public const OK = 'ok';

    public const BLOCKED = 'blocked';

    public const ERROR = 'error';

    public const ASK = 'ask';

    /**
     * @param array{summary?: string, change?: int} $ui
     */
    public function __construct(
        public readonly string $status,
        public readonly mixed $data = null,
        public readonly ?string $content = null,
        public readonly array $ui = [],
        public readonly string $code = '',
        public readonly string $error = '',
        public readonly bool $tainted = false,
    ) {
    }

    /**
     * @since 0.1.0
     */
    public static function blocked(string $code, string $error): self
    {
        return new self(self::BLOCKED, null, null, ['summary' => $error], $code, $error);
    }

    /**
     * @since 0.1.0
     */
    public static function failed(string $code, string $error): self
    {
        return new self(self::ERROR, null, null, ['summary' => $error], $code, $error);
    }

    /**
     * @since 0.1.0
     */
    public function ok(): bool
    {
        return $this->status === self::OK;
    }

    /**
     * The transcript part for call `$id` of tool `$name`.
     *
     * @since 0.1.0
     * @return array<string, mixed>
     */
    public function toPart(string $id, string $name): array
    {
        $part = ['type' => 'tool_result', 'id' => $id, 'name' => $name, 'status' => $this->status];
        if ($this->status === self::OK) {
            $part['data'] = $this->data;
        }
        if ($this->content !== null) {
            $part['content'] = $this->content;
        }
        if ($this->code !== '') {
            $part['code'] = $this->code;
        }
        if ($this->error !== '') {
            $part['error'] = $this->error;
        }
        if ($this->ui !== []) {
            $part['ui'] = $this->ui;
        }
        if ($this->tainted) {
            $part['tainted'] = true;
        }

        return $part;
    }

    /**
     * A stored part read back, old (`result`) or new (`data`).
     *
     * @since 0.1.0
     * @param array<string, mixed> $part
     */
    public static function fromPart(array $part): self
    {
        return new self(
            (string) ($part['status'] ?? self::OK),
            $part['data'] ?? $part['result'] ?? null,
            isset($part['content']) ? (string) $part['content'] : null,
            is_array($part['ui'] ?? null) ? $part['ui'] : [],
            (string) ($part['code'] ?? ''),
            (string) ($part['error'] ?? ''),
            (bool) ($part['tainted'] ?? false),
        );
    }
}