fix(telemetry_public): add server_time + full envelope to match tool convention

[klappy]

The gap

telemetry_public was the sole oddkit tool returning a bare {action, result} envelope. Every other tool — including telemetry_policy after PR #108 — returns the full {action, result, server_time, assistant_text, debug} shape.

Caught during the v0.21.0 regression test sweep on 2026-04-20.

Canon reference

• klappy://docs/appendices/epoch-8-2 — "server_time in every response"
• PR fix(telemetry_policy): canary completeness + knowledge_base rename + live smoke #108 — the envelope-conformance precedent for telemetry_policy

This PR makes reality conform to canon; no new principle is introduced.

What changed

• workers/src/index.ts: telemetry_public handler now emits the full envelope on both the success path and the not-configured error path. startTime captured at the top of the handler; debug.duration_ms derived from it. result.generated_at preserved unchanged (in-result timestamp orthogonal to envelope server_time).
• workers/test/canon-tool-envelope.smoke.mjs: added a telemetry_public assertion via the existing expectFullEnvelope helper.

Verification

• npm run typecheck clean
• Smoke test coverage added; awaiting CF preview deploy for full live verification

Release-validation-gate

Do not merge until:

1. Cursor Bugbot reaches completed (not just in_progress)
2. Independent Sonnet 4.6 validator reviews via Managed Agents

This is an envelope-behavior change; the validator applies.

---

Note

Medium Risk
Medium risk because it changes the telemetry_public tool’s response contract (adds server_time, assistant_text, and debug), which may affect any consumers that assumed the prior minimal envelope shape.

Overview
telemetry_public now returns the standard full tool envelope on both success and “not configured” error paths, including server_time, a derived assistant_text (with row-count/error hints), and debug.duration_ms computed from a per-request startTime.

The live smoke test (canon-tool-envelope.smoke.mjs) is extended to call telemetry_public and assert full-envelope conformance via the existing expectFullEnvelope helper.

^{Reviewed by Cursor Bugbot for commit a024e88. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	oddkit	a024e88	Commit Preview URL Branch Preview URL	Apr 20 2026, 12:10 PM

[klappy]

🔍 Independent Sonnet 4.6 validator — release-validation-gate

Per klappy://canon/constraints/release-validation-gate (tier 1): this PR touches envelope behavior, so an independent validator in fresh context was dispatched.

Agent: claude-sonnet-4-6 via Managed Agents
Read-only: no commits, no pushes, no file modifications
Context: fresh session, no prior knowledge of implementer session

---

I have everything I need. Here is the complete validation report.

---

VALIDATION REPORT — PR #124

Verdict: PASS_WITH_NOTES

---

Check-by-check

#	Check	Status	Evidence
1	Both return paths emit all 5 envelope fields: action, result, server_time, assistant_text, debug	✅	Not-configured path: index.ts:458–464. Success path: index.ts:505–510. Both confirmed in diff.
2	server_time is a fresh new Date().toISOString() — not reused from startTime	✅	Each return path calls new Date().toISOString() inline. startTime is Date.now() (integer), never used as server_time. Lines 462, 507.
3	debug.duration_ms is Date.now() - startTime	✅	startTime = Date.now() at line 452. Both paths use Date.now() - startTime. Lines 463, 509.
4	assistant_text is a non-empty string	✅	Not-configured path: hardcoded non-empty literal (line 462). Success path: assistantText initialized to "Telemetry query completed." (line 493), always overwritten with non-empty string.
5	result.generated_at preserved on success path	✅	Line 506: result: { data: result, generated_at: new Date().toISOString() }. Not flagged as duplication — orthogonal to top-level server_time.
6	Envelope shape matches telemetry_policy pattern	✅	Same five-field order (action, result, server_time, assistant_text, debug) and same field types. telemetry_policy adds debug.knowledge_base_url (line 601) which is absent from telemetry_public — correct, since telemetry_public takes no knowledge_base_url param.
7	Inner try/catch error flows through OUTER success-path envelope (no second return inside catch)	✅	catch block at line 486 sets result = { error: "..." } and falls through. No early return. The single success-path return at line 503 emits the full envelope.
8	assistant_text derivation does not crash when result is an error object	✅	Lines 494–501: if ('error' in result) branch fires → assistantText = "Telemetry query completed with errors.". Type guards prevent crash. Does not attempt .data access on error.
9	No nested try/catch swallows server_time assignment	✅	The inner try/catch (lines 477–487) only touches result. server_time is computed at return time, outside the catch.
10	Smoke test block exists using expectFullEnvelope; SQL is harmless	✅	canon-tool-envelope.smoke.mjs:133–138. SQL: SELECT 1 AS probe FROM oddkit_telemetry WHERE timestamp > NOW() - INTERVAL '1' HOUR LIMIT 1 — read-only, 1-row limit, no mutations.
11	Exactly 2 files changed	✅	git diff --stat main..HEAD → workers/src/index.ts (+19 lines) and workers/test/canon-tool-envelope.smoke.mjs (+9/-1 lines). No others.
12	No version bumps in package.json, package-lock.json, or wrangler.toml	✅	git diff main..HEAD -- "*.json" wrangler.toml → empty output.
13	No changes to orchestrate.ts or telemetry.ts	✅	git diff main..HEAD -- workers/src/orchestrate.ts workers/src/telemetry.ts → empty output.
14	npm run typecheck exits clean	✅	tsc --noEmit exited with no errors, no warnings.

---

Findings

1. [LOW] Smoke test cannot exercise the not-configured error path

The claim states "both success and not-configured error paths" have the full envelope. The code assertion for both paths is correct. However, the smoke test (canon-tool-envelope.smoke.mjs:133–138) calls telemetry_public against the production URL (https://oddkit.klappy.dev/mcp), which is presumed to have CF_ACCOUNT_ID and CF_API_TOKEN configured. The expectFullEnvelope assertion therefore only exercises the success path at runtime. The not-configured envelope is code-correct but not smoke-tested by this PR.

This is not a blocking defect — the not-configured path is simple and verified by code inspection. But the PR claim slightly overstates smoke-test coverage. Flag for documentation honesty, not for merge-blocking.

2. [LOW / PRE-EXISTING] Error location inconsistency between the two error paths

Not-configured path surfaces error at result.error:

{ "result": { "error": "Telemetry queries not configured…" } }

Query-failure path (inner catch) surfaces error at result.data.error:

{ "result": { "data": { "error": "Query execution failed." }, "generated_at": "…" } }

A consumer parsing errors must check two different locations depending on failure type. This inconsistency is pre-existing — not introduced by this PR (the not-configured result.error shape was already present on main; the PR only added the missing envelope fields around it). Flagging for awareness; does not block this PR.

---

Recommendation

merge-to-main-safe

All 14 checks pass. Both findings are low-severity: finding #1 is a truthfulness note about coverage claims (not a code defect), and finding #2 is a pre-existing design inconsistency outside this PR's scope. The envelope implementation is correct on both return paths, typecheck is clean, scope is tight, and no forbidden files were touched.

---

_{Dispatched per release-validation-gate canon. Same-session smoke + self-calls do not satisfy; this is the independent verification.}