@huaqiu/dsh-tool-schematic-gen 0.1.1

package/src/client/trace-names.ts

@@ -0,0 +1,308 @@
+/**
+ * Display names for the agents' graph nodes and tool calls (zh + en).
+ *
+ * The eda.cn backend streams raw code identifiers — `node:schematicDesign`,
+ * `search_parts`, `es_rag_search` — and the call stack used to render them
+ * verbatim, so a Chinese UI showed an English snake_case stack. This module is
+ * the dictionary that turns an identifier into a sentence.
+ *
+ * Port of `hq-eda-ai`'s two resolvers:
+ *
+ *   - schematic  → `apps/web/src/components/sch_sub_gen/TraceTimeline.tsx`
+ *     (`resolveName`: `SchematicGen.Trace.Nodes` → `.Tools` → `ToolCalls`)
+ *   - system     → `apps/web/src/components/modular_circuit/ModuleGenTraceTimeline.tsx`
+ *     (`resolveName`: `ToolCalls` only)
+ *
+ * with the dictionaries taken from `apps/web/src/locales/{cn,en}.ts` — the
+ * `ToolCalls` table plus the `SchematicGen.Trace.{Nodes,Tools}` overrides.
+ *
+ * Names that are NOT in any dictionary are returned unchanged on purpose:
+ * the module worker instances are named after the module the agent is working
+ * on ("Type-C USB2.0 接口保护模块"), and those are already copy, not code.
+ */
+import { useCallback } from 'react'
+import type { AuthLocale } from './login-url.js'
+import { useLocale } from './theme.js'
+
+/** Prefix `traceName()` puts on a LangGraph node so it cannot collide with a tool. */
+const NODE_PREFIX = 'node:'
+
+// ── Shared node / tool vocabulary ──────────────────────────────────────────
+// The system-design agent (`modular_circuit`) resolves EVERYTHING through this
+// one table. The schematic agent uses it as its last resort — which is where
+// `es_rag_search` / `es_category_search` / `es_precise_search` come from, since
+// they are absent from `SchematicGen.Trace.Tools`.
+
+/**
+ * Chinese is the source of truth, as in `client/i18n.ts`: `CallNameKey` is
+ * derived from it and `TOOL_CALLS_EN` is typed against it, so a name added to
+ * zh but missing from en is a COMPILE error rather than a Chinese fallback
+ * leaking into an English UI.
+ */
+const TOOL_CALLS_ZH = {
+  // Search
+  plan_search: '搜索规划',
+  es_category_search: '分类搜索',
+  es_precise_search: '精准搜索',
+  es_rag_search: '语义搜索',
+  ComponentSearchOutput: '元件检索',
+  // Routing / agent
+  intent_resolver: '路由决策',
+  generate_design_plan: '生成设计方案',
+  reflect_design: '设计反思',
+  module_ops_agent: '模块管理助手',
+  // TypeScript graph nodes
+  intentResolver: '需求分析',
+  generateDesignPlan: '生成设计方案',
+  moduleOpsAgent: '模块管理',
+  designAgent: '系统设计',
+  model_request: '分析与决策',
+  tools: '执行工具',
+  design_plan_gen: '生成设计方案',
+  module_search: '模块搜索',
+  module_connect: '模块连接',
+  request_module_change: '模块替换',
+  prepareSearch: '准备搜索任务',
+  planSearch: '搜索规划',
+  componentWorker: '器件搜索',
+  syncModules: '同步模块',
+  connectModules: '模块连接设计',
+  buildModuleGraph: '生成连接图',
+  request_design_decision: '确认设计决策',
+  request_module_review: '确认模块变更',
+  reflectDesign: '设计复核',
+  ercCheckNode: '电气规则检查',
+  exportCircuit: '导出电路',
+  schematicDesign: '原理图设计',
+  checkCircuit: '电路校验',
+  datasheetReview: '数据手册评审',
+  layoutAnnotate: '布局规划',
+  integrateFlat: '生成原理图',
+  genPreviewUrl: '生成预览',
+  // Component / module operations
+  component_worker: '搜索元器件',
+  search_modules: '搜索模块',
+  add_modules: '添加模块',
+  replace_modules: '替换模块',
+  rm_modules: '移除模块',
+  complete_modules: '补全模块',
+  connect_modules: '连接模块',
+  // Design / schematic
+  kicad_schematic_generate: '生成 KiCad 原理图',
+  generate_design_outline: '生成流程图',
+  write_connection: '写入连接',
+  update_virtual_module_ports: '更新模块端口',
+  submit_connection_report: '提交设计报告',
+  // Engineering / validation
+  erc_check: '电气规则检查',
+  add_new_eco: '添加 ECO',
+  apply_user_option: '应用用户选项',
+  // BOM
+  update_bom: '更新 BOM',
+  add_module: '添加模块',
+  delete_module: '删除模块',
+  research_module: '重新搜索模块',
+  replace_module: '替换模块',
+  update_quantity: '更新数量',
+} as const
+
+type CallNameKey = keyof typeof TOOL_CALLS_ZH
+
+const TOOL_CALLS_EN: Record<CallNameKey, string> = {
+  plan_search: 'Search Planning',
+  es_category_search: 'Category Search',
+  es_precise_search: 'Precise Search',
+  es_rag_search: 'Semantic Search',
+  ComponentSearchOutput: 'Component Retrieval',
+  intent_resolver: 'Routing Decision',
+  generate_design_plan: 'Generate Design Plan',
+  reflect_design: 'Design Reflection',
+  module_ops_agent: 'Module Operations Agent',
+  intentResolver: 'Requirements Analysis',
+  generateDesignPlan: 'Design Plan Generation',
+  moduleOpsAgent: 'Module Operations',
+  designAgent: 'System Design',
+  model_request: 'Analysis and Decision',
+  tools: 'Run Tools',
+  design_plan_gen: 'Generate Design Plan',
+  module_search: 'Module Search',
+  module_connect: 'Module Connection',
+  request_module_change: 'Module Replacement',
+  prepareSearch: 'Prepare Search Tasks',
+  planSearch: 'Component Search Planning',
+  componentWorker: 'Component Search',
+  syncModules: 'Module Synchronization',
+  connectModules: 'Module Interconnection Design',
+  buildModuleGraph: 'Build Connection Graph',
+  request_design_decision: 'Confirm Design Decision',
+  request_module_review: 'Review Module Changes',
+  reflectDesign: 'Design Review',
+  ercCheckNode: 'Electrical Rules Validation',
+  exportCircuit: 'Circuit Export',
+  schematicDesign: 'Schematic Design',
+  checkCircuit: 'Circuit Validation',
+  datasheetReview: 'Datasheet Review',
+  layoutAnnotate: 'Schematic Layout Planning',
+  integrateFlat: 'Schematic Generation',
+  genPreviewUrl: 'Preview Rendering',
+  component_worker: 'Search Components',
+  search_modules: 'Search Modules',
+  add_modules: 'Add Modules',
+  replace_modules: 'Replace Modules',
+  rm_modules: 'Remove Modules',
+  complete_modules: 'Complete Modules',
+  connect_modules: 'Connect Modules',
+  kicad_schematic_generate: 'Generate KiCad Schematic',
+  generate_design_outline: 'Generate Diagram',
+  write_connection: 'Write Connections',
+  update_virtual_module_ports: 'Update Module Ports',
+  submit_connection_report: 'Submit Design Report',
+  erc_check: 'Electrical Rules Check',
+  add_new_eco: 'Add ECO',
+  apply_user_option: 'Apply User Options',
+  update_bom: 'Update BOM',
+  add_module: 'Add Module',
+  delete_module: 'Delete Module',
+  research_module: 'Research Module',
+  replace_module: 'Replace Module',
+  update_quantity: 'Update Quantity',
+}
+
+// ── Schematic-gen overrides ────────────────────────────────────────────────
+// The schematic agent reuses some identifiers with a different, more specific
+// meaning than `TOOL_CALLS` gives them — `schematicDesign` is "原理图设计"
+// generically but "需求解析与电路设计" as a schematic node, and `search_parts`
+// is the subagent (子代理) when it is a node but plain 物料搜索与选型 when it is
+// a tool. These two tables are consulted BEFORE `TOOL_CALLS`.
+
+const SCH_NODES_ZH = {
+  schematicDesign: '需求解析与电路设计',
+  datasheetReview: '数据手册设计复核',
+  checkCircuit: '电气连接完整性检查',
+  layoutAnnotate: '原理图布局规划',
+  integrateFlat: '生成 KiCad 原理图',
+  genPreviewUrl: '生成原理图预览',
+  search_parts: '物料搜索与选型子代理',
+  circuit_review: '电路设计评审子代理',
+} as const
+
+type SchNodeKey = keyof typeof SCH_NODES_ZH
+
+const SCH_NODES_EN: Record<SchNodeKey, string> = {
+  schematicDesign: 'Circuit Design Engineering',
+  datasheetReview: 'Design Review',
+  checkCircuit: 'Electrical Design Validation',
+  layoutAnnotate: 'Schematic Layout Planning',
+  integrateFlat: 'Schematic Generation',
+  genPreviewUrl: 'Preview Rendering',
+  search_parts: 'Component Selection Subagent',
+  circuit_review: 'Circuit Design Review Subagent',
+}
+
+const SCH_TOOLS_ZH = {
+  symbol_search: '器件符号检索',
+  ic_search: '芯片型号检索',
+  search_parts: '物料搜索与选型',
+  research_datasheet: '数据手册研究',
+  submit_module: '提交并校验电路设计',
+  check_ic: '芯片应用电路检查',
+  ic_datasheet_search: '芯片数据手册检索',
+  circuit_review: '电路设计评审',
+} as const
+
+type SchToolKey = keyof typeof SCH_TOOLS_ZH
+
+const SCH_TOOLS_EN: Record<SchToolKey, string> = {
+  symbol_search: 'Component Search',
+  ic_search: 'IC Search',
+  search_parts: 'Component Selection',
+  research_datasheet: 'Datasheet Research',
+  submit_module: 'Design Submission',
+  check_ic: 'IC Application Check',
+  ic_datasheet_search: 'IC Datasheet Search',
+  circuit_review: 'Circuit Design Review',
+}
+
+// ── Packs ──────────────────────────────────────────────────────────────────
+
+interface NamePack {
+  /** Schematic graph nodes (checked first, schematic runs only). */
+  nodes: Record<string, string>
+  /** Schematic tool names (checked second). */
+  tools: Record<string, string>
+  /** Shared node + tool vocabulary (system runs use only this one). */
+  calls: Record<string, string>
+}
+
+const PACKS: Record<AuthLocale, NamePack> = {
+  zh: {
+    nodes: SCH_NODES_ZH as Record<string, string>,
+    tools: SCH_TOOLS_ZH as Record<string, string>,
+    calls: TOOL_CALLS_ZH as Record<string, string>,
+  },
+  en: {
+    nodes: SCH_NODES_EN as Record<string, string>,
+    tools: SCH_TOOLS_EN as Record<string, string>,
+    calls: TOOL_CALLS_EN as Record<string, string>,
+  },
+}
+
+/** Exported for tests: the raw packs, so zh/en parity can be asserted. */
+export const TRACE_NAME_PACKS = PACKS
+
+/** Which agent produced the run — decides which tables apply. */
+export type TraceKind = 'schematic' | 'system'
+
+/**
+ * Turn one raw trace identifier into the localized display name.
+ *
+ * Resolution order for a schematic run mirrors `TraceTimeline#resolveName`:
+ * `node:<name>` → schematic nodes → schematic tools → shared table → the bare
+ * name. The last step is what keeps module instance titles intact.
+ */
+export function resolveTraceName(raw: string, kind: TraceKind, locale: AuthLocale): string {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    return raw
+  }
+  const pack = PACKS[locale] ?? PACKS.zh
+  const name = raw.startsWith(NODE_PREFIX) ? raw.slice(NODE_PREFIX.length) : raw
+
+  // System design has no per-agent override tables: one flat lookup, and
+  // anything unknown (a module worker instance named after its module) passes
+  // straight through.
+  if (kind === 'system') {
+    return pack.calls[name] ?? name
+  }
+
+  if (pack.nodes[name]) {
+    return pack.nodes[name]!
+  }
+  const asTool = pack.tools[name] ?? pack.calls[name]
+  if (asTool) {
+    return asTool
+  }
+
+  // `base:suffix` forms render as "Label · suffix". Unlike hq-eda-ai — which
+  // drops the suffix whenever the base is unknown (`tools[base] ?? base`) —
+  // we only split when the base IS known, so a name that merely contains a
+  // colon survives intact.
+  const sep = name.indexOf(':')
+  if (sep > 0 && sep < name.length - 1) {
+    const base = name.slice(0, sep)
+    const label = pack.tools[base] ?? pack.calls[base]
+    if (label) {
+      return `${label} · ${name.slice(sep + 1)}`
+    }
+  }
+
+  return name
+}
+
+/** `resolveTraceName` bound to the host UI language. */
+export function useTraceNames(kind: TraceKind): (name: string) => string {
+  const locale = useLocale()
+  return useCallback(
+    (name: string) => resolveTraceName(name, kind, locale),
+    [kind, locale],
+  )
+}

package/src/client/trace-tree.ts

@@ -0,0 +1,185 @@
+/**
+ * Flat trace frames → nested call stack (browser half).
+ *
+ * Port of `hq-eda-ai`'s prototype
+ * (`docs/prototype/tool_call_stack_prototype.tsx#buildTree`), adapted to the
+ * paired {@link TraceFrame} list produced on the node side rather than to raw
+ * events.
+ *
+ * Each frame carries a `parent>child>leaf` breadcrumb in `path`. This module
+ * turns those breadcrumbs into a tree, synthesizing intermediate frames for
+ * path segments that never emitted an event of their own — exactly the
+ * "Recursive Depth Model" the prototype describes.
+ */
+import { stripTaskIds, type TraceFrame, type TraceStatus } from '../trace.js'
+
+/**
+ * One node of the rendered call stack.
+ *
+ * A row is collapsed — i.e. represents several invocations of the same
+ * logical call at the same visible scope — whenever `repeat > 1`. The runtime
+ * keeps the LATEST frame on `frame`, so the duration column shows the most
+ * recent call's time, and the ×N badge surfaces how many calls actually ran
+ * (the schematic agent fires `ic_search` fourteen times in a row to confirm
+ * the part pick; hq-eda-ai shows ONE row for that).
+ */
+export interface StackNode {
+  /** Stable React key. Path-derived for synthesized nodes, frame id otherwise. */
+  id: string
+  /** Display name (`node:plan` for graph nodes, bare name for tools). */
+  name: string
+  status: TraceStatus
+  /** 0 for a root; each nesting level adds one. */
+  depth: number
+  /**
+   * Start of the LATEST invocation. For a one-off this is also the start of
+   * the only invocation. The card uses this together with `finishedAt` to
+   * compute the latest call's duration.
+   */
+  startedAt: number
+  finishedAt?: number
+  children: StackNode[]
+  /**
+   * How many times this exact call ran. `1` for a one-off.
+   *
+   * Every repeat — whether from a LangGraph `*_TRACE` event with no task id
+   * (schematic) or from the AG-UI tool-call lifecycle with a hidden
+   * `::task:<id>` (system design) — lands on the same leaf, keyed on the
+   * STRIPPED visible path. The card surfaces the count via a `×N` pill.
+   */
+  repeat: number
+  /**
+   * The frame this node was built from. `undefined` for synthesized
+   * intermediate nodes, which exist only to hold the nesting shape.
+   */
+  frame?: TraceFrame
+}
+
+/**
+ * Build the call-stack tree.
+ *
+ * Path prefixes are shared, so a parent emitted by five different children
+ * is one node, not five. Repeated calls of the same tool at the same scope
+ * collapse into one row — both the schematic CUSTOM-trace stream (no task
+ * ids) and the system-design AG-UI lifecycle (hidden `::task:<id>` in each
+ * instance path) end up with one node per logical call.
+ */
+export function buildTree(frames: readonly TraceFrame[]): StackNode[] {
+  const roots: StackNode[] = []
+  const byPath = new Map<string, StackNode>()
+
+  for (const frame of frames) {
+    const segments = frame.path.split('>').map((s) => s.trim()).filter((s) => s.length > 0)
+    if (segments.length === 0) {
+      continue
+    }
+
+    // 1. Walk every path prefix, creating intermediate nodes as needed.
+    //    Key the map on the *visible* path (with any `::task:<id>` marker
+    //    stripped) so repeats land on one node instead of proliferating into
+    //    a sibling per invocation.
+    let parent: StackNode | null = null
+    for (let i = 0; i < segments.length; i++) {
+      const raw = segments.slice(0, i + 1).join('>')
+      const pathId = stripTaskIds(raw)
+      let node = byPath.get(pathId)
+      if (!node) {
+        node = {
+          id: `path:${pathId}`,
+          name: stripTaskIds(segments[i]!),
+          status: 'running',
+          depth: i,
+          startedAt: frame.startedAt,
+          children: [],
+          repeat: 1,
+        }
+        byPath.set(pathId, node)
+        if (parent) {
+          parent.children.push(node)
+        } else {
+          roots.push(node)
+        }
+      }
+      parent = node
+    }
+
+    if (!parent) {
+      continue
+    }
+
+    // 2. Decorate the leaf with this frame.
+    if (!parent.frame) {
+      parent.frame = frame
+      // Prefer the frame's own display name: for a graph node the last path
+      // segment is the bare node name while the frame name is `node:<name>`.
+      parent.name = frame.name
+      parent.status = frame.status
+      parent.startedAt = frame.startedAt
+      if (frame.finishedAt !== undefined) {
+        parent.finishedAt = frame.finishedAt
+      }
+      continue
+    }
+
+    // A repeat of a call we already show: bump the counter and let the
+    // latest invocation win for status + duration.
+    parent.repeat += 1
+    parent.frame = frame
+    parent.name = frame.name
+    parent.status = frame.status
+    parent.startedAt = frame.startedAt
+    if (frame.finishedAt !== undefined) {
+      parent.finishedAt = frame.finishedAt
+    } else {
+      delete parent.finishedAt
+    }
+  }
+
+  return roots
+}
+
+/** Count frames by status, for the `done/total` badge on a parent. */
+export function countStatus(node: StackNode): { finished: number; total: number; failed: number } {
+  let finished = 0
+  let total = 0
+  let failed = 0
+  const walk = (n: StackNode): void => {
+    for (const child of n.children) {
+      total += 1
+      if (child.status === 'finished') {
+        finished += 1
+      }
+      if (child.status === 'failed') {
+        failed += 1
+      }
+      walk(child)
+    }
+  }
+  walk(node)
+  return { finished, total, failed }
+}
+
+/**
+ * Format a span as `123ms` under a second and `4.2s` above, mirroring the
+ * prototype's duration formatter.
+ */
+export function formatDuration(ms: number | null | undefined): string {
+  if (ms === null || ms === undefined || !Number.isFinite(ms) || ms < 0) {
+    return ''
+  }
+  if (ms < 1000) {
+    return `${Math.round(ms)}ms`
+  }
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+/** Format an elapsed wall-clock span as `m:ss` — used by the run timer. */
+export function formatElapsed(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) {
+    return '0:00'
+  }
+  const total = Math.floor(ms / 1000)
+  const m = Math.floor(total / 60)
+  const s = total % 60
+  return `${m}:${String(s).padStart(2, '0')}`
+}

package/src/config.ts

@@ -0,0 +1,203 @@
+/**
+ * `@huaqiu/dsh-tool-schematic-gen` — config, agent identity, run-body and
+ * filename helpers (pure, dependency-free).
+ *
+ * Faithful TypeScript port of the `hq-edge` schematic-gen node half, with ONE
+ * deliberate change per migration plan review #9: the demo eda.cn account is
+ * REMOVED. The account now always comes from the `huaqiuAuth` service
+ * (`getUserInfo()` → `x-user-id` / `x-user-token`); there is no baked-in
+ * default credential.
+ *
+ * @module @huaqiu/dsh-tool-schematic-gen
+ */
+import { randomUUID } from 'node:crypto'
+
+/** CopilotKit `agentId` values the two tools drive. */
+export const agentIds = {
+  /** description → final KiCad schematic (`.kicad_sch` files). */
+  SCHEMATIC: 'schemagen',
+  /** description → module graph → KiCad project zip. */
+  SYSTEM: 'modular_circuit',
+} as const
+
+/** Default production CopilotKit endpoint (the prod value the reference scripts POST to). */
+export const DEFAULT_COPILOTKIT_URL = 'https://gen.eda.cn/api/copilotkit'
+
+/** Default production export-zip endpoint. */
+export const DEFAULT_EXPORT_ZIP_URL = 'https://gen.eda.cn/api/modular_circuit/export-zip'
+
+/**
+ * Language hint sent to the agent when the caller omits `user_language`.
+ *
+ * This was a bare `'简体中文'` literal inside `buildRunBody`, which pinned every
+ * agent reply to Chinese even for an English UI. The node half has no way to
+ * read the host UI locale (the tool is invoked by the model, not the browser),
+ * so the value is a named, overridable default instead of an inline literal.
+ */
+export const DEFAULT_AGENT_LANGUAGE = '简体中文'
+
+/** Resolved runtime config — endpoints only; the account is per-call via auth. */
+export interface SchematicGenConfig {
+  copilotkitUrl: string
+  exportZipUrl: string
+  cookie: string | null
+  /** Fallback agent language; see `DEFAULT_AGENT_LANGUAGE`. */
+  defaultLanguage: string
+}
+
+/** The eda.cn account derived from `huaqiuAuth` per call. */
+export interface EdaAccount {
+  userId: string
+  userToken: string
+}
+
+/**
+ * Resolve the production endpoints from env. No credential defaults: the
+ * account is never baked in (migration plan review #9).
+ */
+export function resolveConfig(env?: Record<string, string | undefined>): SchematicGenConfig {
+  const e = env && typeof env === 'object' ? env : {}
+  const get = (k: string, d: string) => (typeof e[k] === 'string' && e[k].length > 0 ? e[k]! : d)
+  return {
+    copilotkitUrl: get('HQ_EDA_COPILOTKIT_URL', DEFAULT_COPILOTKIT_URL),
+    exportZipUrl: get('HQ_EDA_EXPORT_ZIP_URL', DEFAULT_EXPORT_ZIP_URL),
+    cookie: typeof e['HQ_EDA_COOKIE'] === 'string' && e['HQ_EDA_COOKIE'].length > 0
+      ? e['HQ_EDA_COOKIE']
+      : null,
+    defaultLanguage: get('HQ_EDA_DEFAULT_LANGUAGE', DEFAULT_AGENT_LANGUAGE),
+  }
+}
+
+/** Build the headers for the CopilotKit SSE POST. */
+export function buildHeaders(config: SchematicGenConfig, account: EdaAccount, threadId: string): Record<string, string> {
+  const h: Record<string, string> = {
+    accept: 'text/event-stream',
+    'content-type': 'application/json',
+    'x-user-id': account.userId,
+    'x-user-token': account.userToken,
+    'x-thread-id': threadId,
+    Referer: 'https://gen.eda.cn/',
+  }
+  if (config.cookie) h.cookie = config.cookie
+  return h
+}
+
+/** Build the headers for the export-zip POST (JSON in, zip out). */
+export function buildExportHeaders(config: SchematicGenConfig, account: EdaAccount): Record<string, string> {
+  const h: Record<string, string> = {
+    'content-type': 'application/json',
+    'x-user-id': account.userId,
+    'x-user-token': account.userToken,
+    Referer: 'https://gen.eda.cn/',
+  }
+  if (config.cookie) h.cookie = config.cookie
+  return h
+}
+
+/** Minimal empty state for the schematic agent. */
+export function emptySchematicState(config: SchematicGenConfig, account: EdaAccount, language: string): Record<string, unknown> {
+  return {
+    user_id: account.userId,
+    token: account.userToken,
+    commits: [],
+    requirement: '',
+    architecture: null,
+    circuit: {},
+    report: null,
+    schFiles: [],
+    kicadPro: '',
+    outProject: '',
+    project_achieve_url: '',
+    reportOk: false,
+    reportStage: '',
+    error: '',
+  }
+}
+
+/** Empty state for the system-design agent. */
+export function emptySystemState(config: SchematicGenConfig, account: EdaAccount, language: string): Record<string, unknown> {
+  return {
+    design_name: null,
+    pending_module_replacement_req: null,
+    available_modules: null,
+    connection_outdated: true,
+    commented_outline: null,
+    user_option: null,
+    modules_alternatives: null,
+    user_id: account.userId,
+    token: account.userToken,
+    user_language: language,
+    user_input: '',
+    design_plan: '',
+    original_bom_list: [],
+    top_block: null,
+    search_plan: [],
+    bom_list: [],
+    module_list: [],
+    connect_result: { connections: [] },
+    erc_passed: false,
+    connection_count: 0,
+    pending_bom_updates: [],
+    connect_agent_summary: '',
+    connect_iteration_history: [],
+    bom_exclusion_list: {},
+    reflect_retry_count: 0,
+    task_completed: false,
+    final_report_content: '',
+    circuit_url: null,
+    module_graph: null,
+    kicad_project_zip_url: null,
+  }
+}
+
+/**
+ * Build the CopilotKit `agent/run` body. A FRESH uuid is assigned to both
+ * `threadId` and `runId` (and reused for `x-thread-id`) so every call is a
+ * one-shot, independent run.
+ */
+export function buildRunBody(
+  agentId: string,
+  description: string,
+  config: SchematicGenConfig,
+  account: EdaAccount,
+  language?: string,
+  threadId?: string,
+): Record<string, unknown> {
+  const tid = typeof threadId === 'string' && threadId.length > 0 ? threadId : randomUUID()
+  const runId = randomUUID()
+  const msgId = randomUUID()
+  const lang = typeof language === 'string' && language.length > 0 ? language : config.defaultLanguage
+  const state = agentId === agentIds.SCHEMATIC
+    ? emptySchematicState(config, account, lang)
+    : emptySystemState(config, account, lang)
+  return {
+    method: 'agent/run',
+    params: { agentId },
+    body: {
+      threadId: tid,
+      runId,
+      tools: [],
+      context: [{
+        description: 'Current Module Circuit Design State',
+        value: JSON.stringify({ user_language: lang }),
+      }],
+      forwardedProps: {},
+      state,
+      messages: [{ id: msgId, role: 'user', content: String(description || '') }],
+    },
+  }
+}
+
+/**
+ * Derive a human-readable, filesystem-safe zip basename from the design name.
+ * Keeps Unicode letters/digits (CJK included) intact; only illegal path chars
+ * and whitespace are replaced.
+ */
+export function sanitizeZipBaseName(designName: string): string {
+  return String(designName || '')
+    .replace(/[\\/:*?"<>|\u0000-\u001f]+/g, ' ')
+    .replace(/\s+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 60) || 'circuit'
+}