@evalops/maestro 0.10.18 → 0.10.21

package/dist/telemetry/agent-operating-plane-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-operating-plane-context.js","sourceRoot":"","sources":["../../src/telemetry/agent-operating-plane-context.ts"],"names":[],"mappings":"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","sourcesContent":["import type { MaestroCorrelation } from \"./maestro-event-bus.js\";\n\nexport type AgentOperatingPlaneDataClassification =\n\t| \"public\"\n\t| \"internal\"\n\t| \"customer\"\n\t| \"restricted\";\n\nexport type AgentOperatingPlaneRetentionClass =\n\t| \"ephemeral\"\n\t| \"operational_audit\"\n\t| \"security_audit\"\n\t| \"legal_hold\";\n\nexport interface AgentOperatingPlaneCorrelationInput\n\textends Partial<MaestroCorrelation> {\n\tworkspace_id: string;\n\tsession_id: string;\n}\n\nexport interface AgentOperatingPlaneMetadataInput {\n\tdataClassification?: AgentOperatingPlaneDataClassification;\n\tretentionClass?: AgentOperatingPlaneRetentionClass;\n\tsafeSummary?: string;\n}\n\nexport interface AgentOperatingPlaneContextInput {\n\tcorrelation: AgentOperatingPlaneCorrelationInput;\n\tmetadata?: AgentOperatingPlaneMetadataInput;\n}\n\nexport interface AgentOperatingPlaneContext {\n\tcorrelation: MaestroCorrelation;\n\tmetadata: Record<string, string>;\n}\n\nfunction cleanString(value: string | undefined): string | undefined {\n\tconst cleanValue = value?.trim();\n\treturn cleanValue ? cleanValue : undefined;\n}\n\nfunction compactStringRecord(\n\trecord: Record<string, string> | undefined,\n): Record<string, string> | undefined {\n\tif (!record) return undefined;\n\tconst compacted = Object.fromEntries(\n\t\tObject.entries(record)\n\t\t\t.map(([key, value]) => [key, cleanString(value)] as const)\n\t\t\t.filter((entry): entry is readonly [string, string] => Boolean(entry[1])),\n\t);\n\treturn Object.keys(compacted).length > 0 ? compacted : undefined;\n}\n\nexport function buildAgentOperatingPlaneCorrelation(\n\tinput: AgentOperatingPlaneCorrelationInput,\n): MaestroCorrelation {\n\treturn {\n\t\torganization_id: cleanString(input.organization_id),\n\t\tuser_id: cleanString(input.user_id),\n\t\tworkspace_id: cleanString(input.workspace_id) ?? \"unknown\",\n\t\tsession_id: cleanString(input.session_id) ?? \"unknown\",\n\t\tagent_run_id: cleanString(input.agent_run_id),\n\t\tagent_run_step_id: cleanString(input.agent_run_step_id),\n\t\tagent_id: cleanString(input.agent_id),\n\t\tactor_id: cleanString(input.actor_id),\n\t\tprincipal_id: cleanString(input.principal_id),\n\t\ttrace_id: cleanString(input.trace_id),\n\t\ttraceparent: cleanString(input.traceparent),\n\t\ttracestate: cleanString(input.tracestate),\n\t\trequest_id: cleanString(input.request_id),\n\t\tparent_event_id: cleanString(input.parent_event_id),\n\t\tremote_runner_session_id: cleanString(input.remote_runner_session_id),\n\t\tobjective_id: cleanString(input.objective_id),\n\t\tconversation_id: cleanString(input.conversation_id),\n\t\tattributes: compactStringRecord(input.attributes),\n\t};\n}\n\nexport function buildAgentOperatingPlaneMetadata(\n\tinput: AgentOperatingPlaneMetadataInput = {},\n): Record<string, string> {\n\tconst metadata: Record<string, string> = {};\n\tconst dataClassification = cleanString(input.dataClassification);\n\tconst retentionClass = cleanString(input.retentionClass);\n\tconst safeSummary = cleanString(input.safeSummary);\n\tif (dataClassification) metadata.data_classification = dataClassification;\n\tif (retentionClass) metadata.retention_class = retentionClass;\n\tif (safeSummary) metadata.safe_summary = safeSummary;\n\treturn metadata;\n}\n\nexport function buildAgentOperatingPlaneContext(\n\tinput: AgentOperatingPlaneContextInput,\n): AgentOperatingPlaneContext {\n\treturn {\n\t\tcorrelation: buildAgentOperatingPlaneCorrelation(input.correlation),\n\t\tmetadata: buildAgentOperatingPlaneMetadata(input.metadata),\n\t};\n}\n"]}

package/dist/telemetry/beacon.d.ts

@@ -0,0 +1,24 @@
+export interface BeaconEvent {
+    feature: string;
+    action: string;
+    timestamp: number;
+    source: {
+        client: string;
+        clientVersion: string;
+        surface?: string;
+    };
+    parameters?: {
+        metadata?: Record<string, unknown>;
+        sensitiveMetadata?: Record<string, unknown>;
+    };
+}
+export interface EmitBeaconOptions {
+    env?: NodeJS.ProcessEnv;
+    fetchFn?: typeof fetch;
+}
+export declare function beaconTimeoutMs(env: NodeJS.ProcessEnv): number;
+export declare function isBeaconEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function normalizeBeaconEvent(event: BeaconEvent): BeaconEvent;
+export declare function emitBeacon(event: BeaconEvent, options?: EmitBeaconOptions): Promise<boolean>;
+export declare function emitBeaconBatch(events: BeaconEvent[], options?: EmitBeaconOptions): Promise<boolean>;
+//# sourceMappingURL=beacon.d.ts.map

package/dist/telemetry/beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../../src/telemetry/beacon.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,CAAC,EAAE;QACZ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC;CACF;AAED,MAAM,WAAW,iBAAiB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACvB;AA0BD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAG9D;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAY7E;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAUpE;AAED,wBAAsB,UAAU,CAC/B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,iBAAsB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,eAAe,CACpC,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,GAAE,iBAAsB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAwBlB"}

package/dist/telemetry/beacon.js

@@ -0,0 +1,115 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolveEnvPath } from "../utils/path-expansion.js";
+import { isInternalTelemetryDisabled } from "./disablement.js";
+import { normalizeTelemetryMetadataInputs } from "./metadata-normalization.js";
+const telemetryFlag = (env) => env.MAESTRO_TELEMETRY ?? env.PLAYWRIGHT_TELEMETRY;
+function beaconEndpoint(env) {
+    return (env.MAESTRO_BEACON_ENDPOINT ??
+        env.MAESTRO_TELEMETRY_ENDPOINT ??
+        env.PLAYWRIGHT_TELEMETRY_ENDPOINT);
+}
+function beaconFile(env) {
+    return resolveEnvPath(env.MAESTRO_BEACON_FILE) ?? undefined;
+}
+function sampleRate(env) {
+    const raw = env.MAESTRO_TELEMETRY_SAMPLE ?? env.PLAYWRIGHT_TELEMETRY_SAMPLE;
+    if (!raw) {
+        return 1;
+    }
+    const parsed = Number.parseFloat(raw);
+    return Number.isNaN(parsed) ? 1 : Math.min(Math.max(parsed, 0), 1);
+}
+export function beaconTimeoutMs(env) {
+    const parsed = Number.parseInt(env.MAESTRO_BEACON_TIMEOUT_MS ?? "100", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 100;
+}
+export function isBeaconEnabled(env = process.env) {
+    if (isInternalTelemetryDisabled(env)) {
+        return false;
+    }
+    const flag = telemetryFlag(env)?.toLowerCase();
+    if (flag === "0" || flag === "false") {
+        return false;
+    }
+    if (sampleRate(env) <= 0) {
+        return false;
+    }
+    return Boolean(beaconEndpoint(env) || beaconFile(env));
+}
+export function normalizeBeaconEvent(event) {
+    const { metadata, sensitiveMetadata } = event.parameters ?? {};
+    const normalizedMetadata = normalizeTelemetryMetadataInputs(metadata, sensitiveMetadata);
+    return {
+        ...event,
+        parameters: normalizedMetadata,
+    };
+}
+export async function emitBeacon(event, options = {}) {
+    return emitBeaconBatch([event], options);
+}
+export async function emitBeaconBatch(events, options = {}) {
+    const env = options.env ?? process.env;
+    if (!events.length || !isBeaconEnabled(env)) {
+        return false;
+    }
+    if (sampleRate(env) < 1 && Math.random() > sampleRate(env)) {
+        return false;
+    }
+    try {
+        const normalizedEvents = events.map(normalizeBeaconEvent);
+        const [fileEmitted, endpointEmitted] = await Promise.all([
+            writeBeaconFile(normalizedEvents, env).catch(() => false),
+            postBeaconEvents(normalizedEvents, env, options.fetchFn ?? globalThis.fetch).catch(() => false),
+        ]);
+        return fileEmitted || endpointEmitted;
+    }
+    catch {
+        // Beacon emission is best effort and must never affect CLI startup.
+        return false;
+    }
+}
+async function writeBeaconFile(events, env) {
+    const file = beaconFile(env);
+    if (!file) {
+        return false;
+    }
+    await mkdir(dirname(file), { recursive: true });
+    await appendFile(file, `${JSON.stringify(events)}\n`, "utf8");
+    return true;
+}
+async function postBeaconEvents(events, env, fetchFn) {
+    const endpoint = beaconEndpoint(env);
+    if (!endpoint || !fetchFn) {
+        return false;
+    }
+    try {
+        const headers = {
+            "content-type": "application/json",
+        };
+        const token = env.MAESTRO_BEACON_API_KEY;
+        if (token) {
+            headers.authorization = `Bearer ${token}`;
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), beaconTimeoutMs(env));
+        timeout.unref?.();
+        try {
+            const response = await fetchFn(endpoint, {
+                method: "POST",
+                headers,
+                signal: controller.signal,
+                body: JSON.stringify(events),
+            });
+            return response.ok;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // Beacon emission is best effort and must never affect CLI startup.
+        return false;
+    }
+}
+//# sourceMappingURL=beacon.js.map

package/dist/telemetry/beacon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.js","sourceRoot":"","sources":["../../src/telemetry/beacon.ts"],"names":[],"mappings":"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","sourcesContent":["import { appendFile, mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { resolveEnvPath } from \"../utils/path-expansion.js\";\nimport { isInternalTelemetryDisabled } from \"./disablement.js\";\nimport { normalizeTelemetryMetadataInputs } from \"./metadata-normalization.js\";\n\nexport interface BeaconEvent {\n\tfeature: string;\n\taction: string;\n\ttimestamp: number;\n\tsource: {\n\t\tclient: string;\n\t\tclientVersion: string;\n\t\tsurface?: string;\n\t};\n\tparameters?: {\n\t\tmetadata?: Record<string, unknown>;\n\t\tsensitiveMetadata?: Record<string, unknown>;\n\t};\n}\n\nexport interface EmitBeaconOptions {\n\tenv?: NodeJS.ProcessEnv;\n\tfetchFn?: typeof fetch;\n}\n\nconst telemetryFlag = (env: NodeJS.ProcessEnv): string | undefined =>\n\tenv.MAESTRO_TELEMETRY ?? env.PLAYWRIGHT_TELEMETRY;\n\nfunction beaconEndpoint(env: NodeJS.ProcessEnv): string | undefined {\n\treturn (\n\t\tenv.MAESTRO_BEACON_ENDPOINT ??\n\t\tenv.MAESTRO_TELEMETRY_ENDPOINT ??\n\t\tenv.PLAYWRIGHT_TELEMETRY_ENDPOINT\n\t);\n}\n\nfunction beaconFile(env: NodeJS.ProcessEnv): string | undefined {\n\treturn resolveEnvPath(env.MAESTRO_BEACON_FILE) ?? undefined;\n}\n\nfunction sampleRate(env: NodeJS.ProcessEnv): number {\n\tconst raw = env.MAESTRO_TELEMETRY_SAMPLE ?? env.PLAYWRIGHT_TELEMETRY_SAMPLE;\n\tif (!raw) {\n\t\treturn 1;\n\t}\n\tconst parsed = Number.parseFloat(raw);\n\treturn Number.isNaN(parsed) ? 1 : Math.min(Math.max(parsed, 0), 1);\n}\n\nexport function beaconTimeoutMs(env: NodeJS.ProcessEnv): number {\n\tconst parsed = Number.parseInt(env.MAESTRO_BEACON_TIMEOUT_MS ?? \"100\", 10);\n\treturn Number.isFinite(parsed) && parsed > 0 ? parsed : 100;\n}\n\nexport function isBeaconEnabled(env: NodeJS.ProcessEnv = process.env): boolean {\n\tif (isInternalTelemetryDisabled(env)) {\n\t\treturn false;\n\t}\n\tconst flag = telemetryFlag(env)?.toLowerCase();\n\tif (flag === \"0\" || flag === \"false\") {\n\t\treturn false;\n\t}\n\tif (sampleRate(env) <= 0) {\n\t\treturn false;\n\t}\n\treturn Boolean(beaconEndpoint(env) || beaconFile(env));\n}\n\nexport function normalizeBeaconEvent(event: BeaconEvent): BeaconEvent {\n\tconst { metadata, sensitiveMetadata } = event.parameters ?? {};\n\tconst normalizedMetadata = normalizeTelemetryMetadataInputs(\n\t\tmetadata,\n\t\tsensitiveMetadata,\n\t);\n\treturn {\n\t\t...event,\n\t\tparameters: normalizedMetadata,\n\t};\n}\n\nexport async function emitBeacon(\n\tevent: BeaconEvent,\n\toptions: EmitBeaconOptions = {},\n): Promise<boolean> {\n\treturn emitBeaconBatch([event], options);\n}\n\nexport async function emitBeaconBatch(\n\tevents: BeaconEvent[],\n\toptions: EmitBeaconOptions = {},\n): Promise<boolean> {\n\tconst env = options.env ?? process.env;\n\tif (!events.length || !isBeaconEnabled(env)) {\n\t\treturn false;\n\t}\n\tif (sampleRate(env) < 1 && Math.random() > sampleRate(env)) {\n\t\treturn false;\n\t}\n\n\ttry {\n\t\tconst normalizedEvents = events.map(normalizeBeaconEvent);\n\t\tconst [fileEmitted, endpointEmitted] = await Promise.all([\n\t\t\twriteBeaconFile(normalizedEvents, env).catch(() => false),\n\t\t\tpostBeaconEvents(\n\t\t\t\tnormalizedEvents,\n\t\t\t\tenv,\n\t\t\t\toptions.fetchFn ?? globalThis.fetch,\n\t\t\t).catch(() => false),\n\t\t]);\n\t\treturn fileEmitted || endpointEmitted;\n\t} catch {\n\t\t// Beacon emission is best effort and must never affect CLI startup.\n\t\treturn false;\n\t}\n}\n\nasync function writeBeaconFile(\n\tevents: BeaconEvent[],\n\tenv: NodeJS.ProcessEnv,\n): Promise<boolean> {\n\tconst file = beaconFile(env);\n\tif (!file) {\n\t\treturn false;\n\t}\n\tawait mkdir(dirname(file), { recursive: true });\n\tawait appendFile(file, `${JSON.stringify(events)}\\n`, \"utf8\");\n\treturn true;\n}\n\nasync function postBeaconEvents(\n\tevents: BeaconEvent[],\n\tenv: NodeJS.ProcessEnv,\n\tfetchFn: typeof fetch | undefined,\n): Promise<boolean> {\n\tconst endpoint = beaconEndpoint(env);\n\tif (!endpoint || !fetchFn) {\n\t\treturn false;\n\t}\n\ttry {\n\t\tconst headers: Record<string, string> = {\n\t\t\t\"content-type\": \"application/json\",\n\t\t};\n\t\tconst token = env.MAESTRO_BEACON_API_KEY;\n\t\tif (token) {\n\t\t\theaders.authorization = `Bearer ${token}`;\n\t\t}\n\t\tconst controller = new AbortController();\n\t\tconst timeout = setTimeout(() => controller.abort(), beaconTimeoutMs(env));\n\t\ttimeout.unref?.();\n\t\ttry {\n\t\t\tconst response = await fetchFn(endpoint, {\n\t\t\t\tmethod: \"POST\",\n\t\t\t\theaders,\n\t\t\t\tsignal: controller.signal,\n\t\t\t\tbody: JSON.stringify(events),\n\t\t\t});\n\t\t\treturn response.ok;\n\t\t} finally {\n\t\t\tclearTimeout(timeout);\n\t\t}\n\t} catch {\n\t\t// Beacon emission is best effort and must never affect CLI startup.\n\t\treturn false;\n\t}\n}\n"]}

package/dist/telemetry/cli-command-aggregator.d.ts

@@ -0,0 +1,36 @@
+export interface CliCommandAggregatorOptions {
+    bufferMs?: number;
+    clientVersion: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    bufferFile?: string;
+    lockTimeoutMs?: number;
+}
+export declare class CliCommandAggregator {
+    private readonly bufferMs;
+    private readonly clientVersion;
+    private readonly env;
+    private readonly now;
+    private readonly bufferFile;
+    private readonly lockTimeoutMs;
+    private timer;
+    constructor(options: CliCommandAggregatorOptions);
+    matchesOptions(options: CliCommandAggregatorOptions): boolean;
+    start(): void;
+    submit(command: string): Promise<void>;
+    flush(): Promise<void>;
+    private drainBuffer;
+    private restoreBuffer;
+    private withBufferLock;
+    private lockStaleMs;
+    dispose(): Promise<void>;
+    private buildCommandEvent;
+    private buildCommandEvents;
+    private readBuffer;
+    private writeBuffer;
+    private clearBuffer;
+}
+export declare function getGlobalCliCommandAggregator(options: CliCommandAggregatorOptions): CliCommandAggregator;
+export declare function resetGlobalCliCommandAggregatorForTests(): void;
+export declare function normalizeCommandAction(command: string): string;
+//# sourceMappingURL=cli-command-aggregator.d.ts.map

package/dist/telemetry/cli-command-aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command-aggregator.d.ts","sourceRoot":"","sources":["../../src/telemetry/cli-command-aggregator.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAaD,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,KAAK,CAA+B;gBAEhC,OAAO,EAAE,2BAA2B;IAYhD,cAAc,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO;IAiB7D,KAAK,IAAI,IAAI;IAUP,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAgBd,WAAW;YAcX,aAAa;YAcb,cAAc;IAkC5B,OAAO,CAAC,WAAW;IAIb,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,kBAAkB;YAMZ,UAAU;YAsCV,WAAW;YAcX,WAAW;CAGzB;AAED,wBAAgB,6BAA6B,CAC5C,OAAO,EAAE,2BAA2B,GAClC,oBAAoB,CAMtB;AAED,wBAAgB,uCAAuC,IAAI,IAAI,CAE9D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG9D"}

package/dist/telemetry/cli-command-aggregator.js

@@ -0,0 +1,251 @@
+import { open, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { PATHS } from "../config/constants.js";
+import { emitBeaconBatch, isBeaconEnabled, } from "./beacon.js";
+const DEFAULT_BUFFER_MS = 10_000;
+const LOCK_RETRY_MS = 5;
+const DEFAULT_LOCK_TIMEOUT_MS = 5_000;
+const LOCK_STALE_GRACE_MS = 1_000;
+let globalAggregator = null;
+export class CliCommandAggregator {
+    constructor(options) {
+        this.timer = null;
+        this.bufferMs = options.bufferMs ?? DEFAULT_BUFFER_MS;
+        this.clientVersion = options.clientVersion;
+        this.env = options.env ?? process.env;
+        this.now = options.now ?? Date.now;
+        this.bufferFile =
+            options.bufferFile ??
+                this.env.MAESTRO_CLI_COMMAND_BEACON_BUFFER_FILE ??
+                join(PATHS.MAESTRO_HOME, "telemetry-cli-command-counts.json");
+        this.lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+    }
+    matchesOptions(options) {
+        const env = options.env ?? process.env;
+        const now = options.now ?? Date.now;
+        const bufferFile = options.bufferFile ??
+            env.MAESTRO_CLI_COMMAND_BEACON_BUFFER_FILE ??
+            join(PATHS.MAESTRO_HOME, "telemetry-cli-command-counts.json");
+        return (this.bufferMs === (options.bufferMs ?? DEFAULT_BUFFER_MS) &&
+            this.clientVersion === options.clientVersion &&
+            this.env === env &&
+            this.now === now &&
+            this.bufferFile === bufferFile &&
+            this.lockTimeoutMs === (options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS));
+    }
+    start() {
+        if (this.timer || !isBeaconEnabled(this.env)) {
+            return;
+        }
+        this.timer = setInterval(() => {
+            void this.flush().catch(() => undefined);
+        }, this.bufferMs);
+        this.timer.unref?.();
+    }
+    async submit(command) {
+        if (!isBeaconEnabled(this.env)) {
+            return;
+        }
+        const action = normalizeCommandAction(command);
+        let shouldFlush = false;
+        let shouldStartTimer = false;
+        await this.withBufferLock(async () => {
+            const buffer = await this.readBuffer();
+            buffer.counts[action] = (buffer.counts[action] ?? 0) + 1;
+            if (this.now() - buffer.lastFlushAt >= this.bufferMs) {
+                await this.writeBuffer(buffer);
+                shouldFlush = true;
+                return;
+            }
+            await this.writeBuffer(buffer);
+            shouldStartTimer = true;
+        });
+        if (shouldFlush) {
+            await this.flush();
+            return;
+        }
+        if (shouldStartTimer) {
+            this.start();
+        }
+    }
+    async flush() {
+        if (!isBeaconEnabled(this.env)) {
+            return;
+        }
+        const buffer = await this.drainBuffer();
+        if (!buffer) {
+            return;
+        }
+        const emitted = await emitBeaconBatch(this.buildCommandEvents(buffer), {
+            env: this.env,
+        });
+        if (!emitted) {
+            await this.restoreBuffer(buffer);
+        }
+    }
+    async drainBuffer() {
+        let drained = null;
+        await this.withBufferLock(async () => {
+            const buffer = await this.readBuffer();
+            if (!this.buildCommandEvents(buffer).length) {
+                await this.writeBuffer({ lastFlushAt: this.now(), counts: {} });
+                return;
+            }
+            drained = buffer;
+            await this.clearBuffer();
+        });
+        return drained;
+    }
+    async restoreBuffer(buffer) {
+        await this.withBufferLock(async () => {
+            const current = await this.readBuffer();
+            const counts = { ...current.counts };
+            for (const [action, count] of Object.entries(buffer.counts)) {
+                counts[action] = (counts[action] ?? 0) + count;
+            }
+            await this.writeBuffer({
+                lastFlushAt: Math.min(current.lastFlushAt, buffer.lastFlushAt),
+                counts,
+            });
+        });
+    }
+    async withBufferLock(operation) {
+        const lockFile = `${this.bufferFile}.lock`;
+        const deadline = Date.now() + this.lockTimeoutMs;
+        let handle;
+        while (!handle) {
+            try {
+                handle = await open(lockFile, "wx");
+                break;
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === "ENOENT") {
+                    await mkdirForFile(lockFile);
+                    continue;
+                }
+                if (code === "EEXIST" &&
+                    (await removeStaleLock(lockFile, this.lockStaleMs()))) {
+                    continue;
+                }
+                if (code !== "EEXIST" || Date.now() >= deadline) {
+                    return;
+                }
+                await sleep(LOCK_RETRY_MS, undefined, { ref: false });
+            }
+        }
+        try {
+            await operation();
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+            await rm(lockFile, { force: true }).catch(() => undefined);
+        }
+    }
+    lockStaleMs() {
+        return this.lockTimeoutMs + LOCK_STALE_GRACE_MS;
+    }
+    async dispose() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.flush();
+    }
+    buildCommandEvent(action, count) {
+        return {
+            feature: "cli.command",
+            action,
+            timestamp: this.now() * 1000,
+            source: {
+                client: "cli",
+                clientVersion: this.clientVersion,
+            },
+            parameters: {
+                metadata: {
+                    count,
+                },
+            },
+        };
+    }
+    buildCommandEvents(buffer) {
+        return Object.entries(buffer.counts)
+            .filter(([, count]) => count > 0)
+            .map(([action, count]) => this.buildCommandEvent(action, count));
+    }
+    async readBuffer() {
+        try {
+            const parsed = JSON.parse(await readFile(this.bufferFile, "utf8"));
+            const counts = {};
+            if (parsed.counts &&
+                typeof parsed.counts === "object" &&
+                !Array.isArray(parsed.counts)) {
+                for (const [key, value] of Object.entries(parsed.counts)) {
+                    if (typeof value === "number" &&
+                        Number.isFinite(value) &&
+                        value > 0) {
+                        counts[key] = value;
+                    }
+                }
+            }
+            return {
+                lastFlushAt: typeof parsed.lastFlushAt === "number" &&
+                    Number.isFinite(parsed.lastFlushAt)
+                    ? parsed.lastFlushAt
+                    : this.now(),
+                counts,
+            };
+        }
+        catch {
+            return {
+                lastFlushAt: this.now(),
+                counts: {},
+            };
+        }
+    }
+    async writeBuffer(buffer) {
+        await writeFile(this.bufferFile, `${JSON.stringify(buffer)}\n`, "utf8").catch(async (error) => {
+            if (error.code !== "ENOENT") {
+                return;
+            }
+            await mkdirForFile(this.bufferFile);
+            await writeFile(this.bufferFile, `${JSON.stringify(buffer)}\n`, "utf8");
+        });
+    }
+    async clearBuffer() {
+        await rm(this.bufferFile, { force: true });
+    }
+}
+export function getGlobalCliCommandAggregator(options) {
+    if (!globalAggregator?.matchesOptions(options)) {
+        void globalAggregator?.dispose().catch(() => undefined);
+        globalAggregator = new CliCommandAggregator(options);
+    }
+    return globalAggregator;
+}
+export function resetGlobalCliCommandAggregatorForTests() {
+    globalAggregator = null;
+}
+export function normalizeCommandAction(command) {
+    const trimmed = command.trim();
+    return `cli.command.${trimmed.length > 0 ? trimmed : "interactive"}`;
+}
+async function mkdirForFile(file) {
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(dirname(file), { recursive: true });
+}
+async function removeStaleLock(lockFile, staleAfterMs) {
+    try {
+        const lock = await stat(lockFile);
+        if (Date.now() - lock.mtimeMs < staleAfterMs) {
+            return false;
+        }
+        await rm(lockFile, { force: true });
+        return true;
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+}
+//# sourceMappingURL=cli-command-aggregator.js.map

package/dist/telemetry/cli-command-aggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command-aggregator.js","sourceRoot":"","sources":["../../src/telemetry/cli-command-aggregator.ts"],"names":[],"mappings":"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","sourcesContent":["import { open, readFile, rm, stat, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { setTimeout as sleep } from \"node:timers/promises\";\nimport { PATHS } from \"../config/constants.js\";\nimport {\n\ttype BeaconEvent,\n\temitBeaconBatch,\n\tisBeaconEnabled,\n} from \"./beacon.js\";\n\nexport interface CliCommandAggregatorOptions {\n\tbufferMs?: number;\n\tclientVersion: string;\n\tenv?: NodeJS.ProcessEnv;\n\tnow?: () => number;\n\tbufferFile?: string;\n\tlockTimeoutMs?: number;\n}\n\ninterface CliCommandBuffer {\n\tlastFlushAt: number;\n\tcounts: Record<string, number>;\n}\n\nconst DEFAULT_BUFFER_MS = 10_000;\nconst LOCK_RETRY_MS = 5;\nconst DEFAULT_LOCK_TIMEOUT_MS = 5_000;\nconst LOCK_STALE_GRACE_MS = 1_000;\nlet globalAggregator: CliCommandAggregator | null = null;\n\nexport class CliCommandAggregator {\n\tprivate readonly bufferMs: number;\n\tprivate readonly clientVersion: string;\n\tprivate readonly env: NodeJS.ProcessEnv;\n\tprivate readonly now: () => number;\n\tprivate readonly bufferFile: string;\n\tprivate readonly lockTimeoutMs: number;\n\tprivate timer: NodeJS.Timeout | null = null;\n\n\tconstructor(options: CliCommandAggregatorOptions) {\n\t\tthis.bufferMs = options.bufferMs ?? DEFAULT_BUFFER_MS;\n\t\tthis.clientVersion = options.clientVersion;\n\t\tthis.env = options.env ?? process.env;\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.bufferFile =\n\t\t\toptions.bufferFile ??\n\t\t\tthis.env.MAESTRO_CLI_COMMAND_BEACON_BUFFER_FILE ??\n\t\t\tjoin(PATHS.MAESTRO_HOME, \"telemetry-cli-command-counts.json\");\n\t\tthis.lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;\n\t}\n\n\tmatchesOptions(options: CliCommandAggregatorOptions): boolean {\n\t\tconst env = options.env ?? process.env;\n\t\tconst now = options.now ?? Date.now;\n\t\tconst bufferFile =\n\t\t\toptions.bufferFile ??\n\t\t\tenv.MAESTRO_CLI_COMMAND_BEACON_BUFFER_FILE ??\n\t\t\tjoin(PATHS.MAESTRO_HOME, \"telemetry-cli-command-counts.json\");\n\t\treturn (\n\t\t\tthis.bufferMs === (options.bufferMs ?? DEFAULT_BUFFER_MS) &&\n\t\t\tthis.clientVersion === options.clientVersion &&\n\t\t\tthis.env === env &&\n\t\t\tthis.now === now &&\n\t\t\tthis.bufferFile === bufferFile &&\n\t\t\tthis.lockTimeoutMs === (options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS)\n\t\t);\n\t}\n\n\tstart(): void {\n\t\tif (this.timer || !isBeaconEnabled(this.env)) {\n\t\t\treturn;\n\t\t}\n\t\tthis.timer = setInterval(() => {\n\t\t\tvoid this.flush().catch(() => undefined);\n\t\t}, this.bufferMs);\n\t\tthis.timer.unref?.();\n\t}\n\n\tasync submit(command: string): Promise<void> {\n\t\tif (!isBeaconEnabled(this.env)) {\n\t\t\treturn;\n\t\t}\n\t\tconst action = normalizeCommandAction(command);\n\t\tlet shouldFlush = false;\n\t\tlet shouldStartTimer = false;\n\t\tawait this.withBufferLock(async () => {\n\t\t\tconst buffer = await this.readBuffer();\n\t\t\tbuffer.counts[action] = (buffer.counts[action] ?? 0) + 1;\n\t\t\tif (this.now() - buffer.lastFlushAt >= this.bufferMs) {\n\t\t\t\tawait this.writeBuffer(buffer);\n\t\t\t\tshouldFlush = true;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tawait this.writeBuffer(buffer);\n\t\t\tshouldStartTimer = true;\n\t\t});\n\t\tif (shouldFlush) {\n\t\t\tawait this.flush();\n\t\t\treturn;\n\t\t}\n\t\tif (shouldStartTimer) {\n\t\t\tthis.start();\n\t\t}\n\t}\n\n\tasync flush(): Promise<void> {\n\t\tif (!isBeaconEnabled(this.env)) {\n\t\t\treturn;\n\t\t}\n\t\tconst buffer = await this.drainBuffer();\n\t\tif (!buffer) {\n\t\t\treturn;\n\t\t}\n\t\tconst emitted = await emitBeaconBatch(this.buildCommandEvents(buffer), {\n\t\t\tenv: this.env,\n\t\t});\n\t\tif (!emitted) {\n\t\t\tawait this.restoreBuffer(buffer);\n\t\t}\n\t}\n\n\tprivate async drainBuffer(): Promise<CliCommandBuffer | null> {\n\t\tlet drained: CliCommandBuffer | null = null;\n\t\tawait this.withBufferLock(async () => {\n\t\t\tconst buffer = await this.readBuffer();\n\t\t\tif (!this.buildCommandEvents(buffer).length) {\n\t\t\t\tawait this.writeBuffer({ lastFlushAt: this.now(), counts: {} });\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tdrained = buffer;\n\t\t\tawait this.clearBuffer();\n\t\t});\n\t\treturn drained;\n\t}\n\n\tprivate async restoreBuffer(buffer: CliCommandBuffer): Promise<void> {\n\t\tawait this.withBufferLock(async () => {\n\t\t\tconst current = await this.readBuffer();\n\t\t\tconst counts = { ...current.counts };\n\t\t\tfor (const [action, count] of Object.entries(buffer.counts)) {\n\t\t\t\tcounts[action] = (counts[action] ?? 0) + count;\n\t\t\t}\n\t\t\tawait this.writeBuffer({\n\t\t\t\tlastFlushAt: Math.min(current.lastFlushAt, buffer.lastFlushAt),\n\t\t\t\tcounts,\n\t\t\t});\n\t\t});\n\t}\n\n\tprivate async withBufferLock(operation: () => Promise<void>): Promise<void> {\n\t\tconst lockFile = `${this.bufferFile}.lock`;\n\t\tconst deadline = Date.now() + this.lockTimeoutMs;\n\t\tlet handle: Awaited<ReturnType<typeof open>> | undefined;\n\t\twhile (!handle) {\n\t\t\ttry {\n\t\t\t\thandle = await open(lockFile, \"wx\");\n\t\t\t\tbreak;\n\t\t\t} catch (error) {\n\t\t\t\tconst code = (error as NodeJS.ErrnoException).code;\n\t\t\t\tif (code === \"ENOENT\") {\n\t\t\t\t\tawait mkdirForFile(lockFile);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (\n\t\t\t\t\tcode === \"EEXIST\" &&\n\t\t\t\t\t(await removeStaleLock(lockFile, this.lockStaleMs()))\n\t\t\t\t) {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (code !== \"EEXIST\" || Date.now() >= deadline) {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tawait sleep(LOCK_RETRY_MS, undefined, { ref: false });\n\t\t\t}\n\t\t}\n\t\ttry {\n\t\t\tawait operation();\n\t\t} finally {\n\t\t\tawait handle.close().catch(() => undefined);\n\t\t\tawait rm(lockFile, { force: true }).catch(() => undefined);\n\t\t}\n\t}\n\n\tprivate lockStaleMs(): number {\n\t\treturn this.lockTimeoutMs + LOCK_STALE_GRACE_MS;\n\t}\n\n\tasync dispose(): Promise<void> {\n\t\tif (this.timer) {\n\t\t\tclearInterval(this.timer);\n\t\t\tthis.timer = null;\n\t\t}\n\t\tawait this.flush();\n\t}\n\n\tprivate buildCommandEvent(action: string, count: number): BeaconEvent {\n\t\treturn {\n\t\t\tfeature: \"cli.command\",\n\t\t\taction,\n\t\t\ttimestamp: this.now() * 1000,\n\t\t\tsource: {\n\t\t\t\tclient: \"cli\",\n\t\t\t\tclientVersion: this.clientVersion,\n\t\t\t},\n\t\t\tparameters: {\n\t\t\t\tmetadata: {\n\t\t\t\t\tcount,\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t}\n\n\tprivate buildCommandEvents(buffer: CliCommandBuffer): BeaconEvent[] {\n\t\treturn Object.entries(buffer.counts)\n\t\t\t.filter(([, count]) => count > 0)\n\t\t\t.map(([action, count]) => this.buildCommandEvent(action, count));\n\t}\n\n\tprivate async readBuffer(): Promise<CliCommandBuffer> {\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(await readFile(this.bufferFile, \"utf8\")) as {\n\t\t\t\tlastFlushAt?: unknown;\n\t\t\t\tcounts?: unknown;\n\t\t\t};\n\t\t\tconst counts: Record<string, number> = {};\n\t\t\tif (\n\t\t\t\tparsed.counts &&\n\t\t\t\ttypeof parsed.counts === \"object\" &&\n\t\t\t\t!Array.isArray(parsed.counts)\n\t\t\t) {\n\t\t\t\tfor (const [key, value] of Object.entries(parsed.counts)) {\n\t\t\t\t\tif (\n\t\t\t\t\t\ttypeof value === \"number\" &&\n\t\t\t\t\t\tNumber.isFinite(value) &&\n\t\t\t\t\t\tvalue > 0\n\t\t\t\t\t) {\n\t\t\t\t\t\tcounts[key] = value;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tlastFlushAt:\n\t\t\t\t\ttypeof parsed.lastFlushAt === \"number\" &&\n\t\t\t\t\tNumber.isFinite(parsed.lastFlushAt)\n\t\t\t\t\t\t? parsed.lastFlushAt\n\t\t\t\t\t\t: this.now(),\n\t\t\t\tcounts,\n\t\t\t};\n\t\t} catch {\n\t\t\treturn {\n\t\t\t\tlastFlushAt: this.now(),\n\t\t\t\tcounts: {},\n\t\t\t};\n\t\t}\n\t}\n\n\tprivate async writeBuffer(buffer: CliCommandBuffer): Promise<void> {\n\t\tawait writeFile(\n\t\t\tthis.bufferFile,\n\t\t\t`${JSON.stringify(buffer)}\\n`,\n\t\t\t\"utf8\",\n\t\t).catch(async (error: NodeJS.ErrnoException) => {\n\t\t\tif (error.code !== \"ENOENT\") {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tawait mkdirForFile(this.bufferFile);\n\t\t\tawait writeFile(this.bufferFile, `${JSON.stringify(buffer)}\\n`, \"utf8\");\n\t\t});\n\t}\n\n\tprivate async clearBuffer(): Promise<void> {\n\t\tawait rm(this.bufferFile, { force: true });\n\t}\n}\n\nexport function getGlobalCliCommandAggregator(\n\toptions: CliCommandAggregatorOptions,\n): CliCommandAggregator {\n\tif (!globalAggregator?.matchesOptions(options)) {\n\t\tvoid globalAggregator?.dispose().catch(() => undefined);\n\t\tglobalAggregator = new CliCommandAggregator(options);\n\t}\n\treturn globalAggregator;\n}\n\nexport function resetGlobalCliCommandAggregatorForTests(): void {\n\tglobalAggregator = null;\n}\n\nexport function normalizeCommandAction(command: string): string {\n\tconst trimmed = command.trim();\n\treturn `cli.command.${trimmed.length > 0 ? trimmed : \"interactive\"}`;\n}\n\nasync function mkdirForFile(file: string): Promise<void> {\n\tconst { mkdir } = await import(\"node:fs/promises\");\n\tawait mkdir(dirname(file), { recursive: true });\n}\n\nasync function removeStaleLock(\n\tlockFile: string,\n\tstaleAfterMs: number,\n): Promise<boolean> {\n\ttry {\n\t\tconst lock = await stat(lockFile);\n\t\tif (Date.now() - lock.mtimeMs < staleAfterMs) {\n\t\t\treturn false;\n\t\t}\n\t\tawait rm(lockFile, { force: true });\n\t\treturn true;\n\t} catch (error) {\n\t\treturn (error as NodeJS.ErrnoException).code === \"ENOENT\";\n\t}\n}\n"]}

package/dist/telemetry/cli-startup.d.ts

@@ -0,0 +1,21 @@
+export interface CliStartupArgs {
+    command?: string;
+    subcommand?: string;
+    version?: boolean;
+    help?: boolean;
+    error?: string;
+    headless?: boolean;
+    mode?: "text" | "json" | "rpc" | "headless";
+    messages: string[];
+}
+export interface RecordCliStartupTelemetryOptions {
+    args: CliStartupArgs;
+    clientVersion: string;
+    commandCountLockTimeoutMs?: number;
+    rawArgs?: string[];
+    now?: () => number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function cliCommandName(args: CliStartupArgs): string;
+export declare function recordCliStartupTelemetry(options: RecordCliStartupTelemetryOptions): Promise<void>;
+//# sourceMappingURL=cli-startup.d.ts.map

package/dist/telemetry/cli-startup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-startup.d.ts","sourceRoot":"","sources":["../../src/telemetry/cli-startup.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,cAAc;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;IAC5C,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,gCAAgC;IAChD,IAAI,EAAE,cAAc,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAyB3D;AAED,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,gCAAgC,GACvC,OAAO,CAAC,IAAI,CAAC,CA0Cf"}

package/dist/telemetry/cli-startup.js

@@ -0,0 +1,83 @@
+import { isLegacyHeadlessRuntimeRequested, willDispatchHeadlessRuntime, } from "../cli/headless-runtime-selection.js";
+import { emitBeacon } from "./beacon.js";
+import { getGlobalCliCommandAggregator } from "./cli-command-aggregator.js";
+export function cliCommandName(args) {
+    if (args.version) {
+        return "version";
+    }
+    if (args.help) {
+        return "help";
+    }
+    if (args.error) {
+        return "parse_error";
+    }
+    if (args.command) {
+        return args.subcommand
+            ? `${args.command}.${args.subcommand}`
+            : args.command;
+    }
+    if (args.headless || args.mode === "headless") {
+        return "headless";
+    }
+    if (args.mode === "rpc") {
+        return "rpc";
+    }
+    if (args.messages.length > 0) {
+        return args.mode === "json" ? "prompt.json" : "prompt.text";
+    }
+    return "interactive";
+}
+export async function recordCliStartupTelemetry(options) {
+    const env = options.env ?? process.env;
+    const now = options.now ?? Date.now;
+    const command = cliCommandName(options.args);
+    const mode = cliStartupMode(options.args, command);
+    await Promise.all([
+        emitBeacon({
+            feature: "cli.startup",
+            action: command,
+            timestamp: now() * 1000,
+            source: {
+                client: "cli",
+                clientVersion: options.clientVersion,
+                surface: options.args.headless || options.args.mode === "headless"
+                    ? "headless"
+                    : "cli",
+            },
+            parameters: {
+                metadata: {
+                    command,
+                    mode,
+                    hasPrompt: options.args.messages.length > 0,
+                    legacyRuntimeRequested: willDispatchHeadlessRuntime(options.args) &&
+                        isLegacyHeadlessRuntimeRequested(env),
+                    argCount: options.rawArgs?.length ?? 0,
+                },
+            },
+        }, { env }).catch(() => false),
+        getGlobalCliCommandAggregator({
+            clientVersion: options.clientVersion,
+            env,
+            lockTimeoutMs: options.commandCountLockTimeoutMs,
+            now,
+        })
+            .submit(command)
+            .catch(() => undefined),
+    ]);
+}
+function cliStartupMode(args, command) {
+    if (args.mode) {
+        return args.mode;
+    }
+    if (args.headless) {
+        return "headless";
+    }
+    if (command === "prompt.text") {
+        return "text";
+    }
+    if (command === "prompt.json") {
+        return "json";
+    }
+    return "interactive";
+}
+//# sourceMappingURL=cli-startup.js.map

package/dist/telemetry/cli-startup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-startup.js","sourceRoot":"","sources":["../../src/telemetry/cli-startup.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\tisLegacyHeadlessRuntimeRequested,\n\twillDispatchHeadlessRuntime,\n} from \"../cli/headless-runtime-selection.js\";\nimport { emitBeacon } from \"./beacon.js\";\nimport { getGlobalCliCommandAggregator } from \"./cli-command-aggregator.js\";\n\nexport interface CliStartupArgs {\n\tcommand?: string;\n\tsubcommand?: string;\n\tversion?: boolean;\n\thelp?: boolean;\n\terror?: string;\n\theadless?: boolean;\n\tmode?: \"text\" | \"json\" | \"rpc\" | \"headless\";\n\tmessages: string[];\n}\n\nexport interface RecordCliStartupTelemetryOptions {\n\targs: CliStartupArgs;\n\tclientVersion: string;\n\tcommandCountLockTimeoutMs?: number;\n\trawArgs?: string[];\n\tnow?: () => number;\n\tenv?: NodeJS.ProcessEnv;\n}\n\nexport function cliCommandName(args: CliStartupArgs): string {\n\tif (args.version) {\n\t\treturn \"version\";\n\t}\n\tif (args.help) {\n\t\treturn \"help\";\n\t}\n\tif (args.error) {\n\t\treturn \"parse_error\";\n\t}\n\tif (args.command) {\n\t\treturn args.subcommand\n\t\t\t? `${args.command}.${args.subcommand}`\n\t\t\t: args.command;\n\t}\n\tif (args.headless || args.mode === \"headless\") {\n\t\treturn \"headless\";\n\t}\n\tif (args.mode === \"rpc\") {\n\t\treturn \"rpc\";\n\t}\n\tif (args.messages.length > 0) {\n\t\treturn args.mode === \"json\" ? \"prompt.json\" : \"prompt.text\";\n\t}\n\treturn \"interactive\";\n}\n\nexport async function recordCliStartupTelemetry(\n\toptions: RecordCliStartupTelemetryOptions,\n): Promise<void> {\n\tconst env = options.env ?? process.env;\n\tconst now = options.now ?? Date.now;\n\tconst command = cliCommandName(options.args);\n\tconst mode = cliStartupMode(options.args, command);\n\tawait Promise.all([\n\t\temitBeacon(\n\t\t\t{\n\t\t\t\tfeature: \"cli.startup\",\n\t\t\t\taction: command,\n\t\t\t\ttimestamp: now() * 1000,\n\t\t\t\tsource: {\n\t\t\t\t\tclient: \"cli\",\n\t\t\t\t\tclientVersion: options.clientVersion,\n\t\t\t\t\tsurface:\n\t\t\t\t\t\toptions.args.headless || options.args.mode === \"headless\"\n\t\t\t\t\t\t\t? \"headless\"\n\t\t\t\t\t\t\t: \"cli\",\n\t\t\t\t},\n\t\t\t\tparameters: {\n\t\t\t\t\tmetadata: {\n\t\t\t\t\t\tcommand,\n\t\t\t\t\t\tmode,\n\t\t\t\t\t\thasPrompt: options.args.messages.length > 0,\n\t\t\t\t\t\tlegacyRuntimeRequested:\n\t\t\t\t\t\t\twillDispatchHeadlessRuntime(options.args) &&\n\t\t\t\t\t\t\tisLegacyHeadlessRuntimeRequested(env),\n\t\t\t\t\t\targCount: options.rawArgs?.length ?? 0,\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t\t{ env },\n\t\t).catch(() => false),\n\t\tgetGlobalCliCommandAggregator({\n\t\t\tclientVersion: options.clientVersion,\n\t\t\tenv,\n\t\t\tlockTimeoutMs: options.commandCountLockTimeoutMs,\n\t\t\tnow,\n\t\t})\n\t\t\t.submit(command)\n\t\t\t.catch(() => undefined),\n\t]);\n}\n\nfunction cliStartupMode(args: CliStartupArgs, command: string): string {\n\tif (args.mode) {\n\t\treturn args.mode;\n\t}\n\tif (args.headless) {\n\t\treturn \"headless\";\n\t}\n\tif (command === \"prompt.text\") {\n\t\treturn \"text\";\n\t}\n\tif (command === \"prompt.json\") {\n\t\treturn \"json\";\n\t}\n\treturn \"interactive\";\n}\n"]}

package/dist/telemetry/disablement.d.ts

@@ -0,0 +1,13 @@
+type TelemetryDisablementEnv = {
+    MAESTRO_INTERNAL_TELEMETRY_DISABLED?: string;
+    EVALOPS_INTERNAL_TELEMETRY_DISABLED?: string;
+};
+export type TelemetryDisablementSettings = {
+    internal?: {
+        telemetryDisabled?: boolean;
+    };
+};
+export declare function isInternalTelemetryDisabled(env?: TelemetryDisablementEnv): boolean;
+export declare function resolveInternalTelemetryDisabledSetting(settings: TelemetryDisablementSettings | null | undefined): boolean;
+export {};
+//# sourceMappingURL=disablement.d.ts.map

package/dist/telemetry/disablement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disablement.d.ts","sourceRoot":"","sources":["../../src/telemetry/disablement.ts"],"names":[],"mappings":"AAAA,KAAK,uBAAuB,GAAG;IAC9B,mCAAmC,CAAC,EAAE,MAAM,CAAC;IAC7C,mCAAmC,CAAC,EAAE,MAAM,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IAC1C,QAAQ,CAAC,EAAE;QACV,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACF,CAAC;AAcF,wBAAgB,2BAA2B,CAC1C,GAAG,GAAE,uBAAqC,GACxC,OAAO,CAKT;AAED,wBAAgB,uCAAuC,CACtD,QAAQ,EAAE,4BAA4B,GAAG,IAAI,GAAG,SAAS,GACvD,OAAO,CAET"}