@buildwithtrace/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,786 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Trace: () => Trace,
+  TraceError: () => TraceError,
+  TraceToolExecutionError: () => TraceToolExecutionError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var import_fs2 = require("fs");
+var import_path2 = require("path");
+
+// src/executor.ts
+var import_fs = require("fs");
+var import_path = require("path");
+var ALLOWED_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".trace_sch",
+  ".trace_pcb",
+  ".kicad_sch",
+  ".kicad_pcb",
+  ".kicad_sym",
+  ".kicad_mod",
+  ".net",
+  ".schdoc",
+  ".pcbdoc",
+  ".schlib",
+  ".pcblib",
+  ".prjpcb",
+  ".svg",
+  ".request",
+  ".response",
+  ".backup",
+  ".zip",
+  ".gbr",
+  ".drl",
+  ".md",
+  ".json",
+  ".csv",
+  ".pos"
+]);
+var ALLOWED_FILENAMES = /* @__PURE__ */ new Set([
+  "fp-lib-table",
+  "sym-lib-table"
+]);
+var TRACE_FILE_EXTENSIONS = /* @__PURE__ */ new Set([".trace_sch", ".trace_pcb"]);
+var SEARCHABLE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".trace_sch",
+  ".trace_pcb",
+  ".kicad_sch",
+  ".kicad_pcb",
+  ".kicad_sym",
+  ".kicad_mod",
+  ".md"
+]);
+var FILE_TOOLS = /* @__PURE__ */ new Set([
+  "read_file",
+  "write",
+  "search_replace",
+  "list_dir",
+  "grep",
+  "delete_trace_file",
+  // Trivial no-ops the backend agent may emit during a normal run; handling
+  // them (instead of throwing) keeps multi-step agent loops from dead-locking.
+  "todo_write",
+  "todo_read"
+]);
+function isFileTool(toolName) {
+  return FILE_TOOLS.has(toolName);
+}
+function ok(result, fileModified = false) {
+  return { result, success: true, fileModified };
+}
+function fail(result, fileModified = false) {
+  return { result, success: false, fileModified };
+}
+function argStr(args, ...keys) {
+  for (const k of keys) {
+    const v = args[k];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return "";
+}
+function argInt(args, key, dflt) {
+  const v = args[key];
+  if (typeof v === "number" && Number.isFinite(v)) return Math.trunc(v);
+  if (typeof v === "string" && v.trim() !== "" && !Number.isNaN(Number(v))) return Math.trunc(Number(v));
+  return dflt;
+}
+function argBool(args, key) {
+  return args[key] === true || args[key] === "true";
+}
+function canonicalize(p) {
+  const abs = (0, import_path.resolve)(p);
+  let current = abs;
+  const tail = [];
+  for (; ; ) {
+    try {
+      const real = (0, import_fs.realpathSync)(current);
+      return tail.length ? (0, import_path.join)(real, ...tail.reverse()) : real;
+    } catch {
+      const parent = (0, import_path.dirname)(current);
+      if (parent === current) {
+        return abs;
+      }
+      tail.push((0, import_path.basename)(current));
+      current = parent;
+    }
+  }
+}
+function isInside(parent, child) {
+  if (child === parent) return true;
+  const rel = (0, import_path.relative)(parent, child);
+  return rel !== "" && !rel.startsWith(".." + import_path.sep) && rel !== ".." && !(0, import_path.isAbsolute)(rel);
+}
+function validateFilePath(filePath, projectDir, operation = "access") {
+  if (!filePath) return { ok: false, error: "Security: Empty file path" };
+  let target = filePath;
+  if (!(0, import_path.isAbsolute)(target)) target = (0, import_path.join)(projectDir, target);
+  let canonical;
+  try {
+    canonical = canonicalize(target);
+  } catch {
+    return { ok: false, error: `Security: Could not resolve path: ${filePath}` };
+  }
+  const ext = (0, import_path.extname)(canonical).toLowerCase();
+  const name = (0, import_path.basename)(canonical);
+  if (!ALLOWED_EXTENSIONS.has(ext) && !ALLOWED_FILENAMES.has(name)) {
+    return {
+      ok: false,
+      error: `Security: Blocked ${operation} to disallowed file type: ${ext} (file: ${name})`
+    };
+  }
+  const projectResolved = canonicalize(projectDir);
+  if (!isInside(projectResolved, canonical)) {
+    return { ok: false, error: `Security: Path escapes project directory: ${filePath}` };
+  }
+  return { ok: true, path: canonical };
+}
+function resolveInProject(p, projectDir) {
+  return (0, import_path.isAbsolute)(p) ? p : (0, import_path.join)(projectDir, p);
+}
+function isTraceFile(p) {
+  return TRACE_FILE_EXTENSIONS.has((0, import_path.extname)(p).toLowerCase());
+}
+function traceConversionNote(p) {
+  if (!isTraceFile(p)) return "";
+  return " NOTE: this SDK does not run the trace\u2192KiCad converter, so the matching .kicad_* file was NOT regenerated. Use the `buildwithtrace` CLI or the desktop app to produce the native KiCad file.";
+}
+function executeReadFile(args, projectDir, defaultFile) {
+  const filePath = argStr(args, "target_file", "file_path") || defaultFile;
+  if (!filePath) return fail("Error: No file path specified");
+  const v = validateFilePath(filePath, projectDir, "read");
+  if (!v.ok) return fail(v.error);
+  if (!(0, import_fs.existsSync)(v.path)) return fail(`Error: File not found: ${filePath}`);
+  let content;
+  try {
+    content = (0, import_fs.readFileSync)(v.path, "utf-8");
+  } catch (e) {
+    return fail(`Error reading file: ${e.message}`);
+  }
+  if (content.length === 0) return ok("File is empty.");
+  const lines = content.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  const offset = Math.max(1, argInt(args, "offset", 1));
+  const limit = argInt(args, "limit", -1);
+  if (offset > lines.length) {
+    return fail(`Error: offset ${offset} exceeds file length (${lines.length} lines)`);
+  }
+  const end = limit === -1 ? lines.length : Math.min(offset + limit - 1, lines.length);
+  const out = [];
+  for (let i = offset; i <= end; i++) {
+    out.push(`${String(i).padStart(6)}|${lines[i - 1]}`);
+  }
+  return ok(out.join("\n"));
+}
+function executeWrite(args, projectDir) {
+  const filePath = argStr(args, "file_path");
+  const contents = typeof args.contents === "string" ? args.contents : "";
+  if (!filePath) return fail("Error: file_path is required");
+  const v = validateFilePath(filePath, projectDir, "write");
+  if (!v.ok) return fail(v.error);
+  try {
+    (0, import_fs.mkdirSync)((0, import_path.dirname)(v.path), { recursive: true });
+    (0, import_fs.writeFileSync)(v.path, contents, "utf-8");
+  } catch (e) {
+    return fail(`Error writing file: ${e.message}`);
+  }
+  return ok(`File written successfully.${traceConversionNote(v.path)}`, true);
+}
+function executeSearchReplace(args, projectDir, defaultFile) {
+  const filePath = argStr(args, "file_path") || defaultFile;
+  const oldString = typeof args.old_string === "string" ? args.old_string : "";
+  const newString = typeof args.new_string === "string" ? args.new_string : "";
+  const replaceAll = argBool(args, "replace_all");
+  if (!oldString) return fail("Error: old_string cannot be empty");
+  if (oldString === newString) {
+    return fail("Error: old_string and new_string are identical - no change needed");
+  }
+  if (!filePath) return fail("Error: No file path specified");
+  const v = validateFilePath(filePath, projectDir, "write");
+  if (!v.ok) return fail(v.error);
+  if (!(0, import_fs.existsSync)(v.path)) return fail(`Error: File not found: ${filePath}`);
+  let content;
+  try {
+    content = (0, import_fs.readFileSync)(v.path, "utf-8");
+  } catch (e) {
+    return fail(`Error reading file: ${e.message}`);
+  }
+  const count = content.split(oldString).length - 1;
+  if (count === 0) {
+    return fail("Error: old_string not found in file. Re-read the file to see current content.");
+  }
+  if (!replaceAll && count > 1) {
+    return fail(
+      `Error: old_string found ${count} times in file - must be unique. Provide more surrounding context to make it unique, or set replace_all=true.`
+    );
+  }
+  const newContent = replaceAll ? content.split(oldString).join(newString) : content.replace(oldString, newString);
+  try {
+    (0, import_fs.writeFileSync)(v.path, newContent, "utf-8");
+  } catch (e) {
+    return fail(`Error writing file: ${e.message}`);
+  }
+  const replacements = replaceAll ? count : 1;
+  const base = `Successfully replaced ${replacements} occurrence${replacements > 1 ? "s" : ""}.`;
+  return ok(`${base}${traceConversionNote(v.path)}`, true);
+}
+function executeListDir(args, projectDir) {
+  const dirPath = argStr(args, "path") || projectDir;
+  const path = resolveInProject(dirPath, projectDir);
+  const projectResolved = canonicalize(projectDir);
+  if (!isInside(projectResolved, canonicalize(path))) {
+    return fail("Security error: Path outside project directory");
+  }
+  let stat;
+  try {
+    stat = (0, import_fs.statSync)(path);
+  } catch {
+    return fail(`Error: Not a directory: ${dirPath}`);
+  }
+  if (!stat.isDirectory()) return fail(`Error: Not a directory: ${dirPath}`);
+  const entries = [];
+  let names;
+  try {
+    names = (0, import_fs.readdirSync)(path).sort();
+  } catch (e) {
+    return fail(`Error listing directory: ${e.message}`);
+  }
+  for (const itemName of names) {
+    if (itemName.startsWith(".") && itemName !== ".trace") continue;
+    const full = (0, import_path.join)(path, itemName);
+    let s;
+    try {
+      s = (0, import_fs.statSync)(full);
+    } catch {
+      continue;
+    }
+    if (s.isDirectory()) {
+      if ((0, import_path.extname)(itemName) === ".pretty" || itemName === ".trace") entries.push(`${itemName}/`);
+    } else if (ALLOWED_EXTENSIONS.has((0, import_path.extname)(itemName).toLowerCase()) || ALLOWED_FILENAMES.has(itemName)) {
+      entries.push(itemName);
+    }
+  }
+  const traceDir = (0, import_path.join)(path, ".trace");
+  try {
+    if ((0, import_fs.statSync)(traceDir).isDirectory()) {
+      for (const sub of (0, import_fs.readdirSync)(traceDir).sort()) {
+        if ((0, import_path.extname)(sub).toLowerCase() === ".md") entries.push(`.trace/${sub}`);
+      }
+    }
+  } catch {
+  }
+  return ok(JSON.stringify(entries));
+}
+function walkFiles(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let names;
+    try {
+      names = (0, import_fs.readdirSync)(dir);
+    } catch {
+      continue;
+    }
+    for (const n of names) {
+      const full = (0, import_path.join)(dir, n);
+      let s;
+      try {
+        s = (0, import_fs.statSync)(full);
+      } catch {
+        continue;
+      }
+      if (s.isDirectory()) stack.push(full);
+      else if (SEARCHABLE_EXTENSIONS.has((0, import_path.extname)(full).toLowerCase())) out.push(full);
+    }
+  }
+  return out;
+}
+function executeGrep(args, projectDir) {
+  const pattern = argStr(args, "pattern");
+  if (!pattern) return fail("Error: pattern is required");
+  const searchPath = argStr(args, "path") || projectDir;
+  const path = resolveInProject(searchPath, projectDir);
+  const projectResolved = canonicalize(projectDir);
+  if (!isInside(projectResolved, canonicalize(path))) {
+    return fail("Security error: Path outside project directory");
+  }
+  const caseInsensitive = argBool(args, "i");
+  const outputMode = argStr(args, "output_mode") || "content";
+  let contextBefore = argInt(args, "B", 0);
+  let contextAfter = argInt(args, "A", 0);
+  const contextBoth = argInt(args, "C", 0);
+  const headLimit = argInt(args, "head_limit", -1);
+  if (contextBoth > 0) {
+    contextBefore = contextBoth;
+    contextAfter = contextBoth;
+  }
+  let regex;
+  try {
+    regex = new RegExp(pattern, caseInsensitive ? "i" : "");
+  } catch (e) {
+    return fail(`Error: Invalid regex pattern: ${e.message}`);
+  }
+  let filesToSearch;
+  let isFile = false;
+  try {
+    isFile = (0, import_fs.statSync)(path).isFile();
+  } catch {
+    isFile = false;
+  }
+  filesToSearch = isFile ? [path] : walkFiles(path).sort();
+  let totalMatches = 0;
+  let filesMatched = 0;
+  const outputParts = [];
+  for (const file of filesToSearch) {
+    let lines;
+    try {
+      lines = (0, import_fs.readFileSync)(file, "utf-8").split("\n");
+    } catch {
+      continue;
+    }
+    if (lines.length && lines[lines.length - 1] === "") lines.pop();
+    const matchIdxs = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (regex.test(lines[i])) matchIdxs.push(i);
+      regex.lastIndex = 0;
+    }
+    if (matchIdxs.length === 0) continue;
+    filesMatched++;
+    let rel = (0, import_path.relative)(projectDir, file);
+    if (rel.startsWith("..")) rel = file;
+    if (outputMode === "files_with_matches") {
+      outputParts.push(rel);
+    } else if (outputMode === "count") {
+      outputParts.push(`${rel}:${matchIdxs.length}`);
+    } else {
+      outputParts.push(rel);
+      for (const mi of matchIdxs) {
+        const start = Math.max(0, mi - contextBefore);
+        const end = Math.min(lines.length, mi + 1 + contextAfter);
+        for (let ci = start; ci < end; ci++) {
+          const prefix = ci === mi ? ":" : "-";
+          outputParts.push(`${ci + 1}${prefix}${lines[ci]}`);
+        }
+        if (contextBefore > 0 || contextAfter > 0) outputParts.push("--");
+      }
+    }
+    totalMatches += matchIdxs.length;
+    if (headLimit > 0 && totalMatches >= headLimit) break;
+  }
+  if (outputParts.length === 0) return ok("No matches found.");
+  const header = `Found ${totalMatches} matches in ${filesMatched} files`;
+  return ok(`${header}
+${outputParts.join("\n")}`);
+}
+function executeDeleteTraceFile(args, projectDir) {
+  const filename = argStr(args, "filename", "file_name");
+  if (!filename) return fail("Error: filename is required");
+  const v = validateFilePath(filename, projectDir, "delete");
+  if (!v.ok) return fail(v.error);
+  if (!(0, import_fs.existsSync)(v.path)) return fail(`Error: File not found: ${filename}`);
+  try {
+    (0, import_fs.unlinkSync)(v.path);
+  } catch (e) {
+    return fail(`Error deleting file: ${e.message}`);
+  }
+  if ((0, import_path.extname)(v.path).toLowerCase() === ".trace_sch") {
+    const kicad = v.path.slice(0, -".trace_sch".length) + ".kicad_sch";
+    if ((0, import_fs.existsSync)(kicad)) {
+      try {
+        (0, import_fs.unlinkSync)(kicad);
+      } catch {
+        return ok(`Deleted ${filename} but failed to delete corresponding KiCad file`, true);
+      }
+    }
+  }
+  return ok(`Successfully deleted ${filename}`, true);
+}
+function executeFileTool(toolName, toolArgs, projectDir, defaultFile = "") {
+  switch (toolName) {
+    case "read_file":
+      return executeReadFile(toolArgs, projectDir, defaultFile);
+    case "write":
+      return executeWrite(toolArgs, projectDir);
+    case "search_replace":
+      return executeSearchReplace(toolArgs, projectDir, defaultFile);
+    case "list_dir":
+      return executeListDir(toolArgs, projectDir);
+    case "grep":
+      return executeGrep(toolArgs, projectDir);
+    case "delete_trace_file":
+      return executeDeleteTraceFile(toolArgs, projectDir);
+    case "todo_write":
+      return ok(JSON.stringify({ status: "ok" }));
+    case "todo_read":
+      return ok(JSON.stringify({ todos: [] }));
+    default:
+      return fail(`Unknown file tool '${toolName}'.`);
+  }
+}
+
+// src/index.ts
+var DEFAULT_API_URL = "https://api.buildwithtrace.com";
+var API_VERSION = "latest";
+var TraceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TraceError";
+  }
+};
+var TraceToolExecutionError = class extends TraceError {
+  constructor(message) {
+    super(message);
+    this.name = "TraceToolExecutionError";
+  }
+};
+var Trace = class _Trace {
+  constructor(config) {
+    this.apiKey = config.apiKey || process.env.TRACE_API_KEY || "";
+    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"
+      );
+    }
+    this.baseUrl = (config.baseUrl || process.env.TRACE_BASE_URL || DEFAULT_API_URL).replace(/\/$/, "");
+    this.timeout = config.timeout || 3e5;
+  }
+  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");
+  }
+  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");
+  }
+  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
+    }));
+  }
+  async ask(question, options) {
+    return 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, {
+      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
+   * chat contract: pcbnew vs eeschema (`appType`), multi-turn (`conversationId` —
+   * read it back off the result), team workspaces (`teamId`), multimodal
+   * `attachments`, `filePath` + `fileContent`, and BYOK
+   * (`llmProvider`/`llmApiKey`/`llmModelId`).
+   *
+   * NOTE: mode 'agent'/'plan' produce tool calls that run on the caller's
+   * machine. The SDK runs a client-side tool loop for FILE tools (read_file,
+   * write, search_replace, list_dir, grep, delete_trace_file), executing them
+   * under `projectDir` (defaults to process.cwd()) with the same path +
+   * extension allowlist as the CLI/desktop, and POSTing each result back to the
+   * backend so multi-step agent runs continue. Engine/GUI tools (ERC/DRC,
+   * gerber/export, take_snapshot, run_*, autoroute) are out of scope and throw
+   * TraceToolExecutionError — use the `buildwithtrace` CLI for those.
+   */
+  async chat(message, options) {
+    return this._streamChat(message, options || {});
+  }
+  async _post(path, body) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const resp = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "buildwithtrace-node-sdk/0.1.0"
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!resp.ok) {
+        const text = await resp.text().catch(() => "");
+        throw _Trace._httpError(resp.status, text);
+      }
+      return await resp.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  static _httpError(status, text) {
+    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.");
+    return new Error(`Trace API error ${status}: ${text.slice(0, 200)}`);
+  }
+  async _get(path) {
+    const resp = await fetch(`${this.baseUrl}${path}`, {
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "User-Agent": "buildwithtrace-node-sdk/0.1.0"
+      }
+    });
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => "");
+      throw _Trace._httpError(resp.status, text);
+    }
+    return await resp.json();
+  }
+  /**
+   * Single source of truth for the /chat/stream request body. Mirrors the
+   * backend ChatRequest contract so the SDK stays in lockstep with the
+   * CLI/desktop instead of sending a stale minimal payload.
+   */
+  _buildChatBody(message, opts, sessionId) {
+    const appType = opts.appType || "eeschema";
+    const body = {
+      message,
+      mode: opts.mode || "ask",
+      session_id: sessionId,
+      app_type: appType,
+      api_version: API_VERSION,
+      client: "sdk"
+    };
+    if (opts.conversationId) body.conversation_id = opts.conversationId;
+    if (opts.fileContent) {
+      if (appType === "pcbnew") body.pcb_content = opts.fileContent;
+      else body.schematic_content = opts.fileContent;
+      body.total_lines = opts.fileContent.split("\n").length;
+    }
+    if (opts.filePath) body.file_path = opts.filePath;
+    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;
+    }
+    return body;
+  }
+  /**
+   * Stream /chat/stream and drive a client-side tool loop.
+   *
+   * The backend pauses the SSE stream at each `tool_call` until the client POSTs
+   * the result to /tools/result, so we MUST read the body incrementally (not
+   * buffer it whole — that would dead-lock waiting for `done`). FILE tools are
+   * executed locally under `projectDir`; their result is posted back and the
+   * SAME stream keeps yielding events (the backend drives the multi-step loop)
+   * until `done`. Engine/GUI tools are out of scope and throw.
+   */
+  async _streamChat(message, opts) {
+    const sessionId = `sdk-${Date.now().toString(36)}`;
+    const body = this._buildChatBody(message, opts, sessionId);
+    const resp = await fetch(`${this.baseUrl}/api/${API_VERSION}/chat/stream`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        "Accept": "text/event-stream",
+        "User-Agent": "buildwithtrace-node-sdk/0.1.0"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!resp.ok) {
+      const errText = await resp.text().catch(() => "");
+      throw _Trace._httpError(resp.status, errText);
+    }
+    if (!resp.body) {
+      throw new TraceError("The backend returned an empty response stream.");
+    }
+    const projectDir = opts.projectDir ? (0, import_path2.resolve)(opts.projectDir) : process.cwd();
+    const defaultFile = opts.filePath || "";
+    const textParts = [];
+    let conversationId = opts.conversationId || null;
+    let usage = null;
+    const handleEvent = async (event) => {
+      switch (event.type) {
+        case "text_delta":
+          textParts.push(event.content || "");
+          break;
+        case "done":
+          conversationId = event.conversation_id || conversationId;
+          break;
+        case "metrics":
+          usage = event;
+          break;
+        case "error":
+          throw new TraceError(event.content || "The backend returned an error.");
+        case "tool_call":
+          await this._handleToolCall(event, sessionId, projectDir, defaultFile);
+          break;
+        default:
+          break;
+      }
+    };
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buffer.indexOf("\n")) >= 0) {
+          const line = buffer.slice(0, nl);
+          buffer = buffer.slice(nl + 1);
+          const ev = _Trace._parseSSELine(line);
+          if (ev) await handleEvent(ev);
+        }
+      }
+      buffer += decoder.decode();
+      if (buffer.length) {
+        const ev = _Trace._parseSSELine(buffer);
+        if (ev) await handleEvent(ev);
+      }
+    } finally {
+      reader.cancel().catch(() => {
+      });
+    }
+    return { text: textParts.join(""), conversationId, usage };
+  }
+  static _parseSSELine(line) {
+    if (!line.startsWith("data:")) return null;
+    const payload = line.slice(5).trim();
+    if (!payload) return null;
+    try {
+      return JSON.parse(payload);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Execute one tool call. FILE tools run locally (sandboxed to projectDir) and
+   * their result is POSTed to /tools/result so the backend continues the stream.
+   * Engine/GUI tools are out of scope and throw TraceToolExecutionError.
+   */
+  async _handleToolCall(event, sessionId, projectDir, defaultFile) {
+    const toolName = event.tool_name || "unknown";
+    const toolCallId = event.tool_call_id || "";
+    const toolArgs = event.tool_args || {};
+    if (!isFileTool(toolName)) {
+      throw new TraceToolExecutionError(
+        `The agent requested '${toolName}', which the SDK does not execute. The SDK runs FILE tools only (read_file, write, search_replace, list_dir, grep, delete_trace_file); engine/GUI tools (ERC/DRC, gerber/export, take_snapshot, run_*, autoroute) require the \`buildwithtrace\` CLI or the desktop app.`
+      );
+    }
+    const result = executeFileTool(toolName, toolArgs, projectDir, defaultFile);
+    await this._postToolResult(sessionId, toolCallId, result.result, !result.success);
+  }
+  /**
+   * POST a tool result back to /api/<version>/tools/result (same base URL +
+   * version as /chat/stream). Non-fatal on failure — like the CLI, we warn and
+   * move on rather than crashing the loop (the backend turn will time out).
+   */
+  async _postToolResult(sessionId, toolCallId, result, isError) {
+    const payload = {
+      session_id: sessionId,
+      tool_call_id: toolCallId,
+      result
+    };
+    if (isError) payload.is_error = true;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        const resp = await fetch(`${this.baseUrl}/api/${API_VERSION}/tools/result`, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            "User-Agent": "buildwithtrace-node-sdk/0.1.0"
+          },
+          body: JSON.stringify(payload)
+        });
+        if (resp.ok) return;
+      } catch {
+      }
+      if (attempt < 2) await new Promise((r) => setTimeout(r, 250 * (attempt + 1)));
+    }
+  }
+  _makeGenerateResult(data, type) {
+    const name = data.name || "";
+    const kicadSym = data.kicad_sym || null;
+    const kicadMod = data.kicad_mod || null;
+    return {
+      name,
+      type,
+      description: data.description || "",
+      pinCount: data.pin_count || 0,
+      padCount: data.pad_count || 0,
+      kicadSym,
+      kicadMod,
+      traceJson: data.trace_json || null,
+      warning: data.warning || null,
+      steps: data.steps || [],
+      save(directory = ".") {
+        (0, import_fs2.mkdirSync)(directory, { recursive: true });
+        if (type === "symbol" && kicadSym) {
+          const path = (0, import_path2.join)(directory, `${name}.kicad_sym`);
+          (0, import_fs2.writeFileSync)(path, kicadSym, "utf-8");
+          return path;
+        } else if (type === "footprint" && kicadMod) {
+          const path = (0, import_path2.join)(directory, `${name}.kicad_mod`);
+          (0, import_fs2.writeFileSync)(path, kicadMod, "utf-8");
+          return path;
+        }
+        throw new Error(`No content to save for ${type} '${name}'`);
+      }
+    };
+  }
+};
+var index_default = Trace;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Trace,
+  TraceError,
+  TraceToolExecutionError
+});