happyskills 0.53.0 → 0.54.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.54.0] - 2026-05-26
+
+### Added
+
+- **`intent_id` is now attached to every `/telemetry/discovery` beacon payload** (spec 260521-03 addendum § 4 — CLI half of Phase A). The CLI sources the value from the active intent envelope via a new `get_intent_id()` helper in `cli/src/utils/intent.js`, which decodes the envelope's base64url payload portion and extracts `intent_id`. Sent on all four beacon types fired from `search` and `postlex`: `rerank_started`, `rerank_completed`, `clarify_triggered`, `clarify_completed`. When no envelope is active the payload includes `intent_id: null`. Before this change, every `search.rerank` and `search.clarify` row in `analytics.events` landed with `intent_id = NULL`, defeating the addendum's goal of correlating beacons with the discovery chain.
+
 ## [0.53.0] - 2026-05-25
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.53.0",
+	"version": "0.54.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/commands/postlex.js

@@ -15,6 +15,7 @@ const { exit_with_error, UsageError, CliError } = require('../utils/errors')
 const { EXIT_CODES } = require('../constants')
 const { slug_token_set, compute_lex_tier } = require('../utils/slug_tokens')
 const { fire_discovery_telemetry } = require('../api/telemetry')
+const { get_intent_id } = require('../utils/intent')
 
 const HELP_TEXT = `Usage: happyskills postlex --query <q> --ranking <file|-> [options]
 
@@ -425,9 +426,13 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 	const next_step = determine_next_step(final_ordering, query, clarification_turns_used)
 
 	// Fire telemetry — rerank_completed first (the rerank step succeeded);
-	// clarify_triggered separately if applicable.
+	// clarify_triggered separately if applicable. `intent_id` is sourced from
+	// the active intent envelope so these beacons correlate with the same
+	// discovery chain (spec 260521-03 addendum § 4).
+	const intent_id = get_intent_id()
 	fire_discovery_telemetry({
 		event:                       'rerank_completed',
+		intent_id,
 		query,
 		promoted,
 		promoted_from_rank,
@@ -436,6 +441,7 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 	if (next_step.action === 'clarify') {
 		fire_discovery_telemetry({
 			event:        'clarify_triggered',
+			intent_id,
 			query,
 			reason:       'post_rerank_weak',
 			turn_number:  clarification_turns_used + 1,

package/src/commands/search.js

@@ -6,6 +6,7 @@ const { exit_with_error, UsageError, AuthError } = require('../utils/errors')
 const { EXIT_CODES, VALID_SKILL_TYPES } = require('../constants')
 const { load_token } = require('../auth/token_store')
 const { fire_discovery_telemetry } = require('../api/telemetry')
+const { get_intent_id } = require('../utils/intent')
 
 const HELP_TEXT = `Usage: happyskills search [query] [options]
 
@@ -221,9 +222,14 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 	const next_step = build_search_next_step(response, query, { with_rerank, clarification_turns_used })
 
 	// Telemetry beacons (fire-and-forget). Spec § 5.1 + § 5.3.
+	// `intent_id` is sourced from the active intent envelope (spec 260521-03
+	// addendum § 4) so search.rerank / search.clarify rows correlate with
+	// the same discovery chain as the search.query that minted the envelope.
+	const intent_id = get_intent_id()
 	if (with_rerank && next_step?.action === 'rank_digests_inline') {
 		fire_discovery_telemetry({
 			event: 'rerank_started',
+			intent_id,
 			query,
 			rerank_prompt_version: response?.rerank_prompt_version || null,
 		})
@@ -231,6 +237,7 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 	if (with_rerank && next_step?.action === 'clarify') {
 		fire_discovery_telemetry({
 			event:       'clarify_triggered',
+			intent_id,
 			query,
 			reason:      'match_notice',
 			turn_number: clarification_turns_used + 1,
@@ -241,6 +248,7 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 		// with a refined query.
 		fire_discovery_telemetry({
 			event:       'clarify_completed',
+			intent_id,
 			query,
 			turn_number: clarification_turns_used,
 		})

package/src/utils/intent.js

@@ -39,4 +39,25 @@ const clear_envelope = () => {
 	delete process.env[ENV_VAR]
 }
 
-module.exports = { init_from_env, init_from_flag, get_envelope, set_envelope, clear_envelope, ENV_VAR }
+// Spec 260521-03 addendum § 4 — Extract the intent_id UUID from the active
+// envelope so the CLI can attach it to /telemetry/discovery beacon payloads.
+// The envelope is `<base64url-payload>.<base64url-hmac>`; the CLI doesn't
+// have the HMAC secret and doesn't need to verify — it just reads the
+// payload portion. Returns null when no envelope is active or the payload
+// can't be decoded.
+const get_intent_id = () => {
+	const env = get_envelope()
+	if (!env) return null
+	try {
+		const dot = env.indexOf('.')
+		if (dot <= 0) return null
+		const body = env.slice(0, dot)
+		const json = Buffer.from(body, 'base64url').toString('utf-8')
+		const payload = JSON.parse(json)
+		return payload.intent_id || null
+	} catch {
+		return null
+	}
+}
+
+module.exports = { init_from_env, init_from_flag, get_envelope, set_envelope, clear_envelope, get_intent_id, ENV_VAR }