defmodule Planck.Agent.Sidecar do
  @moduledoc """
  Behaviour and utilities for sidecar applications that extend planck_headless
  over distributed Erlang.

  ## Behaviour

  A sidecar entry-point module implements one required callback:

  - `tools/0` — returns `[Planck.Agent.Tool.t()]` with full `execute_fn` closures.
    These run **locally on the sidecar node**.

  ## Module-level utilities

  `Planck.Agent.Sidecar` itself provides module-level functions that
  planck_headless calls on the sidecar node via `:rpc.call/5`. Because
  `planck_agent` is a dependency of both planck_headless and the sidecar, these
  are available on both nodes:

  - `discover/0` — finds the module implementing this behaviour (cached in
    `:persistent_term` after the first call).
  - `list_tools/0` — discovers the entry module and returns its tools as
    `[Planck.AI.Tool.t()]` (no closures, serialisable across nodes).
  - `list_tools/1` — same but takes an explicit module; intended for tests.
  - `execute_tool/3` — discovers the entry module and executes a named tool.
  - `execute_tool/4` — same but takes an explicit module; intended for tests.

  planck_headless calls:

      :rpc.call(sidecar_node, Planck.Agent.Sidecar, :list_tools, [])
      :rpc.call(sidecar_node, Planck.Agent.Sidecar, :execute_tool,
                [tool_name, agent_id, args], timeout)

  ## Minimal example

      defmodule MySidecar.Planck do
        use Planck.Agent.Sidecar

        @impl true
        def tools do
          [
            Planck.Agent.Tool.new(
              name: "run_tests",
              description: "Run the test suite. Pass timeout_ms to override the default.",
              parameters: %{
                "type" => "object",
                "properties" => %{
                  "timeout_ms" => %{
                    "type" => "integer",
                    "description" => "Max milliseconds to wait (default 120000)"
                  }
                }
              },
              execute_fn: fn _agent_id, _id, args ->
                timeout = Map.get(args, "timeout_ms", 120_000)
                case System.cmd("mix", ["test"], timeout: timeout) do
                  {output, 0} -> {:ok, output}
                  {output, _} -> {:error, output}
                end
              end
            )
          ]
        end
      end

  See `specs/sidecar.md` for the full design.
  """

  @doc """
  Return the sidecar's tools as `Planck.Agent.Tool` structs (with `execute_fn`).

  This is the only required callback. `execute_fn` closures run **locally on the
  sidecar node** — they are never serialised or called on planck_headless.

  Each tool should accept an optional `"timeout_ms"` argument in its parameter
  schema so the AI can hint at how long to wait for the tool call.
  """
  @callback tools() :: [Planck.Agent.Tool.t()]

  @doc """
  Convenience macro for implementing the `Planck.Agent.Sidecar` behaviour.

  `use Planck.Agent.Sidecar` injects:

  - `@behaviour Planck.Agent.Sidecar` — marks the module as a sidecar entry point.
  - A default `tools/0` returning `[]` — override this to provide tools.

  ## Usage

      defmodule MySidecar.Planck do
        use Planck.Agent.Sidecar

        @impl true
        def tools do
          [
            Planck.Agent.Tool.new(
              name: "run_tests",
              description: "Run the test suite.",
              parameters: %{"type" => "object", "properties" => %{}},
              execute_fn: fn _agent_id, _id, _args ->
                {out, 0} = System.cmd("mix", ["test"])
                {:ok, out}
              end
            )
          ]
        end
      end

  The `tools/0` function is the only thing you normally need to override.
  `list_tools/0`, `discover/0`, `execute_tool/3`, and `execute_tool/4` are
  **not** injected here — they are module-level functions on
  `Planck.Agent.Sidecar` itself that planck_headless calls on the sidecar node:

      :rpc.call(node, Planck.Agent.Sidecar, :list_tools, [])
      :rpc.call(node, Planck.Agent.Sidecar, :execute_tool,
                [tool_name, agent_id, args], timeout)

  This design keeps the dispatch logic in `planck_agent` (available on both
  nodes) rather than requiring each sidecar module to implement it. No config
  is needed — `list_tools/0` discovers the entry module automatically via
  `discover/0`.
  """
  defmacro __using__(_options) do
    quote do
      @behaviour Planck.Agent.Sidecar

      @impl Planck.Agent.Sidecar
      def tools, do: []

      defoverridable tools: 0
    end
  end

  # ---------------------------------------------------------------------------
  # Module-level utilities called via :rpc.call on the sidecar node
  # ---------------------------------------------------------------------------

  @doc """
  Discover the module in the current node that implements `Planck.Agent.Sidecar`.

  Scans modules across all loaded OTP applications and returns the first one
  whose `@behaviour` attribute includes `Planck.Agent.Sidecar`, or `nil` if
  none is found. Only Elixir modules (names starting with `"Elixir."`) are
  checked; Erlang modules are skipped.

  Successful results are cached in `:persistent_term`. `nil` results are **not**
  cached — the next call will retry the scan, which is useful when the sidecar
  entry module is loaded after `discover/0` is first called.

  Called by planck_headless on the sidecar node via `list_tools/0`. You
  normally do not need to call this directly.
  """
  @spec discover() :: module() | nil
  def discover do
    sidecar_module_key = {__MODULE__, :entry_module}

    with :miss <- :persistent_term.get(sidecar_module_key, :miss),
         module when not is_nil(module) <- scan_entry_module() do
      :persistent_term.put(sidecar_module_key, module)
      module
    end
  end

  @spec elixir_module?(module()) :: boolean()
  defp elixir_module?(mod), do: mod |> Atom.to_string() |> String.starts_with?("Elixir.")

  @spec scan_entry_module() :: module() | nil
  defp scan_entry_module do
    :application.loaded_applications()
    |> Enum.flat_map(fn {app, _, _} ->
      case :application.get_key(app, :modules) do
        {:ok, mods} -> mods
        _ -> []
      end
    end)
    |> Enum.find(fn mod ->
      elixir_module?(mod) and
        :code.ensure_loaded(mod) == {:module, mod} and
        __MODULE__ in (mod.__info__(:attributes)[:behaviour] || [])
    end)
  end

  @doc """
  Discover the sidecar entry module and return its tools as `[Planck.AI.Tool.t()]`.

  Combines `discover/0` and `list_tools/1`. Returns `[]` if no entry module is
  found.

  Called by planck_headless on the sidecar node:

      :rpc.call(sidecar_node, Planck.Agent.Sidecar, :list_tools, [])
  """
  @spec list_tools() :: [Planck.AI.Tool.t()]
  def list_tools do
    case discover() do
      nil -> []
      module -> list_tools(module)
    end
  end

  @doc """
  Convert `module.tools()` to `[Planck.AI.Tool.t()]` — serialisable, no closures.
  """
  @spec list_tools(module()) :: [Planck.AI.Tool.t()]
  def list_tools(module) do
    Enum.map(module.tools(), fn tool ->
      Planck.AI.Tool.new(
        name: tool.name,
        description: tool.description,
        parameters: tool.parameters
      )
    end)
  end

  @doc """
  Discover the entry module and execute a named tool.

  Called by planck_headless on the sidecar node:

      :rpc.call(sidecar_node, Planck.Agent.Sidecar, :execute_tool,
                [tool_name, agent_id, tool_call_id, args], timeout)

  The `timeout` is read from `args["timeout_ms"]` by the planck_headless RPC
  wrapper, not by this function.
  """
  @spec execute_tool(String.t(), String.t(), String.t(), map()) ::
          {:ok, term()} | {:error, term()}
  def execute_tool(tool_name, agent_id, tool_call_id, args) do
    case discover() do
      nil -> {:error, "no sidecar entry module found"}
      module -> execute_tool(module, tool_name, agent_id, tool_call_id, args)
    end
  end

  @doc """
  Execute a named tool via an explicit sidecar module's `tools/0` list.

  Intended for tests. Production code should use `execute_tool/3`.
  """
  @spec execute_tool(module(), String.t(), String.t(), String.t(), map()) ::
          {:ok, term()} | {:error, term()}
  def execute_tool(module, tool_name, agent_id, tool_call_id, args) do
    case Enum.find(module.tools(), &(&1.name == tool_name)) do
      nil -> {:error, "unknown tool: #{tool_name}"}
      tool -> tool.execute_fn.(agent_id, tool_call_id, args)
    end
  end
end