# `Wardrik.Workers`

Tools offered by workers: programs that connect to Wardrik and run tool calls in their own
process, like MCP servers.

A definition names them as `workers/*`. The model sees each tool as, for example,
`workers__refund_order`.

## Which workers an agent gets

An agent gets the tools of every worker whose scope may `agent.serve` it. The `:worker` role
allows that. Workers of the same principal that offer the same tool share its calls. If several
principals offer it, the agent gets the one whose worker connected first.

## Serving a worker

A surface holds each worker's connection in its own process, which:

  1. Offers the worker's tools with `offer/2`.
  2. Receives each call as `{Wardrik.Workers, :call, call, name, arguments, meta}`.
  3. Answers it with `answer/2`.
  4. Receives `{Wardrik.Workers, :cancel, call}` if Wardrik stops waiting.

A call's `meta` holds the `agent` it's for, the `run` it's part of, the `principal` it acts for,
and an `idempotencyKey` that stays the same if the call is retried.

## Failures

  * No worker for the call raises `Wardrik.Workers.Unavailable`.
  * A worker that goes away or times out raises `Wardrik.Workers.Lost`.

The tool runner retries either on whichever worker offers the tool then, if every worker
offering it marks it read-only or idempotent. Otherwise a call that may have run waits on a
person as `:in_doubt`.

## Trust

A tool is gated unless every worker offering it marks it read-only. Its results are labelled
`"outside"` unless Wardrik's `:trusted_workers` is `true`.

# `call`

```elixir
@type call() :: {pid(), reference()}
```

# `answer`

```elixir
@spec answer(call(), map()) :: :ok
```

Answers `call` with the worker's JSON-RPC `tools/call` response.

# `offer`

```elixir
@spec offer(Wardrik.Scope.t(), term()) :: :ok | {:error, term()}
```

Offers a worker's tools from the calling process, until it exits.

`listed` is in MCP's `tools/list` shape. It replaces what the process offered before. Tools with
invalid names or definitions are left out.

---

*Consult [api-reference.md](api-reference.md) for complete listing*