Practical docs for getting an agent's status

[pdaoust]

Document get_agent_activity and explain its purpose. Probably depends on countersigning, which is the main use case for this -- checking that an agent isn't in some invalid state.

[EDIT 2025-06-02] Constraining the scope of this to not include info about querying a source chain -- only the stuff about the agent's status (forks, warrants, etc). Will require a follow-up PR on the content written in #535 to indicate that querying isn't the primary use case for get_agent_activity.

BLOCKED by lack of stable warrants implementation.

AC:

• a page showing examples that get warrants and chain state (chain forks out of scope for now)

[pdaoust]

some sample content I wrote. The first code example is very expensive and not recommended -- but the prose and the second example may be useful.

## Query another agent's source chain

An agent can query another agent's source chain with the [`get_agent_activity`](https://docs.rs/hdk/latest/hdk/chain/fn.get_agent_activity.html) host function.

`get_agent_activity` returns [`AgentActivity`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/query/struct.AgentActivity.html), a struct with rich info on the agent's source chain status, but it _only returns the action hashes_ of matching records; it's the job of the caller to turn them into records.

```rust
use hdk::prelude::*;

#[hdk_extern]
pub fn get_all_movies_authored_by_other_agent(agent: AgentPubKey) -> ExternResult<Vec<(u32, Option<Record>)>> {
    let activity = get_agent_activity(
        agent,
        ChainQueryFilter::new()
            .entry_type(EntryType::App(UnitEntryTypes::Movie.into()))
            .include_entries(true),
        ActivityRequest::Full
    )?;

    // Now try to retrieve the records for all of the action hashes, turning
    // the whole result into an Err if any record retrieval returns an Err.
    let chain_with_entries = activity.valid_activity
        .iter()
        .map(|a| {
            let maybe_record = get(a.1, GetOptions::network())?;
            // Because some records may be unretrievable if no agent is
            // currently serving them, remember the action hash so we can try
            // retrieving them later.
            Ok((a.1, maybe_record))
        })
        .collect();
    Ok(chain_with_entries)
}
```

### Get source chain status summary

`get_agent_activity` is for more than just querying an agent's source chain. It also returns the _status of the agent's source chain_, which includes evidence of [source chain forks](/resources/glossary/#fork-source-chain) and invalid actions.

To quickly check the status without retrieving the source chain's action hashes, pass `ActivityRequest::Status` to `get_agent_activity` and look at the `status` field of the return value:

```rust
use hdk::prelude::*;

#[hdk_extern]
pub fn check_status_of_peer_source_chain(agent: AgentPubKey) -> ExternResult<ChainStatus> {
    let activity_summary = get_agent_activity(
        agent,
        ChainQueryFilter::new()
            .sequence_range(ChainQueryFilterRange::Unbounded),
        ActivityRequest.Status
    )?;
    Ok(activity_summary.status)
}
```

[This status can be one of](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/query/enum.ChainStatus.html):

* `Empty`: No source chain activity found for the agent.
* <code>Valid(<a href="https://docs.rs/hdk/latest/hdk/prelude/struct.ChainHead.html">ChainHead</a>)</code>: The source chain is valid, with its newest action's sequence index and hash given.
* <code>Forked(<a href="https://docs.rs/holochain_zome_types/latest/holochain_zome_types/query/struct.ChainFork.html">ChainFork</a>)</code>: The source chain has been [forked](/resources/glossary/#fork-source-chain), with the sequence index and conflicting action hashes of the fork point given.
* <code>Invalid(<a href="https://docs.rs/hdk/latest/hdk/prelude/struct.ChainHead.html">ChainHead</a>)</code>: An invalid record was found at the given sequence index and action hash.

[ThetaSinner]

This function is being actively used as a way to query the chain. I think we should split the documentation into two pieces.

• How to query another agent's chain (like you would with query against the local chain).
• How to get an agent status and make sense of it, that can still be deferred for a stakeholder pull. Though I think it would be worth documenting that it's the primary use-case for this function that we're documenting as being possible to use another way.

This doesn't depend on countersigning. Invalid data can be produced more than one way. You won't see anything happen with this function unless warrants are active. So I suggest we defer fully documenting the agent status portion of this until warrants are stable.

[pdaoust]

Okay, documenting the need to talk about remote agent querying in #571. Constraining the scope of this one to talk about just status.

[pdaoust]

Moved to backlog because of this comment.

[ThetaSinner]

Some of the code documentation for the types exposed to the HDK could be improved. I suggest including that in the ACs.