specs/001-openclaw-integration/research.md

Research: OpenClaw Integration

Feature: 001-openclaw-integration | Date: 2026-02-27

R-001: OpenClaw JSONL Transcript Format

Decision: The parser must handle the nested OpenClaw JSONL event format, not flat role/content events.

Rationale: Inspecting the sample transcript (b3db607f-...jsonl) reveals the format is significantly different from what the current parser assumes:

• Top-level fields: type, id, parentId, timestamp, and optionally message
• Event types: "session", "message", "thinking_level_change", "custom"
• Message structure: event["message"] contains role, content (array), api, provider, model, usage
• Content array items: Each has a type field — "text", "thinking", "toolCall", "toolResult"
  • Text: {"type": "text", "text": "..."}
  • Thinking: {"type": "thinking", "thinking": "...", "thinkingSignature": "reasoning_content"}
  • Tool call: {"type": "toolCall", "id": "...", "name": "...", "arguments": {...}}
  • Tool result: {"type": "toolResult", "toolCallId": "...", "content": [{"type": "text", "text": "..."}]}

Current parser bug: parse_session_jsonl() reads event.get("role") and event.get("content") at the top level. The actual data has event["message"]["role"] and event["message"]["content"] (an array, not a string). The current parser will always produce empty traces from real OpenClaw sessions.

Alternatives considered: None — must match the actual format.

R-002: Trace Dict Structure for TraceAnalyser

Decision: Keep the existing trace dict format {question, reasoning, answer, skill_ids, feedback, ground_truth} as TraceAnalyser accepts raw dicts placed on ctx.trace.

Rationale: TraceAnalyser uses raw traces — any dict type is accepted and placed on ctx.trace. The Reflector then reads ctx.trace (or falls back to ctx.agent_output). The trace dict keys should map cleanly to what Reflector's prompt template expects. Existing test patterns confirm this structure works.

Alternatives considered: Using AgentOutput dataclass — rejected because TraceAnalyser explicitly supports raw traces without wrapping.

R-003: Thinking Content Handling

Decision: Preserve thinking content in full — no truncation or filtering.

Rationale: Thinking traces are integral to how the OpenClaw agent works. They contain the richest reasoning data and provide essential context for the ACE learning pipeline to understand the agent's decision-making process. Truncation would lose critical information that the Reflector needs to extract meaningful strategies.

Clarification: User explicitly confirmed thinking traces must be preserved in full (see spec Clarifications 2026-02-27).

Alternatives rejected:

• Head+tail truncation (500/200 chars) — rejected per user requirement; loses critical reasoning context.
• Filtering thinking blocks entirely — rejected; removes the most valuable data for learning.

R-004: Tool Call/Result Pairing

Decision: Extract tool calls with their names and arguments from "toolCall" content items, and pair with results from subsequent "toolResult" events. Preserve all data in full — no truncation of arguments or results.

Rationale: Tool usage is a key signal for the Reflector. The JSONL format stores tool calls as content items within assistant messages, and tool results as separate content items (or messages) with matching toolCallId. Pairing them gives the Reflector a complete picture of what tools were used and what they returned.

Clarification: User explicitly confirmed tool arguments and results must be preserved in full (see spec Clarifications 2026-02-27).

Alternatives rejected: Ignoring tool calls — rejected because tool usage patterns are one of the most valuable things to learn from. Truncating tool results — rejected per user requirement.

R-005: Session Discovery Path

Decision: Discover sessions from ~/.openclaw/agents/<agent_id>/sessions/*.jsonl with the session directory structure matching the JSONL sample.

Rationale: The sample file's "session" event contains "cwd": "/app" and session metadata. OpenClaw stores sessions per-agent under the home directory. The OPENCLAW_AGENT_ID environment variable selects which agent's sessions to process.

Alternatives considered: Recursive glob for all agents — rejected for simplicity (Principle III). Users can run the script multiple times with different OPENCLAW_AGENT_ID values.

R-006: Skillbook Persistence Format

Decision: Use the existing Skillbook.save_to_file() / Skillbook.load_from_file() JSON format. No custom serialization needed.

Rationale: The skillbook JSON format is well-defined with fields: skills, sections, next_id, similarity_decisions. Each skill has id, section, content, justification, evidence, helpful/harmful/neutral, timestamps, and status. The existing API handles all serialization.

Alternatives considered: None — reusing existing infrastructure per Principle III.

R-007: AGENTS.md Sync Format

Decision: Use wrap_skillbook_context() from ace.integrations to format the skillbook content between HTML comment markers <!-- ACE:SKILLBOOK:START/END -->.

Rationale: wrap_skillbook_context() already produces a formatted string with skillbook strategies and usage instructions. The marker-based replacement pattern in sync_to_agents_md() is correct — preserves content outside markers, handles create/update cases.

Alternatives considered: Custom formatting — rejected because wrap_skillbook_context() already exists and produces the right format.

R-008: Error Handling Strategy

Decision: Graceful degradation — skip individual malformed sessions, report errors, continue processing.

Rationale: Constitution Principle I (Ease of Use) requires that a single bad file doesn't crash the entire run. FR-010 explicitly requires skipping malformed files gracefully. The current try/except pattern in parse_session_jsonl() handles JSONDecodeError correctly.

Alternatives considered: Strict mode that fails on first error — rejected as it violates FR-010 and Principle I.

R-009: Testing Strategy

Decision: Unit tests with MockLLMClient, using sample JSONL fixtures. No live LLM calls in tests.

Rationale: Existing test patterns in tests/ use MockLLMClient that returns canned ReflectorOutput and SkillManagerOutput. This allows testing the full flow (parse → analyse → save → sync) without API costs or flakiness. The sample JSONL file can serve as a test fixture.

Alternatives considered: Integration tests with real LLM — useful but should be @pytest.mark.slow and optional.