Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
cursor_cloud_agents
What it is
Part of agent sessions: an ACP agent backed by Cursor cloud agents — one
ACP session is one Cursor agent, one session/prompt is one Cursor
run, and the run's SSE stream is translated into ACP session/update
notifications as it arrives.
Start here
src/lib.rs: the hexagonal layout (domain/api/inbound/outbound) — read this doc comment first, it's the map.src/domain/translate.rs: the Cursor→ACP event translation state machine (TranslateMachine), mirroringagent_fold'sFoldMachine.src/domain/service.rs: ties a prompt to a run.src/domain/prompt_image.rs+src/outbound/http_prompt_images.rs: convert pasted public raster-image links and ACP images into Cursor prompt images.src/api.rs(src/api/): the Cursor cloud REST + SSE client.src/inbound/acp.rs: newline-delimited JSON-RPC ACP adapter (stdio or in-process duplex pipe).src/outbound/postgres_journal.rs: the hosted session journal (Postgres);src/outbound/memory_journal.rsfor standalone/tests.REPLAY.md: the native journal, recovery, and migration-rollout contract — read before touchingdomain/journal.rsoroutbound/postgres_journal.rs.
Scope
- Owns: the Cursor REST/SSE client, the Cursor event→ACP translation, the ACP
JSON-RPC adapter, and (behind the default
postgresfeature) the hosted session journal. - Not here: the per-user Cursor API key and its encryption →
crates/cursor_api_key.
Boundaries
- Depends on:
cursor_api_key(indirectly, via callers),agent_session(postgresfeature),agent_runtime_protocol,static_file_service_client. - Used by:
agent_harness,authentication_service,agent_harness_service.
Recipes
- Handle a new Cursor SSE event kind:
src/domain/event.rs→src/domain/translate.rs→ add a fixture underfixtures/→ the snapshot tests insrc/replay/test.rs/src/inbound/acp/test.rs. - Add a Cursor REST call:
src/api.rs→ its submodule undersrc/api/→ the matchingdomain::portstrait. - Change journal recovery/replay behavior: read
REPLAY.mdfirst, thensrc/domain/journal.rs→src/outbound/postgres_journal.rs→src/replay.rs.
Checks
cargo test -p cursor_cloud_agents(SQLX_OFFLINEunset; default features includepostgres).cargo test -p cursor_cloud_agents --no-default-featuresfor the in-memory path only.
Gotchas
Prompt image resolution preserves the prompt text, tries up to eight unique links within a ten-second budget, and sends at most five images of 15 MiB each. HTTP resolution disables proxies, validates literal addresses and connection-time DNS answers, and checks each redirect. Stop cancels resolution and journals the prompt as aborted without creating remote work. Fetch failures leave links as text; never log link URLs or image bytes. Images are journaled as ACP image blocks for live display and replay.
REPLAY.md's migration-rollout section documents a one-time consolidation of four old migrations into20260906060601_cursor_session_replay; don't reset or DOWN-migrate a database that already has journal history without reading it first.#![deny(missing_docs)]applies to every public item.- Translation is a pure state machine fed one event at a time — keep new
logic in
domain/translate.rs, not inapi.rsorinbound/acp.rs.
Related
- Rules:
.agents/rules/rust/architecture.md,.agents/rules/rust/db.md