authRequired — suspend for authorization

Elixir · package toolnexus · SPEC §10

Not available in Elixir

Elixir ships no auth_required/pending producer helpers — build %ToolResult{metadata: %{pending: %Request{}}} by hand. Only the reader, ToolResult.pending?/1, exists.

The auth-shaped suspension: hand back a URL, resume once the user has granted access.

What to use instead

Build the auth-shaped suspension by hand: a %Toolnexus.ToolResult{} whose metadata.pending carries a %Toolnexus.Request{kind: "authorization"} with a :url instead of expecting typed input:

%Toolnexus.ToolResult{
  output: "Log in",
  is_error: true,
  metadata: %{
    pending: %Toolnexus.Request{
      id: "pnd-2",
      kind: "authorization",
      prompt: "Log in",
      url: "https://example.com/login"
    }
  }
}

Same wire shape as every other port’s authRequired/1, same id correlation discipline as pending — only the constructor is missing, not the behavior. Toolnexus.ToolResult.pending?/1 reads either shape back identically.

See also

• Toolnexus.Client.create — The single hook where the host resolves a suspension — in-process prompt or durable queue, same contract.
• Toolnexus.Agents.Runtime.resume — The answer-carrying entry point: resume a parked run in a different process.