<?php
/**
 * One step being run.
 *
 * @package MazeAi
 * @since   0.1.0
 */

declare(strict_types=1);

namespace MazeAi\Chat;

defined('ABSPATH') || exit;

use MazeAi\Kernel\Support\AgentDefinition;
use MazeAi\Kernel\Support\PermissionMode;

/**
 * Who and where a step runs: the session, its run and step, the person it runs for, the model, the agent and its
 * step limit, and the transcript lines the step has added so far (returned to the caller).
 *
 * @since 0.1.0
 */
final class Turn
{
    /** @var list<array<string, mixed>> */
    public array $added = [];

    /** Total milliseconds spent in model calls for this step, excluding local prompt assembly and tool execution. */
    public int $modelDurationMs = 0;

    /** Unix time at which this request's claim on the step lapses; renewed while it works (CORE-1). */
    public int $leaseUntil = 0;

    public function __construct(
        public readonly int $sessionId,
        public readonly int $userId,
        public readonly string $model,
        public readonly string $runId,
        public readonly int $step,
        public readonly int $maxSteps,
        public readonly AgentDefinition $agent,
        public readonly string $permissionMode = PermissionMode::ASK,
    ) {
    }

    /**
     * @since 0.1.0
     */
    public function lastStep(): bool
    {
        return $this->step + 1 >= $this->maxSteps;
    }

    /**
     * Ids for events about this step.
     *
     * @since 0.1.0
     * @return array{session: int, run: string, step: int, agent: string}
     */
    public function ids(): array
    {
        return ['session' => $this->sessionId, 'run' => $this->runId, 'step' => $this->step, 'agent' => $this->agent->id];
    }
}