Runtime helpers shared by long-lived AI agents: scoped stores, registered sessions, simple counters, and rolling error logs.

Values

REGISTERED_SESSIONS_KEY

REGISTERED_SESSIONS_KEY: Str "registered-sessions"

REGISTER_SESSION_ATTEMPTS

REGISTER_SESSION_ATTEMPTS: Int 100

Functions

bump-counter

fn (store: ::hot::store/Map, key: Str, delta: Int): Int

Increment a numeric counter in a store and return the new value. The store adds atomically, so concurrent bumps are never lost.

Example

::runtime ::ai::agent::runtime

rt ::runtime/create-runtime("team-agent")
key `messages:${::runtime/today-bucket()}`
::runtime/bump-counter(rt.stats-store, key, 1)

create-runtime

fn (agent-name: Str): AgentRuntime
fn (agent-name: Str, opts: Map?): AgentRuntime

Create standard state/stats/errors stores for an agent name.

Example

::runtime ::ai::agent::runtime

rt ::runtime/create-runtime("team-agent", {store-prefix: "team-agent-v2", max-errors: 20})
rt.agent-name  // "team-agent"
rt.state-store.name  // "agent:team-agent-v2:state"
rt.max-errors  // 20

list-registered-sessions

fn (rt: AgentRuntime): Vec<::ai::session/Session>

Materialize registered sessions from the runtime state store.

Example

::runtime ::ai::agent::runtime

rt ::runtime/create-runtime("team-agent")
map(::runtime/list-registered-sessions(rt), %.id)

now-epoch-secs

fn (): Int

Current Unix epoch seconds.

Example

started ::ai::agent::runtime/now-epoch-secs()
`started at ${started}`

record-error

fn (rt: AgentRuntime, where: Str, msg: Str): Any

Append a rolling error entry to the runtime error store.

Example

::runtime ::ai::agent::runtime

rt ::runtime/create-runtime("team-agent")
::runtime/record-error(rt, "daily-recap", "provider timed out")

register-session

fn (rt: AgentRuntime, session: ::ai::session/Session): Vec

Add a session to the runtime's registered-session index. Idempotent. Concurrent registrations are all kept: the index is replaced only while it still holds what was read, and the read is retried otherwise.

Example

::runtime ::ai::agent::runtime

rt ::runtime/create-runtime("team-agent")
::runtime/register-session(rt, ::ai::session/Session({id: "slack:C123"}))

today-bucket

fn (): Int

Day number since Unix epoch, useful for naturally sortable daily counters.

Example

`messages:${::ai::agent::runtime/today-bucket()}`

Types

AgentRuntime

AgentRuntime type {
    agent-name: Str,
    state-store: ::hot::store/Map,
    stats-store: ::hot::store/Map,
    errors-store: ::hot::store/Map,
    notify-store: ::hot::store/Map,
    max-errors: Int
}

Per-agent runtime stores and configuration.

Four stores are kept distinct so unrelated read paths never collide: state-store for arbitrary state (incl. registered sessions), stats-store for counters, errors-store for the rolling error log, and notify-store for the agent notification ledger used by ::ai::agent::notify.