Returns a specification to start this module under a supervisor.

See Supervisor.

Fetch the PID of the open request by ID

Fetch the full metadata map of the open request by ID

Fetch the PID of the open session by ID

Get metadata for a tracked session.

Falls back to process dictionary when Phoenix.Tracker is not tracking.

Return a list of all open requests

Return a list of all listening for resources

Return all tracked streams for a given session ID (across all nodes)

Return a list of all open sessions

Return a list of all listening for task status notifications

Notify tracked sessions that a URL elicitation has completed

Notify any listening MCP sessions that the list of prompts has updated

Notify any listening MCP sessions that the list of prompts has updated

@spec notify_resource_updated(String.t()) ::
  {:ok, non_neg_integer()} | {:error, :tracker_not_in_supervision_tree}

Convenience wrapper for notifying sessions about one updated resource

@spec notify_resources_updated([String.t()]) ::
  {:ok, non_neg_integer()} | {:error, :tracker_not_in_supervision_tree}

Notify listening MCP sessions that a batch of resources has updated.

Prefer this function for write batches. Collect the changed resource URIs in application code and call it once after the write succeeds. Phantom deduplicates the URIs, groups them by subscribed session, and performs one authorization callback per session before emitting the protocol's individual notifications/resources/updated messages.

This function intentionally does not collect calls over a hidden time window. Keeping collection in application code preserves transaction boundaries and gives the authorization callback the largest useful batch.

Returns the number of subscribed session processes that received the batch for authorization. This is not the number of resource notifications ultimately authorized and emitted.

@spec notify_task_updated(Phantom.Tasks.t() | String.t()) ::
  {:ok, non_neg_integer()} | {:error, :tracker_not_in_supervision_tree}

Notify clients listening to a task that it changed. Call it after each change you store, with the task or its ID.

Each listening stream fetches the task with Phantom.Router.get_task/2 and sends what it returns as notifications/tasks, so clients get the stored task even when notifications arrive out of order. Returns the number of listening streams.

Notify any listening MCP sessions that the list of tools has updated

Subscribe the process to resource notifications from the PubSub on topic "phantom:resources"

Claim an in-flight JSON-RPC request for a session to prevent double-dispatch when the same tools/call lands on two nodes (e.g. proxy retry). Returns :ok if the claim is held by this node alone, :duplicate if another node has already claimed it.

Stored on the phantom:requests topic alongside server-initiated request tracking. The {:in_flight, session_id, request_id} tuple key never collides with elicitation keys (binaries), so both kinds of tracking share one replication stream.

The check is best-effort against Phoenix.Tracker replication lag: two nodes racing can both see :ok. Callers should treat this as a hint and combine with deterministic request IDs for defence in depth.

Track a request PID

Track a session PID

Unsubscribe the process to resource notifications from the PubSub on topic "phantom:resources"

Untrack the processe for everything

Release an in-flight claim taken by track_in_flight/2.

Untrack any processes for the request

Untrack any processes for the session

Update metadata for a tracked session.

Falls back to process dictionary when Phoenix.Tracker is not tracking (e.g. stdio transport).