hot.dev/hot-ai / ::ai::stream-labels

Canonical data-type labels used across ::ai::* for ::hot::stream/data emissions. Centralizing the strings keeps consumers (dashboards, replays, logs) stable as new producers are added.

Convention

Labels follow <package>:<topic>:<verb>:

• <package> — top-level namespace identifying the producer (ai, hot, mcp, agent, …).
• <topic> — feature area (chat, tool, bundle, skill).
• <verb> — granularity (step, delta, usage, start, end, error).

Producers SHOULD prefer the constants exported here over string literals; consumers MAY match by prefix to bucket related events.

Currently emitted

• ai:chat:step — ::ai::chat/run-loop per-turn observability record (when opts.emit-steps: true).
• ai:chat:delta — ::ai::chat/run-loop-stream per-event mirror of the streaming ReplyDelta (when opts.emit-stream-deltas: true).

Reserved (future producers)

Reserve namespace prefixes here so adopters know what's safe to use without colliding with built-in producers:

• ai:tool:* — tool-call lifecycle (start/end/error).
• ai:rag:* — RAG pipeline events (retrieve/score/answer).
• ai:skill:* — skill activation lifecycle.
• ai:agent:* — higher-level agent orchestration events.
• mcp:* — MCP server activity.

Values

AGENT_END

AGENT_END: Str "ai:agent:end"

Reserved: stream label for agent run end events. Payload SHOULD include {agent-id, result, usage, duration-ms}.

AGENT_START

AGENT_START: Str "ai:agent:start"

Reserved: stream label for agent run start events. Payload SHOULD include {agent-id, model, opts}.

CHAT_DELTA

CHAT_DELTA: Str "ai:chat:delta"

Stream label for ::ai::chat/run-loop-stream per-event mirrors of the streaming ReplyDelta enum. Payload is a ReplyDelta variant.

CHAT_STEP

CHAT_STEP: Str "ai:chat:step"

Stream label for ::ai::chat/run-loop per-turn step records. Payload shape: {iteration, model, text, tool-calls, tool-results, stop-reason, usage}.

CHAT_USAGE

CHAT_USAGE: Str "ai:chat:usage"

Stream label for normalized provider usage and cost events. Payload is a ::ai::chat/ChatUsage value: {input-tokens, output-tokens, total-tokens, cost-usd, latency-ms, provider, model}. Adapters SHOULD emit this after each chat call so observers (dashboards, rate limiters, cost guards) can react without parsing provider-specific shapes.

RAG_ANSWER

RAG_ANSWER: Str "ai:rag:answer"

Reserved: stream label for RAG final-answer events. Payload SHOULD include {query, answer, sources}.

RAG_COMPACTION_END

RAG_COMPACTION_END: Str "ai:rag:compaction:end"

Stream label for RAG/memory compaction completion events. Payload SHOULD include {agent-name, capsule-id, source-count}.

RAG_COMPACTION_ERROR

RAG_COMPACTION_ERROR: Str "ai:rag:compaction:error"

Stream label for RAG/memory compaction failures. Payload SHOULD include {agent-name, session-id, error}.

RAG_COMPACTION_START

RAG_COMPACTION_START: Str "ai:rag:compaction:start"

Stream label for RAG/memory compaction start events. Payload SHOULD include {agent-name, session-id, window}.

RAG_RETRIEVE

RAG_RETRIEVE: Str "ai:rag:retrieve"

Reserved: stream label for RAG retrieval events. Payload SHOULD include {query, results, scores}.

SKILL_ACTIVATE

SKILL_ACTIVATE: Str "ai:skill:activate"

Reserved: stream label for skill activation events. Payload SHOULD include {name, when-matched}.

TOOL_END

TOOL_END: Str "ai:tool:end"

Reserved: stream label for tool-call lifecycle end events. Payload SHOULD include {id, name, output, duration-ms}.

TOOL_ERROR

TOOL_ERROR: Str "ai:tool:error"

Reserved: stream label for tool-call lifecycle error events. Payload SHOULD include {id, name, error}.

TOOL_START

TOOL_START: Str "ai:tool:start"

Reserved: stream label for tool-call lifecycle start events. Payload SHOULD include {id, name, input}.