`test/openagents/chat/open_router/tool_runtime_test.exs`, and

`OpenAgents.DependencyBoundaryTest`.

### TOOL-006 — The shipped tool catalog is a closed, read-only set

### TOOL-006 — The shipped tool catalog is a closed set, read-only but for consent

Status: Current

The catalog the product installs at boot is enumerated, not accumulated. Every

module in `config/config.exs` under `:tools` is read-only, requires an

authority every conversation caller already holds, and is admitted by name.

A tool that ships must work for every caller that can see it; offering a tool

that always refuses trains the model and the person to ignore refusals.

TOOL-005 narrows the offer to what this caller can reach; this invariant

narrows what exists to be offered at all. Neither substitutes for the other.

module in `config/config.exs` under `:tools` requires an authority every

conversation caller already holds, is admitted by name, and is **either

read-only, or gated on a current consent receipt**. A tool that ships must

work for every caller that can see it; offering a tool that always refuses

trains the model and the person to ignore refusals. TOOL-005 narrows the offer

to what this caller can reach; this invariant narrows what exists to be

offered at all. Neither substitutes for the other.

"Gated on a current consent receipt" is not a softening, and it is the only

admitted exception to read-only. It means the module declares a non-read-only

`side_effect` together with metadata that sends

`OpenAgents.Modules.SurfacePolicy.authorize_execution/2` down its receipt path

— an explicit, person-signed receipt bound to that exact module, version, and

`scope_ref`. For an `external_effect` that is the `external_confirmation` or

`explicit_operator_approval` class the surface contract already requires. The

`reversible_write` plus `executor_consent` combination, which runs without

asking anyone, does not qualify. Because

`OpenAgents.Tools.AdmittedCatalog` applies the same check when it builds the

catalog, such a tool is *not offered* on a turn where the person has not

consented, rather than offered and refused: the standing prompt cost is zero

and the "works for every caller that can see it" rule above still holds, since

the only callers who can see it are the ones who consented. There is no

standing grant to record and no "always" to accumulate — the receipt is scoped

to one conversation and re-checked on every call, which is the ask-every-time

rung of the approval ladder in

`docs/2026-08-23-openagents-coder-cli-spec.md`, section 7.3.

Filing an issue from chat (`OpenAgents.Tools.IssueCapture`) is the first and

currently the only module admitted under that exception. It writes to a public

tracker, so it is `:external_effect`; it files under the requesting account's

own repository membership, so it mints no authority of its own; and a caller

holding no writing role is refused with a typed error that names the missing

role rather than a silent fallback to a repository they did not choose.

Modules that are not admitted stay in `lib/openagents/tools/` and stay under

test through the broader fixture catalog in `config/test.exs`, which must

    # through `owner_user_id`, the one owner field every conversation caller

    # populates correctly today.

    OpenAgents.Tools.ConnectedRepositoryRead,

    OpenAgents.Tools.ConnectedRepositoryList

    OpenAgents.Tools.ConnectedRepositoryList,

    # File a request the person made in chat as an issue, in a repository they

    # can write to (#77). The one tool here that is not read-only, and the

    # reason TOOL-006 now says "read-only, or gated on a current consent

    # receipt" rather than "read-only". It declares `:external_effect` with

    # `approval_enforcement: "host_receipt"`, so `SurfacePolicy` demands an

    # explicit, current, person-signed receipt bound to this module, version,

    # and conversation — checked when the catalog is built as well as when the

    # tool runs. On a turn with no such receipt it is not offered, so it costs

    # nothing and never trains anyone to ignore a refusal. Authority stays the

    # caller's: it files under their own repository membership.

    OpenAgents.Tools.IssueCapture

  ],

  conversation_reset_enabled: false,

  github_api: [

  OpenAgents.Tools.RepoEdit,

  OpenAgents.Tools.RepoWrite,

  OpenAgents.Tools.RepoCommitPush,

  OpenAgents.Tools.IssueCapture,

  OpenAgents.Tools.TestRecall

]

The catalog held **37 tool modules** in one flat list at `config/config.exs:176`,

installed at boot by `lib/openagents/application.ex:41` and gated only by the

`:tools` feature flag. It is now **6**.

`:tools` feature flag. It is now **6** — **7 since 2026-08-24**, when #77

re-admitted `capture_issue` through the section 6 criteria. Section 11 records

that decision and what it changed in TOOL-006; sections 5 and 6 describe the

six-tool base it started from.

Three findings drove the size of the cut, and each is stronger than "too many

tools".

---

## 11. The first re-admission: `capture_issue` (2026-08-24)

Issue #77 admitted a seventh module, `OpenAgents.Tools.IssueCapture`. It is the

first tool to come back, and the first that is not read-only, so TOOL-006 moved

with it: the shipped catalog is now "read-only, **or** gated on a current

consent receipt", and nothing else. Section 6's six criteria, answered.

1. **It works for every caller that can see it.** It resolves the account

   through `owner_user_id`, the one owner field every conversation caller

   populates correctly today — the same field that let `read_repository_file`

   survive the cut, and the field summary finding 1 shows `owner_visitor_id`

   gets wrong. It declares `reach: [:signed_in_owner]`, so an unresolved owner

   never sees it, and its `external_confirmation` gate means the only callers

   offered it are those holding a current consent receipt.

2. **Its authority is one the caller genuinely holds.** `repository.write`, and

   the blanket grant is deliberately *not* the evidence. The real gate is

   per-repository membership, checked at execution against the requesting

   account through `Repositories.writable?/2` — the same shape as the

   repository read tools, whose gate also depends on an argument the catalog

   has not seen. The tool mints no authority: it can file exactly where the

   person could have filed by hand.

3. **Its refusal path has a test.**

   `test/openagents/tools/issue_capture_test.exs` asserts the typed refusals a

   person actually reads: `repository_write_access_required` (with a message

   naming the missing role), `repository_not_found` for a repository the caller

   cannot see, `repository_authentication_required` for a conversation with no

   account, and `module_approval_required` with no consent receipt. Each

   asserts nothing was filed.

4. **Its declared effect matches what it does.** `:external_effect`. A filed

   issue is public, numbered, and notifies watchers; section 7.2 of the coder

   spec settles that "open an issue" is an external effect even with nothing on

   disk changed. This is the criterion `deep_work`, `box_new`, and `code_check`

   each fail, and it is why the surface contract then forces

   `external_confirmation` rather than the `executor_consent` path that would

   have let it run unasked.

5. **Its description says when not to use it.** Four negatives: not to answer a

   question or look something up, not to record a preference or a note, not

   without the person asking for the request to be tracked, not twice for one

   request, and never with a guessed repository.

6. **It earns its prompt budget.** 1,570 bytes encoded, which would be the

   largest definition in the catalog — but **zero on a turn

   where the person has not consented**, because `AdmittedCatalog` applies the

   receipt check when it builds the catalog, so the tool is omitted rather than

   offered-and-refused. It is charged only on turns where someone has already

   said yes to filing. That is the opposite of the `scv_deploy` shape section 6

   warns about, which paid its full cost on every turn to be refused on almost

   all of them.

Two things this did not settle, named rather than hidden.

- **Nothing mints the consent receipt yet.** The gate is real and tested, but

  no surface currently produces a `sarah.module_approval.v1` receipt with

  `approval_class: "external_confirmation"` for this module, so in production

  the tool is presently inert: never offered, never run. That is the correct

  failure direction — an ungated public write would be the wrong one — but the

  capability is not reachable from chat until the preview-and-consent step

  #77's contract calls for is built on the chat surface. The authenticated API

  operation, `POST /api/v3/repos/:owner/:repo/issues/capture`, needs no receipt

  because the person is asking directly rather than through a model, and it

  works today.

- **Deduplication is exact, not semantic.** No embedding index over issues

  exists — `Tools.Embeddings` covers the tool catalog and the pgvector tables

  cover conversation messages — so `Issues.Capture.dedupe/2` matches normalized

  titles exactly. It misses real duplicates rather than swallowing distinct

  requests, which is the safe direction, and it is the single place that

  changes if issue embeddings ever land.

---

## Sources

- `config/config.exs`, `config/test.exs`, `lib/openagents/application.ex`

    Repo.get_by!(Issue, id: id, repository_id: repository_id)

  end

  @doc """

  The oldest open issue in `repository` whose title normalizes to `normalized`.

  The comparison is exact on the normalized form, never a substring or keyword

  match: `maybe_filter_search/2` exists for a person narrowing a list, where a

  loose match costs nothing, but a loose match here would silently swallow a

  distinct request into an unrelated issue. `OpenAgents.Issues.Capture` is the

  only caller and `Capture.normalize_title/1` is the only normalizer; the SQL

  below reproduces it so the comparison happens in the index scan rather than

  by loading every open issue.

  Returns `nil` when nothing matches. Pull-request-backed rows are excluded:

  they share the number space but a pull request is not the issue a request

  should be folded into.

  """

  @spec open_issue_with_normalized_title(Repository.t(), String.t()) :: Issue.t() | nil

  def open_issue_with_normalized_title(%Repository{id: repository_id}, normalized)

      when is_binary(normalized) and normalized != "" do

    repository_id

    |> issue_query(state: "open", type: "issue")

    |> where(

      [issue: issue],

      fragment("btrim(regexp_replace(lower(?), '[^a-z0-9]+', ' ', 'g'))", issue.title) ==

        ^normalized

    )

    |> order_by([issue: issue], asc: issue.number)

    |> limit(1)

    |> Repo.one()

  end

  def open_issue_with_normalized_title(%Repository{}, _normalized), do: nil

  def get_issue_by_number!(%Repository{id: repository_id}, number) when is_integer(number),

    do: Repo.get_by!(Issue, repository_id: repository_id, number: number)

defmodule OpenAgents.Issues.Capture do

  @moduledoc """

  Turns one sentence of a conversation into a scoped forge issue.

  This module is the whole of the behavior. The chat tool

  (`OpenAgents.Tools.IssueCapture`) and the authenticated API operation

  (`POST /api/v3/repos/:owner/:repo/issues/capture`) are two transports over

  it, so the two cannot drift: a refusal the tool gives is the refusal the API

  gives, and a draft the API writes is the draft the tool writes.

  Three things happen here, in this order, and the order matters.

  1. **The repository is resolved under the caller's own membership.** Nothing

     here mints authority. `authorize/2` asks

     `OpenAgents.Repositories.writable?/2` about the account that asked, and a

     caller who cannot write gets a typed refusal that names what is missing

     rather than a silent fallback to some other repository. A repository the

     caller cannot even see is reported as absent, because saying

     "you lack write access" about a private repository discloses that it

     exists.

  2. **A near-duplicate is preferred over a new row.** See `dedupe/2`.

  3. **Only then is an issue created**, through `OpenAgents.Issues.create_issue/3`

     with the caller as author. Going through that function rather than

     inserting directly is what subscribes the requester to the issue's own

     notifications: `create_issue/3` calls `Notifications.issue_opened/2`

     inside its transaction, so the requester follows the issue from the

     moment it exists.

  ## What the public issue says

  The body is a fixed template — outcome, current behavior, acceptance

  criteria — filled only from what the caller supplied. Nothing else reaches

  it. No conversation id, no message id, no prompt, no tool trace, no

  repository metadata, and no model output the caller did not see. The

  template placeholders are honest about being unfilled instead of inventing

  a current behavior nobody observed.

  """

  import Ecto.Changeset, only: [traverse_errors: 2]

  alias OpenAgents.Accounts.User

  alias OpenAgents.Issues

  alias OpenAgents.Issues.Issue

  alias OpenAgents.Repositories

  alias OpenAgents.Repositories.Repository

  @maximum_statement_bytes 4_000

  @maximum_section_bytes 4_000

  @maximum_criteria 12

  @maximum_title_characters 72

  @type outcome :: :created | :existing

  @type result :: %{

          issue: Issue.t(),

          repository: Repository.t(),

          outcome: outcome()

        }

  @type error ::

          :blank_problem_statement

          | :problem_statement_too_long

          | :section_too_long

          | :invalid_repository

          | :repository_not_found

          | :repository_write_access_required

          | {:invalid_issue, map()}

  @doc """

  Captures `attrs` as an issue in `repository_path` on behalf of `actor`.

  `repository_path` is `owner/name`. `attrs` accepts string keys:

  - `"problem"` — required, the requester's own words.

  - `"current_behavior"` — optional.

  - `"acceptance_criteria"` — optional, a list of strings or a newline-separated

    string.

  Returns `{:ok, %{issue: issue, repository: repository, outcome: outcome}}`

  where `outcome` is `:created` for a new issue and `:existing` when

  deduplication matched one that was already open. Retrying the same statement

  against the same repository therefore returns the same issue rather than a

  second one.

  """

  @spec capture(User.t(), String.t(), map()) :: {:ok, result()} | {:error, error()}

  def capture(%User{} = actor, repository_path, attrs) when is_binary(repository_path) do

    with {:ok, problem} <- problem(attrs),

         {:ok, current_behavior} <- section(attrs, "current_behavior"),

         {:ok, criteria} <- criteria(attrs),

         {:ok, repository} <- authorize(actor, repository_path) do

      title = draft_title(problem)

      body = draft_body(problem, current_behavior, criteria)

      case dedupe(repository, title) do

        %Issue{} = existing ->

          {:ok, %{issue: existing, repository: repository, outcome: :existing}}

        nil ->

          create(actor, repository, title, body)

      end

    end

  end

  @doc """

  Resolves `repository_path` to a repository `actor` may write to.

  The two refusals are deliberately different facts. `:repository_not_found`

  means the caller cannot see it, and is also what a caller gets for a private

  repository they hold no membership in — the refusal must not become an

  existence oracle. `:repository_write_access_required` means the caller can

  see it and holds no writing role, which is safe to say because they already

  know it exists, and is the refusal that names the missing authority so the

  person knows what to ask for.

  """

  @spec authorize(User.t(), String.t()) :: {:ok, Repository.t()} | {:error, error()}

  def authorize(%User{} = actor, repository_path) when is_binary(repository_path) do

    with {:ok, owner, name} <- parse_path(repository_path),

         %Repository{} = repository <- Repositories.visible_by_path(owner, name, actor) do

      if Repositories.writable?(repository, actor) do

        {:ok, repository}

      else

        {:error, :repository_write_access_required}

      end

    else

      nil -> {:error, :repository_not_found}

      {:error, reason} -> {:error, reason}

    end

  end

  @doc """

  The open issue this request should be folded into, or `nil`.

  **This is an exact match on the normalized title, not a semantic one, and

  that is a limitation rather than a preference.** The repository has no

  embedding index over issues: `OpenAgents.Tools.Embeddings` covers the tool

  catalog, and the pgvector tables under `OpenAgents.Memory.SemanticIndex`

  cover conversation messages. Neither indexes issue text, and standing one up

  is a larger change than this one.

  So the choice was between an exact normalized-title check and inventing

  keyword or substring heuristics. Heuristics are the worse failure: a

  substring match folds "search is slow" into "search is slow on mobile" and

  the second request disappears without anyone deciding it should. An exact

  match fails in the safe direction — it misses real duplicates, which a person

  can still close by hand, and it never swallows a distinct request.

  Normalization is case, punctuation, and whitespace only, so

  `"Add dark mode"`, `"add dark mode."`, and `"Add  dark   mode"` are one

  issue. When issue embeddings exist, this function is the single place that

  changes.

  """

  @spec dedupe(Repository.t(), String.t()) :: Issue.t() | nil

  def dedupe(%Repository{} = repository, title) when is_binary(title) do

    Issues.open_issue_with_normalized_title(repository, normalize_title(title))

  end

  @doc """

  The comparison form of a title: lowercase, alphanumeric runs, single spaces.

  `OpenAgents.Issues.open_issue_with_normalized_title/2` reproduces this in

  SQL. Change one and you must change the other, or deduplication silently

  stops matching.

  """

  @spec normalize_title(String.t()) :: String.t()

  def normalize_title(title) when is_binary(title) do

    title

    |> String.downcase()

    |> String.replace(~r/[^a-z0-9]+/u, " ")

    |> String.trim()

  end

  @doc "The title this statement drafts to, exposed so a preview can show it."

  @spec draft_title(String.t()) :: String.t()

  def draft_title(problem) when is_binary(problem) do

    problem

    |> collapse()

    |> first_sentence()

    |> truncate(@maximum_title_characters)

    |> capitalize_first()

  end

  @doc "The body this statement drafts to, exposed so a preview can show it."

  @spec draft_body(String.t(), String.t() | nil, [String.t()]) :: String.t()

  def draft_body(problem, current_behavior, criteria)

      when is_binary(problem) and is_list(criteria) do

    """

    ## Outcome

    #{collapse_lines(problem)}

    ## Current behavior

    #{current_behavior_section(current_behavior)}

    ## Acceptance criteria

    #{criteria_section(criteria)}

    """

    |> String.trim()

    |> Kernel.<>("\n")

  end

  defp create(actor, repository, title, body) do

    case Issues.create_issue(repository, %{"title" => title, "body" => body}, actor) do

      {:ok, %Issue{} = issue} ->

        {:ok, %{issue: issue, repository: repository, outcome: :created}}

      {:error, changeset} ->

        {:error, {:invalid_issue, changeset_errors(changeset)}}

    end

  end

  defp changeset_errors(changeset) do

    traverse_errors(changeset, fn {message, options} ->

      Regex.replace(~r/%\{(\w+)\}/, message, fn _whole, key ->

        options |> Keyword.get(String.to_existing_atom(key), key) |> to_string()

      end)

    end)

  end

  defp problem(attrs) do

    case attrs |> Map.get("problem") |> normalize_input() do

      nil ->

        {:error, :blank_problem_statement}

      problem when byte_size(problem) > @maximum_statement_bytes ->

        {:error, :problem_statement_too_long}

      problem ->

        {:ok, problem}

    end

  end

  defp section(attrs, key) do

    case attrs |> Map.get(key) |> normalize_input() do

      nil -> {:ok, nil}

      value when byte_size(value) > @maximum_section_bytes -> {:error, :section_too_long}

      value -> {:ok, value}

    end

  end

  defp criteria(attrs) do

    attrs

    |> Map.get("acceptance_criteria")

    |> List.wrap()

    |> Enum.flat_map(&String.split(to_string(&1), "\n"))

    |> Enum.map(&(&1 |> String.replace_prefix("- [ ]", "") |> String.replace_prefix("-", "")))

    |> Enum.map(&normalize_input/1)

    |> Enum.reject(&is_nil/1)

    |> Enum.take(@maximum_criteria)

    |> then(fn criteria ->

      if Enum.any?(criteria, &(byte_size(&1) > @maximum_section_bytes)) do

        {:error, :section_too_long}

      else

        {:ok, criteria}

      end

    end)

  end

  defp normalize_input(value) when is_binary(value) do

    case String.trim(value) do

      "" -> nil

      trimmed -> trimmed

    end

  end

  defp normalize_input(_value), do: nil

  defp current_behavior_section(nil),

    do: "Not recorded when this was captured. Fill this in before the work starts."

  defp current_behavior_section(current_behavior), do: collapse_lines(current_behavior)

  defp criteria_section([]),

    do: "- [ ] Not recorded when this was captured. Agree these before the work starts."

  defp criteria_section(criteria), do: Enum.map_join(criteria, "\n", &"- [ ] #{collapse(&1)}")

  defp parse_path(repository_path) do

    case repository_path |> String.trim() |> String.split("/", trim: true) do

      [owner, name] when byte_size(owner) in 1..100 and byte_size(name) in 1..100 ->

        {:ok, owner, name}

      _invalid ->

        {:error, :invalid_repository}

    end

  end

  defp collapse(value), do: value |> String.replace(~r/\s+/u, " ") |> String.trim()

  # Paragraphs survive; runs of blank lines and trailing spaces do not. The

  # requester's own prose reaches the issue intact.

  defp collapse_lines(value) do

    value

    |> String.split("\n")

    |> Enum.map(&String.trim_trailing/1)

    |> Enum.join("\n")

    |> String.replace(~r/\n{3,}/, "\n\n")

    |> String.trim()

  end

  defp first_sentence(value) do

    case String.split(value, ~r/(?<=[.!?])\s+/, parts: 2) do

      [sentence, _rest] -> String.trim(sentence)

      [whole] -> whole

    end

    |> String.trim_trailing(".")

  end

  defp truncate(value, limit) do

    if String.length(value) <= limit do

      value

    else

      value

      |> String.slice(0, limit)

      |> String.replace(~r/\s+\S*$/u, "")

      |> String.trim()

      |> then(fn trimmed ->

        if trimmed == "", do: String.slice(value, 0, limit), else: trimmed

      end)

    end

  end

  defp capitalize_first(""), do: ""

  defp capitalize_first(value) do

    {first, rest} = String.split_at(value, 1)

    String.upcase(first) <> rest

  end

end

defmodule OpenAgents.Tools.IssueCapture do

  @moduledoc """

  Files one unmet request from a conversation as a scoped forge issue.

  The behavior lives in `OpenAgents.Issues.Capture`, which

  `POST /api/v3/repos/:owner/:repo/issues/capture` also calls, so the tool and

  the API operation cannot drift apart.

  ## Why this one is `:external_effect`

  A filed issue is public, has a number other people cite, and notifies

  everyone watching the repository. Nothing on disk changed, which is exactly

  why the honest classification is easy to get wrong; the coder specification

  settles it directly — "'open an issue' is an external effect even though

  nothing on your disk changed" (`docs/2026-08-23-openagents-coder-cli-spec.md`,

  section 7.2). Its ladder puts tracker writes at **ask every time**, so this

  tool declares `approval_class: "external_confirmation"` — the class

  `OpenAgents.Modules.SurfacePolicy` requires of an external effect, and the

  one `open_pull_request` already uses for the same reason — with

  `approval_enforcement: "host_receipt"`.

  `OpenAgents.Modules.SurfacePolicy.approval/2` then demands a current,

  explicit, person-signed receipt bound to this exact module, version, and

  conversation before the tool runs — and `OpenAgents.Tools.AdmittedCatalog`

  applies the same check when it builds the catalog, so on a turn where the

  person has not consented the tool is not offered rather than offered and

  refused. There is no standing grant and no "always" to record: the receipt is

  scoped to one conversation and checked again on every call.

  ## Authority is the caller's

  The requesting account's own membership decides where an issue can be filed.

  `Capture.authorize/2` reads `OpenAgents.Repositories.writable?/2` for that

  account and nothing else, so the agent cannot file somewhere the person could

  not have filed by hand, and a caller without a writing role gets

  `repository_write_access_required` naming what is missing. The repository is

  always an argument, never a default: a request that names no repository is

  refused rather than routed to a guess.

  """

  @behaviour OpenAgents.Tools.Tool

  alias OpenAgents.Accounts.User

  alias OpenAgents.Issues.Capture

  alias OpenAgents.Modules.Metadata

  alias OpenAgents.Repo

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

  @impl true

  def specification do

    %Tool{

      module_id: "sarah.tool.issue_capture.v1",

      name: "capture_issue",

      version: 1,

      description:

        "File the person's feature request or bug report as an issue in a Forge repository " <>

          "they can write to, drafted as outcome, current behavior, and acceptance criteria. " <>

          "Returns the issue number and URL, and returns the existing issue instead of a " <>

          "second one when an open issue already has the same title. " <>

          "Do not call this to answer a question, to look something up, or to record a " <>

          "preference or a note — filing a public issue is not a way to remember something. " <>

          "Do not call it without the person asking for the request to be tracked, and do not " <>

          "call it a second time for a request you already filed in this conversation. " <>

          "Do not guess the repository: ask which one if the person has not named it.",

      input_schema: input_schema(),

      output_schema: output_schema(),

      side_effect: :external_effect,

      required_scope: "browser_conversation",

      required_authority: "repository.write",

      executor: %{

        id: "sarah.forge.issues",

        disclosure: "OpenAgents Forge, filing as the signed-in person"

      },

      maintainer: "OpenAgents",

      attribution: ["OpenAgentsInc/openagents.com"],

      policy_facets: %{

        "privacy" => "signed_browser_owner",

        "residency" => "application_process",

        "consent" => "external_confirmation"

      },

      module_metadata:

        Metadata.first_party("repository.write", "browser_conversation",

          effect: :external_effect,

          privacy: "signed_browser_owner",

          residency: "application_process",

          approval_class: "external_confirmation",

          approval_enforcement: "host_receipt"

        ),

      timeout_ms: 15_000,

      maximum_input_bytes: 16_384,

      maximum_output_bytes: 8_192,

      implementation: __MODULE__,

      tags: ["forge", "issue", "tracker", "request", "file"],

      # Filing runs under the person's own membership, so an unresolved owner

      # can never succeed. The repository itself carries no reach requirement:

      # its gate is per-repository write membership, which depends on an

      # argument the catalog has not seen (TOOL-005).

      reach: [:signed_in_owner]

    }

  end

  @impl true

  def execute(%{"repository" => repository} = arguments, %ExecutionContext{} = context)

      when is_binary(repository) do

    with {:ok, actor} <- actor(context),

         {:ok, captured} <- Capture.capture(actor, repository, arguments) do

      {:ok,

       %ExecutionResult{

         result: result(captured),

         target_receipt_refs: ["forge-issue:#{captured.issue.id}"]

       }}

    else

      {:error, {:invalid_issue, _errors}} -> {:error, :invalid_issue}

      {:error, reason} -> {:error, reason}

    end

  end

  def execute(_arguments, _context), do: {:error, :invalid_repository}

  defp actor(%ExecutionContext{owner_user_id: user_id}) when is_binary(user_id) do

    case Repo.get(User, user_id) do

      %User{status: "active"} = user -> {:ok, user}

      _absent -> {:error, :repository_authentication_required}

    end

  end

  defp actor(%ExecutionContext{}), do: {:error, :repository_authentication_required}

  defp result(%{issue: issue, repository: repository, outcome: outcome}) do

    path = repository.owner <> "/" <> repository.name

    %{

      "schema" => "openagents.captured_issue.v1",

      "repository" => path,

      "number" => issue.number,

      "title" => issue.title,

      "state" => issue.state,

      "url" => url(path, issue.number),

      "outcome" => Atom.to_string(outcome)

    }

  end

  defp url(path, number) do

    String.trim_trailing(OpenAgentsWeb.Endpoint.url(), "/") <> "/#{path}/issues/#{number}"

  end

  defp input_schema do

    %{

      "type" => "object",

      "additionalProperties" => false,

      "required" => ["repository", "problem"],

      "properties" => %{

        "repository" => %{

          "type" => "string",

          "description" =>

            "The repository to file in, as owner/name. Required, and never guessed: " <>

              "ask the person which repository if they have not said."

        },

        "problem" => %{

          "type" => "string",

          "description" =>

            "The outcome the person wants, in their own words. Do not add anything they " <>

              "did not say, and do not include conversation, prompt, or credential text."

        },

        "current_behavior" => %{

          "type" => "string",

          "description" =>

            "What happens today, if the person described it. Leave this out rather than " <>

              "inventing behavior nobody observed."

        },

        "acceptance_criteria" => %{

          "type" => "array",

          "items" => %{"type" => "string"},

          "description" =>

            "What must be true for the request to be done, if the person said. " <>

              "Leave this out rather than inventing criteria."

        }

      }

    }

  end

  defp output_schema do

    %{

      "type" => "object",

      "required" => ["schema", "repository", "number", "url", "outcome"],

      "properties" => %{

        "schema" => %{"type" => "string"},

        "repository" => %{"type" => "string"},

        "number" => %{"type" => "integer"},

        "title" => %{"type" => "string"},

        "state" => %{"type" => "string"},

        "url" => %{"type" => "string"},

        "outcome" => %{

          "type" => "string",

          "enum" => ["created", "existing"],

          "description" =>

            "`created` for a new issue, `existing` when an open issue already matched."

        }

      }

    }

  end

end

              :publication_receipt_stale,

              :publication_branch_refused,

              :pull_requests_disabled,

              :repository_write_access_required,

              :forbidden,

              :box_quota_reached,

              :box_not_owned,

  defp error_message(:repository_not_found),

    do: "The repository does not exist or you cannot access it."

  # Names the authority rather than the outcome. "You cannot do that" sends the

  # person back to the agent; naming the missing role sends them to whoever can

  # grant it.

  defp error_message(:repository_write_access_required),

    do:

      "Filing an issue there needs write access to that repository, and this account holds " <>

        "no owner, maintainer, or contributor role in it. Ask an owner for one."

  defp error_message(:blank_problem_statement),

    do: "Filing an issue needs the person's request in their own words."

  defp error_message(:problem_statement_too_long),

    do: "The request is too long to file as one issue. Summarize it first."

  defp error_message(:section_too_long),

    do: "One of the drafted issue sections is too long to file."

  defp error_message(:invalid_issue),

    do: "The drafted issue was rejected by the tracker."

  defp error_message(:ambiguous_repository_name),

    do: "More than one visible repository has that name. Use owner/name."

    "unauthenticated" => {401, "Requires authentication"},

    "forbidden" => {403, "Forbidden"},

    "agent_participation_forbidden" => {403, "This agent may not participate in this repository"},

    # Capturing an issue from chat (#77). A plain `forbidden` would leave the

    # caller unable to tell "no such repository" from "no writing role in a

    # repository you can already see", and only the second is something they

    # can fix by asking an owner. It is only ever returned for a repository the

    # caller can already read, so it discloses nothing a 404 was protecting.

    "repository_write_access_required" =>

      {403, "Writing to this repository needs an owner, maintainer, or contributor role"},

    "not_found" => {404, "Not Found"},

    "label_not_on_issue" => {404, "Label does not exist on this issue"},

    "dependency_not_found" => {404, "Not a prerequisite of this issue"},

      "post /api/v3/forum/topics" => {:required_bearer, :forum, :legacy},

      "post /api/v3/forum/topics/:topic_id/posts" => {:required_bearer, :forum, :legacy},

      "post /api/v3/repos/:owner/:repo/issues" => {:required_bearer, :issue, :envelope},

      "post /api/v3/repos/:owner/:repo/issues/capture" => {:required_bearer, :issue, :envelope},

      "post /api/v3/repos/:owner/:repo/issues/:issue_number/comments" =>

        {:required_bearer, :comment, :envelope},

      "post /api/v3/repos/:owner/:repo/issues/:issue_number/completion_claim" =>

defmodule OpenAgentsWeb.IssueController do

  use OpenAgentsWeb, :controller

  alias OpenAgents.Accounts.User

  alias OpenAgents.Forge.Assignments

  alias OpenAgents.Issues

  alias OpenAgents.Issues.Capture

  alias OpenAgents.Issues.CompletionClaims

  alias OpenAgents.Issues.Evidence

  alias OpenAgents.Issues.Issue

    end

  end

  @doc """

  Captures one problem statement as a drafted, deduplicated issue (#77).

  The API mirror of the `capture_issue` chat tool. Both call

  `OpenAgents.Issues.Capture.capture/3`, so the drafted template, the

  authorization decision, and the deduplication rule are one implementation

  rather than two that agree today.

  The status distinguishes the two outcomes without a body key: `201` when the

  issue was created, `200` when an open issue already matched and is being

  returned instead. A client that retries the same statement therefore sees

  `200` and the same number, which is what makes the operation idempotent for

  the caller rather than only for the database.

  Agents are refused: filing under a personal membership is the point, and an

  `Agent` principal holds no repository membership to file under.

  """

  def capture(conn, %{"owner" => owner, "repo" => repo} = params) do

    case conn.assigns[:current_user] do

      %User{} = actor -> capture_for(conn, actor, owner, repo, params)

      _agent_or_absent -> participation_forbidden(conn, conn.assigns[:current_agent])

    end

  end

  defp capture_for(conn, actor, owner, repo, params) do

    case write_issue(fn -> Capture.capture(actor, "#{owner}/#{repo}", params) end) do

      {:ok, %{issue: issue, repository: repository, outcome: outcome}} ->

        conn

        |> put_status(if(outcome == :created, do: :created, else: :ok))

        |> put_extensions_header()

        |> render(:show,

          issue: issue,

          owner: owner,

          repo: repo,

          dependencies: dependencies(issue),

          progress: progress(issue, actor),

          work: work(issue, repository, actor),

          evidence: evidence(issue, repository, actor),

          completion_claims: completion_claims(issue)

        )

      {:error, :repository_not_found} ->

        not_found(conn)

      {:error, :repository_write_access_required} ->

        ApiError.refuse(conn, "repository_write_access_required")

      {:error, {:invalid_issue, errors}} ->

        ApiError.validation_failed(conn, errors)

      {:error, %UnknownReference{} = unresolved} ->

        unknown_reference(conn, unresolved)

      {:error, reason} when is_atom(reason) ->

        ApiError.validation_failed(conn, %{"problem" => [capture_message(reason)]})

    end

  end

  defp capture_message(:blank_problem_statement),

    do: "can't be blank"

  defp capture_message(:problem_statement_too_long),

    do: "is too long to file as one issue"

  defp capture_message(:section_too_long),

    do: "one of the drafted sections is too long to file"

  defp capture_message(:invalid_repository),

    do: "the repository must be an owner/name path"

  defp capture_message(reason), do: "is invalid (#{reason})"

  # Writing an issue resolves a label, an assignee, and a milestone by name, and

  # a name this repository does not have is a rejected field rather than a

  # missing resource. It is caught here rather than beside the repository

    post "/forum/topics", ForumApiController, :create_topic

    post "/forum/topics/:topic_id/posts", ForumApiController, :create_post

    post "/repos/:owner/:repo/issues", IssueController, :create

    # Drafts, deduplicates, and files one problem statement (#77). It sits

    # beside :create rather than replacing it: :create is the GitHub-compatible

    # operation and takes a finished issue, this one takes a sentence.

    post "/repos/:owner/:repo/issues/capture", IssueController, :capture

    post "/repos/:owner/:repo/issues/:issue_number/comments", CommentController, :create

    post "/repos/:owner/:repo/issues/:issue_number/completion_claim",

defmodule OpenAgents.Issues.CaptureTest do

  @moduledoc """

  Capturing a chat request as an issue (#77).

  The tool and the API operation are transports over this module, so the rules

  that matter — whose authority files the issue, what the public text may say,

  and when a repeat becomes the same issue rather than a second one — are

  proven once here.

  """

  use OpenAgents.DataCase, async: true

  import OpenAgents.AccountsFixtures

  alias OpenAgents.Issues

  alias OpenAgents.Issues.Capture

  alias OpenAgents.Notifications

  alias OpenAgents.Repositories

  setup do

    author = repository_user_fixture("capture-author")

    repository = repository_with_member_fixture(author, %{}, "maintainer")

    %{author: author, repository: repository}

  end

  defp path(repository), do: repository.owner <> "/" <> repository.name

  describe "filing for a caller who may write" do

    test "creates the issue and reports the number", %{author: author, repository: repository} do

      assert {:ok, captured} =

               Capture.capture(author, path(repository), %{

                 "problem" => "Let me export a board to CSV."

               })

      assert captured.outcome == :created

      assert captured.repository.id == repository.id

      assert captured.issue.number > 0

      assert captured.issue.state == "open"

      assert captured.issue.title == "Let me export a board to CSV"

      assert captured.issue.author_user_id == author.id

    end

    test "the body carries the template sections, and the request verbatim", %{

      author: author,

      repository: repository

    } do

      assert {:ok, captured} =

               Capture.capture(author, path(repository), %{

                 "problem" => "Let me export a board to CSV.",

                 "current_behavior" => "The board only renders on screen.",

                 "acceptance_criteria" => ["A CSV downloads", "It carries every visible column"]

               })

      body = captured.issue.body

      assert body =~ "## Outcome"

      assert body =~ "## Current behavior"

      assert body =~ "## Acceptance criteria"

      assert body =~ "Let me export a board to CSV."

      assert body =~ "The board only renders on screen."

      assert body =~ "- [ ] A CSV downloads"

      assert body =~ "- [ ] It carries every visible column"

    end

    test "an unfilled section says so instead of inventing one", %{

      author: author,

      repository: repository

    } do

      assert {:ok, captured} =

               Capture.capture(author, path(repository), %{"problem" => "Add a dark theme."})

      assert captured.issue.body =~ "## Current behavior\n\nNot recorded when this was captured."

      assert captured.issue.body =~ "- [ ] Not recorded when this was captured."

    end

    # #77: "Public issue text contains no private prompt, trace, credential, or

    # repository metadata." The template is filled from named arguments only, so

    # anything else the caller passes has nowhere to land.

    test "nothing but the named arguments reaches the public text", %{

      author: author,

      repository: repository

    } do