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

Reusable harness primitives for AI agents.

hot-ai owns the low-level ::ai::* building blocks: chat loops, memory, RAG, skills, tools, and inter-agent bus messages. This package extends that family with ::ai::agent::*, the higher-level runtime surface that concrete agents can share:

• ::ai::agent::transport for normalized transport messages.
• ::ai::agent::command for command parsing and declarations.
• ::ai::agent::runtime for session registries, stores, stats, and error logging.
• ::ai::agent::render for neutral reply records and text helpers.
• ::ai::agent::stream for agent-level stream event labels and emit helpers (a thin wrapper over the engine's ::hot::stream).
• ::ai::agent::memory for reusable memory lifecycle command declarations and response shapes (the command-surface sibling of ::ai::memory, which is the memory engine).
• ::ai::agent::lifecycle for scheduled memory lifecycle helpers.
• ::ai::agent::mcp for common MCP tool plumbing.
• ::ai::agent::request for per-request session/identity bindings that let statically-registered tools recover the active caller.
• ::ai::agent::chat-turn for the canonical memory-grounded LLM reply lifecycle (recall → persist user → stream → persist assistant) used by free-chat handlers.
• ::ai::agent::notify for a runtime-scoped notification ledger so scheduled handlers (daily recaps, stale-task nudges, standups) have somewhere to land output when no client is listening.
• ::ai::agent::synthesis for the one-shot, non-streaming LLM pattern that scheduled handlers use to turn a memory window into a notification body.

Types

AgentRuntime alias of ::ai::agent::runtime/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.

Command alias of ::ai::agent::command/Command

Command type {
    name: Str,
    aliases: Vec?,
    description: Str?,
    usage: Str?,
    route: Str?,
    is-async: Bool?,
    handler: Fn?,
    meta: Map?
}

Declarative command metadata for docs, help text, and dispatch tables.

IncomingMessage alias of ::ai::agent::transport/IncomingMessage

IncomingMessage type {
    session: ::ai::session/Session,
    sender: ::ai::session/Identity,
    text: Str,
    message-id: Str,
    timestamp: Int,
    voice: Map?,
    raw: Any?
}

Normalized inbound message shape produced by transport adapters.

LifecycleJob alias of ::ai::agent::lifecycle/LifecycleJob

LifecycleJob type {
    session-id: Str,
    action: Str,
    ok: Bool,
    result: Any?,
    error: Str?
}

Result record from a lifecycle job applied to one session.

MemoryInspection alias of ::ai::agent::memory/MemoryInspection

MemoryInspection type {
    session-count: Int,
    user-count: Int,
    kb-count: Int,
    capsule-count: Int,
    graph-node-count: Int,
    graph-edge-count: Int,
    metadata: Map?
}

Neutral memory-inspection response shape for agents.

Notification alias of ::ai::agent::notify/Notification

Notification type {
    id: Str,
    recipient-id: Str,
    session-id: Str?,
    kind: Str,
    body: Str,
    source: Str?,
    created-at: Int,
    read-at: Int?,
    meta: Map?
}

One notification record. recipient-id is opaque (user id for personal, channel:<sid> for team). kind identifies the cron handler that wrote it; UIs can group/badge by kind.

OutboundMessage alias of ::ai::agent::transport/OutboundMessage

OutboundMessage type {
    session: ::ai::session/Session,
    text: Str,
    reply-to: Str?,
    metadata: Map?
}

Normalized outbound message request before a transport adapter renders or sends it.

Reply alias of ::ai::agent::render/Reply

Reply type {
    text: Str,
    format: Str?,
    sources: Vec?,
    metadata: Map?
}

Neutral reply record before transport-specific rendering.

RetentionPolicy alias of ::ai::agent::memory/RetentionPolicy

RetentionPolicy type {
    name: Str,
    raw-retention-secs: Int?,
    capsule-retention-secs: Int?,
    compact-after-secs: Int?,
    export-allowed: Bool?,
    forget-allowed: Bool?,
    metadata: Map?
}

Reusable retention policy shape for agent memory lifecycle jobs.

SynthesisInput alias of ::ai::agent::synthesis/SynthesisInput

SynthesisInput type {
    chat-opts: ::ai::chat/ChatOptions,
    system: Str,
    user-text: Str,
    fallback-text: Str?
}

Input for one synthesis call.

• chat-opts — the agent's chat options. system is replaced by the value passed in below; the rest (chat-fn, model, max-iterations, tools) flows through.
• system — the synthesis system prompt.
• user-text — the pre-baked body to send as the user message (typically the result of ::ai::rag/recent-text or recent-channel-text).
• fallback-text — when non-null, the LLM is skipped and this string is returned as the result. Use when the provider key is not wired.

SynthesisResult alias of ::ai::agent::synthesis/SynthesisResult

SynthesisResult type {
    ok: Bool,
    text: Str,
    error: Str?
}

Outcome of one synthesis call.

TransportCapabilities alias of ::ai::agent::transport/TransportCapabilities

TransportCapabilities type {
    name: Str,
    markup: Str?,
    supports-typing: Bool?,
    supports-deeplink: Bool?,
    supports-streaming: Bool?,
    max-message-size: Int?,
    reply-mode: Str?,
    meta: Map?
}

Capability description for a transport implementation.

markup is an application-level hint such as html, mrkdwn, plain, or json. reply-mode can describe whether the adapter posts, threads, returns a webhook response, or streams.