Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
agent_harness
What it is
Part of agent sessions: orchestrates sandboxed coding-agent sessions end to end — provisioning containers, speaking to each coding-agent runtime (Cursor, Codex), routing triggers to a session, and relaying ACP traffic between the sandbox and the rest of the product.
Start here
src/domain/service.rs+src/domain/ports.rs: the harness service and the ports every runtime/container provider implements.src/domain/model/coding_preferences/: workflows injected into coding sessions (create-tasks, open-pull-requests). Task mentions use the lexical<m-document-mention>chip.src/domain/codex.rs: per-runtime session setup.src/outbound/sidecar.rs+sidecar_pump.rs: the container sidecar transport that speaksagent_runtime_protocol.src/outbound/containers.rs/managed_containers.rs: container provisioning.src/outbound/cursor/manager.rs: compose Cursor sessions, including public prompt-image fetching through thecursor_cloud_agentsimage-fetcher port.src/domain/trigger_router.rs: routes an incoming trigger to a session.src/domain/runtime_closed.rs: the turn observer that hands a runtime's_session/closed(a deliberate close, never a disconnect) to auto-archive.src/inbound/kafka.rs: trigger ingestion.src/domain/mode_choice.rs+src/inbound/mode_choice.rs: the agent composer's Auto mode,POST /agent-mode-choice, which asks Clef Flash (jev) whether a prompt goes to a chat or a coding agent.
Scope
- Owns: session lifecycle orchestration, container provisioning, runtime selection, MCP/tool-approval wiring for sandboxed sessions.
- Not here: session state/persistence →
agent_session; credential stamping for sandbox egress →agent_egress; the ACP wire protocol →agent_runtime_protocol.
Boundaries
- Depends on:
agent_session,agent_egress,agent_runtime_protocol,agent_trigger,ai_billing,jev. - Used by:
agent_harness_service(its sole host).
Recipes
- Add a new runtime:
src/domain/<runtime>.rs(session setup) →src/outbound/<runtime>.rs(adapter) →src/domain/service.rs(dispatch) →src/inbound/capability_discovery.rsif it needs discovery. - Add a trigger source:
crates/agent_trigger(context) →src/domain/trigger_router.rs→src/inbound/kafka.rs.
External runtimes receive the session's configured MCP selection when binding,
including enabled owner connections and custom servers under OwnerConnections.
Under Selected, an overlaid app (pipedream_mcp mcp_overlays) the owner
authorized natively is advertised as that custom server instead of its slug;
an app connected that way also satisfies the app.connected resume check.
Use external_mcp_servers to preserve the host-reachable egress URL override.
External chat replies use domain/service/external_replies.rs and the
agent_external_replies journal. Macrod sends the triggering message ID as the
control action ID; the harness joins that completion to its authorized reply
origin, regardless of arrival order. Recovery reads terminal results from the
original durable action history when an observer callback was lost, including
turns hidden by a later session load, and retries message updates
without re-prompting. Keep deduplication inside the serialized command worker.
Remember successful announcements. After 24 hours, recover replies without a
persisted completion at most hourly, preserving late answers after lost callbacks.
Persisted completions bypass this backoff; direct completion handling is immediate.
External runtimes bind sessions lazily. On each dial RuntimeRegistry has the
connection run initialize (shared with every session through its handshake)
and ACP session/list, and AgentHarnessService::reattach_live_sessions runs
HarnessCommand::Reattach for the listed sessions bound to that harness,
restoring each (session/load or session/resume) without a prompt, then
dispatching whatever its durable queue still holds when no turn is running;
attached, archived and managed sessions are skipped. macrod's herdr-acp lists native
sessions whose Herdr agent still runs.
Durable system events use the agent_session outbox, distinct from the user
push notifications planned in domain/notifications.rs. The serialized session
worker drains waking batches after a turn; quiet batches join a real prompt.
Recovery reconciles the original action before rebinding/retrying, preserves
prompter authority, and waits for a running invocation instead of re-prompting.
Attach notifications before claiming the conversation journal, so a recovered
running batch leaves the next real message queued. Recovery retains one drain
future per session and waits at most two seconds per sweep; lease renewals and
other sessions continue after a slow drain or an individual renewal error.
Keep duplicate-completion suppression bounded to recent actions.
Advance the bounded discovery cursor even when a session is busy or unreachable;
wrap after its final page so those sessions cannot starve later ones.
Reconcile active leases against terminal log evidence too: an observer can miss a
completion during takeover. Previously bound quiet attempts reconcile before new
wakes; interrupted quiet batches return to the next real prompt.
Harness presence is per connection, because a runtime's redial can land on a
different replica than the socket it replaced, and a stalled replica can notice
that socket's end long after. RuntimeRegistry mints a RuntimeConnectionId per
dial and reports it to HarnessPresence; a close removes only its own row, and
each replica renews the leases of what it holds, so a crash reads offline within
the lease. To debug a harness in Datadog, search @harness:<id> for
@telemetry_event:(harness_runtime_connected OR harness_runtime_disconnected OR harness_runtime_lease_restored): each carries connection and replica, and a
disconnect's other_live_connections above 0 is a stale close that changed nothing.
Checks
cargo nextest run -p agent_harness --lib --test-threads=2(SQLX_OFFLINEunset). Use CI's process isolation for the full database-backed suite so each test has its own process and runtime.
Gotchas
- A session's first prompt carries static files from the mentioning message
and the rest of its thread (mention first, then root and replies), capped
at 8 and deduped by file id; follow-ups carry only their own files.
Background channel messages are not attached.
trigger_routerfills each context attachment'surlfromStaticFileLinks, and<m-agent-context>lists them per message; ACPresource_links are what vision models fetch. - Every composed prompt's
<m-agent-context>states<current_time>in the sender's (else owner's) primary calendar time zone, via theUserTimeZonesport, or UTC when unknown. Models have no other source for the date, so never drop it from a composition path.
Related
- Rules:
.agents/rules/rust/architecture.md,.agents/rules/rust/security.md