An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): extend DebugEvent telemetry context (#5971)
Joeyb7667d1144ac
diff --git a/.changeset/debug-event-telemetry-context.md b/.changeset/debug-event-telemetry-context.mdnew file mode 100644index 0000000000..593d0cec55--- /dev/null+++ b/.changeset/debug-event-telemetry-context.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[feat] Add result and agent-session context to DebugEvent (#PR)++@josephfarinadiff --git a/packages/cli/README.md b/packages/cli/README.mdindex bd6acf85bb..09fbafeba3 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -406,7 +406,7 @@ Every response has a `type` discriminant. The full set is below (generated from| `discover.search` | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components. || `search` | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant). || `build.help` | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given. |-| `build.kit` | The grouped composition kit: echoed query, hasResults/directMatch flags, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays. |+| `build.kit` | The grouped composition kit: echoed query, hasResults/matchCount/directMatch fields, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays. || `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. || `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note. || `template.list` | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags. |diff --git a/packages/cli/api/build/build.doc.mjs b/packages/cli/api/build/build.doc.mjsindex 899ec03a2b..76fe5e72f2 100644--- a/packages/cli/api/build/build.doc.mjs+++ b/packages/cli/api/build/build.doc.mjs@@ -59,7 +59,7 @@ export const doc = {{type: 'build.kit',description:- 'The grouped composition kit: the echoed query, hasResults/directMatch flags, the closest page templates (≤3), drop-in block patterns (≤5), idea-specific components/hooks (≤6), and the always-on frame + foundation component-name arrays.',+ 'The grouped composition kit: the echoed query, hasResults/matchCount/directMatch fields, the closest page templates (≤3), drop-in block patterns (≤5), idea-specific components/hooks (≤6), and the always-on frame + foundation component-name arrays.',},],throws: [diff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjsindex e47d0027ad..572938f12c 100644--- a/packages/cli/api/build/build.test.mjs+++ b/packages/cli/api/build/build.test.mjs@@ -8,9 +8,13 @@ import {describe, it, expect, vi} from 'vitest';import * as path from 'node:path';import {fileURLToPath} from 'node:url';import {build} from './build.mjs';+import {search} from '../search/search.mjs';// api/build/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).-const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');+const REPO = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../../..',+);// build() delegates to search(), whose first (cold) call is slow under vitest.vi.setConfig({testTimeout: 30000});@@ -28,6 +32,8 @@ describe('build API', () => {if (r.type !== 'build.kit') return;expect(r.data.query).toBe('dashboard');expect(r.data.hasResults).toBe(true);+ const raw = await search('dashboard', {cwd: REPO, limit: 60});+ expect(r.data.matchCount).toBe(raw.data.results.length);expect(r.data.frame).toContain('AppShell');expect(r.data.foundation).toContain('Button');expect(Array.isArray(r.data.pages)).toBe(true);@@ -80,11 +86,23 @@ describe('build API', () => {for (const d of domain) expect(['component', 'hook']).toContain(d.domain);});+ it('keeps raw matches when every result is filtered out of the kit', async () => {+ const r = await build('color', {cwd: REPO, type: 'doc'});+ expect(r.type).toBe('build.kit');+ if (r.type !== 'build.kit') return;+ expect(r.data.hasResults).toBe(true);+ expect(r.data.matchCount).toBeGreaterThan(0);+ expect(r.data.pages).toHaveLength(0);+ expect(r.data.blocks).toHaveLength(0);+ expect(r.data.domain).toHaveLength(0);+ });+it('no matches → build.kit with hasResults=false and empty groups', async () => {const r = await build('zzznomatch99', {cwd: REPO});expect(r.type).toBe('build.kit');if (r.type !== 'build.kit') return;expect(r.data.hasResults).toBe(false);+ expect(r.data.matchCount).toBe(0);expect(r.data.pages).toHaveLength(0);expect(r.data.blocks).toHaveLength(0);expect(r.data.domain).toHaveLength(0);diff --git a/packages/cli/api/build/build.type.mjs b/packages/cli/api/build/build.type.mjsindex 8b718119c7..bad56fcb65 100644--- a/packages/cli/api/build/build.type.mjs+++ b/packages/cli/api/build/build.type.mjs@@ -27,6 +27,7 @@* @property {object} data* @property {string} data.query* @property {boolean} data.hasResults False when search returned nothing (renderer shows "No matches").+ * @property {number} data.matchCount Number of ranked search matches before kit score floors and caps.* @property {boolean} data.directMatch True when the top page template is a confident direct match.* @property {import('../search/search.type.mjs').SearchResultEntry[]} data.pages Closest page templates (≤3).* @property {import('../search/search.type.mjs').SearchResultEntry[]} data.blocks Drop-in block patterns covering parts of the idea (≤5).diff --git a/packages/cli/api/build/kit/kit.mjs b/packages/cli/api/build/kit/kit.mjsindex 73044f3b0b..e6a7418541 100644--- a/packages/cli/api/build/kit/kit.mjs+++ b/packages/cli/api/build/kit/kit.mjs@@ -1,7 +1,7 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file build.kit leaf — the grouped composition kit for an idea.+ * @file build.kit leaf — the grouped composition kit and raw match count.** Runs the unified search for the query and groups the results into a* composition KIT: the closest page templates, the blocks that cover parts,@@ -30,8 +30,18 @@ const DOMAIN_FLOOR = 55;*/const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];const FOUNDATION = [- 'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',- 'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',+ 'VStack',+ 'HStack',+ 'Grid',+ 'StackItem',+ 'Card',+ 'Section',+ 'Text',+ 'Heading',+ 'Button',+ 'Icon',+ 'Badge',+ 'Divider',];const ALWAYS = new Set([...FRAME, ...FOUNDATION]);@@ -47,16 +57,25 @@ export async function buildKit(query, options = {}) {// search()'s JSDoc @returns widens results to object[]; the SearchResponse// shape is the contract (api/search/search.type.mjs). Cast locally rather than// tightening the search @returns (a separate follow-up).- const result = /** @type {import('../../search/search.type.mjs').SearchResponse} */ (- await search(query, {cwd, type, limit})- );+ const result =+ /** @type {import('../../search/search.type.mjs').SearchResponse} */ (+ await search(query, {cwd, type, limit})+ );const results = result.data.results;const pages = results- .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)+ .filter(+ r =>+ r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR,+ ).slice(0, 3);const blocks = results- .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)+ .filter(+ r =>+ r.domain === 'template' &&+ r.kind === 'block' &&+ r.score >= DOMAIN_FLOOR,+ ).slice(0, 5);const domain = results.filter(@@ -75,6 +94,7 @@ export async function buildKit(query, options = {}) {// Distinguishes "search found nothing" (renderer shows "No matches")// from a weak-but-non-empty result set (renderer still shows the kit).hasResults: results.length > 0,+ matchCount: results.length,directMatch,pages,blocks,diff --git a/packages/cli/authoring/debug/parse.mjs b/packages/cli/authoring/debug/parse.mjsindex 4732962463..3b76a84b84 100644--- a/packages/cli/authoring/debug/parse.mjs+++ b/packages/cli/authoring/debug/parse.mjs@@ -41,6 +41,16 @@ const optionSourceSchema = z.enum(['implied',]);+const resultKindSchema = z.enum([+ 'component',+ 'template',+ 'doc',+ 'hook',+ 'mixed',+]);++const invocationSourceSchema = z.enum(['human', 'ai', 'automation', 'unknown']);+const errorSchema = z.object({name: z.string(),@@ -56,6 +66,10 @@ const outputSchema = zenvelopeTypes: z.array(z.string()),handled: z.boolean(),helpDisplayed: z.boolean(),+ resultCount: z.number().int().nonnegative().nullable().default(null),+ emptyResult: z.boolean().nullable().default(null),+ resultKind: resultKindSchema.nullable().default(null),+ directMatch: z.boolean().nullable().default(null),stdout: z.string(),stderr: z.string(),stdoutBytes: z.number(),@@ -73,6 +87,11 @@ const envSchema = zci: z.boolean(),ciName: z.string().nullable(),agent: z.string().nullable(),+ agentIdentity: z.string().nullable().default(null),+ agentSessionId: z.string().nullable().default(null),+ agentSessionIdHash: z.string().nullable().default(null),+ agentSessionIdSource: z.string().nullable().default(null),+ invocationSource: invocationSourceSchema.default('unknown'),oneOff: z.boolean(),packageManager: z.string().nullable(),tty: z.boolean(),diff --git a/packages/cli/authoring/debug/type.ts b/packages/cli/authoring/debug/type.tsindex f3c9735976..765aaf9748 100644--- a/packages/cli/authoring/debug/type.ts+++ b/packages/cli/authoring/debug/type.ts@@ -41,6 +41,13 @@ export type DebugOutcome =export type DebugOptionSource ='cli' | 'default' | 'env' | 'config' | 'implied';+/** The kind of content represented by a command's result set. */+export type DebugResultKind =+ 'component' | 'template' | 'doc' | 'hook' | 'mixed';++/** What initiated the CLI invocation, based only on positive evidence. */+export type DebugInvocationSource = 'human' | 'ai' | 'automation' | 'unknown';+/** The failure, when there was one. */export interface DebugEventError {name: string;@@ -64,6 +71,14 @@ export interface DebugEventOutput {handled: boolean;/** Whether the run ended by printing help rather than doing work. */helpDisplayed: boolean;+ /** Number of matches before presentation-only grouping or caps. */+ resultCount: number | null;+ /** Whether the command's underlying match set was empty. */+ emptyResult: boolean | null;+ /** One surfaced result kind, `mixed`, or null when none was surfaced. */+ resultKind: DebugResultKind | null;+ /** Whether the command found a confident direct match, when it defines one. */+ directMatch: boolean | null;/*** Everything the command printed to stdout — the answer the user actually* got. Scrubbed like every other captured value, and truncated past@@ -81,9 +96,9 @@ export interface DebugEventOutput {}/**- * Machine and runtime facts. Deliberately coarse: no hostname, no username,- * no network identity — everything here is either a bucket or something the- * user could read off their own `astryx doctor` output.+ * Machine, runtime, and invocation-attribution facts. There is no hostname,+ * username, or network identity. Agent session values come only from explicit+ * environment signals supplied by the invoking tool.*/export interface DebugEventEnv {cliVersion: string | null;@@ -95,8 +110,25 @@ export interface DebugEventEnv {ci: boolean;/** Detected CI provider, e.g. 'github-actions'. Null outside CI. */ciName: string | null;- /** Coding agent that invoked the CLI, e.g. 'cursor' | 'claude-code'. */+ /** Legacy broad detector, retained for compatibility with existing consumers. */agent: string | null;+ /**+ * Coding-agent identity from `ASTRYX_AGENT_ID`, `AGENT`,+ * `ASTRYX_AGENT_METADATA`, or a known public agent signal.+ */+ agentIdentity: string | null;+ /**+ * Opaque session identifier from `ASTRYX_AGENT_SESSION_ID`,+ * `AGENT_SESSION_ID`, or `ASTRYX_AGENT_METADATA`. It is included verbatim so+ * a handler can choose the raw value or the hash below.+ */+ agentSessionId: string | null;+ /** SHA-256 of `agentSessionId`, for joins that do not need the raw value. */+ agentSessionIdHash: string | null;+ /** Public environment signal that supplied `agentSessionId`. */+ agentSessionIdSource: string | null;+ /** Whether a human, AI agent, or automation invoked the CLI. */+ invocationSource: DebugInvocationSource;/** Run one-off via npx/dlx rather than an installed binary. */oneOff: boolean;packageManager: string | null;diff --git a/packages/cli/authoring/index.d.ts b/packages/cli/authoring/index.d.tsindex 9b68b4d552..1f9a5c90c7 100644--- a/packages/cli/authoring/index.d.ts+++ b/packages/cli/authoring/index.d.ts@@ -114,6 +114,8 @@ export type {DebugSchemaVersion,DebugOutcome,DebugOptionSource,+ DebugResultKind,+ DebugInvocationSource,DebugEventError,DebugEventOutput,DebugEventEnv,diff --git a/packages/cli/clients/cli/commands/build.mjs b/packages/cli/clients/cli/commands/build.mjsindex 7c010c132b..c9b5472e8e 100644--- a/packages/cli/clients/cli/commands/build.mjs+++ b/packages/cli/clients/cli/commands/build.mjs@@ -1,7 +1,7 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file build command — thin wrapper around api/build.+ * @file build command — thin wrapper with stable result telemetry.** astryx build → the PLAYBOOK (how to build a page)* astryx build "<what>" → a COMPOSITION KIT (closest page template,@@ -12,9 +12,20 @@* (never in the API payload) via formatCliCommand/getCliInvocation.*/-import {getCliInvocation, formatCliCommand} from '../../../foundation/env/package-manager.mjs';+import {+ getCliInvocation,+ formatCliCommand,+} from '../../../foundation/env/package-manager.mjs';import {jsonOut} from '../../../foundation/response/json.mjs';-import {emit, section, text, record, records, ARROW} from '../formatters/index.mjs';+import {recordResultSummary} from '../../../foundation/debug/index.mjs';+import {+ emit,+ section,+ text,+ record,+ records,+ ARROW,+} from '../formatters/index.mjs';import {cliError} from '../lib/cli-error.mjs';import {defineCommand} from '../lib/define-command.mjs';import {build as buildApi} from '../../../api/build/build.mjs';@@ -71,7 +82,10 @@ function printPlaybook(run) {export function registerBuild(program) {defineCommand(program, buildCommand, {fn: buildFn,- action: async (/** @type {string | undefined} */ query, /** @type {{type?: import('../../../api/search/search.type.mjs').SearchDomain, limit?: string, verbose?: boolean}} */ options) => {+ action: async (+ /** @type {string | undefined} */ query,+ /** @type {{type?: import('../../../api/search/search.type.mjs').SearchDomain, limit?: string, verbose?: boolean}} */ options,+ ) => {const run = getCliInvocation();const json = program.opts().json || false;@@ -93,19 +107,39 @@ export function registerBuild(program) {/** @type {import('../../../api/build/build.type.mjs').BuildKitResponse} */let result;try {- result = /** @type {import('../../../api/build/build.type.mjs').BuildKitResponse} */ (- await buildApi(query, {cwd: process.cwd(), type: options.type, limit})- );+ result =+ /** @type {import('../../../api/build/build.type.mjs').BuildKitResponse} */ (+ await buildApi(query, {+ cwd: process.cwd(),+ type: options.type,+ limit,+ })+ );} catch (e) {- const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);+ const err =+ /** @type {import('../../../api/error.mjs').AstryxError} */ (e);cliError(err.message, {suggestions: err.suggestions, code: err.code});return;}- if (json) return jsonOut(result);+ const {+ query: q,+ hasResults,+ matchCount,+ directMatch,+ pages,+ blocks,+ domain,+ frame,+ foundation,+ } = result.data;+ recordResultSummary([...pages, ...blocks, ...domain], {+ directMatch,+ resultCount: matchCount,+ emptyResult: !hasResults,+ });- const {query: q, hasResults, directMatch, pages, blocks, domain, frame, foundation} =- result.data;+ if (json) return jsonOut(result);if (!hasResults) {emit(@@ -119,7 +153,16 @@ export function registerBuild(program) {// already says the kind, so drop `domain`/`import` by default (they're in// --json and under --verbose). Keeps each item to name/displayName/desc/cmd.const fields = options.verbose- ? ['name', 'domain', 'displayName', 'score', 'reason', 'import', 'description', 'command']+ ? [+ 'name',+ 'domain',+ 'displayName',+ 'score',+ 'reason',+ 'import',+ 'description',+ 'command',+ ]: ['name', 'displayName', 'description', 'command'];/** @type {import('../formatters/index.mjs').RecordOptions} */const recordOpts = {fields, format: {command: formatCliCommand}};@@ -184,7 +227,10 @@ export function registerBuild(program) {}out.push(- section('FRAME + FOUNDATION', 'Always-available shell + layout/text/action primitives.'),+ section(+ 'FRAME + FOUNDATION',+ 'Always-available shell + layout/text/action primitives.',+ ),record({frame,foundation,diff --git a/packages/cli/clients/cli/commands/debug-result-summary.test.mjs b/packages/cli/clients/cli/commands/debug-result-summary.test.mjsnew file mode 100644index 0000000000..a3d3ca512c--- /dev/null+++ b/packages/cli/clients/cli/commands/debug-result-summary.test.mjs@@ -0,0 +1,132 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file CLI coverage for the structured result summary on DebugEvent.+ *+ * @input real search and build command responses+ * @output result counts, kinds, empty-state, and direct-match telemetry+ * @position packages/cli/clients/cli/commands — debug result integration+ */++import {afterEach, describe, expect, it} from 'vitest';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';+import {runCli} from '../../../test-utils/run-cli.mjs';+import {+ begin,+ finish,+ resetRecorder,+ setEventHandler,+} from '../../../foundation/debug/recorder.mjs';++const REPO = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../../../..',+);+const SLOW = 30_000;++/** @param {string[]} args */+async function runWithDebug(args) {+ resetRecorder();+ begin({argv: args, cliVersion: 'test'});+ const run = await runCli(args, REPO);+ /** @type {any[]} */+ const events = [];+ setEventHandler(event => events.push(event));+ finish({exitCode: run.status});+ expect(events).toHaveLength(1);+ return {run, event: events[0]};+}++afterEach(() => resetRecorder());++describe('DebugEvent result summary', () => {+ it(+ 'distinguishes a successful search with no results',+ async () => {+ const {event} = await runWithDebug([+ 'search',+ 'zzqqxx_definitely_no_match',+ ]);+ expect(event.outcome).toBe('ok');+ expect(event.output).toMatchObject({+ resultCount: 0,+ emptyResult: true,+ resultKind: null,+ directMatch: null,+ });+ },+ SLOW,+ );++ it(+ 'records a single kind for a filtered search',+ async () => {+ const {run, event} = await runWithDebug([+ '--json',+ 'search',+ 'button',+ '--type',+ 'component',+ '--limit',+ '2',+ ]);+ const response = JSON.parse(run.stdout);+ expect(event.output).toMatchObject({+ resultCount: response.data.results.length,+ emptyResult: false,+ resultKind: 'component',+ directMatch: null,+ });+ },+ SLOW,+ );++ it(+ 'records build count, kind, and direct-match state',+ async () => {+ const {run, event} = await runWithDebug(['--json', 'build', 'dashboard']);+ const response = JSON.parse(run.stdout);+ const results = [+ ...response.data.pages,+ ...response.data.blocks,+ ...response.data.domain,+ ];+ const domains = new Set(results.map(result => result.domain));+ const resultKind =+ domains.size === 0+ ? null+ : domains.size === 1+ ? domains.values().next().value+ : 'mixed';+ expect(event.output).toMatchObject({+ resultCount: response.data.matchCount,+ emptyResult: !response.data.hasResults,+ resultKind,+ directMatch: response.data.directMatch,+ });+ },+ SLOW,+ );++ it(+ 'keeps text build nonempty when raw matches are filtered from the kit',+ async () => {+ const {run, event} = await runWithDebug([+ 'build',+ 'color',+ '--type',+ 'doc',+ ]);+ expect(run.status).toBe(0);+ expect(run.stdout).toContain('Build kit for');+ expect(event.output).toMatchObject({+ emptyResult: false,+ resultKind: null,+ directMatch: false,+ });+ expect(event.output.resultCount).toBeGreaterThan(0);+ },+ SLOW,+ );+});diff --git a/packages/cli/clients/cli/commands/search.mjs b/packages/cli/clients/cli/commands/search.mjsindex a601c60704..3236705e69 100644--- a/packages/cli/clients/cli/commands/search.mjs+++ b/packages/cli/clients/cli/commands/search.mjs@@ -1,7 +1,7 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file search command — unified ranked search across all content domains.+ * @file search command — unified ranked search with a stable result summary.** One "I'm looking for X" entry point spanning components, hooks, docs topics,* and templates (page + block). Results are ranked by relevance and tagged@@ -20,8 +20,12 @@* astryx search button --json Typed JSON envelope*/-import {getCliInvocation, formatCliCommand} from '../../../foundation/env/package-manager.mjs';+import {+ getCliInvocation,+ formatCliCommand,+} from '../../../foundation/env/package-manager.mjs';import {jsonOut} from '../../../foundation/response/json.mjs';+import {recordResultSummary} from '../../../foundation/debug/index.mjs';import {emit, section, text, records} from '../formatters/index.mjs';import {cliError} from '../lib/cli-error.mjs';import {defineCommand} from '../lib/define-command.mjs';@@ -53,24 +57,28 @@ export function registerSearch(program) {// Parse --limit to a number; the API validates it (positive integer) and// throws ERR_INVALID_ARGUMENT, so we pass NaN through rather than// pre-rejecting with a generic code here.- const limit = options.limit != null ? Number.parseInt(options.limit, 10) : 20;+ const limit =+ options.limit != null ? Number.parseInt(options.limit, 10) : 20;/** @type {import('../../../api/search/search.type.mjs').SearchResponse} */let result;try {- result = /** @type {import('../../../api/search/search.type.mjs').SearchResponse} */ (- await searchApi(query, {- cwd: process.cwd(),- type: options.type,- limit,- })- );+ result =+ /** @type {import('../../../api/search/search.type.mjs').SearchResponse} */ (+ await searchApi(query, {+ cwd: process.cwd(),+ type: options.type,+ limit,+ })+ );} catch (e) {- const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);+ const err =+ /** @type {import('../../../api/error.mjs').AstryxError} */ (e);cliError(err.message, {suggestions: err.suggestions, code: err.code});return;}+ recordResultSummary(result.data.results);if (json) return jsonOut(result);// ── Text output ──────────────────────────────────────────────@@ -90,7 +98,16 @@ export function registerSearch(program) {// fields in a fixed order (missing ones skipped), command prefixed for the// caller's package manager. Ranked order is preserved (best match first).const fields = options.verbose- ? ['name', 'domain', 'displayName', 'score', 'reason', 'import', 'description', 'command']+ ? [+ 'name',+ 'domain',+ 'displayName',+ 'score',+ 'reason',+ 'import',+ 'description',+ 'command',+ ]: ['name', 'domain', 'displayName', 'import', 'description', 'command'];emit(diff --git a/packages/cli/foundation/debug/event.mjs b/packages/cli/foundation/debug/event.mjsindex 753f00ddf8..e3e3930c0d 100644--- a/packages/cli/foundation/debug/event.mjs+++ b/packages/cli/foundation/debug/event.mjs@@ -72,10 +72,9 @@ const CI_PROVIDERS = [];/**- * Coding agents and editors worth distinguishing. This CLI is explicitly built- * to be driven by agents, so "which agent invoked this" is the single most- * useful dimension in the log — it separates human ergonomics problems from- * agent-prompt problems.+ * Coding-agent signals. The first six are positive evidence of an AI agent.+ * The final two are retained only by the legacy `agent` field because they can+ * also describe a human development environment.*/const AGENT_SIGNALS = [['CURSOR_TRACE_ID', 'cursor'],@@ -87,6 +86,7 @@ const AGENT_SIGNALS = [['REPLIT_USER', 'replit'],['CODESPACES', 'codespaces'],];+const POSITIVE_AGENT_SIGNAL_COUNT = 6;/** @returns {{ci: boolean, ciName: string | null}} */function detectCi() {@@ -101,8 +101,81 @@ function detectCi() {return {ci: generic, ciName: generic ? 'unknown' : null};}-/** @returns {string | null} */-function detectAgent() {+/** @param {unknown} value @returns {string | null} */+function nonEmptyString(value) {+ if (value == null) return null;+ const text = String(value).trim();+ return text || null;+}++/**+ * ASTRYX_AGENT_METADATA accepts both JSON and comma-separated key=value+ * forms. Unknown or malformed entries are ignored so a producer cannot break+ * command recording.+ *+ * @param {unknown} value+ * @returns {Record<string, string>}+ */+function parseCodingAgentMetadata(value) {+ const raw = nonEmptyString(value);+ if (!raw) return {};++ try {+ const decoded = JSON.parse(raw);+ if (decoded && typeof decoded === 'object' && !Array.isArray(decoded)) {+ /** @type {Record<string, string>} */+ const metadata = Object.create(null);+ for (const [key, entry] of Object.entries(decoded)) {+ if (+ typeof entry !== 'string' &&+ typeof entry !== 'number' &&+ typeof entry !== 'boolean'+ ) {+ continue;+ }+ const item = nonEmptyString(entry);+ if (item) metadata[key] = item;+ }+ return metadata;+ }+ } catch {+ // The compact form is comma-separated key=value, not JSON.+ }++ /** @type {Record<string, string>} */+ const metadata = Object.create(null);+ for (const entry of raw.split(',')) {+ const separator = entry.indexOf('=');+ if (separator <= 0) continue;+ const key = entry.slice(0, separator).trim();+ const item = nonEmptyString(entry.slice(separator + 1));+ if (key && item) metadata[key] = item;+ }+ return metadata;+}++/** @param {Record<string, string>} metadata @returns {string | null} */+function detectAgentIdentity(metadata) {+ const astryxAgent = nonEmptyString(process.env.ASTRYX_AGENT_ID);+ if (astryxAgent) return astryxAgent.toLowerCase();++ const genericAgent = nonEmptyString(process.env.AGENT);+ if (genericAgent) return genericAgent.toLowerCase();++ for (const [key, name] of AGENT_SIGNALS.slice(+ 0,+ POSITIVE_AGENT_SIGNAL_COUNT,+ )) {+ if (process.env[key]) return name;+ }++ const metadataId = nonEmptyString(metadata.id);+ return metadataId ? metadataId.toLowerCase() : null;+}++/** @param {string | null} identity @returns {string | null} */+function detectAgent(identity) {+ if (identity) return identity;for (const [key, name] of AGENT_SIGNALS) {if (process.env[key]) return name;}@@ -112,15 +185,64 @@ function detectAgent() {}/**- * Snapshot the machine and runtime. Everything here is either a coarse- * bucket or a value the user could read off their own `astryx doctor`- * output — no hostname, no username, no network identity.+ * @param {Record<string, string>} metadata+ * @returns {{id: string | null, source: string | null}}+ */+function detectAgentSession(metadata) {+ /** @type {Array<[unknown, string]>} */+ const candidates = [+ [process.env.ASTRYX_AGENT_SESSION_ID, 'ASTRYX_AGENT_SESSION_ID'],+ [process.env.AGENT_SESSION_ID, 'AGENT_SESSION_ID'],+ [+ metadata.session_id ?? metadata.sessionId,+ 'ASTRYX_AGENT_METADATA.session_id',+ ],+ [+ metadata.invocation_id ?? metadata.invocationId,+ 'ASTRYX_AGENT_METADATA.invocation_id',+ ],+ ];++ for (const [value, source] of candidates) {+ const id = nonEmptyString(value);+ if (id) return {id, source};+ }+ return {id: null, source: null};+}++/** @param {string | null} id @returns {string | null} */+function hashAgentSessionId(id) {+ return id == null+ ? null+ : crypto.createHash('sha256').update(id, 'utf8').digest('hex');+}++/**+ * @param {{agentIdentity: string | null, agentSessionId: string | null, ci: boolean}} facts+ * @returns {import('../../authoring/debug/type').DebugInvocationSource}+ */+function detectInvocationSource({agentIdentity, agentSessionId, ci}) {+ if (agentIdentity || agentSessionId) return 'ai';+ if (ci) return 'automation';+ if (process.stdout.isTTY) return 'human';+ return 'unknown';+}++/**+ * Snapshot the machine, runtime, and invocation attribution. There is no+ * hostname, username, or network identity. Agent session values come only from+ * explicit environment signals supplied by the invoking tool.** @param {{cliVersion?: string}} [options]* @returns {import('../../authoring/debug/type').DebugEventEnv}*/export function captureEnv({cliVersion} = {}) {const {ci, ciName} = detectCi();+ const agentMetadata = parseCodingAgentMetadata(+ process.env.ASTRYX_AGENT_METADATA,+ );+ const agentIdentity = detectAgentIdentity(agentMetadata);+ const agentSession = detectAgentSession(agentMetadata);return {cliVersion: cliVersion ?? null,nodeVersion: process.versions.node,@@ -128,14 +250,20 @@ export function captureEnv({cliVersion} = {}) {arch: process.arch,ci,ciName,- agent: detectAgent(),+ agent: detectAgent(agentIdentity),+ agentIdentity,+ agentSessionId: agentSession.id,+ agentSessionIdHash: hashAgentSessionId(agentSession.id),+ agentSessionIdSource: agentSession.source,+ invocationSource: detectInvocationSource({+ agentIdentity,+ agentSessionId: agentSession.id,+ ci,+ }),oneOff: safe(() => isCliOneOff(), false),packageManager: safe(() => detectPackageManager(), null),tty: Boolean(process.stdout.isTTY),- locale: safe(- () => Intl.DateTimeFormat().resolvedOptions().locale,- null,- ),+ locale: safe(() => Intl.DateTimeFormat().resolvedOptions().locale, null),timezone: safe(() => Intl.DateTimeFormat().resolvedOptions().timeZone,null,@@ -196,6 +324,10 @@ export function createEvent({command = '', argv = []} = {}) {envelopeTypes: [],handled: false,helpDisplayed: false,+ resultCount: null,+ emptyResult: null,+ resultKind: null,+ directMatch: null,stdout: '',stderr: '',stdoutBytes: 0,diff --git a/packages/cli/foundation/debug/index.mjs b/packages/cli/foundation/debug/index.mjsindex db5c9dde2c..65b5913283 100644--- a/packages/cli/foundation/debug/index.mjs+++ b/packages/cli/foundation/debug/index.mjs@@ -12,6 +12,7 @@** begin() once, before Commander parses* setCommand/setArgs/… as facts become known+ * recordResultSummary() when a command returns a result set* setOutcome() from every terminal path (error, fatal, gate)* finish() automatic, via the exit listener begin() installs*@@ -32,6 +33,7 @@ export {setOptions,setGlobalOptions,setProject,+ recordResultSummary,setEventHandler,noteConfigGateSkipped,setOutcome,diff --git a/packages/cli/foundation/debug/recorder.mjs b/packages/cli/foundation/debug/recorder.mjsindex 6bba4f9397..0abb7322bd 100644--- a/packages/cli/foundation/debug/recorder.mjs+++ b/packages/cli/foundation/debug/recorder.mjs@@ -28,7 +28,7 @@* swallows its own errors; the worst outcome of a bug in here is a missing or* partial event.*- * @input lifecycle calls from the command layer, plus a handler from config+ * @input lifecycle calls, result summaries, and a handler from config* @output one event per invocation, delivered to that handler* @position packages/cli/foundation/debug — runtime*/@@ -345,6 +345,51 @@ export function setProject(facts) {});}+/** Values `resultKind` may carry — mirrors DebugResultKind. */+const RESULT_KINDS = new Set(['component', 'template', 'doc', 'hook']);++/**+ * Record a stable summary of a command's result set and presentation.+ *+ * @param {Array<{domain?: unknown}>} results Surfaced results used for kind.+ * @param {{directMatch?: boolean, resultCount?: number, emptyResult?: boolean}} [options]+ */+export function recordResultSummary(+ results,+ {directMatch, resultCount, emptyResult} = {},+) {+ guard(() => {+ if (!_event || !Array.isArray(results)) return;++ const kinds = new Set(+ results+ .map(result => result?.domain)+ .filter(kind => typeof kind === 'string' && RESULT_KINDS.has(kind)),+ );+ const count =+ typeof resultCount === 'number' &&+ Number.isInteger(resultCount) &&+ resultCount >= 0+ ? resultCount+ : results.length;++ _event.output.resultCount = count;+ _event.output.emptyResult =+ typeof emptyResult === 'boolean' ? emptyResult : count === 0;+ _event.output.resultKind =+ kinds.size === 0+ ? null+ : kinds.size === 1+ ? /** @type {import('../../authoring/debug/type').DebugResultKind} */ (+ kinds.values().next().value+ )+ : 'mixed';+ if (typeof directMatch === 'boolean') {+ _event.output.directMatch = directMatch;+ }+ });+}+/** Note a JSON envelope discriminator the command emitted. @param {string} type */export function recordEnvelope(type) {guard(() => {diff --git a/packages/cli/foundation/debug/telemetry-fields.test.mjs b/packages/cli/foundation/debug/telemetry-fields.test.mjsnew file mode 100644index 0000000000..c59d9fcae4--- /dev/null+++ b/packages/cli/foundation/debug/telemetry-fields.test.mjs@@ -0,0 +1,296 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Contract coverage for DebugEvent result and agent-session fields.+ *+ * @position packages/cli/foundation/debug — telemetry contract coverage+ */++import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+import {createHash} from 'node:crypto';+import {+ begin,+ finish,+ recordResultSummary,+ resetRecorder,+ setEventHandler,+} from './recorder.mjs';+import {captureEnv} from './event.mjs';+import {parseDebugEvent} from '../../authoring/debug/parse.mjs';++const ATTRIBUTION_ENV_KEYS = [+ 'ASTRYX_AGENT_ID',+ 'ASTRYX_AGENT_SESSION_ID',+ 'ASTRYX_AGENT_METADATA',+ 'AGENT',+ 'AGENT_SESSION_ID',+ 'CURSOR_TRACE_ID',+ 'CURSOR_AGENT',+ 'CLAUDECODE',+ 'CLAUDE_CODE',+ 'AIDER_MODEL',+ 'GITHUB_COPILOT_AGENT',+ 'REPLIT_USER',+ 'CODESPACES',+ 'TERM_PROGRAM',+ 'CI',+ 'GITHUB_ACTIONS',+ 'GITLAB_CI',+ 'CIRCLECI',+ 'BUILDKITE',+ 'TRAVIS',+ 'JENKINS_URL',+ 'TEAMCITY_VERSION',+ 'TF_BUILD',+ 'BITBUCKET_BUILD_NUMBER',+ 'CODEBUILD_BUILD_ID',+ 'DRONE',+ 'VERCEL',+ 'NETLIFY',+];++function clearAttributionEnv() {+ for (const key of ATTRIBUTION_ENV_KEYS) vi.stubEnv(key, '');+}++/** @param {() => void} [setup] */+function collectEvent(setup = () => {}) {+ /** @type {any[]} */+ const seen = [];+ setEventHandler(event => seen.push(event));+ begin({argv: ['docs'], cliVersion: '9.9.9'});+ setup();+ finish({exitCode: 0});+ expect(seen).toHaveLength(1);+ return seen[0];+}++beforeEach(() => {+ vi.unstubAllEnvs();+ resetRecorder();+});++afterEach(() => {+ vi.unstubAllEnvs();+ resetRecorder();+});++describe('DebugEvent additive fields', () => {+ it('keeps every existing field and adds null result fields', () => {+ const event = collectEvent();+ expect(Object.keys(event).sort()).toEqual(+ [+ 'args',+ 'argv',+ 'command',+ 'commandPath',+ 'durationMs',+ 'endedAt',+ 'env',+ 'error',+ 'exitCode',+ 'globalOptions',+ 'id',+ 'optionSources',+ 'options',+ 'outcome',+ 'output',+ 'project',+ 'redacted',+ 'schemaVersion',+ 'signal',+ 'startedAt',+ ].sort(),+ );+ expect(Object.keys(event.output).sort()).toEqual(+ [+ 'directMatch',+ 'emptyResult',+ 'envelopeTypes',+ 'handled',+ 'helpDisplayed',+ 'jsonMode',+ 'resultCount',+ 'resultKind',+ 'stderr',+ 'stderrBytes',+ 'stdout',+ 'stdoutBytes',+ 'truncated',+ ].sort(),+ );+ expect(Object.keys(event.env).sort()).toEqual(+ [+ 'agent',+ 'agentIdentity',+ 'agentSessionId',+ 'agentSessionIdHash',+ 'agentSessionIdSource',+ 'arch',+ 'ci',+ 'ciName',+ 'cliVersion',+ 'invocationSource',+ 'locale',+ 'nodeVersion',+ 'oneOff',+ 'packageManager',+ 'platform',+ 'timezone',+ 'tty',+ ].sort(),+ );+ expect(event.output).toMatchObject({+ resultCount: null,+ emptyResult: null,+ resultKind: null,+ directMatch: null,+ });+ expect(() => parseDebugEvent(event)).not.toThrow();+ });++ it('accepts persisted schema-v1 events that predate the fields', () => {+ const legacy = structuredClone(collectEvent());+ for (const key of [+ 'resultCount',+ 'emptyResult',+ 'resultKind',+ 'directMatch',+ ]) {+ delete legacy.output[key];+ }+ for (const key of [+ 'agentIdentity',+ 'agentSessionId',+ 'agentSessionIdHash',+ 'agentSessionIdSource',+ 'invocationSource',+ ]) {+ delete legacy.env[key];+ }+ expect(parseDebugEvent(legacy)).toMatchObject({+ schemaVersion: 1,+ output: {+ resultCount: null,+ emptyResult: null,+ resultKind: null,+ directMatch: null,+ },+ env: {+ agentIdentity: null,+ agentSessionId: null,+ agentSessionIdHash: null,+ agentSessionIdSource: null,+ invocationSource: 'unknown',+ },+ });+ });++ it('records count, empty, kind, and direct-match facts', () => {+ const event = collectEvent(() => {+ recordResultSummary([{domain: 'template'}, {domain: 'component'}], {+ directMatch: true,+ resultCount: 9,+ emptyResult: false,+ });+ });+ expect(event.output).toMatchObject({+ resultCount: 9,+ emptyResult: false,+ resultKind: 'mixed',+ directMatch: true,+ });+ });++ it('records a successful empty result set', () => {+ const event = collectEvent(() => recordResultSummary([]));+ expect(event.outcome).toBe('ok');+ expect(event.output).toMatchObject({+ resultCount: 0,+ emptyResult: true,+ resultKind: null,+ directMatch: null,+ });+ });+});++describe('environment attribution', () => {+ it('detects an explicit agent and hashes its session id', () => {+ clearAttributionEnv();+ vi.stubEnv('ASTRYX_AGENT_ID', 'test-agent');+ vi.stubEnv('ASTRYX_AGENT_SESSION_ID', 'agent-session-123');+ const env = captureEnv();+ expect(env).toMatchObject({+ agent: 'test-agent',+ agentIdentity: 'test-agent',+ agentSessionId: 'agent-session-123',+ agentSessionIdSource: 'ASTRYX_AGENT_SESSION_ID',+ invocationSource: 'ai',+ });+ expect(env.agentSessionIdHash).toBe(+ createHash('sha256').update('agent-session-123', 'utf8').digest('hex'),+ );+ });++ it('uses the generic AGENT identity', () => {+ clearAttributionEnv();+ vi.stubEnv('AGENT', 'generic-agent');+ expect(captureEnv()).toMatchObject({+ agent: 'generic-agent',+ agentIdentity: 'generic-agent',+ invocationSource: 'ai',+ });+ });++ it('parses comma-separated metadata', () => {+ clearAttributionEnv();+ vi.stubEnv(+ 'ASTRYX_AGENT_METADATA',+ 'id=future-agent,invocation_id=future-session,malformed',+ );+ expect(captureEnv()).toMatchObject({+ agentIdentity: 'future-agent',+ agentSessionId: 'future-session',+ agentSessionIdSource: 'ASTRYX_AGENT_METADATA.invocation_id',+ invocationSource: 'ai',+ });+ });++ it('parses JSON metadata', () => {+ clearAttributionEnv();+ vi.stubEnv(+ 'ASTRYX_AGENT_METADATA',+ JSON.stringify({id: 'json-agent', session_id: 'json-session'}),+ );+ expect(captureEnv()).toMatchObject({+ agentIdentity: 'json-agent',+ agentSessionId: 'json-session',+ agentSessionIdSource: 'ASTRYX_AGENT_METADATA.session_id',+ invocationSource: 'ai',+ });+ });++ it('leaves agent fields null without a signal', () => {+ clearAttributionEnv();+ vi.stubEnv('CI', '1');+ expect(captureEnv()).toMatchObject({+ agent: null,+ agentIdentity: null,+ agentSessionId: null,+ agentSessionIdHash: null,+ agentSessionIdSource: null,+ invocationSource: 'automation',+ });+ });++ it('keeps vscode in the legacy field without calling it AI', () => {+ clearAttributionEnv();+ vi.stubEnv('TERM_PROGRAM', 'vscode');+ vi.stubEnv('CI', '1');+ expect(captureEnv()).toMatchObject({+ agent: 'vscode',+ agentIdentity: null,+ invocationSource: 'automation',+ });+ });+});diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex 3827eb670f..d72fbc19d7 100644--- a/packages/cli/foundation/response/response-types.doc.mjs+++ b/packages/cli/foundation/response/response-types.doc.mjs@@ -20,7 +20,7 @@ export const doc = {{value: 'init.run',description:- "The install receipt: the `mode` (`default` | `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` | `created` | `skipped`) plus its path, and whether the next-steps were emitted.",+ 'The install receipt: the `mode` (`default` | `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` | `created` | `skipped`) plus its path, and whether the next-steps were emitted.',},{value: 'init.remove',@@ -123,7 +123,7 @@ export const doc = {{value: 'build.kit',description:- 'The grouped composition kit: echoed query, hasResults/directMatch flags, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.',+ 'The grouped composition kit: echoed query, hasResults/matchCount/directMatch fields, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.',},// swizzle@@ -192,7 +192,7 @@ export const doc = {{value: 'theme.build.batch',description:- 'Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme\'s theme.build (or theme.build.check) envelope, or null when it produced no CSS.',+ "Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS.",},{value: 'theme.list',