<?php
/**
 * A question for the policy engine.
 *
 * @package MazeAi
 * @since   0.1.0
 */

declare(strict_types=1);

namespace MazeAi\Kernel\Support;

defined('ABSPATH') || exit;

/**
 * Actions: `run.start` (a person sends or regenerates), `run.step` (a step is about to call the model), `tool.offer`
 * (may the model see this tool now?), `tool.execute` (may this call run?), `memory.write`, `agent.delegate`, `agent.use` (a person starts a chat or a Studio document with an agent).
 * `resource` names the thing (a tool name, a model id); `context` carries the facts the caller gathered, so rules
 * stay pure: `tool` (a `MazeAi\Tools\Tool`), `permitted` (the ability's own check), `step`, `max_steps`, `tainted`,
 * `args_hash`, `approved_hash`, `agent_tools`, `via` (`model` or `person`), `surface_on`.
 *
 * @since 0.1.0
 */
final class PolicyRequest
{
    /**
     * @param array<string, mixed> $context
     */
    public function __construct(
        public readonly Principal $principal,
        public readonly string $action,
        public readonly string $resource = '',
        public readonly array $context = [],
    ) {
    }

    /**
     * @since 0.1.0
     */
    public function get(string $key, mixed $default = null): mixed
    {
        return array_key_exists($key, $this->context) ? $this->context[$key] : $default;
    }

    /**
     * Whether the action is one of `$actions`; a trailing `*` matches a prefix (`tool.*`).
     *
     * @since 0.1.0
     */
    public function is(string ...$actions): bool
    {
        foreach ($actions as $action) {
            if ($action === $this->action || (str_ends_with($action, '*') && str_starts_with($this->action, substr($action, 0, -1)))) {
                return true;
            }
        }

        return false;
    }
}