Skip to content

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.md
new file mode 100644
index 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)
+
+@josephfarina
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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 = z
envelopeTypes: 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 = z
ci: 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.ts
index 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.ts
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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',