Skip to content

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.md
new file mode 100644
index 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.mjs
index 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.mjs
index 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.ts
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.