Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
agent_session
What it is
Part of agent sessions: the coding-agent session entity itself — lifecycle, control, sharing, and the Postgres/HTTP surface every agent-harness consumer talks to.
Start here
src/domain/service.rs+src/domain/ports.rs: the session service and its ports — the widest surface in the crate.src/domain/lifecycle.rs: create/resume/stop state machine.src/domain/model.rs: theAgentSessionentity shape.src/domain/turn_state.rs+src/domain/control.rs: per-turn state and the control-plane commands (used by held tool-call approvals).src/inbound/axum_router.rs: the HTTP surface.GET /{id}/logserves raw frames for the web client's wasm fold;GET /{id}/log/foldedserves the same fold run server-side for the SDK and agents.src/domain/read.rsandsrc/inbound/toolset/read_agent_session.rs: bounded, view-authorized conversation reads using the shared transcript fold.src/domain/updates.rs: owner-scoped blocked and stalled coding-session updates, capped to 25 sessions before folding their logs.src/outbound/postgres.rs: the session repository.src/outbound/broker_lifecycle_publisher.rs/broker_log_realtime.rs: Kafka publication of lifecycle and log events.
Scope
- Owns: session identity, lifecycle, sharing/audience, credentials, pull request links, and the Postgres/HTTP/Kafka adapters for all of that.
- Not here: container provisioning and runtime wiring →
agent_harness,agent_inmem; PR diff capture →agent_changes; the ACP wire format →agent_runtime_protocol.
Boundaries
- Depends on:
agent_runtime_protocol,agent_fold,jev,teams,macro_authorization. - Used by:
agent_harness,agent_inmem,agent_egress,agent_trigger,agent_changes,agent_session_realtime,ai_tools(coding-agent toolset),complete_graph,graphql_registered_work,webhook,search_service,soup_realtime, and the cloud-agent crates (cursor_cloud_agents,codex_cloud_agents).
Recipes
- Add a session field:
src/domain/model.rs→src/outbound/postgres.rs(migration + query) →src/inbound/axum_router.rs(DTO) if exposed over HTTP. - Add a lifecycle transition:
src/domain/lifecycle.rs→src/domain/service.rs→src/outbound/broker_lifecycle_publisher.rsif it should publish.
Tool contracts
src/inbound/toolset/: session reads, creation, lifecycle actions, and sharing. Mutations preserve acting-user identity and existing owner/edit receipts; internal controls accept only prompt/stop, never human approvals.link_taskreturns amentionchip to paste when naming the task.
Internal action recovery uses AgentSessionService::recorded_action, which reads
one durable log snapshot including pre-load frames. Keep this separate from the
effective history served to transcript readers: replayed prompts lose action IDs.
domain/notifications.rs owns durable typed system-event production and the
transaction-aware producer port. outbound/notifications.rs owns the outbox
queries and leased batches. Retain unreadable payloads for a delayed retry; a
previously bound action stays whole and returns its identity for runtime
reconciliation, even when this consumer cannot decode its input.
Fresh unreadable rows keep no action identity and do not block valid siblings.
Await rollback on empty or blocked claims so their session lock is released
before the next real prompt attempts to attach quiet events.
Discovery uses bounded cursor pages so callers can
advance past unavailable sessions. Quiet batches bind to the actual prompt action ID;
notification-only turns record PrompterKind::System and no human authority.
Never expose notification metadata through public session controls. Notification
sessions read original log frames across load boundaries to retain trusted event
provenance when runtimes echo their prompt history. Queue reads discard legacy
private-context entries; the migration bridge preserves their review outcomes
without restoring owner authority. Claim legacy actions with a conditional
update of only their matching prompter; recover acting identity from that
persisted prompter, never from an old wire actor or a newer user turn.
Archive state lives on agent_session: archived_by
(agent_session_archive_cause: user, pull_request_merged,
runtime_closed; NULL is active) and archived_at. A person archiving sets
user; restoring clears both. is_archived remains only while older replicas
roll out; a trigger mirrors it, and no code may read or write it.
Auto-archive (domain/auto_archive.rs, outbound/postgres/auto_archive.rs,
inbound/axum_router/auto_archive.rs): opt-in triggers (pull requests merged,
runtime deliberately closed). User defaults are columns on
user_agent_coding_preferences; per-session overrides are nullable
agent_session.auto_archive_on_* columns (NULL follows the owner).
auto_archive locks the row and archives only an idle session with no queued
prompts that does not answer a conversation, setting archived_by to the
trigger and auto_archived_at. auto_archived_at is never cleared, even on
restore, so a session auto-archives at most once. A session archives for pull
requests once every linked pull request is closed and at least one merged;
links with no github_pull_request row count as open.
Registered work (domain/work_registration.rs, outbound/postgres/work_registration.rs,
inbound/axum_router/work_registration.rs, inbound/work_registration_sweep.rs): any account
registers a session it can edit as its work; registering shares nothing, and readers see only
sessions they can view. Rows in work_registration end, never delete, and a later turn does
not bring one back. Finished pull requests end them from the pull request consumer regardless
of auto-archive preferences; every archive path ends them in its own transaction, so a new
archive path must call end_work_registrations_on_archive; the sweep ends idle and blocked
sessions and catches up on the rest, in one guarded statement that is safe across replicas.
WorkRegistrationRealtime wraps a session service's realtime so turn, rename, and archive
changes reach viewers of registered sessions as Soup patches
(soup_realtime::outbound::agent_sessions::SoupWorkRegistrationSignal); wrap any new
publisher of list-field changes. GraphQL is graphql_registered_work.
Followers: a session started from a thread (SessionPurpose::visibility, any
agent) is hidden. The harness calls add_follower beside set_turn_prompter
for a prompt typed into the session itself (QueuedEntry::direct_prompter: a
human prompt with no announce origin and no trigger context), recording an
agent_session_follower row; Soup lists hidden sessions for their followers.
Thread mentions, runtime-forwarded triggers, system and bot turns record
nothing. Following never grants access.
Session names: the first prompt names a session (set_name_if_default), and
after each turn that ends with a reply, domain/retitle.rs hands the
conversation digest to the namer. name_generation::ClassifiedRetitle asks Jev
whether the name stopped fitting (threshold 0.8) before Haiku proposes a new
one. Only names with agent_session.name_is_generated are retitled; a rename
through set_name clears it, so a name a person chose is never replaced.
Checks
cargo test -p agent_session(SQLX_OFFLINEunset).
Gotchas
What opened a session is an
agent_session_sourcerow, referenced byagent_session.source_idand written in the transaction that writes the session (outbound/postgres/source.rs). It holds references only, astrigger_context::TriggerOrigin. Null means unknown: a session older than this, an unclaimed warm session, or an older runtime. It describes a session;sourceandvisibilitydecide what happens to it, and a runtime's claim never sets them. Whoever can view a session reads its origin:AgentSessionResponse, the SDK'sAgentSession.origin(), andReadAgentSession.Where a session is shown is
agent_session.visibility(listed,unlisted,hidden), set at creation and changed later only by warm claims and the DM-context backfill (list_visibility.rs).hiddenreplaceslist_hidden. Never read or writelist_hidden: until a later migration drops it, theagent_session_hidden_synctrigger keeps it in step for replicas on older code, and it must keep sorting beforeagent_session_legacy_warm_write(triggers fire in name order).ReadAgentSessionbounds its response, not storage work: it folds the full effective history like the app. Raw log limits break replay and turn numbering; bounded reads need a persisted conversation projection or a fold-aware port.The row's fenced log writer and the Cursor projection both lock the session row
FOR UPDATE; never add a secondNOWAITlocker without checking both paths (see git history onsrc/domain/control.rs).modified_atis Agents/Home list recency. Bump it for user-visible work (moves_session_list: starting/running/stopping/blocked) and metadata the viewer asked to change. Do not bump it for claim, release, recovery, ACP session id, or system events (acp_ready,disconnected).
Related
Rules:
.agents/rules/rust/architecture.md,.agents/rules/rust/db.mdThe activity route requires session view access, including for rows affecting other entities; its optional invocation filter stays scoped to the session.