@blaxel/core 0.3.35-preview.344 → 0.3.36-preview.347

package/dist/esm-browser/common/coding-agent.js

@@ -0,0 +1,71 @@
+/**
+ * Environment variables coding agents set for the commands they run, first
+ * match wins, with the agent id the SDK reports. Ids match the Blaxel CLI's.
+ */
+const CODING_AGENTS = [
+    ["CLAUDECODE", "claude-code"],
+    ["CODEX_THREAD_ID", "codex"],
+    ["CODEX_SANDBOX", "codex"],
+    ["CURSOR_AGENT", "cursor"],
+    ["GEMINI_CLI", "gemini-cli"],
+    ["QWEN_CODE", "qwen-code"],
+    ["OPENCODE_TERMINAL", "opencode"],
+    ["OPENCODE", "opencode"],
+    ["GOOSE_TERMINAL", "goose"],
+    ["AUGMENT_AGENT", "augment"],
+];
+/**
+ * Agent names found in the generic `AI_AGENT` and `AGENT` variables, mapped to
+ * the same ids. Any other `AI_AGENT` name is reported as "other".
+ */
+const CODING_AGENT_NAMES = {
+    "claude-code": "claude-code",
+    claude: "claude-code",
+    codex: "codex",
+    cursor: "cursor",
+    "cursor-cli": "cursor",
+    "gemini-cli": "gemini-cli",
+    gemini: "gemini-cli",
+    "qwen-code": "qwen-code",
+    opencode: "opencode",
+    goose: "goose",
+    augment: "augment",
+    "augment-cli": "augment",
+    crush: "crush",
+    "github-copilot": "github-copilot",
+    "github-copilot-cli": "github-copilot",
+};
+/** Every environment variable `detectCodingAgent` reads. */
+export const CODING_AGENT_ENV_VARS = [
+    ...CODING_AGENTS.map(([name]) => name),
+    "AI_AGENT",
+    "AGENT",
+];
+function agentName(value) {
+    const name = value?.trim().toLowerCase() ?? "";
+    // Claude Code sets AI_AGENT=claude-code_<version>_agent: keep the name.
+    const end = name.search(/[_/@ ]/);
+    return end > 0 ? name.slice(0, end) : name;
+}
+function knownAgentId(name) {
+    return Object.prototype.hasOwnProperty.call(CODING_AGENT_NAMES, name)
+        ? CODING_AGENT_NAMES[name]
+        : undefined;
+}
+/**
+ * Id of the coding agent whose environment the SDK runs in, "other" for an
+ * agent without a known name, or "" for none.
+ */
+export function detectCodingAgent(getenv) {
+    for (const [name, id] of CODING_AGENTS) {
+        if (getenv(name)?.trim()) {
+            return id;
+        }
+    }
+    const name = agentName(getenv("AI_AGENT"));
+    if (name) {
+        return knownAgentId(name) ?? "other";
+    }
+    // AGENT is a generic name, so only a known agent name counts.
+    return knownAgentId(agentName(getenv("AGENT"))) ?? "";
+}

package/dist/esm-browser/common/coding-agent.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { detectCodingAgent } from "./coding-agent.js";
+function detect(vars) {
+    return detectCodingAgent((name) => vars[name]);
+}
+describe("detectCodingAgent", () => {
+    it("returns nothing outside a coding agent", () => {
+        expect(detect({})).toBe("");
+        expect(detect({ CLAUDECODE: "", AI_AGENT: "  " })).toBe("");
+    });
+    it.each([
+        [{ CLAUDECODE: "1" }, "claude-code"],
+        [{ CODEX_THREAD_ID: "thread" }, "codex"],
+        [{ CODEX_SANDBOX: "seatbelt" }, "codex"],
+        [{ CURSOR_AGENT: "1" }, "cursor"],
+        [{ GEMINI_CLI: "1" }, "gemini-cli"],
+        [{ QWEN_CODE: "1" }, "qwen-code"],
+        [{ OPENCODE_TERMINAL: "1" }, "opencode"],
+        [{ OPENCODE: "1", AGENT: "1" }, "opencode"],
+        [{ GOOSE_TERMINAL: "1" }, "goose"],
+        [{ AUGMENT_AGENT: "1" }, "augment"],
+    ])("detects the marker %j", (vars, id) => {
+        expect(detect(vars)).toBe(id);
+    });
+    it("prefers an agent-specific marker over the generic variables", () => {
+        expect(detect({ AI_AGENT: "something-else", CODEX_SANDBOX: "seatbelt" })).toBe("codex");
+    });
+    it.each([
+        ["claude-code_2-1-306_agent", "claude-code"],
+        ["Cursor", "cursor"],
+        ["crush", "crush"],
+        ["github-copilot-cli", "github-copilot"],
+        ["some-new-agent", "other"],
+    ])("maps AI_AGENT=%j to %j", (value, id) => {
+        expect(detect({ AI_AGENT: value })).toBe(id);
+    });
+    it("reads AGENT only for a known agent name", () => {
+        expect(detect({ AGENT: "goose" })).toBe("goose");
+        expect(detect({ AGENT: "1" })).toBe("");
+        expect(detect({ AGENT: "build-runner" })).toBe("");
+        expect(detect({ AGENT: "goose", AI_AGENT: "claude" })).toBe("claude-code");
+    });
+    it("never reports a free-form name", () => {
+        expect(detect({ AI_AGENT: "Jane Doe's laptop" })).toBe("other");
+        expect(detect({ AI_AGENT: "toString" })).toBe("other");
+        expect(detect({ AGENT: "toString" })).toBe("");
+    });
+});

package/dist/esm-browser/common/sentry.js

@@ -181,9 +181,25 @@ function generateEventId() {
         return value.toString(16);
     });
 }
+const SAFE_WORKSPACE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 /**
- * Build an allowlisted event. Raw messages, response bodies, workspace/resource
- * context, and absolute host paths are deliberately excluded.
+ * The workspace name is the only user identifier, so an issue shows how many
+ * workspaces it affects. Omitted when unknown or not a workspace name.
+ */
+function sentryUser() {
+    try {
+        const workspace = settings.workspace;
+        return typeof workspace === "string" && SAFE_WORKSPACE_NAME.test(workspace)
+            ? { id: workspace }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build an allowlisted event. Raw messages, response bodies, resource context,
+ * and absolute host paths are deliberately excluded.
  */
 function errorToSentryEvent(error, ownedFrames) {
     return {
@@ -193,6 +209,7 @@ function errorToSentryEvent(error, ownedFrames) {
         level: "error",
         environment: settings.env,
         release: `sdk-typescript@${settings.version}`,
+        user: sentryUser(),
         tags: {
             "blaxel.version": settings.version,
             "blaxel.commit": settings.commit,
@@ -286,6 +303,7 @@ function h2DegradationToSentryEvent(reason, domainTag, count) {
         release: `sdk-typescript@${settings.version}`,
         message: `h2 transport degradation: ${reason}`,
         fingerprint: ["h2-degradation", reason, domainTag],
+        user: sentryUser(),
         tags: {
             "blaxel.version": settings.version,
             "blaxel.commit": settings.commit,

package/dist/esm-browser/common/sentry.test.js

@@ -5,7 +5,7 @@ const mockSettings = vi.hoisted(() => ({
     env: "prod",
     version: "9.9.9",
     commit: "abcdef0",
-    workspace: "private-workspace",
+    workspace: "acme-staging",
 }));
 vi.mock("./settings.js", () => ({ settings: mockSettings }));
 const appFrameUrl = "file:///Users/customer/private-project/app.ts";
@@ -129,6 +129,8 @@ describe("SDK Sentry boundary", () => {
                 "blaxel.error_source": "unhandled-sdk-exception",
             });
             expect(event.tags).not.toHaveProperty("blaxel.workspace");
+            // The workspace is the only user identifier, so issues count affected workspaces.
+            expect(event.user).toEqual({ id: "acme-staging" });
             const frames = event.exception?.values[0]?.stacktrace.frames ?? [];
             expect(frames.length).toBeGreaterThan(0);
             for (const frame of frames) {
@@ -137,7 +139,6 @@ describe("SDK Sentry boundary", () => {
             const serialized = JSON.stringify(event);
             expect(serialized).not.toContain("secret response body");
             expect(serialized).not.toContain("customer-123");
-            expect(serialized).not.toContain("private-workspace");
             expect(serialized).not.toContain("/Users/customer");
         }
         finally {
@@ -234,8 +235,27 @@ describe("SDK Sentry boundary", () => {
                 domainTag,
             },
             extra: { count: 100 },
+            user: { id: "acme-staging" },
         });
     });
+    it("leaves the user out when the workspace is not a workspace name", async () => {
+        const fetchMock = createFetchMock();
+        vi.stubGlobal("fetch", fetchMock);
+        const workspace = mockSettings.workspace;
+        mockSettings.workspace = "/Users/customer/private project";
+        try {
+            const { flushSentry, initSentry } = await import("./sentry.js");
+            initSentry();
+            emitUncaughtExceptionMonitor(makeSdkError());
+            await flushSentry();
+            const event = eventFromFetch(fetchMock);
+            expect(event.user).toBeUndefined();
+            expect(JSON.stringify(event)).not.toContain("/Users/customer");
+        }
+        finally {
+            mockSettings.workspace = workspace;
+        }
+    });
     it("groups keys independently and hashes external domains", async () => {
         const fetchMock = createFetchMock();
         vi.stubGlobal("fetch", fetchMock);

package/dist/esm-browser/common/settings.js

@@ -3,6 +3,7 @@ import { ApiKey } from "../authentication/apikey.js";
 import { ClientCredentials } from "../authentication/clientcredentials.js";
 import { MissingCredentials } from "../authentication/credentials.js";
 import { authentication } from "../authentication/index.js";
+import { detectCodingAgent } from "../common/coding-agent.js";
 import { env } from "../common/env.js";
 import { CredentialsError } from "../common/errors.js";
 import { isBrokenBunH2Runtime } from "../common/h2-runtime.js";
@@ -24,8 +25,8 @@ function missingCredentialsMessage() {
     return "No Blaxel credentials found. Set the BL_API_KEY and BL_WORKSPACE environment variables, or run `bl login`.";
 }
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.3.35-preview.344";
-const BUILD_COMMIT = "5f8cd5a9c6ba61ebc883d5c583b198b67da4167d";
+const BUILD_VERSION = "0.3.36-preview.347";
+const BUILD_COMMIT = "bb3cd5806f537daac42970497c263d4ccb4b2455";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-09-22";
 // Bun < 1.3.11 never sends connection-level WINDOW_UPDATE: the pooled h2
@@ -62,6 +63,18 @@ function getConfigTracking() {
     }
     return null;
 }
+/**
+ * Whether `DO_NOT_TRACK` (`1` or `true`) opts out of the coding agent token.
+ * The process environment is checked on its own as well, so a project `.env`
+ * or `blaxel.toml` can't undo an opt-out set for the process. The saved
+ * `tracking` setting is not read: it is an opt-in for error reports, and
+ * `bl login` saves it as false until the user turns it on.
+ */
+function trackingOptedOut() {
+    const optsOut = (value) => value === "true" || value === "1";
+    const processValue = typeof process !== "undefined" ? process.env?.DO_NOT_TRACK : undefined;
+    return optsOut(processValue) || optsOut(env.DO_NOT_TRACK);
+}
 // Function to get OS and architecture
 function getOsArch() {
     try {
@@ -218,16 +231,32 @@ class Settings {
     set integration(value) {
         this.config.integration = value;
     }
+    /**
+     * Id of the coding agent (Claude Code, Codex, Cursor, ...) whose environment
+     * runs the SDK, `"other"` for an agent without a known name, or `""` for none
+     * or when telemetry is opted out. Sent as an `agent/<id>` User-Agent token.
+     */
+    get codingAgent() {
+        const agent = detectCodingAgent((name) => env[name]);
+        return agent && !trackingOptedOut() ? agent : "";
+    }
     get headers() {
         this.assertCredentials();
         const osArch = getOsArch();
-        const sdkUserAgent = `blaxel/sdk/typescript/${this.version} (${osArch}) blaxel/${this.commit}`;
+        let userAgent = `blaxel/sdk/typescript/${this.version} (${osArch}) blaxel/${this.commit}`;
         const integration = this.integration;
+        if (integration) {
+            userAgent += ` ${integration}`;
+        }
+        const codingAgent = this.codingAgent;
+        if (codingAgent) {
+            userAgent += ` agent/${codingAgent}`;
+        }
         return {
             "x-blaxel-authorization": this.authorization,
             "x-blaxel-workspace": this.workspace || "",
             "Blaxel-Version": this.apiVersion,
-            "User-Agent": integration ? `${sdkUserAgent} ${integration}` : sdkUserAgent,
+            "User-Agent": userAgent,
         };
     }
     get name() {

package/dist/esm-browser/common/settings.test.js

@@ -1,7 +1,39 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { ApiKey } from '../authentication/apikey.js';
+import { CODING_AGENT_ENV_VARS } from './coding-agent.js';
 import { env } from './env.js';
 import { isBrokenBunH2Runtime } from './h2-runtime.js';
+/**
+ * These tests may run inside a coding agent, which sets the variables the SDK
+ * reads to tag its User-Agent. Clear them (and DO_NOT_TRACK) for each test.
+ */
+function withoutCodingAgentEnv() {
+    const names = [...CODING_AGENT_ENV_VARS, 'DO_NOT_TRACK', 'HOME', 'USERPROFILE'];
+    const saved = {};
+    return {
+        clear() {
+            for (const name of names) {
+                saved[name] = process.env[name];
+            }
+            for (const name of [...CODING_AGENT_ENV_VARS, 'DO_NOT_TRACK']) {
+                delete process.env[name];
+            }
+        },
+        restore() {
+            for (const name of names) {
+                if (saved[name] === undefined) {
+                    delete process.env[name];
+                }
+                else {
+                    process.env[name] = saved[name];
+                }
+            }
+        },
+    };
+}
 describe('Settings.apiVersion', () => {
     beforeEach(() => {
         // Reset the module-level settings singleton between tests if needed
@@ -218,6 +250,7 @@ describe('Settings H2 tuning knobs (config > env > default)', () => {
 });
 describe('Settings.integration', () => {
     const sdkUserAgent = /^blaxel\/sdk\/typescript\/\S+ \([^)]+\) blaxel\/\S+/;
+    const agentEnv = withoutCodingAgentEnv();
     async function authenticated() {
         const { settings } = await import('./settings.js');
         settings.credentials = new ApiKey({ apiKey: 'test-key', workspace: 'test-ws' });
@@ -225,7 +258,9 @@ describe('Settings.integration', () => {
         delete process.env.BL_INTEGRATION;
         return settings;
     }
+    beforeEach(() => agentEnv.clear());
     afterEach(async () => {
+        agentEnv.restore();
         const { settings } = await import('./settings.js');
         delete settings.config.integration;
         delete process.env.BL_INTEGRATION;
@@ -286,3 +321,100 @@ describe('Settings.integration warnings', () => {
         }
     });
 });
+describe('Settings.codingAgent', () => {
+    const sdkUserAgent = /^blaxel\/sdk\/typescript\/\S+ \([^)]+\) blaxel\/\S+/;
+    const agentEnv = withoutCodingAgentEnv();
+    let home = '';
+    /** A fresh settings module, so it reads the empty test home directory. */
+    async function authenticated() {
+        const { settings } = await import('./settings.js');
+        settings.credentials = new ApiKey({ apiKey: 'test-key', workspace: 'test-ws' });
+        delete settings.config.integration;
+        delete process.env.BL_INTEGRATION;
+        return settings;
+    }
+    /** A fresh settings module whose home directory holds this config.yaml. */
+    async function withConfig(config) {
+        mkdirSync(join(home, '.blaxel'));
+        writeFileSync(join(home, '.blaxel', 'config.yaml'), config);
+        return authenticated();
+    }
+    // Keep the tracking choice saved on the machine running the tests out.
+    beforeEach(() => {
+        agentEnv.clear();
+        home = mkdtempSync(join(tmpdir(), 'blaxel-home-'));
+        process.env.HOME = home;
+        process.env.USERPROFILE = home;
+        vi.resetModules();
+    });
+    afterEach(() => {
+        agentEnv.restore();
+        delete process.env.BL_INTEGRATION;
+        rmSync(home, { recursive: true, force: true });
+        vi.resetModules();
+    });
+    it('sends no agent token outside a coding agent', async () => {
+        const settings = await authenticated();
+        expect(settings.codingAgent).toBe('');
+        expect(settings.headers['User-Agent']).toMatch(new RegExp(sdkUserAgent.source + '$'));
+    });
+    it('appends the agent token detected from the environment', async () => {
+        const settings = await authenticated();
+        process.env.CLAUDECODE = '1';
+        expect(settings.codingAgent).toBe('claude-code');
+        const userAgent = settings.headers['User-Agent'];
+        expect(userAgent).toMatch(sdkUserAgent);
+        expect(userAgent.endsWith(' agent/claude-code')).toBe(true);
+    });
+    it('puts the agent token after the integration token', async () => {
+        const settings = await authenticated();
+        process.env.CODEX_SANDBOX = 'seatbelt';
+        settings.integration = 'herdr/1.4.0';
+        expect(settings.headers['User-Agent'].endsWith(' herdr/1.4.0 agent/codex')).toBe(true);
+    });
+    it.each(['1', 'true'])('drops the token when DO_NOT_TRACK=%s', async (value) => {
+        const settings = await authenticated();
+        process.env.CLAUDECODE = '1';
+        process.env.DO_NOT_TRACK = value;
+        expect(settings.codingAgent).toBe('');
+        expect(settings.headers['User-Agent']).toMatch(new RegExp(sdkUserAgent.source + '$'));
+    });
+    it('drops the token when the process sets DO_NOT_TRACK=1 and the project .env says false', async () => {
+        vi.doMock('./node.js', async (importOriginal) => {
+            const original = await importOriginal();
+            const fs = original.fs;
+            const readFileSync = ((file, ...rest) => file === '.env' ? 'DO_NOT_TRACK=false\n' : fs.readFileSync(file, ...rest));
+            return { ...original, fs: { ...fs, readFileSync } };
+        });
+        try {
+            const settings = await authenticated();
+            const { env: projectEnv } = await import('./env.js');
+            expect(projectEnv.DO_NOT_TRACK).toBe('false');
+            process.env.CLAUDECODE = '1';
+            process.env.DO_NOT_TRACK = '1';
+            expect(settings.codingAgent).toBe('');
+            expect(settings.headers['User-Agent']).toMatch(new RegExp(sdkUserAgent.source + '$'));
+        }
+        finally {
+            vi.doUnmock('./node.js');
+        }
+    });
+    it('keeps the token when DO_NOT_TRACK turns tracking on', async () => {
+        const settings = await authenticated();
+        process.env.CLAUDECODE = '1';
+        process.env.DO_NOT_TRACK = '0';
+        expect(settings.codingAgent).toBe('claude-code');
+    });
+    it('keeps the token when config.yaml says tracking: false', async () => {
+        // bl login saves tracking: false until the user opts in to error reports.
+        const settings = await withConfig('tracking: false\n');
+        process.env.CURSOR_AGENT = '1';
+        expect(settings.codingAgent).toBe('cursor');
+    });
+    it('keeps the token when no tracking choice was saved', async () => {
+        const settings = await withConfig('context:\n  workspace: test-ws\n');
+        process.env.CURSOR_AGENT = '1';
+        expect(settings.tracking).toBe(false);
+        expect(settings.codingAgent).toBe('cursor');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blaxel/core",
-	"version": "0.3.35-preview.344",
+	"version": "0.3.36-preview.347",
 	"description": "Blaxel Core SDK for TypeScript",
 	"license": "MIT",
 	"author": "Blaxel, INC (https://blaxel.ai)",