`test/openagents/agents_test.exs`, and

`test/openagents_web/controllers/agent_controller_test.exs`.

### IDENTITY-005 — Box control is account-scoped and human-only

Status: Current

The `box:control` API scope is independent from forge, deployment, chat, and

agent participation scopes. Only a human account token can use it in this

slice. Every request names a conversation owned by that account, and a foreign

conversation or Box is indistinguishable from a missing one. Agent Box control

through an approved human link is deferred to the linked-principal contract.

Evidence: `OpenAgentsWeb.Plugs.BoxControlAuth`, `OpenAgents.Box`,

`OpenAgentsWeb.BoxController`, and

`test/openagents_web/controllers/box_controller_test.exs`.

## Data authority and synchronization

### DATA-001 — PostgreSQL is authoritative

| IDENTITY-002 | `test/openagents_web/auth_gate_test.exs` |

| IDENTITY-003 | `test/openagents/memory_portability_test.exs` |

| IDENTITY-004 | `test/openagents/agents_test.exs`, `test/openagents_web/controllers/agent_controller_test.exs` |

| IDENTITY-005 | `test/openagents_web/controllers/box_controller_test.exs` |

| PROMISE-001 | `test/openagents/promise_registry_test.exs`, `test/openagents_web/controllers/project_controller_test.exs` |

| PROMISE-002 | `test/openagents/promise_registry_test.exs` |

| DATA-001 | `test/openagents/conversations_test.exs` |

    maximum_active_boxes: 10,

    ttl_seconds: 3_600,

    poll_interval_ms: 1_000,

    poll_attempts: 60

    poll_attempts: 60,

    rate_limit_window_seconds: 60,

    create_rate_limit: 10,

    command_rate_limit: 30

  ],

  # The provider does not report a context window, so the `/chat` console shows

  # a context meter only where a deployment states one.

`agent:participate` scope.

Create a token in the authenticated browser at `/settings/api-tokens`. Choose a

name and a lifetime from 1 through 90 days. The `oa_pat_…` plaintext appears

name, one or more independent scopes, and a lifetime from 1 through 90 days.

The `oa_pat_…` plaintext appears

once; OpenAgents stores only its SHA-256 digest. Send it as a bearer:

```sh

Product-data deletion retains API credentials until the person revokes them;

credential management is independent from conversation deletion.

### Box control credentials

The `box:control` scope gives a human account token access to the Box API. It

does not grant forge, deployment, chat, or agent-participation authority, and

those scopes do not grant Box authority.

Use the conversation ID owned by the token's account:

```sh

openagents api -X GET conversations/CONVERSATION_ID/boxes

openagents api -X POST conversations/CONVERSATION_ID/boxes

openagents api -X GET conversations/CONVERSATION_ID/boxes/BOX_ID

openagents api -X POST --input command.json \

  conversations/CONVERSATION_ID/boxes/BOX_ID/commands

openagents api -X POST conversations/CONVERSATION_ID/boxes/BOX_ID/stop

```

The API returns only Box IDs, lifecycle and setup state, timestamps, and

bounded, redacted command output. It never returns provider, desktop, viewer,

or token-bearing URLs. A foreign conversation or Box returns `404` without a

provider request. Agent participation credentials receive

`{"error":{"code":"agent_box_control_forbidden"}}`; linked-agent Box control is

deferred to the linked-principal contract.

### Agent participation credentials

An agent can register without GitHub by sending its handle and display name to

An unlinked link record uses the `unlinked` status, while an explicit human

decline uses `rejected`; a later request reuses either record as `pending`.

## Work with Box computers

Use a human account token with the `box:control` scope to manage the Box

computers owned by one conversation:

```sh

openagents api conversations/CONVERSATION_ID/boxes

openagents api -X POST conversations/CONVERSATION_ID/boxes

openagents api conversations/CONVERSATION_ID/boxes/BOX_ID

openagents api -X POST --input command.json \

  conversations/CONVERSATION_ID/boxes/BOX_ID/commands

openagents api -X POST conversations/CONVERSATION_ID/boxes/BOX_ID/stop

```

The Box API returns bounded, redacted command output and selected lifecycle

metadata. It does not return provider, desktop, viewer, or token-bearing URLs.

The conversation must belong to the token's account. A foreign conversation or

Box returns `404` without contacting the provider. Agent participation

credentials are refused with

`{"error":{"code":"agent_box_control_forbidden"}}` until linked-agent Box

control is implemented.

## Work with issues

List open issues. The API returns an object with an `issues` array:

  # `deployments:promote` fleet scope: holding it lets a caller address the

  # deployment API, while repository membership and environment policy still

  # decide what it may deploy.

  @allowed_scopes ["chat:account", "forge:write", "deployments:write"]

  @allowed_scopes ["chat:account", "forge:write", "deployments:write", "box:control"]

  @maximum_lifetime_days 90

  @spec create(User.t(), map()) ::

        OpenAgents.Forge.BootConverge,

        {DNSCluster, query: Application.get_env(:openagents, :dns_cluster_query) || :ignore},

        {Phoenix.PubSub, name: OpenAgents.PubSub},

        OpenAgents.RuntimeSupervisor

        OpenAgents.RuntimeSupervisor,

        OpenAgentsWeb.BoxRateLimiter

      ] ++ analytics_children() ++ [OpenAgentsWeb.Endpoint]

    # See https://elixir.hexdocs.pm/Supervisor.html

    |> Enum.map(&refresh/1)

  end

  @doc "Reads one conversation-owned box, refreshing its provider state."

  @spec get_box(String.t(), String.t()) :: {:ok, ConversationBox.t()} | {:error, term()}

  def get_box(conversation_id, box_id)

      when is_binary(conversation_id) and is_binary(box_id) do

    with {:ok, record} <- fetch_owned(conversation_id, box_id) do

      {:ok, refresh(record)}

    end

  end

  @doc """

  Provisions a new box for a conversation and bootstraps OpenCode on it.

    |> Repo.one()

  end

  @doc "Gets a conversation owned by the account, returning nil for other accounts or invalid IDs."

  @spec get_conversation_for_user(User.t(), String.t()) :: Conversation.t() | nil

  def get_conversation_for_user(%User{id: user_id}, conversation_id)

      when is_binary(conversation_id) do

    with {:ok, conversation_id} <- Ecto.UUID.cast(conversation_id) do

      from(c in Conversation,

        join: v in assoc(c, :visitor),

        where: c.id == ^conversation_id and v.user_id == ^user_id

      )

      |> Repo.one()

    else

      :error -> nil

    end

  end

  @doc false

  def get_conversation_for_browser(browser_key) when is_binary(browser_key) do

    browser_key_hash = :crypto.hash(:sha256, browser_key)

  alias OpenAgents.Box

  alias OpenAgents.Modules.Metadata

  alias OpenAgents.Tools.{ExecutionResult, Redaction, Tool}

  alias OpenAgents.Tools.{BoxOutput, ExecutionResult, Tool}

  @default_timeout_seconds 60

  # The registry caps a tool run at 600 seconds; the remote command budget

  # stays below it so the HTTP round trip fits inside the tool budget.

  @maximum_timeout_seconds 570

  @maximum_stream_bytes 24 * 1_024

  @impl true

  def specification do

  end

  defp build_result(box_id, body) do

    {stdout, stdout_truncated} = bounded(body["stdout"])

    {stderr, stderr_truncated} = bounded(body["stderr"])

    {stdout, stdout_truncated} = BoxOutput.bounded(body["stdout"])

    {stderr, stderr_truncated} = BoxOutput.bounded(body["stderr"])

    exit_code = body["exitCode"]

    timed_out = body["timedOut"] == true

       target_receipt_refs: ["box:#{box_id}"]

     }}

  end

  defp bounded(nil), do: {"", false}

  defp bounded(stream) when is_binary(stream) do

    redacted = stream |> scrub() |> Redaction.redact_text()

    if byte_size(redacted) <= @maximum_stream_bytes do

      {redacted, false}

    else

      {tail_bytes(redacted, @maximum_stream_bytes), true}

    end

  end

  defp bounded(_other), do: {"", false}

  defp scrub(output) do

    if String.valid?(output) do

      output

    else

      output

      |> String.chunk(:valid)

      |> Enum.map_join(fn chunk -> if String.valid?(chunk), do: chunk, else: "\uFFFD" end)

    end

  end

  defp tail_bytes(text, limit) do

    text

    |> binary_part(byte_size(text) - limit, limit)

    |> trim_partial_prefix(3)

  end

  defp trim_partial_prefix(text, 0), do: text

  defp trim_partial_prefix(text, attempts) do

    case text do

      <<_first, rest::binary>> ->

        if String.valid?(text), do: text, else: trim_partial_prefix(rest, attempts - 1)

      _empty ->

        text

    end

  end

end

defmodule OpenAgents.Tools.BoxOutput do

  @moduledoc "Bounds and redacts output returned by Box commands."

  alias OpenAgents.Tools.Redaction

  @maximum_stream_bytes 24 * 1_024

  @credential_url_pattern ~r{https?://[^\s/@:]+:[^\s/@]+@[^\s]+}i

  @token_query_url_pattern ~r{https?://[^\s]+[?&](?:access[_-]?token|token|api[_-]?key|auth(?:entication)?[_-]?token|secret|credential)=[^\s&#]+[^\s]*}i

  @provider_url_pattern ~r{https?://(?:desktop|viewer)\.ascii\.dev[^\s]*}i

  @spec bounded(term()) :: {String.t(), boolean()}

  def bounded(nil), do: {"", false}

  def bounded(stream) when is_binary(stream) do

    redacted =

      stream

      |> scrub()

      |> Redaction.redact_text()

      |> redact_credential_urls()

    if byte_size(redacted) <= @maximum_stream_bytes do

      {redacted, false}

    else

      {tail_bytes(redacted, @maximum_stream_bytes), true}

    end

  end

  def bounded(_other), do: {"", false}

  defp redact_credential_urls(text) do

    text =

      Regex.replace(@credential_url_pattern, text, "[REDACTED_URL]")

    text =

      Regex.replace(@token_query_url_pattern, text, "[REDACTED_URL]")

    Regex.replace(@provider_url_pattern, text, "[REDACTED_URL]")

  end

  defp scrub(output) do

    if String.valid?(output) do

      output

    else

      output

      |> String.chunk(:valid)

      |> Enum.map_join(fn chunk -> if String.valid?(chunk), do: chunk, else: "\uFFFD" end)

    end

  end

  defp tail_bytes(text, limit) do

    text

    |> binary_part(byte_size(text) - limit, limit)

    |> trim_partial_prefix(3)

  end

  defp trim_partial_prefix(text, 0), do: text

  defp trim_partial_prefix(text, attempts) do

    case text do

      <<_first, rest::binary>> ->

        if String.valid?(text), do: text, else: trim_partial_prefix(rest, attempts - 1)

      _empty ->

        text

    end

  end

end

      "post /api/v3/chat/turns" => :required_bearer,

      "get /api/v3/capacity" => :required_bearer,

      "post /api/v3/capacity/matches" => :required_bearer,

      "get /api/v3/conversations/:conversation_id/boxes" => :required_bearer,

      "post /api/v3/conversations/:conversation_id/boxes" => :required_bearer,

      "get /api/v3/conversations/:conversation_id/boxes/:box_id" => :required_bearer,

      "post /api/v3/conversations/:conversation_id/boxes/:box_id/commands" => :required_bearer,

      "post /api/v3/conversations/:conversation_id/boxes/:box_id/stop" => :required_bearer,

      "delete /api/v3/repos/:owner/:repo" => :required_bearer,

      "delete /api/v3/repos/:owner/:repo/issues/:issue_number/assignees" => :required_bearer,

      "delete /api/v3/repos/:owner/:repo/issues/:issue_number/labels/:name" => :required_bearer,

defmodule OpenAgentsWeb.BoxRateLimiter do

  @moduledoc false

  use GenServer

  @table :openagents_box_api_rate_limits

  @default_window_seconds 60

  @default_create_limit 10

  @default_command_limit 30

  @minimum_sweep_interval_ms 1_000

  @maximum_sweep_interval_ms 60_000

  @spec start_link(keyword()) :: GenServer.on_start()

  def start_link(options \\ []) do

    GenServer.start_link(__MODULE__, options, name: __MODULE__)

  end

  @spec allow?(term(), :create | :command) :: :ok | {:error, :rate_limited}

  def allow?(principal, operation) when operation in [:create, :command] do

    GenServer.call(__MODULE__, {:allow, principal, operation})

  end

  @impl true

  def init(_options) do

    table = :ets.new(@table, [:named_table, :public, :set, read_concurrency: true])

    schedule_sweep()

    {:ok, %{table: table}}

  end

  @impl true

  def handle_call({:allow, principal, operation}, _from, %{table: table} = state) do

    window_seconds = setting(:rate_limit_window_seconds, @default_window_seconds)

    limit = setting(rate_limit_key(operation), default_limit(operation))

    bucket = div(System.system_time(:second), window_seconds)

    key = {operation, principal, bucket}

    :ets.insert_new(table, {key, 0})

    count = :ets.update_counter(table, key, {2, 1})

    reply =

      if count <= limit do

        :ok

      else

        :ets.update_counter(table, key, {2, -1})

        {:error, :rate_limited}

      end

    {:reply, reply, state}

  end

  @impl true

  def handle_info(:sweep, %{table: table} = state) do

    current_bucket = div(System.system_time(:second), setting(:rate_limit_window_seconds, 60))

    table

    |> :ets.tab2list()

    |> Enum.each(fn {{_operation, _principal, bucket} = key, _count} ->

      if bucket < current_bucket, do: :ets.delete(table, key)

    end)

    schedule_sweep()

    {:noreply, state}

  end

  defp schedule_sweep do

    Process.send_after(self(), :sweep, sweep_interval_ms())

  end

  defp sweep_interval_ms do

    :rate_limit_window_seconds

    |> setting(@default_window_seconds)

    |> then(&:timer.seconds/1)

    |> max(@minimum_sweep_interval_ms)

    |> min(@maximum_sweep_interval_ms)

  end

  defp rate_limit_key(:create), do: :create_rate_limit

  defp rate_limit_key(:command), do: :command_rate_limit

  defp default_limit(:create), do: @default_create_limit

  defp default_limit(:command), do: @default_command_limit

  defp setting(key, default) do

    case Keyword.get(Application.get_env(:openagents, :box_api, []), key, default) do

      value when is_integer(value) and value > 0 -> value

      _ -> default

    end

  end

end

defmodule OpenAgentsWeb.BoxController do

  @moduledoc "Authenticated API access to conversation-owned Box computers."

  use OpenAgentsWeb, :controller

  alias OpenAgents.{Box, Conversations}

  alias OpenAgents.Conversations.Conversation

  alias OpenAgents.Tools.BoxOutput

  alias OpenAgentsWeb.BoxRateLimiter

  @default_timeout_seconds 60

  @maximum_timeout_seconds 570

  def index(conn, %{"conversation_id" => conversation_id}) do

    with {:ok, _conversation} <- owned_conversation(conn, conversation_id) do

      boxes = Box.list_boxes(conversation_id)

      json(conn, %{"boxes" => Enum.map(boxes, &box_projection/1)})

    else

      {:error, :not_found} -> refusal(conn, :not_found, "conversation_not_found")

    end

  end

  def create(conn, %{"conversation_id" => conversation_id}) do

    with {:ok, _conversation} <- owned_conversation(conn, conversation_id),

         :ok <- BoxRateLimiter.allow?(conn.assigns.current_user.id, :create),

         {:ok, record} <- Box.create_box(conversation_id) do

      conn

      |> put_status(:created)

      |> json(%{"box" => box_projection(record)})

    else

      {:error, :not_found} -> refusal(conn, :not_found, "conversation_not_found")

      {:error, :rate_limited} -> refusal(conn, :too_many_requests, "box_api_rate_limited")

      {:error, reason} -> box_error(conn, reason)

    end

  end

  def show(conn, %{"conversation_id" => conversation_id, "box_id" => box_id}) do

    with {:ok, _conversation} <- owned_conversation(conn, conversation_id),

         {:ok, record} <- Box.get_box(conversation_id, box_id) do

      json(conn, %{"box" => box_projection(record)})

    else

      {:error, :not_found} -> refusal(conn, :not_found, "conversation_not_found")

      {:error, reason} -> box_error(conn, reason)

    end

  end

  def command(

        conn,

        %{"conversation_id" => conversation_id, "box_id" => box_id, "command" => command} = params

      )

      when is_binary(command) do

    with :ok <- validate_command(command),

         {:ok, timeout_seconds} <- timeout_seconds(params),

         {:ok, _conversation} <- owned_conversation(conn, conversation_id),

         :ok <- BoxRateLimiter.allow?(conn.assigns.current_user.id, :command),

         {:ok, body} <- Box.run_command(conversation_id, box_id, command, timeout_seconds) do

      json(conn, %{"result" => command_projection(box_id, body)})

    else

      {:error, :invalid_command} ->

        refusal(conn, :unprocessable_entity, "invalid_command")

      {:error, :invalid_command_timeout} ->

        refusal(conn, :unprocessable_entity, "invalid_command_timeout")

      {:error, :not_found} ->

        refusal(conn, :not_found, "conversation_not_found")

      {:error, :rate_limited} ->

        refusal(conn, :too_many_requests, "box_api_rate_limited")

      {:error, reason} ->

        box_error(conn, reason)

    end

  end

  def command(conn, _params), do: refusal(conn, :unprocessable_entity, "invalid_command")

  def stop(conn, %{"conversation_id" => conversation_id, "box_id" => box_id}) do

    with {:ok, _conversation} <- owned_conversation(conn, conversation_id),

         {:ok, record} <- Box.stop_box(conversation_id, box_id) do

      json(conn, %{"box" => box_projection(record)})

    else

      {:error, :not_found} -> refusal(conn, :not_found, "conversation_not_found")

      {:error, reason} -> box_error(conn, reason)

    end

  end

  defp owned_conversation(conn, conversation_id) do

    case Conversations.get_conversation_for_user(conn.assigns.current_user, conversation_id) do

      %Conversation{} = conversation -> {:ok, conversation}

      nil -> {:error, :not_found}

    end

  end

  defp box_projection(record) do

    %{

      "box_id" => record.box_id,

      "state" => record.state,

      "setup_status" => record.setup_status,

      "created_at" => iso8601(record.inserted_at),

      "updated_at" => iso8601(record.updated_at),

      "stopped_at" => iso8601(record.stopped_at)

    }

  end

  defp command_projection(box_id, body) do

    {stdout, stdout_truncated} = BoxOutput.bounded(body["stdout"])

    {stderr, stderr_truncated} = BoxOutput.bounded(body["stderr"])

    %{

      "box_id" => box_id,

      "exit_code" => body["exitCode"],

      "stdout" => stdout,

      "stderr" => stderr,

      "timed_out" => body["timedOut"] == true,

      "stdout_truncated" => stdout_truncated or body["stdoutTruncated"] == true,

      "stderr_truncated" => stderr_truncated or body["stderrTruncated"] == true

    }

  end

  defp validate_command(command) do

    cond do

      String.trim(command) == "" -> {:error, :invalid_command}

      not String.valid?(command) -> {:error, :invalid_command}

      String.contains?(command, "\0") -> {:error, :invalid_command}

      byte_size(command) > 4_000 -> {:error, :invalid_command}

      true -> :ok

    end

  end

  defp timeout_seconds(params) do

    case Map.get(params, "timeout_seconds", @default_timeout_seconds) do

      seconds

      when is_integer(seconds) and seconds >= 1 and seconds <= @maximum_timeout_seconds ->

        {:ok, seconds}

      _invalid ->

        {:error, :invalid_command_timeout}

    end

  end

  defp iso8601(nil), do: nil

  defp iso8601(%DateTime{} = value), do: DateTime.to_iso8601(value)

  defp box_error(conn, :box_quota_reached),

    do: refusal(conn, :conflict, "box_quota_reached")

  defp box_error(conn, reason) when reason in [:box_not_owned, :box_not_found],

    do: refusal(conn, :not_found, "box_not_found")

  defp box_error(conn, :box_billing_required),

    do: refusal(conn, :payment_required, "box_billing_required")

  defp box_error(conn, :box_rate_limited),

    do: refusal(conn, :too_many_requests, "box_provider_rate_limited")

  defp box_error(conn, reason) when reason in [:box_not_configured, :box_unreachable],

    do: refusal(conn, :service_unavailable, Atom.to_string(reason))

  defp box_error(conn, :box_response_invalid),

    do: refusal(conn, :bad_gateway, "box_provider_response_invalid")

  defp box_error(conn, {:box_request_refused, _status, _code}),

    do: refusal(conn, :bad_gateway, "box_provider_request_refused")

  defp box_error(conn, :box_unauthorized),

    do: refusal(conn, :bad_gateway, "box_provider_unauthorized")

  defp box_error(conn, :box_stopped),

    do: refusal(conn, :conflict, "box_stopped")

  defp box_error(conn, :box_not_ready),

    do: refusal(conn, :conflict, "box_not_ready")

  defp box_error(conn, _reason), do: refusal(conn, :bad_gateway, "box_request_failed")

  defp refusal(conn, status, code) do

    conn

    |> put_status(status)

    |> json(%{"error" => %{"code" => code}})

  end

end

defmodule OpenAgentsWeb.Plugs.BoxControlAuth do

  @moduledoc "Authenticates a human bearer credential with Box control authority."

  import Plug.Conn

  alias OpenAgents.Agents

  alias OpenAgents.ApiTokens

  def init(options), do: Keyword.fetch!(options, :scope)

  def call(conn, required_scope) do

    with ["Bearer " <> token] <- get_req_header(conn, "authorization"),

         true <- token != "" do

      authenticate(conn, token, required_scope)

    else

      _ -> refuse(conn, :unauthorized, "invalid_api_token")

    end

  end

  defp authenticate(conn, "oa_agent_" <> _rest = token, _required_scope) do

    case Agents.authenticate(token, "agent:participate") do

      {:ok, _agent, _credential} ->

        refuse(conn, :forbidden, "agent_box_control_forbidden")

      _ ->

        refuse(conn, :unauthorized, "invalid_api_token")

    end

  end

  defp authenticate(conn, token, required_scope) do

    case ApiTokens.authenticate(token, required_scope) do

      {:ok, user, credential} ->

        conn

        |> put_resp_header("cache-control", "no-store")

        |> assign(:current_user, user)

        |> assign(:api_token, credential)

        |> assign(:api_scope, required_scope)

      _ ->

        refuse(conn, :unauthorized, "invalid_api_token")

    end

  end

  defp refuse(conn, status, code) do

    conn

    |> put_status(status)

    |> put_resp_header("cache-control", "no-store")

    |> Phoenix.Controller.json(%{"error" => %{"code" => code}})

    |> halt()

  end

end

        true

      )

  defp policy(%{path: "/api/v3/conversations/:conversation_id/boxes", verb: verb})

       when verb in [:get, :post],

       do:

         declaration(

           :authenticated_api,

           "human account bearer token",

           "box:control",

           verb == :post

         )

  defp policy(%{path: "/api/v3/conversations/:conversation_id/boxes/:box_id", verb: :get}),

    do: declaration(:authenticated_api, "human account bearer token", "box:control", false)

  defp policy(%{

         path: "/api/v3/conversations/:conversation_id/boxes/:box_id/commands",

         verb: :post

       }),

       do: declaration(:authenticated_api, "human account bearer token", "box:control", true)

  defp policy(%{path: "/api/v3/conversations/:conversation_id/boxes/:box_id/stop", verb: :post}),

    do: declaration(:authenticated_api, "human account bearer token", "box:control", true)

  defp policy(%{path: "/api/operator/artifact-listings" <> _path, verb: verb}),

    do:

      declaration(

    plug OpenAgentsWeb.Plugs.ApiTokenAuth, scope: "chat:account"

  end

  pipeline :box_control_api do

    plug :accepts, ["json"]

    plug OpenAgentsWeb.Plugs.RequestOrigin

    plug OpenAgentsWeb.Plugs.BoxControlAuth, scope: "box:control"

  end

  # The deployment control plane authenticates two principals: a human holding

  # `deployments:write`, and a short-lived workflow grant. Neither carries the

  # operator-only fleet promotion authority.

    post "/capacity/matches", CapacityController, :matches

  end

  scope "/api/v3/conversations/:conversation_id/boxes", OpenAgentsWeb do

    pipe_through :box_control_api

    get "/", BoxController, :index

    post "/", BoxController, :create

    get "/:box_id", BoxController, :show

    post "/:box_id/commands", BoxController, :command

    post "/:box_id/stop", BoxController, :stop

  end

  scope "/api/v3", OpenAgentsWeb do

    pipe_through :forge_write_api

    20260823120247,

    20260823122038,

    20260823122039,

    20260823122040

    20260823122040,

    20260823131739

  ],

  "required_tables": [

    "users",

defmodule OpenAgents.Repo.Migrations.AllowBoxControlApiTokenScope do

  use Ecto.Migration

  def change do

    drop constraint(:api_tokens, :api_tokens_scopes_allowed)

    create constraint(:api_tokens, :api_tokens_scopes_allowed,

             check:

               "scopes <@ ARRAY['chat:account', 'forge:write', 'deployments:write', 'box:control']::varchar[]"

           )

  end

end

             })

  end

  test "box control is an independent allowed scope" do

    {:ok, user} = Accounts.upsert_github_user(profile(803, "api-box-owner"))

    assert {:ok, token, plaintext} =

             ApiTokens.create(user, %{

               name: "box automation",

               scopes: ["box:control"],

               lifetime_days: 1

             })

    assert token.scopes == ["box:control"]

    assert {:ok, authenticated, _used} = ApiTokens.authenticate(plaintext, "box:control")

    assert authenticated.id == user.id

    assert {:error, :invalid_api_token} = ApiTokens.authenticate(plaintext, "forge:write")

    assert {:error, :invalid_api_token} = ApiTokens.authenticate(plaintext, "deployments:write")

    assert {:error, :invalid_api_token} = ApiTokens.authenticate(plaintext, "chat:account")

  end

  defp profile(id, login) do

    %{

      github_id: id,

      Req.Test.json(conn, %{

        "exitCode" => 0,

        "stdout" => "0.4.0\n",

        "stdout" => "clone https://openagents.com/OpenAgentsInc/openagents.com\n",

        "stderr" => "",

        "timedOut" => false

      })

    assert outcome["status"] == "succeeded"

    assert outcome["result"]["exit_code"] == 0

    assert outcome["result"]["stdout"] == "0.4.0\n"

    assert outcome["result"]["stdout"] ==

             "clone https://openagents.com/OpenAgentsInc/openagents.com\n"

    assert outcome["target_receipt_refs"] == ["box:#{@box_id}"]

  end

    Req.Test.expect(__MODULE__, fn conn ->

      Req.Test.json(conn, %{

        "exitCode" => 0,

        "stdout" => "key is sk-or-v1-abcdefghijklmnop1234 done\n",

        "stdout" =>

          "key is sk-or-v1-abcdefghijklmnop1234 done\n" <>

            "clone https://openagents.com/OpenAgentsInc/openagents.com\n" <>

            "https://viewer.ascii.dev/desktop?access_token=secret\n",

        "stderr" => "",

        "timedOut" => false

      })

             )

    refute outcome["result"]["stdout"] =~ "sk-or-v1"

    refute outcome["result"]["stdout"] =~ "viewer.ascii.dev"

    assert outcome["result"]["stdout"] =~ "[REDACTED]"

    assert outcome["result"]["stdout"] =~

             "clone https://openagents.com/OpenAgentsInc/openagents.com"

  end

  test "box_exec reports a timed-out command as failed", %{

defmodule OpenAgentsWeb.BoxControllerTest do

  use OpenAgentsWeb.ConnCase, async: false

  alias OpenAgents.{Conversations, Repo}

  alias OpenAgents.Box.ConversationBox

  setup {Req.Test, :verify_on_exit!}

  setup do

    original_api = Application.get_env(:openagents, :box_api)

    original_key = Application.get_env(:openagents, :box_api_key)

    Application.put_env(

      :openagents,

      :box_api,

      Keyword.merge(original_api || [],

        base_url: "https://box-api.internal",

        poll_interval_ms: 0,

        poll_attempts: 3,

        request_options: [plug: {Req.Test, __MODULE__}, retry_delay: 0]

      )

    )

    Application.put_env(:openagents, :box_api_key, "box_api_test_credential")

    Req.Test.stub(__MODULE__, fn request -> Req.Test.json(request, box_body()) end)

    on_exit(fn ->

      restore_env(:box_api, original_api)

      restore_env(:box_api_key, original_key)

    end)

    :ok

  end

  test "human box control token completes the create, command, list, show, and stop cycle", %{

    conn: conn

  } do

    user = github_user("api-token-box-api-cycle")

    {:ok, conversation} = Conversations.ensure_conversation(user)

    Req.Test.expect(__MODULE__, fn request ->

      assert request.method == "POST"

      assert request.request_path == "/boxes"

      Req.Test.json(request, box_body())

    end)

    create_response =

      conn

      |> put_box_api_token("box-api-cycle")

      |> post(box_path(conversation.id), %{})

      |> json_response(201)

    box_id = create_response["box"]["box_id"]

    assert create_response["box"]["state"] == "ready"

    refute Map.has_key?(create_response["box"], "desktopUrl")

    Req.Test.expect(__MODULE__, fn request ->

      assert request.method == "POST"

      assert request.request_path == "/boxes/#{box_id}/commands"

      Req.Test.json(request, command_body())

    end)

    command_response =

      conn

      |> put_box_api_token("box-api-cycle")

      |> post("#{box_path(conversation.id)}/#{box_id}/commands", %{"command" => "echo hi"})

      |> json_response(200)

    assert command_response["result"]["exit_code"] == 0

    assert command_response["result"]["stdout"] == "hi\n"

    Req.Test.stub(__MODULE__, fn request -> Req.Test.json(request, box_body()) end)

    assert %{"boxes" => [%{"box_id" => ^box_id}]} =

             conn

             |> put_box_api_token("box-api-cycle")

             |> get(box_path(conversation.id))

             |> json_response(200)

    assert %{"box" => %{"box_id" => ^box_id}} =

             conn

             |> put_box_api_token("box-api-cycle")

             |> get("#{box_path(conversation.id)}/#{box_id}")

             |> json_response(200)

    Req.Test.expect(__MODULE__, fn request ->

      assert request.method == "POST"

      assert request.request_path == "/boxes/#{box_id}/stop"

      Req.Test.json(request, box_body(%{"state" => "archiving"}))

    end)

    assert %{"box" => %{"box_id" => ^box_id, "state" => "archiving"}} =

             conn

             |> put_box_api_token("box-api-cycle")

             |> post("#{box_path(conversation.id)}/#{box_id}/stop", %{})

             |> json_response(200)

  end

  test "a token without box control is refused on every route", %{conn: conn} do

    user = github_user("api-token-box-api-auth")

    {:ok, conversation} = Conversations.ensure_conversation(user)

    box_id = "bx_8bhkse3n"

    paths = [

      {:get, box_path(conversation.id), %{}},

      {:post, box_path(conversation.id), %{}},

      {:get, "#{box_path(conversation.id)}/#{box_id}", %{}},

      {:post, "#{box_path(conversation.id)}/#{box_id}/commands", %{"command" => "id"}},

      {:post, "#{box_path(conversation.id)}/#{box_id}/stop", %{}}

    ]

    for {method, path, params} <- paths do

      response =

        conn

        |> put_forge_api_token("box-api-auth")

        |> request(method, path, params)

      assert response.status == 401

      assert json_response(response, 401) == %{

               "error" => %{"code" => "invalid_api_token"}

             }

    end

  end

  test "an agent credential receives a typed refusal on every route", %{conn: conn} do

    {:ok, _agent, credential} =

      OpenAgents.Agents.register(%{

        "handle" => "box-agent-auth",

        "display_name" => "Box agent",

        "registration_ip" => "198.51.100.21"

      })

    {:ok, conversation} = Conversations.ensure_conversation(github_user("box-agent-owner"))

    authorization = "Bearer " <> credential

    for {method, path, params} <- [

          {:get, box_path(conversation.id), %{}},

          {:post, box_path(conversation.id), %{}},

          {:get, "#{box_path(conversation.id)}/bx_8bhkse3n", %{}},

          {:post, "#{box_path(conversation.id)}/bx_8bhkse3n/commands", %{"command" => "id"}},

          {:post, "#{box_path(conversation.id)}/bx_8bhkse3n/stop", %{}}

        ] do

      response =

        conn

        |> put_req_header("authorization", authorization)

        |> request(method, path, params)

      assert response.status == 403

      assert json_response(response, 403) == %{

               "error" => %{"code" => "agent_box_control_forbidden"}

             }

    end

  end

  test "a foreign box returns 404 without an outbound provider request", %{conn: conn} do

    owner = github_user("api-token-box-api-owner")

    {:ok, conversation} = Conversations.ensure_conversation(owner)

    {:ok, foreign_conversation} =

      Conversations.ensure_conversation(github_user("box-api-foreign"))

    insert_box(foreign_conversation.id, "bx_8bhkse3n")

    Req.Test.stub(__MODULE__, fn request ->

      send(self(), :unexpected_box_provider_request)

      Req.Test.json(request, box_body())

    end)

    assert conn

           |> put_box_api_token("box-api-owner")

           |> post("#{box_path(conversation.id)}/bx_8bhkse3n/commands", %{"command" => "id"})

           |> json_response(404) == %{"error" => %{"code" => "box_not_found"}}

    refute_receive :unexpected_box_provider_request

  end