Session replay: OpenClaw mapper — ACP replay stream + subagent_runs + flow_runs + approvals audit

[vivekchand]

Context

OpenClaw has the richest on-disk trace of any runtime we support — a purpose-built acp_replay_events stream (ACP = Agent Client Protocol), plus normalized subagent_runs + flow_runs + task_runs + command_log_entries tables. We ignore all of it and render the flat JSONL.

Substrate

• State DB (orchestration truth): ~/.openclaw/state/openclaw.sqlite
• Transcripts: ~/.openclaw/agents/<alias>/sessions/*.jsonl — v3 envelope {"type":"message","message":{...},"id","parentId","timestamp"} — parentId is a chain, not a tree (reference_openclaw_v3_parentid_is_chain.md)

Sub-agent model

First-class. Table subagent_runs with run_id, child_session_key, controller_session_key, requester_session_key, task, task_name, model, workspace_dir, spawn_mode, outcome_json. This is a REAL parent→child graph — the chain-not-tree warning only applies to the transcript, not to spawn relationships.

Workflow model

Table flow_runs — flow_id, shape, sync_mode, controller_id, status, goal, current_step, blocked_task_id, state_json, wait_json. Steps land in task_runs with parent_flow_id, parent_task_id, agent_id, requester_agent_id, delivery_status, notify_policy. A genuine DAG with a controller.

Replay-native stream: acp_replay_events(session_id, seq, at, update_json) + acp_replay_sessions — literally designed for step-by-step replay. Use it directly instead of reconstructing from the JSONL.

Mode + approvals

• Mode config: exec_approvals_config(default_security, default_ask, default_ask_fallback, auto_allow_skills). default_ask=never + auto_allow_skills=1 = auto. Per-agent overrides in agent_count / allowlist_count.
• Approval audit trail: command_log_entries(action, session_key, sender_id, entry_json) — the exec-side decisions. Plugin capability approvals in plugin_binding_approvals (per-plugin per-channel).
• User reply: in command_log_entries.entry_json and in the ACP replay update stream. NeMo Guardrails approval queue writes its own rows (project_runtime_scoped_alerts_approvals.md).

Deliverable

Implement iter_replay_events(session_id) → Iterator[ReplayEvent] for OpenClaw. Read the SQLite in mode=ro immutable=0 (daemon may be writing).

Output per the canonical schema (OSS-01):

• Primary source: acp_replay_events.update_json — this is the pre-normalized event stream. Map its update_type values to canonical kind.
• Enrich with joins to subagent_runs (for agent.spawn / agent.return), flow_runs + task_runs (for workflow.*), command_log_entries (for approval.decided), exec_approvals_config (for mode.changed — session-scoped, one at start).
• Fall back to JSONL parse if acp_replay_sessions has no row for a session_id (older sessions).

Acceptance

• 3 fixtures replay:
  1. A session with a subagent_runs fanout ≥3 children (delegations render inline)
  2. A flow_runs session with ≥5 task_runs steps (workflow swimlane renders with controller + step status)
  3. A session with an exec_approvals_config that denied ≥1 tool call (approvals rail shows the denied entries with command_log_entries.entry_json as decision_reason)
• Mode chip shows correct value from exec_approvals_config + per-agent override count in tooltip
• plugin_binding_approvals rows render as approvals with resolver=policy

Depends on

• OSS-01 (schema)
• OSS-02 (mode + approvals ingest + UI wiring)

Gotchas

• Do not treat transcript parentId as a tree. Use subagent_runs for delegation, parentId only for message ordering within a session.
• Two approvals systems (reference_approvals_architecture.md) — exec (command_log_entries) and plugin capability (plugin_binding_approvals). Both must land in the approvals rail with different resolver values so the UI can distinguish.
• Daemon writes to openclaw.sqlite continuously — every read opens mode=ro, never grab a writer lock.

References

• OSS substrate: clawmetry/sync.py OpenClaw ingest branch (grep ~/.openclaw in sync.py)
• ACP replay is currently unused — grep acp_replay in this repo returns zero — this issue lights it up
• Approvals arch memory: reference_approvals_architecture.md

[vivekchand]

Hi @vivekchand! Took a careful look at the OpenClaw replay mapper spec. Here's the plan:

The problem
ClawMetry ignores OpenClaw's rich acp_replay_events stream and sub-agent graphs entirely, coercing everything into a flat JSONL render — so sub-agent fanouts, workflow DAGs, mode changes, and tool-call approval decisions are all invisible in the replay UI even though OpenClaw records them natively.

Approach

1. clawmetry/sync.py near line 10622 — new function _sync_replay_events_openclaw(config, state, store) (~180 LOC), modeled on the existing _sync_cron_runs_from_state_sqlite pattern (same sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=5) idiom, same state["oc_replay_last_seq"] cursor for incremental ingestion). Core loop: fetch new rows from acp_replay_events WHERE rowid > last_rowid ORDER BY rowid, parse update_json, map update_type → canonical kind (see mapping table below), then enrich with:

   • LEFT JOIN subagent_runs on controller_session_key = session_id to emit agent.spawn / agent.return events with real parent_span_id delegation edges
   • One-shot query to exec_approvals_config (per session, at start) → one mode.changed event with permission = default_ask and sandbox = default_security
   • command_log_entries WHERE session_key = ? for approval.decided rows, mapped via the resolver logic in reference_approvals_architecture.md
   • LEFT JOIN flow_runs + task_runs on parent_flow_id to emit workflow.start / workflow.stage / workflow.end events with the controller span as parent
   • Fall back to JSONL parse (KIND_LLM_CALL / KIND_LLM_RESPONSE) for sessions with no acp_replay_sessions row

2. clawmetry/local_store.py near line 8033 — add upsert_replay_events(rows: list[dict]) -> int (~30 LOC) as the write counterpart to query_replay_events. Uses INSERT OR REPLACE INTO replay_events(span_id, parent_span_id, session_id, runtime, kind, ts, payload, mode, approval, created_at) VALUES (...) with executemany for batch efficiency.

3. clawmetry/sync.py — call site — wire _sync_replay_events_openclaw into the main daemon loop at the same cadence as the cron-runs sync (grep _sync_cron_runs_from_state_sqlite for the exact hook point).

Proposed update_type → kind mapping (needs validation against a real openclaw.sqlite)

update_type (assumed)	canonical kind
model_request / llm_call	llm.call
model_response / llm_response	llm.response
tool_call / tool_invoke	tool.call
tool_result / tool_output	tool.result
agent_spawn / subagent_start	agent.spawn
agent_return / subagent_end	agent.return
thinking / reasoning	thinking
compaction / context_compression	compaction

This is the biggest unknown — the actual update_type strings inside acp_replay_events.update_json aren't documented in the issue or surfaced by grep acp_replay in the repo. They need to be confirmed against a real instance before the mapper ships.

Test plan

• 3 acceptance fixtures from the issue body: (1) ≥3-child subagent_runs fanout → delegations render inline; (2) ≥5-step flow_runs → workflow swimlane with controller + step status; (3) exec_approvals_config that denied ≥1 tool call → approvals rail with command_log_entries.entry_json as decision_reason
• Unit test for upsert_replay_events + query_replay_events round-trip against an in-memory DuckDB (same pattern as existing tests/test_local_store_*.py)
• acp_replay_sessions absence guard: verify the JSONL fallback path returns non-empty events for an older session with no ACP rows

Estimated change
~210 lines across 2 files (clawmetry/sync.py +180, clawmetry/local_store.py +30).

This one's bigger than I'm comfortable autonomously shipping: the update_type enum values are undocumented — shipping a mapper with incorrect type strings would silently drop every event into an unrecognised-kind bucket, giving the appearance of working while the replay tree stays empty. That's worse than no mapper. Leaving the plan here; if you can share even a short excerpt of real acp_replay_events.update_json rows (or point at the ACP spec), I can fill in the mapping table and proceed. Or if you'd like me to implement the scaffold now with TODOs for the mapping strings, comment bot-go and I'll pick it up next run.

---

Generated by Claude Code

[vivekchand]

Re-verified against origin/main (4c192fe, 2026-09-12). Still not implemented — leaving open.

• git grep -n "acp_replay" origin/main -- clawmetry/ routes/ returns zero hits. The acp_replay_events stream this issue asks to consume is still completely unused.
• clawmetry/local_store.py has the replay_events table (:1775) and the reader query_replay_events (:14911), but there is no upsert_replay_events writer anywhere in the file — git grep -n "upsert_replay_events" origin/main matches nothing.
• clawmetry/sync.py has sync_openclaw_subagent_runs (:13542) which mirrors subagent_runs/flow_runs into the existing registry snapshot (_build_flow_runs_snapshot, :17978), but there is no _sync_replay_events_openclaw or any function that maps ACP/subagent/flow data into canonical ReplayEvent rows.
• No iter_replay_events implementation exists for OpenClaw (git grep -n "iter_replay_events" only matches doc comments/placeholders in local_store.py, app.js, trace_capture.py, trace_viewer.py, routes/sessions.py, routes/tracing.py — none of them an actual OpenClaw mapper).

This matches the prior plan-only comment from 2026-08-16, which correctly identified the update_type mapping as unvalidated and asked for bot-go. No further progress has landed since. Leaving open, no state change.

---

Generated by Claude Code