hot.dev/hot-ai-agent / ::ai::agent::request

Functions

Identity alias

Alias of ::session/Identity

Session alias

Alias of ::session/Session

bind

fn (session: ::ai::session/Session, sender: ::ai::session/Identity, extras: Map?): Null

Bind the active session/identity into the per-run context so tool functions (registered statically at namespace top-level) can recover them. Returns null; the binding lives for the rest of the current ::hot::ctx scope.

extras (optional) is stored under the ai.agent.extras key and is intended for transport- or agent-specific fields (e.g. channel id, transport name, locale). Keep it small — anything routinely consumed by tools deserves its own typed ctx key.

clear

fn (): Null

Clear the per-request bindings. Rarely needed — ::hot::ctx is request-scoped — but handy in long-running test loops that reuse a single ctx and want to reset between iterations.

extras

fn (): Map

Returns the extras map bound by bind for this request, or {} if none.

ns alias

Alias of ::ai::agent::request/

Per-request session/identity bindings for one agent chat turn.

Not to be confused with ::hot::ctx, which is the engine's request-scoped store for configuration values (API keys, feature flags, env-specific settings, secrets that get masked in logs). ::ai::agent::request is a thin facade on top of that store, reserving a namespaced set of keys (ai.agent.*) for one job: tracking who the current chat turn is for.

The problem it solves: concrete agents typically expose LLM tools as top-level functions in their namespace (e.g. record-task-completion, forget-source, record-decision). Those tools must know whose session and identity to write against, but they're registered once at the top of the file — they don't take session/identity as parameters, because that would let the model spoof them.

The pattern is:

1. The event handler calls bind(session, sender) immediately after resolving session/identity from the incoming event.
2. The tool body calls session() / sender() to recover them inside the per-run context.

Hot's ::hot::ctx is request-scoped (each agent run gets its own ctx inheritance), so the bindings are isolated to one event and cannot leak between concurrent requests.

Tools that recover session/identity this way are tamper-resistant: the model can send any tool arguments it likes, but it cannot rewrite the per-run bindings. Callers can still pass extra typed fields via extras (e.g. transport name, channel id) without polluting the fixed keys.

sender

fn (): ::ai::session/Identity?

Recover the bound identity as an Identity value for this request. Returns null if bind has not been called in this request scope. The returned identity has meta = {}; if your tools need richer identity metadata, pass it through extras and recover it with extras.

session

fn (): ::ai::session/Session?

Recover the bound session as a Session value for this request. Returns null if bind has not been called in this request scope.

Callers that need transport-decorated sessions should wrap the returned value with ::ai::agent::transport/session-with-transport.

session-id

fn (): Str?

Returns the session id bound by bind for this request, or null if unbound.

user-id

fn (): Str?

Returns the user id bound by bind for this request, or null if unbound.

user-name

fn (): Str?

Returns the user name bound by bind for this request, or null if unbound.