MATTERMOST_OPENCLAW_LIVESTATUS/discoveries/README.md

Discovery Findings: Live Status v4

Overview

Planner sub-agent (proj035-planner) conducted inline discovery before drafting the plan. Key findings are documented here.

Discovery 1: JSONL Transcript Format

Confirmed format (JSONL, version 3):

Each line is a JSON object with type field:

• session — First line only. Contains id (UUID), version: 3, cwd
• model_change — provider, modelId change events
• thinking_level_change — thinking on/off
• custom — Subtypes: model-snapshot, openclaw.cache-ttl (turn boundary marker)
• message — Main event type. role = user, assistant, or toolResult

Message content types:

• {type: "text", text: "..."} — plain text from any role
• {type: "toolCall", id, name, arguments: {...}} — tool invocations in assistant messages
• {type: "thinking", thinking: "..."} — internal reasoning (thinking mode)

Assistant messages carry extra fields: api, provider, model, usage, stopReason, timestamp

ToolResult messages carry: toolCallId, toolName, isError, content: [{type, text}]

Key signals for watcher:

• stopReason: "stop" + no new lines → agent turn complete → idle
• stopReason: "toolUse" → agent waiting for tool results → NOT idle
• custom.customType: "openclaw.cache-ttl" → turn boundary marker

Discovery 2: Session Keying

Session keys in sessions.json follow the pattern: agent:{agentId}:{context}

Examples:

• agent:main:main — direct session
• agent:main:mattermost:channel:{channelId} — channel session
• agent:main:mattermost:channel:{channelId}:thread:{threadId} — thread session
• agent:main:subagent:{uuid} — SUB-AGENT SESSION (has spawnedBy, spawnDepth, label)
• agent:main:hook:gitea:{repo}:issue:{n} — hook-triggered session
• agent:main:cron:{name} — cron session

Sub-agent entry fields relevant to watcher:

• sessionId — maps to {sessionId}.jsonl filename
• spawnedBy — parent session key (for nesting)
• spawnDepth — nesting depth (1 = direct child of main)
• label — human-readable name (e.g., "proj035-planner")
• channel — delivery channel (mattermost, etc.)

Sessions files: /home/node/.openclaw/agents/{agentId}/sessions/

• sessions.json — registry (updated on every message)
• {uuid}.jsonl — transcript files
• {uuid}-topic-{topicId}.jsonl — topic-scoped transcripts

Discovery 3: OpenClaw Hook Events

Available internal hook events (confirmed from source):

• command:new, command:reset, command:stop — user commands
• command — all commands
• agent:bootstrap — before workspace files injected
• gateway:startup — gateway startup (250ms after channels start)

NO session:start or session:end hooks exist. The hooks system covers commands and gateway lifecycle only, NOT individual agent runs.

Sub-agent lifecycle hooks (subagent_spawned, subagent_ended) are channel plugin hooks, not internal hooks — not directly usable from workspace hooks.

Hook handler files: workspace hooks support handler.ts OR handler.js (both discovered automatically via handlerCandidates in workspace.ts).

Discovery 4: Mattermost API

• PostEditTimeLimit = -1 — unlimited edits on this server
• Bot token: n73636eit7bg3rgmpsj693mwno (default/main bot account)
• Multiple bot accounts available per agent (see openclaw.json accounts)
• API base: https://slack.solio.tech/api/v4
• Post update: PUT /api/v4/posts/{id} — no time limit, no count limit

Discovery 5: Current v1 Failure Modes

• Agents call live-status create/update/complete manually
• deploy-to-agents.sh injects verbose 200-word protocol into AGENTS.md
• Agents forget to call it (no enforcement mechanism)
• IDs get lost between tool calls (no persistent state)
• No sub-agent visibility (sub-agents have separate sessions)
• Thread sessions create separate OpenClaw sessions → IDs not shared
• Final response dumps multiple status updates (spam from forgotten updates)

Discovery 6: Repo State

• Workspace copy: /home/node/.openclaw/workspace/projects/openclaw-live-status/
  • src/live-status.js — 283 lines, v2 CLI with --agent, --channel, --reply-to, create/update/complete/delete
  • deploy-to-agents.sh — AGENTS.md injection approach
  • skill/SKILL.md — manual usage instructions
  • src/agent-accounts.json — agent→bot account mapping
• Remote repo (ROOH/MATTERMOST_OPENCLAW_LIVESTATUS): src/live-status.js is outdated (114 lines v1)
• Makefile with check/test/lint/fmt targets already exists in remote repo

Synthesis

The transcript-tailing daemon approach is sound and the format is stable. The key implementation insight is: watch sessions.json to discover new sessions, then watch each JSONL file for that session. Sub-agents are automatically discoverable via spawnedBy fields. The hook system can auto-start the daemon on gateway startup via gateway:startup event. No new OpenClaw core changes are needed.