feat: treat OpenClaw as a first-class agent source

[bradcypert]

Closes DNO-959.

Split out of the original combined PR so the schema change can be rolled forward or back independently — see the sibling PRs below.

Why

OpenClaw sessions weren't treated as a real, named source: the agent-type filter didn't list OpenClaw as one surface, and prompt-to-response turn correlation skipped it.

What changed

• sourceAliases: an openclaw entry, so the agent-type filter lists it once rather than leaking raw casing variants as separate surfaces
• canonicalAgentTurnID: accept the openclaw adapter, plus the proxied agent-turn prefix for LiteLLM-routed OpenClaw turns

The issue gated turn correlation on OpenClaw's turn IDs being "proven stable." They are: ctx.runId is identical across before_agent_run, before_tool_call, llm_output and agent_end in the DNO-950 spike fixtures. If a future OpenClaw build breaks that, correlation degrades silently rather than erroring, so it's called out in the fixture README (speakeasy-api/agenthooks#24).

The dashboard display label (openclaw: "OpenClaw") already existed.

Related PRs

Independent of each other — all three branch from main, no stacking:

• mig: fold openclaw into the summary MV usage predicates #5932 — mig: the materialized-view change that makes OpenClaw count toward usage totals
• docs: OpenClaw customer install runbook + generated README section #5933 — docs: customer install runbook and the generated package README section

Testing

server/internal/hooks turn-correlation tests pass, including new cases for the direct and proxied OpenClaw turn IDs.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TiJy9DrFpsmnD2vEkDHKNv

[linear-code]

DNO-959

DNO-960

[changeset-bot]

🦋 Changeset detected

Latest commit: ed4fd87

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
server	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

Running ultrareview automatically — Hand-edited ClickHouse MV migrations change usage aggregation predicates across all agents — a missed bug could corrupt token/cost/tool-call summaries and billing data, so this warrants a deeper multi-pass review.. I'll post findings when complete.

[github-actions]

atlas migrate lint on server/migrations

Status	Step	Result
	No migration files detected
	ERD and visual diff generated	View Visualization
	No issues found	View Report
Read the full linting report on Atlas Cloud

[github-actions]

atlas migrate lint on server/clickhouse/migrations

Status	Step	Result
	1 new migration file detected	20260831204723_openclaw-usage-rows.sql
	ERD and visual diff generated	View Visualization
	No issues found	View Report
Read the full linting report on Atlas Cloud

[cubic-dev-ai]

Ultrareview completed in 18m 43s

1 issue found across 15 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="server/internal/hooks/ingest_hooks.go">

<violation number="1" location="server/internal/hooks/ingest_hooks.go:1635">
P1: When an embedded OpenClaw session is also observed through LiteLLM, this new correlation path leaves both assistant responses in the chat transcript. Mark correlated OpenClaw prompts as native and classify `openclaw` in `nativeAssistantTurnSource` so `proxiedTurnDuplicatesNativeStream` suppresses the proxy row.</violation>
</file>

Linked issue analysis

Linked issue: DNO-959: First-class source: alias, display label, turn correlation, usage rows

Status	Acceptance criteria	Notes
✅	OpenClaw appears once in the dashboard agent-type filter with the “OpenClaw” label	The PR adds the OpenClaw source alias, and the PR notes the display label already existed.
✅	OpenClaw is included in canonical turn correlation after stable turn IDs are proven	The whitelist accepts OpenClaw and tests cover both native and proxied turn IDs.
✅	OpenClaw usage rows populate usage dashboards when the generic usage path does not already cover them	Both materialized views and the mirrored session predicates admit OpenClaw per-turn usage and completed tool-call rows, with a migration applying the changes.
❌	Existing goldens are updated	The supplied diff shows new correlation tests and schema-sync coverage, but no golden-file updates or evidence of existing goldens being regenerated.

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: When an embedded OpenClaw session is also observed through LiteLLM, this new correlation path leaves both assistant responses in the chat transcript. Mark correlated OpenClaw prompts as native and classify openclaw in nativeAssistantTurnSource so proxiedTurnDuplicatesNativeStream suppresses the proxy row.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At server/internal/hooks/ingest_hooks.go, line 1635:

<comment>When an embedded OpenClaw session is also observed through LiteLLM, this new correlation path leaves both assistant responses in the chat transcript. Mark correlated OpenClaw prompts as native and classify `openclaw` in `nativeAssistantTurnSource` so `proxiedTurnDuplicatesNativeStream` suppresses the proxy row.</comment>

<file context>
@@ -1630,15 +1630,17 @@ func canonicalAgentTurnID(payload *gen.IngestPayload) string {
-	if adapter != "codex" && adapter != "opencode" && adapter != "litellm" {
+	// openclaw carries OpenClaw's own ctx.runId, which the spike proved stable
+	// across before_agent_run, before_tool_call, llm_output and agent_end.
+	if adapter != "codex" && adapter != "opencode" && adapter != "openclaw" && adapter != "litellm" {
 		return ""
 	}
</file context>