An open source design system that's fully customizable and agent ready
TypeScript
fix!: stop reading the Astryx-owned agent variables (AST-017 FR14) (#7127)
Joeyd859ae98479c
diff --git a/.changeset/remove-astryx-env-vars.md b/.changeset/remove-astryx-env-vars.mdnew file mode 100644index 0000000000..dab335d658--- /dev/null+++ b/.changeset/remove-astryx-env-vars.md@@ -0,0 +1,13 @@+---+'@astryxdesign/cli': minor+---++[breaking] Stop reading the Astryx-owned agent variables ASTRYX_AGENT_ID, ASTRYX_AGENT_SESSION_ID, and ASTRYX_AGENT_METADATA+@josephfarina++The CLI must not define or read an Astryx-owned environment variable (spec:AST-017 FR14). The theme-import change already stopped reading ASTRYX_THEME; these three were the last. A test now fails on any `process.env.ASTRYX_*` read in the CLI source.++Classification: incompatible-fix. IFIX-0001 / CLN-0007.+Authority: spec:AST-017 FR14 (current): "The CLI MUST NOT define or read an Astryx-owned environment variable."+Released victim: published 0.6.5 and every later release read ASTRYX_AGENT_ID, ASTRYX_AGENT_SESSION_ID, and ASTRYX_AGENT_METADATA to attribute debug events to an agent and its session.+Migration: set `AGENT` and `AGENT_SESSION_ID`, which the CLI already reads, instead of the Astryx-prefixed variants. ASTRYX_AGENT_METADATA has no replacement variable.diff --git a/packages/cli/api/doctor/doctor.test.mjs b/packages/cli/api/doctor/doctor.test.mjsindex d72ad878ff..25f668f1f6 100644--- a/packages/cli/api/doctor/doctor.test.mjs+++ b/packages/cli/api/doctor/doctor.test.mjs@@ -1122,3 +1122,31 @@ describe('doctor says why it skipped and what it checked', () => {);});});++describe('no Astryx-owned environment variables (spec:AST-017 FR14)', () => {+ it('no source file reads an ASTRYX_* env var', () => {+ const cliDir = path.resolve(REPO, 'packages/cli');+ const SKIP = new Set(['node_modules', 'dist', 'coverage']);+ const ENV_READ = /process\.env(?:\.|\[\s*['"`])ASTRYX_/;+ /** @type {string[]} */+ const hits = [];+ /** @param {string} dir */+ const walk = dir => {+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {+ if (SKIP.has(entry.name)) continue;+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) {+ walk(full);+ continue;+ }+ if (!/\.[cm]?[jt]sx?$/.test(entry.name)) continue;+ if (/\.test\.|\.d\.[cm]?ts$/.test(entry.name)) continue;+ if (ENV_READ.test(fs.readFileSync(full, 'utf8'))) {+ hits.push(path.relative(cliDir, full));+ }+ }+ };+ walk(cliDir);+ expect(hits).toEqual([]);+ });+});diff --git a/packages/cli/api/gap-report/gap-report.test.mjs b/packages/cli/api/gap-report/gap-report.test.mjsindex edd3b8de1a..f6e3dbffc6 100644--- a/packages/cli/api/gap-report/gap-report.test.mjs+++ b/packages/cli/api/gap-report/gap-report.test.mjs@@ -1195,7 +1195,7 @@ describe('gapReport aggregate status and CLI exit', () => {`,});configure(['@test/inspector']);- vi.stubEnv('ASTRYX_AGENT_ID', 'secret-agent');+ vi.stubEnv('AGENT', 'secret-agent');const result = await gapReport('Button', {...reportOptions,diff --git a/packages/cli/authoring/debug/type.ts b/packages/cli/authoring/debug/type.tsindex d0d4a338bc..81fb081339 100644--- a/packages/cli/authoring/debug/type.ts+++ b/packages/cli/authoring/debug/type.ts@@ -176,8 +176,8 @@ export interface DebugEventEnv {/** 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. Scrubbed.+ * Coding-agent identity from `AGENT` or a known public agent signal.+ * Scrubbed.*/agentIdentity: string | null;/**diff --git a/packages/cli/foundation/debug/debug-fields.test.mjs b/packages/cli/foundation/debug/debug-fields.test.mjsindex ddd550fc74..85c6c3134e 100644--- a/packages/cli/foundation/debug/debug-fields.test.mjs+++ b/packages/cli/foundation/debug/debug-fields.test.mjs@@ -20,9 +20,6 @@ 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',@@ -262,14 +259,14 @@ describe('DebugEvent additive fields', () => {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');+ vi.stubEnv('AGENT', 'test-agent');+ vi.stubEnv('AGENT_SESSION_ID', 'agent-session-123');const env = captureEnv();expect(env).toMatchObject({agent: 'test-agent',agentIdentity: 'test-agent',agentSessionId: null,- agentSessionIdSource: 'ASTRYX_AGENT_SESSION_ID',+ agentSessionIdSource: 'AGENT_SESSION_ID',invocationSource: 'ai',});expect(env.agentSessionIdHash).toBe(@@ -287,40 +284,21 @@ describe('environment attribution', () => {});});- it('parses comma-separated metadata', () => {+ it('reads no Astryx-owned or metadata variable for attribution', () => {clearAttributionEnv();+ // The removed variables, set: none of them attributes the run.+ vi.stubEnv('ASTRYX_AGENT_ID', 'old-agent');+ vi.stubEnv('ASTRYX_AGENT_SESSION_ID', 'old-session');vi.stubEnv('ASTRYX_AGENT_METADATA',- 'id=future-agent,invocation_id=future-session,malformed',+ 'id=old-agent,session_id=old-session,invocation_id=old-invocation',);- const env = captureEnv();- expect(env).toMatchObject({- agentIdentity: 'future-agent',- agentSessionId: null,- agentSessionIdSource: 'ASTRYX_AGENT_METADATA.invocation_id',- invocationSource: 'ai',- });- expect(env.agentSessionIdHash).toBe(- createHash('sha256').update('future-session', 'utf8').digest('hex'),- );- });-- it('parses JSON metadata', () => {- clearAttributionEnv();- vi.stubEnv(- 'ASTRYX_AGENT_METADATA',- JSON.stringify({id: 'json-agent', session_id: 'json-session'}),- );- const env = captureEnv();- expect(env).toMatchObject({- agentIdentity: 'json-agent',- agentSessionId: null,- agentSessionIdSource: 'ASTRYX_AGENT_METADATA.session_id',- invocationSource: 'ai',+ vi.stubEnv('AGENT_METADATA', JSON.stringify({id: 'meta-agent'}));+ expect(captureEnv()).toMatchObject({+ agentIdentity: null,+ agentSessionIdHash: null,+ agentSessionIdSource: null,});- expect(env.agentSessionIdHash).toBe(- createHash('sha256').update('json-session', 'utf8').digest('hex'),- );});it('leaves agent fields null without a signal', () => {diff --git a/packages/cli/foundation/debug/event.mjs b/packages/cli/foundation/debug/event.mjsindex a20419edcf..bb574729af 100644--- a/packages/cli/foundation/debug/event.mjs+++ b/packages/cli/foundation/debug/event.mjs@@ -123,56 +123,12 @@ function nonEmptyString(value) {}/**- * 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>}+ * Agent identity: the generic AGENT variable, else the first positive+ * coding-agent signal. ASTRYX_AGENT_ID and ASTRYX_AGENT_METADATA are not read+ * (spec:AST-017 FR14), and no replacement metadata variable is introduced.+ * @returns {string | null}*/-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();-+function detectAgentIdentity() {const genericAgent = nonEmptyString(process.env.AGENT);if (genericAgent) return genericAgent.toLowerCase();@@ -182,9 +138,7 @@ function detectAgentIdentity(metadata) {)) {if (process.env[key]) return name;}-- const metadataId = nonEmptyString(metadata.id);- return metadataId ? metadataId.toLowerCase() : null;+ return null;}/** @param {string | null} identity @returns {string | null} */@@ -199,29 +153,13 @@ function detectAgent(identity) {}/**- * @param {Record<string, string>} metadata+ * Agent session: the generic AGENT_SESSION_ID variable. ASTRYX_AGENT_SESSION_ID+ * and ASTRYX_AGENT_METADATA are not read (spec:AST-017 FR14).* @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};+function detectAgentSession() {+ const id = nonEmptyString(process.env.AGENT_SESSION_ID);+ return id ? {id, source: 'AGENT_SESSION_ID'} : {id: null, source: null};}/** @param {string | null} id @returns {string | null} */@@ -254,11 +192,8 @@ function detectInvocationSource({agentIdentity, agentSessionId, ci}) {*/export function captureEnv({cliVersion} = {}) {const {ci, ciName} = detectCi();- const agentMetadata = parseCodingAgentMetadata(- process.env.ASTRYX_AGENT_METADATA,- );- const agentIdentity = detectAgentIdentity(agentMetadata);- const agentSession = detectAgentSession(agentMetadata);+ const agentIdentity = detectAgentIdentity();+ const agentSession = detectAgentSession();return {cliVersion: cliVersion ?? null,nodeVersion: process.versions.node,diff --git a/packages/cli/foundation/debug/privacy-contract.test.mjs b/packages/cli/foundation/debug/privacy-contract.test.mjsindex aed09e8a84..6f48d15cbb 100644--- a/packages/cli/foundation/debug/privacy-contract.test.mjs+++ b/packages/cli/foundation/debug/privacy-contract.test.mjs@@ -61,30 +61,38 @@ afterEach(() => {describe('no raw stable identifier is recorded', () => {it('hands the handler the hash and never the session id itself', () => {- vi.stubEnv('ASTRYX_AGENT_ID', 'astryx-test-agent');- vi.stubEnv('ASTRYX_AGENT_SESSION_ID', RAW_SESSION);+ vi.stubEnv('AGENT', 'astryx-test-agent');+ vi.stubEnv('AGENT_SESSION_ID', RAW_SESSION);const event = collectEvent();expect(event.env.agentSessionId).toBe(null);expect(event.env.agentSessionIdHash).toBe(RAW_SESSION_HASH);- expect(event.env.agentSessionIdSource).toBe('ASTRYX_AGENT_SESSION_ID');+ expect(event.env.agentSessionIdSource).toBe('AGENT_SESSION_ID');// Not just the field: nowhere in the record at all.expect(JSON.stringify(event)).not.toContain(RAW_SESSION);});- it('never records one from the metadata env var either', () => {+ it('reads no Astryx-owned variable, so a session left in one is never recorded', () => {+ // spec:AST-017 FR14: the CLI reads no Astryx-owned environment variable.+ // A value left in a removed one records nothing, raw or hashed.+ vi.stubEnv('AGENT', '');+ vi.stubEnv('AGENT_SESSION_ID', '');+ vi.stubEnv('ASTRYX_AGENT_ID', 'metadata-agent');+ vi.stubEnv('ASTRYX_AGENT_SESSION_ID', RAW_SESSION);vi.stubEnv('ASTRYX_AGENT_METADATA',JSON.stringify({id: 'metadata-agent', session_id: RAW_SESSION}),);const event = collectEvent();expect(event.env.agentSessionId).toBe(null);- expect(event.env.agentSessionIdHash).toBe(RAW_SESSION_HASH);+ expect(event.env.agentSessionIdHash).toBe(null);+ expect(event.env.agentSessionIdSource).toBe(null);expect(JSON.stringify(event)).not.toContain(RAW_SESSION);+ expect(JSON.stringify(event)).not.toContain('metadata-agent');});it('still joins runs of one session, which is what the raw value was for', () => {- vi.stubEnv('ASTRYX_AGENT_SESSION_ID', RAW_SESSION);+ vi.stubEnv('AGENT_SESSION_ID', RAW_SESSION);const first = collectEvent().env.agentSessionIdHash;resetRecorder();const second = collectEvent().env.agentSessionIdHash;@@ -101,9 +109,9 @@ describe('no raw stable identifier is recorded', () => {describe('environment free text is scrubbed', () => {it('scrubs a credential pasted into the agent identity', () => {- // ASTRYX_AGENT_ID is free text: whatever the invoking tool exports lands+ // AGENT is free text: whatever the invoking tool exports lands// here, and `env` used to skip the scrubbing pass entirely.- vi.stubEnv('ASTRYX_AGENT_ID', 'ghp_abcdefghijklmnopqrstuvwxyz01');+ vi.stubEnv('AGENT', 'ghp_abcdefghijklmnopqrstuvwxyz01');const event = collectEvent();expect(event.env.agentIdentity).toBe(REDACTED);expect(event.env.agent).toBe(REDACTED);@@ -117,7 +125,7 @@ describe('environment free text is scrubbed', () => {});it('rewrites an absolute path in the agent identity', () => {- vi.stubEnv('ASTRYX_AGENT_ID', '/users/someone/tools/my-agent');+ vi.stubEnv('AGENT', '/users/someone/tools/my-agent');const event = collectEvent();expect(event.env.agentIdentity).not.toContain('/users/someone');expect(event.env.agentIdentity).toContain('…');@@ -125,7 +133,7 @@ describe('environment free text is scrubbed', () => {it('keeps ordinary free text readable', () => {// Scrubbing that ate every agent name would make the field worthless.- vi.stubEnv('ASTRYX_AGENT_ID', 'astryx-test-agent');+ vi.stubEnv('AGENT', 'astryx-test-agent');expect(collectEvent().env.agentIdentity).toBe('astryx-test-agent');});});@@ -135,11 +143,11 @@ describe('derived environment facts survive verbatim', () => {// `isSensitiveKey` matches the substring "session", so a key-based pass// over `env` would blank the hash — and with it the only way to join the// runs of one session, which is the whole reason the raw id can go.- vi.stubEnv('ASTRYX_AGENT_SESSION_ID', RAW_SESSION);+ vi.stubEnv('AGENT_SESSION_ID', RAW_SESSION);const event = collectEvent();expect(event.env.agentSessionIdHash).toBe(RAW_SESSION_HASH);expect(event.env.agentSessionIdHash).not.toBe(REDACTED);- expect(event.env.agentSessionIdSource).toBe('ASTRYX_AGENT_SESSION_ID');+ expect(event.env.agentSessionIdSource).toBe('AGENT_SESSION_ID');});it('keeps the machine and runtime facts exactly as captured', () => {diff --git a/packages/cli/foundation/debug/redact.mjs b/packages/cli/foundation/debug/redact.mjsindex a389108e13..ac182bc693 100644--- a/packages/cli/foundation/debug/redact.mjs+++ b/packages/cli/foundation/debug/redact.mjs@@ -407,8 +407,8 @@ export function createRedactor({* and their exact values are the whole reason the snapshot is useful.** Everything else in `env` is free text handed to us by the invoking- * environment — an agent name from `ASTRYX_AGENT_ID`, `AGENT`, or- * `ASTRYX_AGENT_METADATA` — so it goes through the same content rules as argv.+ * environment — an agent name from `AGENT` or a known agent signal — so it+ * goes through the same content rules as argv.* The list is a positive allowlist rather than a denylist of risky fields: a* field added to the snapshot later is scrubbed until someone decides* otherwise, which is the safe direction to be wrong in.