Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Cursor-managed agents as a third session transport
Status: implemented. This is the design as built; where the shipped code diverged from the original draft the text says so rather than describing a plan that no longer exists.
Goal
Let a user register their Cursor API key in Macro settings, then @cursor in any
channel and get an agent session that behaves like Macro Coder — same thread
announcement, same session page, same log — except the work runs on a Cursor
cloud agent instead of a sandbox we provision.
Second goal, which shapes the first: @cursor and @macro must work at the
same time, in the same deployment, in the same channel. This is the first time
the harness has had two live container providers rather than one chosen at boot.
What exists today
The pieces this builds on, so the design can be read against real code.
The transport seam
ContainerManager (crates/agent_harness/src/domain/ports.rs:49) is the port
every provider implements:
pub trait ContainerManager: Send + Sync + 'static {
type Transport: AgentConnector;
fn spawn(&self, command: SpawnContainer) -> impl Future<Output = Result<Self::Transport>> + Send;
fn resume(&self, session: AgentSessionId) -> impl Future<Output = Result<Self::Transport>> + Send;
fn teardown(&self, session: AgentSessionId) -> impl Future<Output = Result<()>> + Send;
}
AgentConnector is just Transport<ToRuntimeMessage, ToServerMessage>
(crates/agent_session/src/domain/ports.rs). And SidecarTransport
(crates/agent_harness/src/outbound/sidecar.rs) exists purely to wrap a raw ACP
JSON-RPC websocket into those envelopes — its own doc comment says the sidecar
"is a byte pipe: it speaks bare ACP JSON-RPC ... and knows nothing about the
runtime protocol."
The harness is already an ACP client and does not care what is on the other end of the pipe. That is the whole reason this project is small.
What the harness actually asks of an ACP agent
From the session actor (crates/agent_session/src/domain/session/session.rs):
initialize- one of
session/new,session/resume,session/load(SessionOpening, line 309) session/prompt- it answers
session/request_permission, auto-approving (line 421)
It never sends fs/read_text_file, fs/write_text_file, or any terminal/*
request. This matters: a Cursor cloud agent's filesystem lives inside Cursor's
VM and we only observe it through SSE tool-call events. If the harness needed
filesystem service from the agent side, this design would not work. It doesn't.
crates/cursor_acp
Already an ACP agent backed by the Cursor Cloud Agents API, written sans-io:
domain/service.rs—CursorSessionService, the use cases. One ACP session ↔ one Cursor agent, created lazily on first prompt (Cursor mints agent + first run together). Turns are strictly sequential per session, enforced withTurnAlreadyActive— which happens to match Cursor's own409 agent_busy.domain/ports.rs—CursorAgents,RunStream,SessionNotifier,RepoResolver.domain/translate.rs—TranslateMachine, SSE events → ACPSessionUpdate.cursor/— the HTTP/SSE client.CursorClient::newvalidates agrok_orcrsr_prefix.inbound/acp.rs— stdio JSON-RPC adapter. Handlesinitialize,authenticate,session/new,session/prompt.replay.rs+fixtures/real/*.sse+ insta snapshots — recorded real sessions pinned as tests.
The other providers
Daytona (outbound/daytona/manager.rs), namespace, and local
(outbound/local/, PR #5826) are mutually exclusive deployment choices. The
composition root picks exactly one. ContainerManager::Transport is a single
associated type, resolved once.
Product surface
1. Settings → Agents → Harness
A field to enter a Cursor API key. On submit we validate it before storing:
GET /v1/me with the key. A grok_- or crsr_-prefixed key that authenticates is stored;
anything else is rejected with a useful message rather than silently saved.
The stored record is per Macro user. Deleting it is supported and revokes
@cursor for that user.
2. @cursor in any channel
Behaves exactly like Macro Coder: mention it, a session opens, the bot posts the magic-chip announcement into the thread, the mention text becomes the first prompt, follow-up mentions in the thread route to the same session.
The enable-cursor-agents frontend rollout flag controls the built-in @cursor
mention (local override: VITE_ENABLE_CURSOR_AGENTS). Custom agents keep their
channel visibility rules. Within the rollout,
mentions are offered before key registration. A mention from someone with no
key must be answered, never silently dropped or turned into a session that
cannot spawn. The rollout flag is not a backend authorization boundary.
How the keyless mention is handled. Before open creates anything, the
domain asks ContainerManager::preflight(kind, owner). The Cursor manager
resolves the owner's configuration through CursorApiKeys::resolve: a missing
key yields SessionBlocker::CursorNotConnected, while read/decryption failures
remain errors. A successful preflight decrypts the key, and spawn resolves it
again. Codex and Claude perform the same account preflight; providers requiring no user connection take the default Ok(None).
On a blocker the domain calls SessionAnnouncer::decline with a
DeclinedMention and returns without a session row, an egress token, or an
announcement. MessageAnnouncer::decline posts as the bot with the sender's
current write access into the mention's
thread. The lexical service composes the explanation and connection chip from real Lexical nodes. The Cursor chip payload is
{"appSlug":"cursor","name":"Cursor","target":"harness"}. The frontend's
ConnectAppNode reads target: "harness" as "open Settings → Harness, and
show connected once this reader's own key status says so".
The original design hid @cursor until a key existed. That is why nobody
found it: discovery is the feature. Hiding was also never enforcement — a
mention can arrive from a copied message or another client — so the refusal
had to live in the harness regardless. The create composer keeps its own
Connect Cursor button for the same reason; it never posts anything.
CursorContainerManager::spawn still resolves the key and still fails with
HarnessError::CursorNotConnected when it is gone: sessions opened from the
create menu, and rows written before the preflight existed, reach it.
Settings needs its own small surface regardless, for the connections tab:
GET /me/cursor-key → { registered: bool }, PUT to set, DELETE to revoke.
The GET never returns key material.
3. Repo hardcoded for the first pass; model chosen per session
Repo: hardcoded to https://github.com/macro-inc/macro. Deliberately
temporary. agent_session.repo_url is TEXT NOT NULL, so a session must name
one, and picking it properly means either a settings field or the rate-limited
GET /v1/repositories. Neither belongs in a first pass. Put it behind a single
named constant — CURSOR_DEFAULT_REPO in the harness config — so replacing it
is one edit and grep finds every use.
The known limitation: this only works for a user whose Cursor GitHub App
installation can see macro-inc/macro. For anyone else, agent creation fails at
the Cursor API. That failure needs to surface as a legible session error
("Cursor cannot access this repository") rather than a generic 400, because it
will be the most common first-run failure.
Model: chosen per session, over ACP. Absent, Cursor resolves user default →
team default → system default, and that stays the default: it respects whatever
the user already chose in their own Cursor settings. But it is no longer the only
option — the session advertises the account's models as an ACP model config
option and accepts session/set_config_option at any time.
Two API facts this rests on, both established by probing rather than from the docs, which are wrong about the first:
POST /v1/agents/{id}/runsacceptsmodel. Cursor's reference lists onlyprompt,modeandmcpServersfor follow-up runs and states that they inherit the agent's model. They do not have to: the field is validated and honoured there. The endpoint's schema is strict — an unknown key comes back asvalidation_errornaming the key — which is how the field was shown to exist rather than be silently ignored. The full accepted set isprompt,model,mode,mcpServers,envVars.- A selection is an id plus its params.
{"id": "grok-4.5"}is rejected withModel 'grok-4.5' does not match a known variant; the same id witheffort=high, fast=trueis accepted.GET /v1/modelsenumerates the accepted combinations asvariants, one flaggedisDefault.
So a mid-session model change needs no new agent and no second credential — it is
a field on the next run, reachable with the user's own scoped API key. There
is no agent-level model update: PATCH/PUT/POST on /v1/agents/{id} do not
exist.
One thing the API will not tell us: which model a run actually used. It is absent from the run record, the run list and the stream, so the advertised current value is our own record of what we last asked for.
CURSOR_MODEL still pins a starting model for the standalone binary, by id; its
params come from that model's default variant.
4. Agent sessions page
When a session has a joined external record, show a provider link with a logo —
for Cursor, https://cursor.com/agents/<agentId> (the API returns this as
agent.url, so we store it rather than reconstruct it).
Architecture
The transport: in-process ACP over a duplex pipe
CursorContainerManager::spawn does not create a container. It:
- Resolves the session owner's Cursor API key.
- Builds a
CursorClientfor that key. - Creates a
tokio::io::duplexpair. - Spawns
cursor_acp'sserveloop on one end, wired to aCursorSessionServiceover that client. - Wraps the other end in an envelope adapter and returns it as the
Transport.
The harness then speaks real ACP JSON-RPC down the pipe, exactly as it does to a
sidecar websocket. Every tested path in cursor_acp — dispatch, the service,
TranslateMachine, the replay fixtures — is reused unchanged.
Cost: one serialize/deserialize hop per frame, in-process. Worth it. The
alternative (an adapter calling CursorSessionService directly and synthesizing
frames) means reimplementing the request/response correlation that
inbound/acp.rs already does and has tests for.
The envelope adapter is a near-clone of SidecarTransport differing only in its
carrier — a duplex pipe instead of a WebSocketStream. Both should end up over
one generic AcpPipeTransport<Socket> rather than two copies; SidecarTransport
is already written against AsyncRead + AsyncWrite, so this is a small
generalization, not a rewrite.
Provider routing: the part with real blast radius
ContainerManager has one associated Transport type. Cursor coexists with
Daytona rather than replacing it, so the choice moves from boot-time to
per-session.
Introduce a routing manager in the composition root:
pub struct RoutedContainerManager<Sandbox> {
sandbox: Sandbox, // Daytona | local | namespace
cursor: CursorContainerManager,
}
pub enum RoutedTransport<Sandbox> {
Sandbox(Sandbox),
Cursor(CursorTransport),
}
RoutedTransport implements Transport<ToRuntimeMessage, ToServerMessage> by
delegating to whichever variant it holds; same for its Sender and Receiver.
Static dispatch, no dyn, both variants concrete and testable.
Routing key: the session's bot. spawn reads it from SpawnContainer, which
means SpawnContainer needs a bot_id — it currently carries only
session_id and repo_url (domain/model.rs:167). resume and teardown
take only an AgentSessionId, so they route by looking the session up in the
external-session registry: a session with a Cursor external record routes to
Cursor, anything else to the sandbox provider.
is_managed_bot stops being a single value
pub fn is_managed_bot(bot: BotId) -> bool {
bot == bot_id::MACRO_CODER_BOT_ID
}
Its own doc comment anticipates this: "This becomes a bot attribute the day
managed bots stop being a closed set of one." That day is now. Add
CURSOR_BOT_ID to bot_id and make this a set membership test. Promoting it to
a real bot column is a larger change; the set keeps this PR honest and small,
and the comment should be updated to say the set is now two rather than deleted.
Data model
external_agent_session
One row per agent session that is served by an external provider.
Note the existing table is agent_session, singular
(migrations/20260818220644_new_ai_agents.up.sql:8).
CREATE TABLE external_agent_session (
agent_session_id UUID PRIMARY KEY REFERENCES agent_session (id) ON DELETE CASCADE,
provider TEXT NOT NULL, -- 'cursor'
external_id TEXT NOT NULL, -- 'bc-<uuid>'
external_name TEXT, -- Cursor's derived agent name
external_url TEXT, -- agent.url, for the frontend link
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (provider, external_id)
);
Keyed by agent_session_id rather than a synthetic id: a session has at most
one external backing, so the join is 1:1 and the FK is the key. ON DELETE CASCADE means deleting a session cleans this up. UNIQUE (provider, external_id) stops two sessions from claiming the same Cursor agent.
This is why the mapping cannot be memory-only. Daytona's resume finds a
sandbox by label:
self.client.find_by_label(SESSION_LABEL, &session.to_string())
The Cursor API has no labels. GET /v1/agents returns id, name, status,
env, url, timestamps, latestRunId — nothing we can write a session id
into. There is no query that recovers AgentSessionId → CursorAgentId, so it
has to be persisted at spawn time or it is gone.
No external_session_meta column on agent_session. The table alone is the
record. A column would duplicate what the join already answers, and the frontend
condition ("joined external session is non-null") is a LEFT JOIN ... IS NOT NULL either way.
Cursor API keys
Two existing precedents in the repo, one generation apart:
mcp_servers.credentials(crates/mcp_client/src/outbound/pg_server_repo.rs) — AES-256-GCM under a single process-wideAesKeyfrom config. No AAD, no per-record key, no KMS. One key compromise reads every row, and without AAD a ciphertext is interchangeable between rows, so moving user A's blob into user B's row decrypts happily. Do not copy this.microsoft_oauth_grants(services/authentication_service/src/microsoft_token_cipher.rs, migration20260819123655) — KMS envelope encryption, per-record data key, AAD binding the ciphertext topurpose ‖ version ‖ user ‖ mailbox, the same tuple as KMS encryption context,Zeroizingplaintext, versioned scheme, deliberately opaque errors. This is the considered one.
Recommendation: direct KMS Encrypt/Decrypt, not the envelope. KMS handles
plaintexts up to 4 KB directly and a Cursor key is ~60 bytes, so the envelope's
benefits do not apply: we are not over 4 KB, we make one KMS round trip either
way, KMS manages its own nonces so there is no GCM nonce-reuse bound to dodge,
and CMK auto-rotation keeps old ciphertext readable so nothing gets re-encrypted.
We keep the three properties that matter — KMS gates every read, the encryption
context binds the row to its user and is enforced by KMS with a CloudTrail
record, and the root key never leaves KMS — with no hand-rolled AES at all.
The counter-argument is that the envelope is already written and tested. But
reusing it means extracting and generalizing 364 lines of pub(crate) security
code out of authentication_service into a shared crate, which is careful work.
Direct Encrypt is roughly 40 lines and no new schema columns.
CREATE TABLE cursor_api_key (
user_id TEXT PRIMARY KEY,
key_ciphertext BYTEA NOT NULL,
encryption_version SMALLINT NOT NULL,
kms_key_id TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT cursor_api_key_ciphertext_not_empty CHECK (octet_length(key_ciphertext) > 0),
CONSTRAINT cursor_api_key_version_positive CHECK (encryption_version > 0)
);
encryption_version is worth keeping even in the simple scheme: it is what lets
a later move to the envelope be additive rather than a rewrite.
Encryption context: { macro:purpose = "cursor-api-key", macro:encryption-version, macro:user-id }. Bind to the Macro user id only — not to any Cursor-side
identity, which changes if they swap Cursor accounts and would strand the row.
Use a separate KMS key from the Microsoft one. The deciding argument is IAM,
not rotation: reusing it means granting agent_harness_service decrypt on the
key that also protects everyone's mail refresh tokens. A separate key means a
compromised harness cannot reach mailbox credentials.
The real exposure is plaintext residency, not the table
The Microsoft pattern's Zeroizing discipline assumes short-lived plaintext. Our
usage breaks that assumption: the key is decrypted on every spawn and every
resume, and then lives in CursorConfig.api_key as a plain String for the
whole life of the session — hours, one copy per concurrent session, in a
long-lived process, eligible for any core dump.
Worse, CursorConfig originally derived Debug over a pub api_key: String,
and CursorClient derives Debug and holds one. A single
tracing::debug!(?config) would print a live user key into logs.
Done:
ApiKeyis a newtype with a hand-writtenDebugthat redacts, over aZeroizing<String>so the plaintext does not linger in freed memory when a session's client is dropped. The plaintext leaves only throughexpose(), which feeds the Basic-auth header and nothing else. Reads of the settings endpoint return{ registered, updatedAt }and nothing more.
Still open:
- Building the
Authorizationheader once at client construction and dropping the plaintext, rather than holding it for the session's lifetime.Zeroizingbounds the damage; it does not shorten the residency.
Revocation is not ours
If a user rotates their key at Cursor, our copy silently starts returning 401 mid-session. That needs a distinct "reconnect your Cursor account" state rather than a generic session failure. And deleting our row does not revoke anything at Cursor — the settings UI must say so rather than implying we have.
The alternative that was considered and rejected: sub-tokens
POST /v1/sub-tokens takes a team service-account key and mints 1-hour
user-scoped tokens by forUserEmail. The agent runs as that teammate, with
their attribution and repo access, and we store one org secret — exactly how
DAYTONA_API_KEY already works — and zero user secrets.
This is viable for v1 precisely because the repo is hardcoded to
macro-inc/macro: the only people who can productively use @cursor are those
whose Cursor GitHub App installation can see it, which is our Cursor team. BYO
keys only become necessary when we support arbitrary repos for people outside
it, which is out of scope.
Cost: tokens last an hour and cannot self-refresh, so they must be minted per API call rather than per session — a session outliving its token is the failure mode to design against.
Not taken. It deletes the secret-at-rest problem by deleting the property the feature is for: the agent would run as a service account acting for a teammate rather than as the teammate, and the repo scope would be Macro's rather than theirs. The per-user key is the whole point, so the residency discipline above is the cost of admission.
Lifecycle mapping
Durable Load History
Cursor restores through ACP session/load, not session/resume. The implementation
captures original prompts, complete SSE records, polling bodies, and local
lifecycle decisions before translating them. Loading uses the same processing
machine as live delivery and never executes a provider prompt or tool again.
Every replayed ACP frame is appended to agent_session_log, including repeated
conversation content. Only a matching, valid, successfully persisted load
response selects a new effective-history window, starting at that connection's
initialization. The selection is atomic with the response under the session's
ownership fence. The raw audit history is retained; the product log endpoint
reads the selected indexed range. Generic server and browser folds stage load
updates separately and replace visible history only on success. Failed or
incomplete loads preserve the committed conversation; resume does not replace it.
A run started on cursor.com while the session is idle is not recovery: the
background mirror journals it and publishes its frames as they arrive, exactly
as a Macro turn does, then checkpoints it. The fold opens a turn for the
cursor.com prompt and closes it on _session/turn_complete. Streaming is only
whole when the client already has everything journaled before the run, so the
mirror falls back to recovery while a prompt waits behind it (that prompt's
turn is already open on the client) or while anything journaled since the last
load was never sent.
Recovery uses this same load path. Cursor captures foreign or interrupted runs
into its native journal without publishing replacement conversation frames.
Its notifier enqueues a typed, host-local reload requirement; the pipe adapter
delivers that requirement before a queued prompt response. The session domain
waits for the current prompt response, queues subsequent commands, and initiates
initialize followed by standard session/load. Each successful load therefore
has its own durable initialization boundary. There is no agent-initiated client
request or separate history replacement protocol. The notification never waits
for load while holding Cursor's writer gate; the load reply remains serialized
with live writers through ReplayGuard.
The requirement is consumed internally, never persisted as a user-facing status.
Already-dispatched prompts may finish while reload is pending; subsequent commands
wait at the host's handshake gate. Recovery observed while a load reply is queued
causes another load before those commands are flushed. Standalone ACP clients
without the host channel continue serving prompts and expose captured history on
their next client-initiated load, without unsolicited replacement traffic.
One pending-reload bit suppresses further background capture until load completes,
without rejecting already-dispatched prompts. Recovery validates the journal before
requesting load; unavailable original prompts retain the old visible history rather
than demanding a replacement known to be incomplete.
Existing sessions without a complete native journal require provider-history hydration. If Cursor no longer exposes enough history to reconstruct the conversation, load must fail explicitly rather than select an incomplete replacement. Operators should account for this retention limitation before rollout. The delivered-run watermark remains separate from journal capture progress, and local journal sequence numbers are not remote SSE resume tokens.
The journal's atomic owner fence is not a second ownership authority. The
session service acquires the claim and binds that exact generation once through
activate_reserved and RuntimeAttachment::on_activate, which receives the typed
SessionClaim before actor startup. Container providers return attachments;
transport mapping preserves the callback and shared handshake. Physical
transports carry frames only. The journal never
claims ownership or refreshes its fence from a database read.
The browser forwards the effective-history snapshot and buffered/live durable
rows to Rust LogIngestion through WASM snapshot and push_rows. Ingestion
retains the snapshot IDs and inclusive (created_at, id) boundary, preserving
Postgres timestamp precision without a JavaScript timestamp comparator. It drops
only snapshot duplicates and excluded older rows, never distinct ACP replay
rows, and preserves live delivery order without a moving high-water mark.
The ID set stays bounded by snapshot size. FoldMachine remains append-only;
raw recording consumers retain the existing extend and push API.
Routing new commands away from a stale replica does not stop its existing work.
PgAgentSessionRepo::claim can take over when the old replica's heartbeat is
stale, without notifying its process. activate_reserved gives the actor a
fenced ACP log writer; the next rejected append stops that actor. run_session
then drops its transport, and the pipe pump closes asynchronously. Independently,
CursorContainerManager::serve_session awaits sync_foreign_runs inside its
timer branch: pipe cancellation is not polled again until that await finishes.
A provider response can therefore reach the native journal after takeover even
with no new command dispatched to the old replica.
PgCursorJournal::lock_owner checks the bound replica/generation while holding
the agent_session row lock through journal commit. Takeover updates that same
row: either the old append commits before takeover, or it fails after takeover.
The existing SessionClaim is a token, not a transaction-bound storage capability;
the existing fenced ACP writer only covers ACP log appends. Wrapping a simple
journal with a preflight ownership check would lose this atomicity. Retain the
small storage fence rather than introduce a new generic transaction wrapper.
Native SSE records contain only event name, original data, and provider ID. Scripted providers emit the same wire-shaped records through the production decoder; recorded fixtures retain their original payloads rather than being decoded and re-encoded as domain enums.
Most of the sandbox lifecycle is meaningless for Cursor. Stating what each port method degenerates to, so the small implementation does not read as an oversight:
| Port | Daytona | Cursor |
|---|---|---|
spawn |
create sandbox, ensure_ready.sh, port preview, ping, dial |
build client, spawn serve on a duplex pipe. The Cursor agent itself is not created until the first prompt — CursorSessionService is lazy by design |
resume |
find by label, start sandbox, re-run readiness, re-dial | read external_agent_session, build client, new pipe, session/load with the stored agent id. No boot, no readiness, effectively free |
teardown |
destroy sandbox | POST /v1/agents/{id}/archive, delete the row |
| idle reaping | stop sandboxes after IDLE_TIMEOUT to stop paying |
nothing. No sandbox to stop and no per-minute cost to us. ManagedContainers, IDLE_TIMEOUT, STOP_CONCURRENCY have no Cursor analogue |
Consequences worth being explicit about:
- Archive, not delete.
DELETE /v1/agents/{id}is irreversible and destroys the user's own work in their Cursor account. Archive is reversible and idempotent. Teardown of a Macro session should not vaporize a Cursor agent the user may still want; archive is the right default and delete should not be reachable from session teardown at all. - Cancel is terminal in Cursor, but ACP cancel just ends a turn.
cursor_acpalready handles this correctly: cancel the run, and the next prompt opens a new run on the same agent, so the conversation survives.
Changes needed in crates/cursor_acp
The crate is currently shaped for one process, one key, stdio. Four changes:
Generalize
serve. It readstokio::io::stdin()directly (inbound/acp.rs:190) and the service type is hardcoded toStdioNotifier(line 184). Make it generic overAsyncRead + AsyncWriteand over the notifier. The bin keeps passing stdio; the harness passes a duplex half.StdioWriter/StdioNotifierbecome a writer/notifier over anyAsyncWrite.Implement
session/loadand advertise it. Two separate bugs here, and without both,resumedoes not merely degrade — the session dies. See "Resume is the sharp edge" below.Report the created agent back out. The manager has to persist
external_id,external_name, andexternal_urlwhen the first prompt mints the agent — which happens inside the service, well afterspawnreturned. Needs an observer port, e.g.AgentCreated { agent_id, name, url }, that the manager implements by writing theexternal_agent_sessionrow.Configuration from arguments. The bin reads
CURSOR_API_KEY,CURSOR_REF, andCURSOR_MODELfrom environment configuration and leaves the repository unset. Hosted sessions supply configuration and repository selection through constructor arguments.
None of these change the domain or the fixtures. They are adapter-shaped.
Once generalized, src/bin/cursor_acp.rs becomes a thin example over the general
pieces: read env, build a CursorClient, wire the service to stdio, call the
generic serve. It stays a real working ACP agent for editor clients, but it
holds no logic the harness path does not also go through — nothing gets to be
"the stdio special case."
Resume is the sharp edge
Two independent gaps that only bite on the second prompt after a restart, so they will not show up in a first happy-path test.
The capability gate. begin_opening
(crates/agent_session/src/domain/session/session.rs:270) picks the opening
method from what the agent advertised at initialize:
Some(session_id) if restore.resume => self.build_resume_session_request(session_id),
Some(session_id) if restore.load => self.build_load_session_request(session_id),
Some(_) => { self.resume_unsupported(effects); return; } // <- session dies
None => self.build_new_session_request(),
cursor_acp's agent_capabilities() (inbound/acp.rs:188) is
AgentCapabilities::default().prompt_capabilities(…embedded_context(true)) —
it advertises neither session_capabilities.resume nor load_session. So
any session with a stored acp_session_id that gets resumed hits
resume_unsupported and dies. Advertising load_session is mandatory, not
optional polish.
Session-id rehydration. CursorSessionService::new_session mints ids from an
in-memory counter (cursor-acp-{n}, service.rs:96) and holds sessions in a
HashMap that starts empty in a fresh process. The harness, meanwhile, persists
that string as agent_session.acp_session_id and sends it back on
session/load. So after a restart the id the harness asks for cannot be found,
and the service has no database to look it up in — by design, it is sans-io.
The manager closes that loop. CursorContainerManager::resume:
- reads
external_agent_sessionfor the session'sexternal_id(bc-…) andagent_session.acp_session_id, - constructs the
CursorSessionServicepre-seeded with that(AcpSessionId → CursorAgentId)pair and the resolved repo, - then serves the pipe, so the incoming
session/loadfinds a live session already pointing at the right Cursor agent.
This wants a constructor like CursorSessionService::with_sessions(...) — or a
restore_session(id, agent) method the manager calls before serving. Either way
the service stays sans-io and the manager stays the only thing that touches
Postgres. Worth stating plainly because it is the one piece of the design that is
not obvious from either crate alone.
In-memory registry and boot reconciliation
On agent_harness_service boot, build the in-memory view of Cursor-backed
sessions and keep it current as sessions are created and torn down.
The important ordering point: the mapping is read from Postgres, not from
Cursor. external_agent_session is authoritative for
AgentSessionId → CursorAgentId, because Cursor cannot answer that question.
GET /v1/agents is useful for a second, different thing — liveness. So boot is:
- Load Cursor-backed sessions from
external_agent_session. - Optionally, per distinct API key,
GET /v1/agentsand mark rows whose agent is gone or archived, so a resume fails fast with a real message instead of a 404 mid-prompt.
Step 2 is a nice-to-have and has a cost: it is one paginated listing per
registered user key, and GET /v1/repositories is documented as very heavily
rate-limited (1/user/min) though /v1/agents is not called out that way. Start
without it; add it if stale rows turn out to bite.
Honest limitations
Things @cursor will not do that @macro does, worth knowing before they are
reported as bugs:
- Repo access is the user's, not ours. Cursor cloud agents reach GitHub through the Cursor GitHub App installation on the key owner's account. A repo our Daytona sandboxes can clone may be invisible to their Cursor agent.
- No MCP servers from our side.
inbound/acp.rsalready logs a warning and ignoresmcpServersonsession/new. The Cursor API does accept inline MCP definitions at create time, so this is a later possibility, not a wall. - Streaming can degrade, but a turn cannot lose its answer. Cursor's
stream endpoint refuses connects (
stream_unavailable, both as a 409 and as an in-stream error) for a second or two after a run is created, and can drop mid-run. The client reconnects through the head-of-stream refusals, and any later streaming failure falls back to pollingGET rununtil the run is terminal, delivering the final result text. What the fallback gives up is liveness and per-tool-call detail, never the outcome.Last-Event-IDresumption (picking a broken stream back up mid-run without losing detail) remains a follow-up. - Turns driven from cursor.com mirror into Macro within about a second. While a session's pipe is up, the manager polls the agent's runs once a second (Cursor's v1 API has no webhooks yet) and replays anything it did not drive itself through the run's own stream — the cursor.com prompt (quoted, attributed), thoughts, tool calls, and answer, at the same fidelity as a Macro-driven turn. Degradations, in order: a run whose stream has left the retention window mirrors as its recorded final text only; a restored session has no watermark and does not replay history it cannot tell from missed runs; and a mirror that lands after newer Macro messages appends late, because the log is append-only — with the 1s poll that inversion effectively requires the session's pipe to have been down.
- Idle pipes retire themselves, Daytona-reaper style. Five minutes without a frame in either direction closes the pipe, reclaiming its tasks and its poll; the session parks on a clean disconnect and the next prompt resumes it. A parked session mirrors nothing until then.
- A provisioning failure does not reach the thread. When spawn fails
after the session row exists, the session is marked disconnected and the
reason goes to a log. The most common cause — the mentioning user has no
Cursor key — no longer gets this far:
ContainerManager::preflightcatches it before the row andSessionAnnouncer::declineanswers in the thread. Other spawn failures (Cursor API down, a key that no longer decrypts) still end in a log rather than a reply. - One run at a time per agent. Cursor returns
409 agent_busy. Already matched by the service's sequential-turn rule, so this surfaces as a clean error rather than a race.
Suggested sequencing
cursor_acpadapter refactor — the four changes above. Self-contained, fully unit-testable, no harness or DB involvement. Fixtures keep passing.- Migrations + repos —
external_agent_session,cursor_api_keys, the cipher, the key-resolver port.just prepare_db, tests against live Postgres. CursorContainerManager+ routing — the manager,RoutedTransport,bot_idonSpawnContainer,is_managed_botas a set, composition root.- Settings +
@cursorgating — the connections UI, key validation viaGET /v1/me, mention-autocomplete filtering (since replaced by the preflight-and-decline reply above). - Sessions page link — the joined read and the provider logo.
Steps 1 and 2 are independent and can go in parallel.
Testing
cursor_acp: existing replay fixtures must keep passing through the generalizedserve. Add a fixture exercisingsession/load.- Transport: drive the duplex pipe end-to-end against the in-memory
CursorAgents/RunStreamdoubles already intesting.rs— a fullinitialize→session/new→session/prompt→ updates round trip with no network. - Routing:
RoutedContainerManagersends a Cursor bot to the Cursor manager and anything else to the sandbox manager. Cheap, and it is the piece whose failure mode is worst. - Cipher: round-trip encrypt/decrypt, and a test asserting the plaintext key
does not appear in the
Debugoutput of the types that hold it. - Repos: standard live-Postgres tests. Include the
UNIQUE (provider, external_id)conflict and theON DELETE CASCADE.
Resolved questions
Resolved in review: the external table alone (no agent_session column), one
global seeded @cursor system bot, channel-bots server-side filtering for the
mention gate (later replaced by the in-thread decline, so @cursor is offered to
everyone), hardcoded macro-inc/macro repo, and omitted model.
Do we store user keys at all in v1? Yes. Sub-tokens were the alternative, and they lose the property that makes this feature legible: the agent runs as the user, on their own Cursor account, with their attribution and their repo access. There is no deployment-wide
CURSOR_API_KEY— the manager resolves the session owner's key fromcursor_api_keysat every spawn, resume, and teardown, and a user who has not connected Cursor gets the bot's connect reply in the channel rather than a silent skip.Lazy or eager agent creation? Lazy, as leaned.
RecordingCursordecoratesCursorAgentsand writes theexternal_agent_sessionrow insidecreate_agent, before it returns — so no prompt can be answered by an agent the database does not know about, and the laziness stays load-bearing in the service's own tests.IsResolved: yes, and it is a primary path.ContainerManager::resumeexercised today?domain/service.rscalls it whenever an action is sent to a session with nothing attached (AgentSessionError::Disconnected), gated on the bot being managed. So it fires on every follow-up mention after a service restart. The resume work — capability advertisement,session/load, service pre-seeding — is mandatory, not a follow-up. A@cursorsession that cannot resume is one that stops answering after any deploy.That gate is why
CURSOR_BOT_IDhad to join the managed set (nowAgentKind::is_managed): without it, a disconnected Cursor session takes the external-runtime branch and waits forever for an operator to dial in that will never come.