mig: fold openclaw into the summary MV usage predicates - #5932
Merged
Conversation
Contributor
🦋 Changeset detectedLatest commit: 27501ef The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
Contributor
|
Running ultrareview automatically — This migration rewires both usage materialized views and the matching Go predicates to include OpenClaw rows — any predicate mismatch risks silently dropping or double-counting usage data across summaries, so a deep multi-pass review is warranted.. I'll post findings when complete. |
This was referenced Sep 1, 2026
Contributor
|
|
||||||||||||||||
Contributor
|
|
||||||||||||||||
This comment has been minimized.
This comment has been minimized.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Ultrareview completed in 7m 9s
All reported issues were addressed across 9 files
Reply with feedback, questions, or to request a fix.
Fix all with cubic | Re-trigger cubic
Thegreatsura
pushed a commit
to Thegreatsura/gram
that referenced
this pull request
Sep 2, 2026
…peakeasy-api#5933) Closes DNO-960. Split from speakeasy-api#5929 so nothing here shares a rollback fate with the schema change. ## Why We ship an OpenClaw observability package but never told anyone how to install it. The generated ZIP README had sections for Claude Code, Cursor, Codex and OpenCode, and nothing for OpenClaw. There was also no runbook for the two things that silently break an OpenClaw install — both of which produce a *partly* working state rather than an obvious failure, which is the worst kind. ## What changed - **Generated package README**: an OpenClaw install section — the directory install, `--force` when replacing, the required `allowConversationAccess` block, the Gateway restart, and the coverage caveat - **`docs/runbooks/openclaw-install.md`**: laptop and server/CI install paths, verification, enforcement semantics, version-pin policy, and the operational gotchas from the DNO-950 spike - **`docs/plugins/overview.md`**: OpenClaw listed alongside the other observability packages and in the `downloadObservabilityPlugin` enum ## The two traps the runbook exists for 1. **`allowConversationAccess`.** Without it the conversation hooks silently never fire — no prompts, no assistant responses, no usage — while tool hooks keep working. A half-configured install looks partly fine. 2. **The harness split.** When a model routes through the Claude CLI harness (`agentRuntime: claude-cli`, which `openclaw models auth login` writes *by default* when a claude-cli profile exists), OpenClaw delegates the model and tool loop out-of-process and its tool/LLM hooks never fire. Those sessions are still covered — by our Claude Code hooks — so this is complementary coverage rather than a hole, but a customer in that mode will otherwise think the integration is broken. ## Notes - `generate.go` is a server implementation file, but the change is purely the customer-facing install text, so it belongs with the runbook rather than the feature PR. - No `hooksGeneratorVersion` bump needed: the README is not part of the rendered hook-plugin subtree that `check-generator-versions` diffs. Confirmed by rendering `export-hook-plugin -published` and checking the file list. - The runbook records that our fixtures were captured from OpenClaw 2026.6.34 while 2026.7.1-2 is what installs today, and documents the qualification procedure for that gap. The fixture-side half is speakeasy-api/agenthooks#24. - Deliberately no nightly canary against OpenClaw `latest`: it would page on OpenClaw's release cadence and registry flakes without telling us what we actually support — the same reasoning that keeps the LiteLLM real-proxy suite on `workflow_dispatch`. ## Related PRs Independent — all three branch from `main`, no stacking: - speakeasy-api#5929 — `feat:` source alias and turn correlation - speakeasy-api#5932 — `mig:` the materialized-view change 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01TiJy9DrFpsmnD2vEkDHKNv <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Adds OpenClaw install docs for the observability plugin — the generated ZIP README now has an OpenClaw section, and a new runbook covers laptop and server/CI installs. Two configuration states silently break coverage without any error, and both are now documented. - The README's OpenClaw section is generated only when a hooks API key exists, so it never describes files that aren't in the ZIP. - The runbook details the two traps: missing `allowConversationAccess` drops prompt and usage capture while tool hooks keep working, and the Claude CLI harness routes sessions through Claude Code hooks, which capture them only if those hooks are also deployed on the machine. - Documents how coverage depends on model-auth mode, the enforcement timeout budgets, the version-pin qualification procedure, and that the hooks binary is fetched from the org's Gram server rather than GitHub. - Adds an OpenClaw package-format section in `docs/plugins/package-format.md`, and lists OpenClaw in `docs/plugins/overview.md`, the `downloadObservabilityPlugin` enum, and the observability slug table in `docs/plugins/publishing.md`. - Closes DNO-960. <sup>Written for commit 024520e. Summary will update on new commits.</sup> <a href="https://cubic.dev/pr/speakeasy-api/gram/pull/5933?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
bradcypert
force-pushed
the
brad/dno-959-openclaw-mv-migration
branch
from
September 2, 2026 18:49
c96aec3 to
f28d669
Compare
danielkov
approved these changes
Sep 2, 2026
Both summary MVs gate counting on a hook-source allowlist that named Codex, Cursor and OpenCode but not OpenClaw, so OpenClaw rows were ingested and then skipped by every token, cost and tool-call aggregate. Atlas generates DROP VIEW + CREATE for an MV SELECT change, which leaves a window where telemetry_logs inserts bypass the aggregates and are lost from the summaries permanently. Hand-edited to ALTER ... MODIFY QUERY in both flavors, mirroring 20260727130626_opencode-usage-rows and 20260803192750_litellm-usage-in-summaries. The file header records the two decisions review kept re-raising: no backfill, and the pair not being atomic. The repo-layer session predicates move with the schema: the schema-sync test pins them against schema.sql in both directions, so they cannot be split from the MV definition without failing on both sides. Regenerated on top of main rather than rebased: 20260902165930 meta-mcp-attribution landed with a later timestamp than the previous migration, so a rebase would have left this one out of order. Its telemetry_logs and trace_summaries changes are untouched here, and the MV SELECTs were re-derived from main's current schema.sql rather than carried over, so the meta_mcp_server_id work is preserved. Verified against the ClickHouse image CI pins: the chain replays clean with meta-mcp-attribution applying first, both MVs come back carrying openclaw, meta_mcp_server_id survives, and a follow-up diff reports the directory synced with schema.sql. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TiJy9DrFpsmnD2vEkDHKNv
bradcypert
force-pushed
the
brad/dno-959-openclaw-mv-migration
branch
from
September 2, 2026 19:41
f28d669 to
27501ef
Compare
bradcypert
enabled auto-merge
September 2, 2026 19:50
![https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source](https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source){kind=link}
![https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img](https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img){kind=link}
![https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a](https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a){kind=link}
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of DNO-959. Split from #5929 so the schema change rolls forward and back on its own.
Why
Both summary materialized views gate counting on a hook-source allowlist that named Codex, Cursor and OpenCode but not OpenClaw. OpenClaw rows were ingested and then silently skipped by every token, cost and tool-call aggregate — no error, nothing in the logs, just sessions that showed up with nothing behind them.
The bit worth reviewing
Atlas generated
DROP VIEW+CREATE MATERIALIZED VIEWfor both MVs. Shipping that would open a window wheretelemetry_logsinserts bypass the aggregates and are lost from the summaries permanently.Hand-edited to
ALTER … MODIFY QUERYin both flavors, mirroring20260727130626_opencode-usage-rowsand20260803192750_litellm-usage-in-summaries, which carry the same note for the same reason.is_opencode_usage_rowis renamed tois_hook_turn_usage_row, since the predicate now covers two adapters.Why repo-layer Go is in a migration PR
server/internal/telemetry/repo/sessions.gomirrors these predicates for the rawListSessionspath, andsessions_schema_sync_test.gopins the two copies againstschema.sqlin both directions. Splitting them from the MV definition fails the test on both sides, so they have to move together. The migration-mixing check allows this: its filter excludesserver/internal/**/repo/**.I also added the per-turn usage fragment to that test's pinned list, which was previously unpinned.
Verification
Against the ClickHouse image CI pins (
26.2.19.43, same digest):20260831204729/u openclaw-usage-rowsopenclawdown 1cleanly restores the previous definitionsclickhouse:diffreports the migration directory synced withschema.sqlReviewer notes
Related PRs
Independent — all three branch from
main, no stacking:feat:source alias and turn correlationdocs:customer install runbook🤖 Generated with Claude Code
https://claude.ai/code/session_01TiJy9DrFpsmnD2vEkDHKNv
Summary by cubic
Implements DNO-959 by updating both summary materialized views to count OpenClaw per-turn usage and completed tool calls. OpenClaw rows were previously ingested but excluded by hook-source allowlists; they now contribute from deployment onward, without backfilling existing rows, and cost remains $0 because the payload has no dollar value.
Migration
ALTER ... MODIFY QUERYto avoid dropping either materialized view during deployment.is_hook_turn_usage_rowand keeps the Go session path and schema-sync test aligned.Written for commit 27501ef. Summary will update on new commits.