Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

8.7 KB
Raw Blame

Agent session activity projection

agent_session.turn_state is a list projection of the authoritative ACP fold. The live writer commits each changed state with its log frame under the session's ownership fence. Streamed tokens do not trigger repeated projection writes.

Apply migrations before deploying the writer. For sessions created before the projection existed, run the bounded backfill against the intended MacroDB:

cargo build -p agent_session --features cli --bin backfill_turn_states
target/debug/backfill_turn_states --database-url "$DATABASE_URL" --limit 100

Repeat the second command until it reports examined=0. Each invocation folds at most 100 session histories. It uses the same fold as the live writer and initializes only missing projections, checking the latest log cursor while holding the session lock. A concurrent append or projection causes that session to be skipped; rerunning is safe. It does not change logs or session timestamps.

Runtime working branches

agent_session.working_branch stores the branch a provider actually reports for the session's configured repository. It is independent of repo_branch, which is only the selected starting branch, and of whether a pull request exists. Changing the configured repository clears the working branch. Writes check the owner, repository, and active runtime claim; changed facts invalidate list rows. Malformed or unrelated provider git metadata is ignored without blocking the session's transcript or history replay.

Deploy the additive agent_session_working_branch migration before the agent harness and document storage services. The harness persists the provider facts; document storage returns them in the existing Soup workingBranch field. Deploy both backend services before relying on that field in a frontend preview.

Cursor terminal result events supply the pushed branch, including when no PR was opened. Replaying a saved Cursor native journal restores historical branch facts when that journal contains them. Sessions without such a result remain unknown until the provider reports one; loading the list does not launch an agent. Other harnesses do not currently publish authoritative working branch facts. Soup retains the last captured linked-PR branch as a fallback for those sessions and older rows only while its captured repository matches the session's current one; it never substitutes the starting branch.

Initialization and first streamed text latency

On each invoke_agent span, the session actor records independent millisecond measurements from sending ACP session/prompt:

  • macro.genai.turn.time_to_first_text_ms: first non-whitespace agent message text; excludes reasoning, tool calls, and empty chunks.
  • macro.genai.turn.time_to_first_reasoning_ms: first non-whitespace thought.
  • macro.genai.turn.time_to_first_tool_call_ms: first tool call.
  • macro.genai.turn.time_to_first_output_ms: the existing combined metric, which also counts thought/tool events and is not answer-text latency.

Each milestone is recorded once per turn, regardless of content-capture policy. Turns without text have no text-latency measurement, rather than a zero. A correlated agent first output milestone log emits immediately with output_kind and elapsed_ms, so a turn need not finish before it is observable. These are server-observed timings, not browser render measurements, and they exclude work before the prompt reaches the runtime.

For that preceding work, inspect agent.init.* spans in the harness: admission, preferences, egress, persistence, publishing, runtime creation, permissions, and attachment. agent.init.acp spans measure actual request-to-response time for initialize, session/new, session/load, and session/resume, with rpc.method, agent.session.id, and outcome (success/error/stopped). Runtime attachment alone is not a readiness measurement.

The in-memory connector exposes agent.mcp.initialize and agent.mcp.list_tools durations per server, alongside the aggregate connector pooled, dialed, failed, and elapsed_ms fields. Servers initialize in parallel: compare the critical path, not the sum of their durations. In-memory prompt spans also split agent.turn.lock_wait_ms, agent.turn.admission_wait_ms, and agent.turn.first_text_ms; their legacy ttft_ms can include reasoning or a tool call, but excludes usage and tool-result events.

A turn that ended without an answer

In-memory prompt spans record what the turn said: agent.turn.stop_reason (end_turn, cancelled, error), agent.turn.text_chars, agent.turn.tool_calls, and agent.turn.replied, which is false when no text followed the last tool call. Such a turn also logs the turn ended without a reply after its last tool call; query @agent.turn.replied:false to find them. Then read the turn's last chat_streaming span: gen_ai.response.finish_reasons carries the provider's own stop reason (end_turn, refusal, max_tokens, max_output_tokens, SAFETY, ...), which Rig does not record for streamed calls. Each execute_tool span carries macro.genai.tool.result_bytes, whatever the content policy, so a result large enough to crowd the context shows there.

From the send click to the first painted text

The web app's agent.prompt span (service web-app) covers one prompt end to end. Every harness request made inside it carries its traceparent, so the harness's request, redis.process, invoke_agent and chat_streaming spans join the same trace. Its *_at_ms attributes are milliseconds from the send:

Stage Attribute Where
New session created, loaded, configured agent.prompt.created_at_ms, loaded_at_ms, configured_at_ms browser
Prompt accepted, including dispatch to the runtime: the control POST answered, or the create for a first prompt that rode on it agent.prompt.accepted_at_ms browser
session/prompt → first model chunk, per call macro.genai.chat.time_to_first_chunk_ms on chat_streaming harness
session/prompt → first text at the session actor macro.genai.turn.time_to_first_text_ms on invoke_agent harness
First agent output of any kind folded agent.prompt.first_output_at_ms browser
First-text frame stored → received (gateway fan-out) agent.prompt.first_text_delivery_ms, with agent.prompt.first_text_via (socket, or snapshot when a refetch caught what the socket missed) browser
Received → folded agent.prompt.first_text_fold_ms browser
First text folded agent.prompt.first_text_at_ms browser
First text painted agent.prompt.first_text_paint_at_ms browser

agent.prompt.outcome says how the span ended: text, no_text (reasoning or tool calls only), no_output, failed, released, or stalled (five minutes). A hidden tab never paints, so it ends at the first text with agent.prompt.hidden. The delivery stage compares the server's clock with the browser's, so read it as a distribution. A turn that calls tools before answering spends that time between the first model chunk and the first text: macro.genai.chat.first_chunk_kind says what each call streamed first.

To investigate a slow first session in Datadog, correlate by agent.session.id, compare cold and pooled connects separately, and report sample counts and p50/p95 for initialization and first text by harness/model. Include the fraction of turns with no text rather than silently counting them as fast answers. None of these new fields supplies historical measurements before its deployment.

Home and Agents can prepare an unprompted session through POST /agent-sessions/warm. It stays hidden until normal creation claims the same id for the same owner, bot, model and instructions. Reusing the session also reuses its egress token, which is part of the MCP pool key; creating and immediately deleting a throwaway session would release those cached clients. The warm response waits for ACP initialization and the shared MCP listing, so background initialization is finished before a ready reservation is offered. No model invocation or tool execution occurs during warming.

The browser consumes a result once within five minutes. Unclaimed rows expire after ten minutes and are deleted through the managing replica. Each replica keeps at most 64 outstanding warm reservations, with at most two per user. Reservations age out after ten minutes; claims and expiry handled by the preparing replica free its capacity sooner. The MCP pool holds at most 256 entries, evicts entries idle for ten minutes, and limits handshakes to 16 concurrent attempts with a 30-second timeout. agent.session.warm and agent.session.warm_hit on the open span distinguish preparation, successful reuse and ordinary creation for latency comparisons.