@buildwithtrace/sdk 0.1.0 → 0.1.1

package/dist/index.mjs

@@ -1,6 +1,6 @@
 // src/index.ts
-import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
-import { join as join2, resolve as resolve2 } from "path";
+import { writeFileSync as writeFileSync4, mkdirSync as mkdirSync4 } from "fs";
+import { join as join4, resolve as resolve2 } from "path";
 
 // src/executor.ts
 import {
@@ -421,8 +421,401 @@ function executeFileTool(toolName, toolArgs, projectDir, defaultFile = "") {
   }
 }
 
-// src/index.ts
+// src/auth.ts
+import * as childProcess from "child_process";
+import { createServer } from "http";
+import { homedir, platform } from "os";
+import { join as join2 } from "path";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, rmSync, chmodSync } from "fs";
+import { URL } from "url";
 var DEFAULT_API_URL = "https://api.buildwithtrace.com";
+var PRODUCTION_FRONTEND_URL = "https://buildwithtrace.com";
+var LOCAL_FRONTEND_URL = "http://localhost:3000";
+var DEFAULT_LOGIN_TIMEOUT_MS = 12e4;
+function deriveFrontendUrl(baseUrl) {
+  const envOverride = process.env.TRACE_FRONTEND_URL;
+  if (envOverride && envOverride.trim()) {
+    return envOverride.trim().replace(/\/$/, "");
+  }
+  const api = (baseUrl || process.env.TRACE_BASE_URL || DEFAULT_API_URL).trim();
+  try {
+    const u = new URL(api);
+    const host = u.hostname;
+    if (host === "localhost" || host === "127.0.0.1") {
+      return LOCAL_FRONTEND_URL;
+    }
+    if (host.startsWith("api.")) {
+      return `${u.protocol}//${host.slice("api.".length)}`;
+    }
+    return PRODUCTION_FRONTEND_URL;
+  } catch {
+    return PRODUCTION_FRONTEND_URL;
+  }
+}
+var CREDENTIALS_FILENAME = "credentials.json";
+function getConfigDir() {
+  const override = process.env.TRACE_CONFIG_DIR;
+  if (override && override.trim()) return override.trim();
+  const home = homedir();
+  switch (platform()) {
+    case "darwin":
+      return join2(home, "Library", "Application Support", "trace");
+    case "win32": {
+      const appData = process.env.APPDATA || join2(home, "AppData", "Roaming");
+      return join2(appData, "buildwithtrace", "trace");
+    }
+    default: {
+      const xdg = process.env.XDG_CONFIG_HOME;
+      const base = xdg && xdg.trim() ? xdg.trim() : join2(home, ".config");
+      return join2(base, "trace");
+    }
+  }
+}
+function credentialsPath() {
+  return join2(getConfigDir(), CREDENTIALS_FILENAME);
+}
+function storeCredentials(creds) {
+  const dir = getConfigDir();
+  mkdirSync2(dir, { recursive: true });
+  const path = credentialsPath();
+  const data = {
+    access_token: creds.access_token,
+    refresh_token: creds.refresh_token
+  };
+  if (creds.user_data) data.user_data = creds.user_data;
+  writeFileSync2(path, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  try {
+    chmodSync(path, 384);
+  } catch {
+  }
+  return path;
+}
+function readCredentials() {
+  const path = credentialsPath();
+  if (!existsSync2(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf-8"));
+    if (parsed && typeof parsed.access_token === "string" && parsed.access_token) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function getStoredAccessToken() {
+  return readCredentials()?.access_token ?? null;
+}
+function clearCredentials() {
+  const path = credentialsPath();
+  if (existsSync2(path)) {
+    rmSync(path, { force: true });
+  }
+}
+function openBrowser(url) {
+  let command;
+  let args;
+  switch (platform()) {
+    case "darwin":
+      command = "open";
+      args = [url];
+      break;
+    case "win32":
+      command = "cmd";
+      args = ["/c", "start", "", url];
+      break;
+    default:
+      command = "xdg-open";
+      args = [url];
+      break;
+  }
+  try {
+    const child = childProcess.spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+var SUCCESS_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>Trace</title></head>
+<body style="font-family:system-ui,-apple-system,sans-serif;text-align:center;padding:64px;color:#2a2119">
+<h1 style="font-weight:600">&#10003; Authentication successful</h1>
+<p>You can close this window and return to your terminal.</p>
+<script>setTimeout(function(){window.close();},500)</script>
+</body></html>`;
+var PENDING_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>Trace</title></head>
+<body style="font-family:system-ui,-apple-system,sans-serif;text-align:center;padding:64px;color:#2a2119">
+<h1 style="font-weight:600">Waiting for authentication&#8230;</h1>
+<p>This page is the Trace login callback. Complete sign-in in the other tab.</p>
+</body></html>`;
+function parseCallback(query) {
+  const accessToken = query.get("token") || query.get("access_token");
+  if (!accessToken) return null;
+  const refreshToken = query.get("refresh_token") || "";
+  let user = null;
+  const userRaw = query.get("user");
+  if (userRaw) {
+    try {
+      user = JSON.parse(userRaw);
+    } catch {
+      user = null;
+    }
+  }
+  return { accessToken, refreshToken, user };
+}
+function browserLogin(opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_LOGIN_TIMEOUT_MS;
+  const frontendUrl = opts.frontendUrl?.trim().replace(/\/$/, "") || deriveFrontendUrl(opts.baseUrl);
+  const openFn = opts.open ?? openBrowser;
+  return new Promise((resolve3, reject) => {
+    let settled = false;
+    let timer;
+    const shutdown = () => {
+      try {
+        server.closeAllConnections?.();
+      } catch {
+      }
+      server.close();
+    };
+    const settle = (run) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      run();
+    };
+    const server = createServer((req, res) => {
+      let url;
+      try {
+        url = new URL(req.url || "/", "http://127.0.0.1");
+      } catch {
+        res.writeHead(400).end();
+        return;
+      }
+      if (!url.pathname.startsWith("/callback")) {
+        res.writeHead(204).end();
+        return;
+      }
+      const result = parseCallback(url.searchParams);
+      if (!result) {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(PENDING_HTML);
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(SUCCESS_HTML);
+      res.on("finish", shutdown);
+      res.on("close", shutdown);
+      settle(() => resolve3(result));
+    });
+    server.on("error", (err) => {
+      settle(() => {
+        shutdown();
+        reject(new Error(`Failed to start the local login callback server: ${err.message}`));
+      });
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address) {
+        settle(() => {
+          shutdown();
+          reject(new Error("Could not determine the local callback port."));
+        });
+        return;
+      }
+      const port = address.port;
+      const callbackUrl = `http://localhost:${port}/callback`;
+      const loginUrl = `${frontendUrl}/login?callback=${encodeURIComponent(callbackUrl)}`;
+      console.error(`Opening your browser to sign in to Trace...
+If it does not open, visit:
+  ${loginUrl}
+`);
+      openFn(loginUrl);
+      timer = setTimeout(() => {
+        settle(() => {
+          shutdown();
+          reject(
+            new Error(
+              `Login timed out after ${Math.round(timeoutMs / 1e3)}s. Re-run login, or open this URL manually:
+  ${loginUrl}`
+            )
+          );
+        });
+      }, timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+    });
+  });
+}
+
+// src/analytics.ts
+import { randomUUID } from "crypto";
+import { release as osRelease } from "os";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join3 } from "path";
+import { PostHog } from "posthog-node";
+
+// src/_build_config.ts
+var BUILD_POSTHOG_KEY = "phc_YbXW9ynLyGf9qHVxOY87InoZNSRikTCQ14GDJOZtSxX";
+var BUILD_POSTHOG_HOST = "https://us.i.posthog.com";
+var BUILD_SDK_VERSION = "0.1.1";
+
+// src/analytics.ts
+var DEFAULT_HOST = "https://us.i.posthog.com";
+var INSTALL_ID_FILENAME = "install_id";
+var MAX_STRING_LEN = 80;
+var MAX_KEY_LEN = 64;
+function envSet(name) {
+  const v = process.env[name];
+  if (!v) return false;
+  const t = v.trim().toLowerCase();
+  return t !== "" && t !== "0" && t !== "false";
+}
+function isOptedOut() {
+  return envSet("DO_NOT_TRACK") || envSet("TRACE_NO_ANALYTICS");
+}
+function isCI() {
+  return envSet("CI") || envSet("CONTINUOUS_INTEGRATION") || envSet("GITHUB_ACTIONS");
+}
+function resolveKey() {
+  return (process.env.POSTHOG_API_KEY || BUILD_POSTHOG_KEY || "").trim();
+}
+function resolveHost() {
+  return (process.env.POSTHOG_HOST || BUILD_POSTHOG_HOST || DEFAULT_HOST).trim() || DEFAULT_HOST;
+}
+function isAnalyticsEnabled() {
+  try {
+    if (isOptedOut()) return false;
+    if (isCI()) return false;
+    return resolveKey().length > 0;
+  } catch {
+    return false;
+  }
+}
+var _installId;
+function getInstallId() {
+  if (_installId) return _installId;
+  try {
+    const dir = getConfigDir();
+    const path = join3(dir, INSTALL_ID_FILENAME);
+    if (existsSync3(path)) {
+      const existing = readFileSync3(path, "utf-8").trim();
+      if (existing) {
+        _installId = existing;
+        return existing;
+      }
+    }
+    const id = randomUUID();
+    mkdirSync3(dir, { recursive: true });
+    writeFileSync3(path, `${id}
+`, { encoding: "utf-8", mode: 384 });
+    _installId = id;
+    return id;
+  } catch {
+    if (!_installId) _installId = randomUUID();
+    return _installId;
+  }
+}
+function storedUserId() {
+  try {
+    const id = readCredentials()?.user_data?.id;
+    return typeof id === "string" && id ? id : null;
+  } catch {
+    return null;
+  }
+}
+function sanitizeProps(props) {
+  const out = {};
+  if (!props || typeof props !== "object") return out;
+  for (const [key, value] of Object.entries(props)) {
+    if (typeof key !== "string" || !key || key.length > MAX_KEY_LEN) continue;
+    if (typeof value === "boolean") {
+      out[key] = value;
+    } else if (typeof value === "number") {
+      if (Number.isFinite(value)) out[key] = value;
+    } else if (typeof value === "string") {
+      if (!value) continue;
+      if (value.length > MAX_STRING_LEN) continue;
+      if (/[\\/\n\r\t]/.test(value)) continue;
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function superProps() {
+  return {
+    client: "sdk-node",
+    client_version: BUILD_SDK_VERSION || "0.0.0",
+    os: process.platform,
+    os_version: osRelease(),
+    node_version: process.version,
+    is_ci: isCI(),
+    install_id: getInstallId()
+  };
+}
+var _client;
+var _exitHookRegistered = false;
+function registerExitFlush() {
+  if (_exitHookRegistered) return;
+  _exitHookRegistered = true;
+  try {
+    process.once("beforeExit", () => {
+      try {
+        _client?.shutdown?.();
+      } catch {
+      }
+    });
+  } catch {
+  }
+}
+function getClient() {
+  if (_client !== void 0) return _client;
+  if (!isAnalyticsEnabled()) {
+    _client = null;
+    return null;
+  }
+  try {
+    _client = new PostHog(resolveKey(), {
+      host: resolveHost(),
+      flushAt: 1,
+      // short-lived SDK processes: send promptly
+      flushInterval: 1e4
+    });
+    registerExitFlush();
+    return _client;
+  } catch {
+    _client = null;
+    return null;
+  }
+}
+function track(event, props) {
+  try {
+    if (!event) return;
+    const client = getClient();
+    if (!client) return;
+    const distinctId = storedUserId() || getInstallId();
+    const properties = { ...sanitizeProps(props), ...superProps() };
+    client.capture({ distinctId, event, properties });
+  } catch {
+  }
+}
+function identify(distinctId, traits) {
+  try {
+    if (!distinctId) return;
+    const client = getClient();
+    if (!client) return;
+    client.identify({ distinctId, properties: { ...sanitizeProps(traits), ...superProps() } });
+  } catch {
+  }
+}
+function alias(distinctId, aliasId) {
+  try {
+    if (!distinctId || !aliasId || distinctId === aliasId) return;
+    const client = getClient();
+    if (!client) return;
+    client.alias?.({ distinctId, alias: aliasId });
+  } catch {
+  }
+}
+
+// src/index.ts
+var DEFAULT_API_URL2 = "https://api.buildwithtrace.com";
 var API_VERSION = "latest";
 var TraceError = class extends Error {
   constructor(message) {
@@ -436,66 +829,179 @@ var TraceToolExecutionError = class extends TraceError {
     this.name = "TraceToolExecutionError";
   }
 };
+var TracePlanRestrictedError = class extends TraceError {
+  constructor(message, opts) {
+    super(message);
+    /** Always true — lets callers branch on a flag, mirroring the backend `code`. */
+    this.planRestricted = true;
+    this.name = "TracePlanRestrictedError";
+    this.mode = opts?.mode;
+    this.plan = opts?.plan;
+  }
+};
+function parsePlanRestricted(text) {
+  if (!text) return null;
+  try {
+    const data = JSON.parse(text);
+    const detail = typeof data.detail === "object" && data.detail !== null ? data.detail : data;
+    if (detail.error === "plan_restricted" || detail.code === "plan_restricted") {
+      const message = detail.message || "This feature requires a paid plan.";
+      const plan = typeof detail.current_plan_id === "string" ? detail.current_plan_id : void 0;
+      return { message, plan };
+    }
+  } catch {
+  }
+  if (text.includes("plan_restricted")) {
+    return { message: "This feature requires a paid plan." };
+  }
+  return null;
+}
 var Trace = class _Trace {
-  constructor(config) {
-    this.apiKey = config.apiKey || process.env.TRACE_API_KEY || "";
+  constructor(config = {}) {
+    this.apiKey = config.apiKey || process.env.TRACE_API_KEY || getStoredAccessToken() || "";
     if (!this.apiKey) {
       throw new Error(
-        "API key required. Pass apiKey in config or set TRACE_API_KEY env var. Get your key at buildwithtrace.com/dashboard/settings > Developer, or via CLI: buildwithtrace auth token"
+        "API key required. Sign in with `await Trace.login()`, pass apiKey in config, or set TRACE_API_KEY env var. Get your key at buildwithtrace.com/dashboard/settings > Developer, or via CLI: buildwithtrace auth token"
       );
     }
-    this.baseUrl = (config.baseUrl || process.env.TRACE_BASE_URL || DEFAULT_API_URL).replace(/\/$/, "");
+    this.authed = true;
+    this.baseUrl = (config.baseUrl || process.env.TRACE_BASE_URL || DEFAULT_API_URL2).replace(/\/$/, "");
     this.timeout = config.timeout || 3e5;
+    this.byokProvider = config.llmProvider;
+    this.byokApiKey = config.llmApiKey;
+    this.byokModelId = config.llmModelId;
+    track("sdk_init", { authed: this.authed });
+  }
+  /**
+   * Wrap a public method call: emit `sdk_call` (with timing + outcome) on every
+   * call and `sdk_error` (with the error class) on failure. Analytics is
+   * fire-and-forget; it must never change behavior, so the underlying result /
+   * thrown error always propagates unchanged.
+   */
+  async _instrument(method, streaming, byok, fn) {
+    const start = Date.now();
+    try {
+      const result = await fn();
+      track("sdk_call", {
+        method,
+        api_version: API_VERSION,
+        streaming,
+        byok,
+        duration_ms: Date.now() - start,
+        ok: true,
+        authed: this.authed
+      });
+      return result;
+    } catch (err) {
+      track("sdk_call", {
+        method,
+        api_version: API_VERSION,
+        streaming,
+        byok,
+        duration_ms: Date.now() - start,
+        ok: false,
+        authed: this.authed
+      });
+      track("sdk_error", {
+        method,
+        error_type: err instanceof Error && err.name || "Error",
+        authed: this.authed
+      });
+      throw err;
+    }
+  }
+  /**
+   * Sign in via the browser deeplink flow, persist the returned tokens to a
+   * 0600 `credentials.json`, and return a ready-to-use `Trace` instance.
+   *
+   * Opens `{FRONTEND}/login?callback=http://localhost:PORT/callback` in the
+   * browser; the user authenticates there (captcha included) and the page
+   * redirects back to the loopback server with the final Supabase JWTs.
+   *
+   * @example
+   * ```typescript
+   * const trace = await Trace.login();
+   * const answer = await trace.ask('What ERC violations exist?');
+   * ```
+   */
+  static async login(opts = {}) {
+    const result = await browserLogin({
+      baseUrl: opts.baseUrl,
+      frontendUrl: opts.frontendUrl,
+      timeoutMs: opts.timeoutMs,
+      open: opts.open
+    });
+    storeCredentials({
+      access_token: result.accessToken,
+      refresh_token: result.refreshToken,
+      user_data: result.user
+    });
+    const userId = result.user?.id;
+    if (typeof userId === "string" && userId) {
+      identify(userId);
+      alias(userId, getInstallId());
+    }
+    return new _Trace({ apiKey: result.accessToken, baseUrl: opts.baseUrl, timeout: opts.timeout });
+  }
+  /** Clear stored credentials (sign out). Subsequent `new Trace()` will need a token again. */
+  static logout() {
+    clearCredentials();
   }
   async generateSymbol(description, options) {
-    const body = { description };
-    if (options?.datasheetUrl) body.datasheet_url = options.datasheetUrl;
-    if (options?.additionalInstructions) body.additional_instructions = options.additionalInstructions;
-    const data = await this._post(`/api/${API_VERSION}/components/generate/symbol`, body);
-    return this._makeGenerateResult(data, "symbol");
+    return this._instrument("generateSymbol", false, false, async () => {
+      const body = { description };
+      if (options?.datasheetUrl) body.datasheet_url = options.datasheetUrl;
+      if (options?.additionalInstructions) body.additional_instructions = options.additionalInstructions;
+      const data = await this._post(`/api/${API_VERSION}/components/generate/symbol`, body);
+      return this._makeGenerateResult(data, "symbol");
+    });
   }
   async generateFootprint(description, options) {
-    const body = { description };
-    if (options?.packageType) body.package_type = options.packageType;
-    if (options?.datasheetUrl) body.datasheet_url = options.datasheetUrl;
-    const data = await this._post(`/api/${API_VERSION}/components/generate/footprint`, body);
-    return this._makeGenerateResult(data, "footprint");
+    return this._instrument("generateFootprint", false, false, async () => {
+      const body = { description };
+      if (options?.packageType) body.package_type = options.packageType;
+      if (options?.datasheetUrl) body.datasheet_url = options.datasheetUrl;
+      const data = await this._post(`/api/${API_VERSION}/components/generate/footprint`, body);
+      return this._makeGenerateResult(data, "footprint");
+    });
   }
   async search(query, options) {
-    const params = new URLSearchParams({ q: query, limit: String(options?.limit || 20) });
-    if (options?.type) params.set("type", options.type);
-    const data = await this._get(`/api/${API_VERSION}/components/search?${params}`);
-    return (data.results || []).map((r) => ({
-      name: r.name || "",
-      library: r.library || "",
-      description: r.description || "",
-      pinCount: r.pin_count || 0,
-      padCount: r.pad_count || 0,
-      category: r.category || "",
-      source: r.source || "",
-      score: r.score || 0
-    }));
+    return this._instrument("search", false, false, async () => {
+      const params = new URLSearchParams({ q: query, limit: String(options?.limit || 20) });
+      if (options?.type) params.set("type", options.type);
+      const data = await this._get(`/api/${API_VERSION}/components/search?${params}`);
+      return (data.results || []).map((r) => ({
+        name: r.name || "",
+        library: r.library || "",
+        description: r.description || "",
+        pinCount: r.pin_count || 0,
+        padCount: r.pad_count || 0,
+        category: r.category || "",
+        source: r.source || "",
+        score: r.score || 0
+      }));
+    });
   }
   async ask(question, options) {
-    return this._streamChat(question, {
+    return this._instrument("ask", true, false, () => this._streamChat(question, {
       mode: "ask",
       appType: options?.appType,
       projectDir: options?.projectDir,
       fileContent: options?.fileContent,
       filePath: options?.filePath,
       conversationId: options?.conversationId
-    });
+    }));
   }
   async review(options) {
     let prompt = "Review this design for issues, best practices, and improvements.";
     if (options?.focus) prompt += ` Focus on: ${options.focus}`;
-    return this._streamChat(prompt, {
+    return this._instrument("review", true, false, () => this._streamChat(prompt, {
       mode: "ask",
       appType: options?.appType,
       projectDir: options?.projectDir,
       fileContent: options?.fileContent,
       filePath: options?.filePath
-    });
+    }));
   }
   /**
    * Stream a chat turn and collect the full response. Exposes the full backend
@@ -514,7 +1020,9 @@ var Trace = class _Trace {
    * TraceToolExecutionError — use the `buildwithtrace` CLI for those.
    */
   async chat(message, options) {
-    return this._streamChat(message, options || {});
+    const resolved = this._resolveByok(options || {});
+    const byok = !!(resolved.provider && resolved.apiKey);
+    return this._instrument("chat", true, byok, () => this._streamChat(message, options || {}));
   }
   async _post(path, body) {
     const controller = new AbortController();
@@ -539,10 +1047,14 @@ var Trace = class _Trace {
       clearTimeout(timeoutId);
     }
   }
-  static _httpError(status, text) {
+  static _httpError(status, text, mode) {
     if (status === 401) return new TraceError("Invalid or expired API key. Get a new one at buildwithtrace.com/dashboard/settings > Developer");
     if (status === 402) return new TraceError("Quota exceeded. Upgrade at buildwithtrace.com/dashboard/billing");
-    if (status === 403) return new TraceError("Access denied. This feature requires a paid plan.");
+    if (status === 403) {
+      const pr = parsePlanRestricted(text);
+      if (pr) return new TracePlanRestrictedError(pr.message, { mode, plan: pr.plan });
+      return new TraceError("Access denied. This feature requires a paid plan.");
+    }
     return new Error(`Trace API error ${status}: ${text.slice(0, 200)}`);
   }
   async _get(path) {
@@ -563,6 +1075,37 @@ var Trace = class _Trace {
    * backend ChatRequest contract so the SDK stays in lockstep with the
    * CLI/desktop instead of sending a stale minimal payload.
    */
+  /**
+   * Resolve BYOK routing with precedence: per-call options > constructor config >
+   * env (`TRACE_LLM_PROVIDER` / `TRACE_LLM_API_KEY` / `TRACE_LLM_MODEL`). Provider
+   * and key are resolved as a UNIT from the first source supplying BOTH (we never
+   * mix a per-call provider with an env key); the model id is layered (a more
+   * specific source's model wins). Node has no keyring `byok set` store, so env is
+   * the "persisted" mechanism. Returns `{}` when no complete config is found, so
+   * nothing is attached and the backend uses Trace-hosted Bedrock.
+   */
+  _resolveByok(opts) {
+    if (opts.llmProvider && opts.llmApiKey) {
+      return { provider: opts.llmProvider, apiKey: opts.llmApiKey, modelId: opts.llmModelId };
+    }
+    if (this.byokProvider && this.byokApiKey) {
+      return {
+        provider: this.byokProvider,
+        apiKey: this.byokApiKey,
+        modelId: opts.llmModelId || this.byokModelId
+      };
+    }
+    const envProvider = process.env.TRACE_LLM_PROVIDER;
+    const envKey = process.env.TRACE_LLM_API_KEY;
+    if (envProvider && envKey) {
+      return {
+        provider: envProvider,
+        apiKey: envKey,
+        modelId: opts.llmModelId || this.byokModelId || process.env.TRACE_LLM_MODEL
+      };
+    }
+    return {};
+  }
   _buildChatBody(message, opts, sessionId) {
     const appType = opts.appType || "eeschema";
     const body = {
@@ -583,10 +1126,11 @@ var Trace = class _Trace {
     if (opts.projectDir) body.project_dir = opts.projectDir;
     if (opts.teamId) body.team_id = opts.teamId;
     if (opts.attachments) body.attachments = opts.attachments;
-    if (opts.llmProvider && opts.llmApiKey) {
-      body.llm_provider = opts.llmProvider;
-      body.llm_api_key = opts.llmApiKey;
-      if (opts.llmModelId) body.llm_model_id = opts.llmModelId;
+    const byok = this._resolveByok(opts);
+    if (byok.provider && byok.apiKey) {
+      body.llm_provider = byok.provider;
+      body.llm_api_key = byok.apiKey;
+      if (byok.modelId) body.llm_model_id = byok.modelId;
     }
     return body;
   }
@@ -615,7 +1159,7 @@ var Trace = class _Trace {
     });
     if (!resp.ok) {
       const errText = await resp.text().catch(() => "");
-      throw _Trace._httpError(resp.status, errText);
+      throw _Trace._httpError(resp.status, errText, opts.mode);
     }
     if (!resp.body) {
       throw new TraceError("The backend returned an empty response stream.");
@@ -744,14 +1288,14 @@ var Trace = class _Trace {
       warning: data.warning || null,
       steps: data.steps || [],
       save(directory = ".") {
-        mkdirSync2(directory, { recursive: true });
+        mkdirSync4(directory, { recursive: true });
         if (type === "symbol" && kicadSym) {
-          const path = join2(directory, `${name}.kicad_sym`);
-          writeFileSync2(path, kicadSym, "utf-8");
+          const path = join4(directory, `${name}.kicad_sym`);
+          writeFileSync4(path, kicadSym, "utf-8");
           return path;
         } else if (type === "footprint" && kicadMod) {
-          const path = join2(directory, `${name}.kicad_mod`);
-          writeFileSync2(path, kicadMod, "utf-8");
+          const path = join4(directory, `${name}.kicad_mod`);
+          writeFileSync4(path, kicadMod, "utf-8");
           return path;
         }
         throw new Error(`No content to save for ${type} '${name}'`);
@@ -763,6 +1307,15 @@ var index_default = Trace;
 export {
   Trace,
   TraceError,
+  TracePlanRestrictedError,
   TraceToolExecutionError,
-  index_default as default
+  browserLogin,
+  clearCredentials,
+  index_default as default,
+  deriveFrontendUrl,
+  getConfigDir,
+  getStoredAccessToken,
+  openBrowser,
+  readCredentials,
+  storeCredentials
 };