Skip to content

fix(skill): align telemetry dispatch and field name with server#44

Merged
lxcong merged 1 commit into
mainfrom
fix/skill-telemetry-dispatch-and-field-names
May 14, 2026
Merged

fix(skill): align telemetry dispatch and field name with server#44
lxcong merged 1 commit into
mainfrom
fix/skill-telemetry-dispatch-and-field-names

Conversation

@lxcong
Copy link
Copy Markdown
Contributor

@lxcong lxcong commented May 14, 2026

Summary

PR #31 wired skill-side telemetry through two paths that don't actually
connect, so zero usable events reach PostHog from a real LLM session.

  • Bug 1 (dispatch path): SKILL.md told the LLM
    execute_tool(name="agentkey_internal", params={...}), but
    agentkey_internal is registered as a separate top-level MCP tool in
    @agentkey/mcp ≥0.3.10. execute_tool's router only knows
    agentkey_search / scrape / social / crypto, so the call returned
    tool not found and SKILL.md's silent-fallback swallowed the error.

  • Bug 2 (field name): Body wrapped properties under props: {...}
    but internal/handler/telemetry_handler.go decodes
    Properties map[string]interface{} json:"properties". Mismatched tag
    → nil map → server substituted empty map → every business field
    stripped before reaching PostHog. Only posthog-go's auto-injected
    $lib / $os / $ip plus agent: "unknown" (from
    NormalizeAgent("")) survived.

Evidence

Direct call vs SKILL.md-shaped call, same distinct_id, minutes apart in
PostHog (project agentkey):

body field name PostHog record for upgrade_decision
properties: {...} from_version=1.5.0, to_version=1.6.0, choice=accept_once, agent=claude-code — all fields
props: {...} All None

Sink / auth / posthog-go batching / 24h dedupe all confirmed fine. Bug
surface is exactly the two items above.

Changes

SKILL.md only:

  • 6 dispatch sites: execute_tool(name="agentkey_internal", params={...})
    agentkey_internal({...})
  • Body field: propsproperties

No change to check-update.sh, MCP forwarder, or server. Skill-only is
the cheaper side to align: 1.6.0 just shipped and has no install base.

Agent attribution (server falling back to agent: "unknown") is left as
a follow-up — needs cross-client identification logic.

Test plan

  • bats tests/check-update.bats — 10/10 still passing
    (script-level TELEMETRY emission unchanged)
  • Manual end-to-end: directly invoke
    agentkey_internal({path: "telemetry/event", params: {event: "upgrade_decision", properties: {...}}})
    → confirmed all fields land in PostHog
  • Smoke after release: bump version, install fresh, trigger a real
    upgrade flow, verify PostHog receives populated skill_loaded /
    upgrade_decision / upgrade_result

🤖 Generated with Claude Code

…rver

PR #31 wired the skill-side telemetry through two paths that don't
connect, so zero usable events reached PostHog from a real LLM session:

1. SKILL.md instructed the LLM to call
   execute_tool(name="agentkey_internal", params={...}), but
   agentkey_internal is registered as a separate top-level MCP tool
   in @agentkey/mcp 0.3.10+ — not a route under execute_tool's
   router (which only knows agentkey_search / scrape / social /
   crypto). Calls returned "tool not found" and SKILL.md's
   silent-fallback swallowed the error.

2. The body wrapped properties under props: {...} but the server
   handler decodes Properties map[string]interface{} `json:"properties"`.
   Mismatched JSON tag → server saw a nil map and substituted an
   empty one, so the few events that did arrive had every business
   field stripped (only $lib/$os/$ip from posthog-go's auto-meta
   plus agent: "unknown" from NormalizeAgent("") survived).

End-to-end isolation test confirmed that calling agentkey_internal
directly with {event, properties: {...}} delivers all fields; the
SKILL.md-prescribed shape {event, props: {...}} drops them all —
sink, auth, dedupe all fine. Bug surface is exactly the two items
above.

Changes (skill-side only — 1.6.0 has no install base yet, easier to
align skill with server than ship a breaking server change):

- SKILL.md: all 6 dispatch sites use agentkey_internal({path, params})
  directly instead of going through execute_tool.
- SKILL.md: body field renamed props → properties to match the
  server handler's struct tag.

No change to check-update.sh, MCP forwarder, or server. Existing 10
bats tests in tests/check-update.bats still pass — they cover the
TELEMETRY-line emission, which is unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@lxcong lxcong merged commit 6e8e544 into main May 14, 2026
2 checks passed
@lxcong lxcong deleted the fix/skill-telemetry-dispatch-and-field-names branch May 14, 2026 09:17
lxcong added a commit that referenced this pull request May 14, 2026
## Why

PR #44 merged successfully (the SKILL.md telemetry fix is on `main`),
but release-please did not open a 1.6.1 release PR.

Looking at the workflow log of the post-merge run, the
conventional-commits
parser bailed on the squash-merge commit:

```
commit could not be parsed: 6e8e544 fix(skill): align telemetry dispatch and field name with server (#44)
error message: Error: unexpected token \n at 56:61, valid tokens [)]
commits: 0
No commits for path: ., skipping
```

GitHub's squash-merge took the full PR body (which contained inline code
fragments with `{}` and `()`) and wrapped one of them across a line
boundary. That left an unbalanced expression that the parser treats as a
hard error, dropping the whole commit from the release window.

Result: release-please saw zero parseable commits since v1.6.0 and
skipped opening a release PR.

## Fix

A single empty commit with a clean body so release-please re-runs with a
parseable commit chain. Code on `main` is unchanged; the diff is zero
files / zero lines.

## Test plan

- [x] Squash-merge body contains no inline code fragments with parens or
      braces — should parse cleanly.
- [ ] After merge, release-please workflow opens a `chore(main): release
      1.6.1` PR that includes the SKILL.md fix from #44.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
@lxcong lxcong mentioned this pull request May 14, 2026
lxcong added a commit that referenced this pull request May 14, 2026
🤖 I have created a release *beep* *boop*
---


##
[1.6.1](v1.6.0...v1.6.1)
(2026-05-14)


### Bug Fixes

* **skill:** re-trigger release-please after
[#44](#44) parse error
([#45](#45))
([3caa5c3](3caa5c3))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant