Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Chat crate
This crate owns AI chat models, persistence ports, service policy, and the HTTP and toolset adapters for chats and chat messages. The chat and message services also produce sanitized lifecycle and message events for successful chat mutations.
Chat event producer
The events below use schema version 1 and are published to the macro.chats
Kafka topic. Every record uses the subject chat's bare UUID string as its
Kafka key (for example, 3f6f8b0a-6f9f-4a3f-9c3a-2b1e5d4c7a90, without a
chat| prefix). The key is not part of the JSON envelope. Events for one chat
therefore use the same Kafka partition and retain per-chat ordering; ordering
between different chats is unspecified.
| Event name | Emitted after | Metadata |
|---|---|---|
chat.created |
ChatService::create and its project bookkeeping succeed; also emitted by the DCS streaming flow when sending a message implicitly creates a chat |
chat_id, owner, name, project_id |
chat.updated |
A chat PATCH (ChatService::patch) is persisted |
chat_id, actor_user_id, requested name, previous_project_id, requested project_id, share_permission_updated |
chat.deleted |
Soft deletion succeeds | chat_id, actor_user_id, project_id |
chat.permanently_deleted |
Permanent deletion succeeds | chat_id, actor_user_id, project_id |
chat.restored |
ChatService::revert_delete succeeds |
chat_id, actor_user_id, project_id |
chat.copied |
ChatService::copy_chat succeeds |
chat_id (the new copy), source_chat_id, owner, name |
chat.message_sent |
MessageService::create (user message) or MessageService::store (assistant message) persists the message |
chat_id, message_id, role, model, actor_user_id, attachment_count |
chat.message_deleted |
MessageService::delete permanently deletes the message |
chat_id, message_id |
Optional metadata is serialized as null. On chat.updated, name and
project_id describe the requested PATCH: null means the field was omitted,
and project_id: "" means the chat was removed from its project (mirroring
the PatchChatArgs semantics). previous_project_id is the project in the
pre-PATCH chat snapshot when known. share_permission_updated is true for
any sharePermission patch, including an explicit teamShareAccessLevel,
which only the chat's persisted owner may set (shared with the owner's team
through the canonical SharePermission.team_share_* state and an
entity_access team grant). On the deleted, permanently-deleted, and
restored events, actor_user_id is null for unauthenticated or internal
callers.
role on chat.message_sent is lowercase (user, assistant, or system)
and distinguishes user messages from assistant messages. actor_user_id is
the sender for user messages and null for assistant messages. chat.copied
is keyed by the new chat's id; chat.message_sent is keyed by the parent
chat's id. chat.message_deleted is also keyed by the parent chat's id, so
both message events preserve per-chat ordering.
Sanitization
Event payloads exclude message content and attachment content; the only
attachment-derived value is the attachment_count field on chat.message_sent.
Share-permission payloads are also excluded: a PATCH that changes share
permissions is represented only by the share_permission_updated: bool flag
on chat.updated.
owner and actor_user_id are Macro user IDs serialized as
macro|<email address>; they embed the owning or acting user's email and must
be treated as personal data. This matches identifiers already published on the
macro.documents and macro.teams topics.
Excluded flows and known gaps
Only the successful mutations in the table produce these events. Read/list
operations and tool-call mutations emit nothing. Message update operations
and tool events (for example chat.tool_called and chat.tool_rejected) are
not yet produced; they can be added later as new enum variants.
The AI auto-rename flow
(services/agent_harness_service/src/cognition/service/chat_renamer.rs) patches
via PgChatRepo directly and does not emit chat.updated.
Only the document cognition service (DCS) HTTP chat router, the DCS
stream-side implicit chat creation, and the DCS MessageServiceImpl publish
to Kafka. The ChatServiceImpl instances in mcp_service, memory, and
ai_tools agent contexts and in the DCS chat tool context use the
NoopMacroEventBroker default and do not publish.
This crate provides production only; it adds no chat-event consumer.
Delivery semantics and compatibility
Publication occurs after the relevant committed mutation and is fire-and-forget. The API does not wait for Kafka delivery, and a scheduling or publication failure is logged without rolling back or failing an otherwise successful request. There is no transaction, outbox, or retry coupling database persistence to publication. Delivery is therefore at-most-once relative to chat mutations: a committed mutation can have no corresponding event.
Consumers must tolerate unknown event_type values and unknown metadata
fields so new event variants and additive fields remain forward compatible.
Consumers should use schema_version when interpreting a known event; every
event in this contract currently uses version 1.
Rollout
Provision the macro.chats topic before or alongside deploying DCS: a
kafka-cluster stack redeploy picks up the regenerated
.github/kafka-cluster-topics.json. If the producer is deployed before the
topic is available, chat mutations still succeed, but events can be lost under
the at-most-once contract.