@huaqiu/dsh-tool-schematic-gen 0.1.1

package/lib/index.mjs

@@ -0,0 +1,1439 @@
+import { randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/config.ts
+/**
+* `@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
+*/
+/** CopilotKit `agentId` values the two tools drive. */
+const agentIds = {
+	/** description → final KiCad schematic (`.kicad_sch` files). */
+	SCHEMATIC: "schemagen",
+	/** description → module graph → KiCad project zip. */
+	SYSTEM: "modular_circuit"
+};
+/** Default production CopilotKit endpoint (the prod value the reference scripts POST to). */
+const DEFAULT_COPILOTKIT_URL = "https://gen.eda.cn/api/copilotkit";
+/** Default production export-zip endpoint. */
+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.
+*/
+const DEFAULT_AGENT_LANGUAGE = "简体中文";
+/**
+* Resolve the production endpoints from env. No credential defaults: the
+* account is never baked in (migration plan review #9).
+*/
+function resolveConfig(env) {
+	const e = env && typeof env === "object" ? env : {};
+	const get = (k, d) => 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. */
+function buildHeaders(config, account, threadId) {
+	const h = {
+		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). */
+function buildExportHeaders(config, account) {
+	const h = {
+		"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. */
+function emptySchematicState(config, account, language) {
+	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. */
+function emptySystemState(config, account, language) {
+	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.
+*/
+function buildRunBody(agentId, description, config, account, language, threadId) {
+	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.
+*/
+function sanitizeZipBaseName(designName) {
+	return String(designName || "").replace(/[\\/:*?"<>|\u0000-\u001f]+/g, " ").replace(/\s+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").slice(0, 60) || "circuit";
+}
+//#endregion
+//#region src/trace.ts
+/**
+* Custom-event names the eda.cn agents are known to use. Matching is
+* deliberately tolerant: any name ending in `_TRACE` is accepted too, so a
+* backend rename does not silently kill progress.
+*/
+const KNOWN_TRACE_EVENT_NAMES = [
+	"SCHEMATIC_GENERATOR_TRACE",
+	"SCHEMAGEN_TRACE",
+	"MODULAR_CIRCUIT_TRACE",
+	"MODULE_GEN_TRACE"
+];
+function isTraceEventName(name) {
+	if (typeof name !== "string" || name.length === 0) return false;
+	if (KNOWN_TRACE_EVENT_NAMES.includes(name)) return true;
+	return /_TRACE$/i.test(name);
+}
+function isRecord(v) {
+	return !!v && typeof v === "object" && !Array.isArray(v);
+}
+/**
+* Validate one decoded `CUSTOM` payload as a {@link TraceEvent}.
+* Returns `null` for anything else (interrupts, future event shapes).
+*/
+function parseTraceEvent(value) {
+	if (!isRecord(value)) return null;
+	const kind = value["kind"];
+	const phase = value["phase"];
+	const ts = value["ts"];
+	if (phase !== "start" && phase !== "end") return null;
+	const timestamp = typeof ts === "number" && Number.isFinite(ts) ? ts : Date.now();
+	if (kind === "node") {
+		const node = value["node"];
+		if (typeof node !== "string" || node.length === 0) return null;
+		const ev = {
+			kind: "node",
+			phase,
+			node,
+			ts: timestamp
+		};
+		const scope = value["scope"];
+		if (typeof scope === "string" && scope.length > 0) ev.scope = scope;
+		const note = value["note"];
+		if (typeof note === "string" && note.length > 0) ev.note = note;
+		return ev;
+	}
+	if (kind === "tool") {
+		const name = value["name"];
+		if (typeof name !== "string" || name.length === 0) return null;
+		const scope = value["scope"];
+		const ev = {
+			kind: "tool",
+			phase,
+			scope: typeof scope === "string" && scope.length > 0 ? scope : name,
+			name,
+			ts: timestamp
+		};
+		const path = value["path"];
+		if (typeof path === "string" && path.length > 0) ev.path = path;
+		if (value["ok"] === false) ev.ok = false;
+		return ev;
+	}
+	return null;
+}
+/**
+* Collect every {@link TraceEvent} inside one `CUSTOM` payload. The backend
+* normally writes one event per chunk, but array payloads are accepted so a
+* batched writer cannot drop the stream.
+*/
+function collectTraceEvents(value) {
+	if (Array.isArray(value)) {
+		const out = [];
+		for (const item of value) {
+			const ev = parseTraceEvent(item);
+			if (ev) out.push(ev);
+		}
+		return out;
+	}
+	const ev = parseTraceEvent(value);
+	return ev ? [ev] : [];
+}
+/**
+* Canonical `a>b>c` path for one event — the breadcrumb the card nests by.
+*
+* Mirrors `TraceTimeline.buildStatusEntries`: a node's path is its own scope
+* (falling back to its name when the backend omits scope), while a tool's path
+* is its caller scope with the tool name appended.
+*/
+function tracePath(ev) {
+	if (ev.kind === "node") return ev.scope && ev.scope.length > 0 ? ev.scope : ev.node;
+	if (ev.path && ev.path.length > 0) return ev.path;
+	return ev.scope === ev.name ? ev.name : `${ev.scope}>${ev.name}`;
+}
+/** Display name of one event (`node:foo` for nodes, bare name for tools). */
+function traceName(ev) {
+	return ev.kind === "node" ? `node:${ev.node}` : ev.name;
+}
+/**
+* Pair `start`/`end` events into {@link TraceFrame}s, preserving nesting via
+* `path`.
+*
+* Uses the same per-key open stack as `buildStatusEntries`, so nested calls
+* with the same name (a tool re-entered inside its own subtree) close in LIFO
+* order instead of cross-contaminating.
+*/
+function pairTraceEvents(events) {
+	const frames = [];
+	const open = /* @__PURE__ */ new Map();
+	let seq = 0;
+	for (const ev of events) {
+		const name = traceName(ev);
+		const path = tracePath(ev);
+		const key = `${path}|${name}`;
+		if (ev.phase === "start") {
+			const stack = open.get(key);
+			const index = frames.length;
+			if (stack) stack.push(index);
+			else open.set(key, [index]);
+			frames.push({
+				id: `trace-${seq++}`,
+				name,
+				path,
+				status: "running",
+				startedAt: ev.ts
+			});
+			continue;
+		}
+		const index = open.get(key)?.pop();
+		if (index === void 0) continue;
+		const failed = ev.kind === "tool" && ev.ok === false;
+		frames[index] = {
+			...frames[index],
+			status: failed ? "failed" : "finished",
+			finishedAt: ev.ts
+		};
+	}
+	return frames;
+}
+/**
+* Convert the **standard AG-UI tool-call lifecycle** (`TOOL_CALL_START` /
+* `TOOL_CALL_END`) into {@link TraceEvent}s.
+*
+* This exists because the two eda.cn agents report progress differently:
+*
+*   - `schemagen` (schematic) emits LangGraph `custom`-stream `TraceEvent`s,
+*     republished as AG-UI `CUSTOM` events named `SCHEMATIC_GENERATOR_TRACE`.
+*   - `modular_circuit` (system design) does NOT emit those. Its stack is
+*     rebuilt by the agent server from LangGraph *tasks* and published as the
+*     ordinary AG-UI `TOOL_CALL_START` / `TOOL_CALL_END` pair — see
+*     `ModuleGenTraceProvider.onToolCallStartEvent` in hq-eda-ai.
+*
+* Without this adapter the system-design tool reported no progress at all.
+*
+* Port of `createToolInstancePath` + `toToolTraceEvent` in
+* `apps/web/src/lib/modular_circuit/context/ModuleGenTraceProvider.tsx`.
+*/
+var ToolCallTracker = class ToolCallTracker {
+	active = /* @__PURE__ */ new Map();
+	/** Forget every open call — invoke on `RUN_STARTED`. */
+	reset() {
+		this.active.clear();
+	}
+	/**
+	* Build an instance path, reusing the deepest currently-open call whose
+	* semantic path is a prefix of this one so nested tools nest properly.
+	*/
+	instancePath(semanticPath, toolCallId) {
+		let parent;
+		for (const candidate of this.active.values()) {
+			if (!semanticPath.startsWith(`${candidate.semanticPath}>`)) continue;
+			if (!parent || candidate.semanticPath.length > parent.semanticPath.length) parent = candidate;
+		}
+		const segments = (parent ? semanticPath.slice(parent.semanticPath.length + 1) : semanticPath).split(">").map((s) => s.trim()).filter((s) => s.length > 0);
+		const leaf = segments.length - 1;
+		if (leaf >= 0) segments[leaf] = `${segments[leaf]}::task:${toolCallId}`;
+		const current = segments.join(">");
+		return parent ? `${parent.instancePath}>${current}` : current;
+	}
+	/** Split a semantic path into its parent scope and leaf display name. */
+	static split(semanticPath) {
+		const segments = semanticPath.split(">").map((s) => s.trim()).filter((s) => s.length > 0);
+		const name = segments[segments.length - 1] || "unknown";
+		return {
+			scope: segments.length > 1 ? segments.slice(0, -1).join(">") : name,
+			name
+		};
+	}
+	/** Open a tool call. Returns the `start` trace event. */
+	start(toolCallId, semanticPath, ts = Date.now()) {
+		const instancePath = this.instancePath(semanticPath, toolCallId);
+		if (toolCallId) this.active.set(toolCallId, {
+			semanticPath,
+			instancePath
+		});
+		const { scope, name } = ToolCallTracker.split(semanticPath);
+		return {
+			kind: "tool",
+			phase: "start",
+			scope,
+			name,
+			path: instancePath,
+			ts
+		};
+	}
+	/**
+	* Close a tool call. Returns the `end` trace event, or `null` when the id
+	* was never opened (a late/duplicate frame we must not invent a span for).
+	*/
+	end(toolCallId, ts = Date.now()) {
+		const known = this.active.get(toolCallId);
+		if (!known) return null;
+		this.active.delete(toolCallId);
+		const { scope, name } = ToolCallTracker.split(known.semanticPath);
+		return {
+			kind: "tool",
+			phase: "end",
+			scope,
+			name,
+			path: known.instancePath,
+			ts,
+			ok: true
+		};
+	}
+	/** Ids still open. Exposed for diagnostics/tests. */
+	get openIds() {
+		return [...this.active.keys()];
+	}
+};
+//#endregion
+//#region src/sse.ts
+/**
+* Overall SSE / zip budget — the eda.cn design agents routinely run 9–12+
+* minutes per generation (observed runs exceeded the old 10-min cap), so
+* allow 30 minutes before aborting the stream. This single constant drives
+* both the backend SSE stream timeout and the agent-facing tool timeout hint
+* (`TOOL_TIMEOUT_MS` in tools.ts references it).
+*/
+const HTTP_TIMEOUT_MS = 18e5;
+/**
+* Apply one `STATE_DELTA` op set to the accumulating state. Only **top-level**
+* patches (`/key`) are applied; nested paths are ignored because the final
+* `STATE_SNAPSHOT` is authoritative for the deliverable fields.
+*/
+function applyDelta(delta, state) {
+	if (!Array.isArray(delta)) return;
+	for (const op of delta) {
+		if (!op || typeof op !== "object") continue;
+		const record = op;
+		const path = typeof record.path === "string" ? record.path : "";
+		const m = /^\/([^/]+)$/.exec(path);
+		if (!m) continue;
+		const key = m[1];
+		if (record.op === "remove") delete state[key];
+		else if (record.op === "add" || record.op === "replace") state[key] = record.value;
+	}
+}
+/** Read a string field that may be camelCase (AG-UI) or snake_case (older builds). */
+function strField(rec, ...keys) {
+	for (const key of keys) {
+		const v = rec[key];
+		if (typeof v === "string" && v.length > 0) return v;
+	}
+	return "";
+}
+/** Parse one `todo_progress` entry; anything else is dropped. */
+function parseTodo(value) {
+	if (!value || typeof value !== "object") return null;
+	const rec = value;
+	const content = typeof rec["content"] === "string" ? rec["content"] : "";
+	if (content.length === 0) return null;
+	const status = rec["status"];
+	return {
+		content,
+		status: status === "completed" ? "completed" : status === "in_progress" ? "in_progress" : "pending"
+	};
+}
+/** Parse a design-stage announcement (`kind: "progress"`). */
+function parseNote(value) {
+	const message = typeof value["message"] === "string" ? value["message"].trim() : "";
+	if (message.length === 0) return null;
+	const phase = value["phase"];
+	const stage = typeof value["stage"] === "string" ? value["stage"] : "";
+	return {
+		phase: phase === "complete" ? "complete" : phase === "error" ? "error" : "start",
+		stage,
+		message,
+		ts: typeof value["ts"] === "number" && Number.isFinite(value["ts"]) ? value["ts"] : Date.now()
+	};
+}
+/**
+* Handle one decoded SSE event, mutating `state` and returning any text /
+* lifecycle signals for the caller to aggregate.
+*
+* `tracker` is required only for agents that report progress through the
+* standard AG-UI tool-call lifecycle instead of `CUSTOM` trace events —
+* that is, `modular_circuit` (system design).
+*/
+function handleEvent(evt, state, tracker) {
+	if (!evt || typeof evt !== "object") return {};
+	const record = evt;
+	const rec = evt;
+	const type = record.type;
+	if (type === "STATE_SNAPSHOT") {
+		if (record.snapshot && typeof record.snapshot === "object") Object.assign(state, record.snapshot);
+		return { stateChanged: true };
+	}
+	if (type === "STATE_DELTA") {
+		applyDelta(record.delta, state);
+		return { stateChanged: true };
+	}
+	if (type === "RUN_STARTED") {
+		tracker?.reset();
+		return { runStarted: true };
+	}
+	if (type === "TOOL_CALL_START" && tracker) {
+		const id = strField(rec, "toolCallId", "tool_call_id");
+		const name = strField(rec, "toolCallName", "tool_call_name") || "unknown";
+		return { trace: [tracker.start(id, name)] };
+	}
+	if (type === "TOOL_CALL_END" && tracker) {
+		const id = strField(rec, "toolCallId", "tool_call_id");
+		const ev = tracker.end(id);
+		return ev ? { trace: [ev] } : {};
+	}
+	if (type === "CUSTOM") {
+		const name = typeof record.name === "string" ? record.name : "";
+		if (name === "SYSTEM_DESIGN_EVENT") {
+			const value = record.value;
+			if (value && typeof value === "object") {
+				const payload = value;
+				if (payload["kind"] === "todo_progress" && Array.isArray(payload["todos"])) {
+					const todos = [];
+					for (const item of payload["todos"]) {
+						const todo = parseTodo(item);
+						if (todo) todos.push(todo);
+					}
+					return todos.length > 0 ? { todos } : {};
+				}
+				if (payload["kind"] === "progress") {
+					const note = parseNote(payload);
+					return note ? { note } : {};
+				}
+			}
+			return {};
+		}
+		if (!isTraceEventName(name)) return {};
+		const events = collectTraceEvents(record.value);
+		return events.length > 0 ? { trace: events } : {};
+	}
+	if (type === "TEXT_MESSAGE_CONTENT") return { text: typeof evt.delta === "string" ? evt.delta : "" };
+	if (type === "RUN_FINISHED") return { finished: true };
+	if (type === "RUN_ERROR") return { error: typeof record.error === "string" ? record.error : typeof record.message === "string" ? record.message : "unknown run error" };
+	return {};
+}
+/** Parse one `data: …` SSE block into event(s) and route them through `handleEvent`. */
+function dispatchRaw(raw, state, acc) {
+	const lines = raw.split(/\r?\n/);
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("data:")) continue;
+		const payload = trimmed.slice(5).trim();
+		if (!payload) continue;
+		let evt;
+		try {
+			evt = JSON.parse(payload);
+		} catch {
+			continue;
+		}
+		const r = handleEvent(evt, state, acc.tracker);
+		if (r.text) acc.text += r.text;
+		if (r.finished) acc.finished = true;
+		if (r.error) acc.error = r.error;
+		if (r.trace && r.trace.length > 0) {
+			for (const ev of r.trace) acc.trace.push(ev);
+			acc.onTrace?.(r.trace);
+		}
+		if (r.todos && r.todos.length > 0) acc.onTodos?.(r.todos);
+		if (r.note) acc.onNote?.(r.note);
+		if (r.stateChanged) acc.onState?.(state);
+	}
+}
+/** Decode a chunk, split on SSE boundaries, dispatch complete events, return
+*  the unterminated remainder. */
+function feed(chunkStr, state, leftover, acc) {
+	const parts = (leftover + chunkStr).split(/\r?\n\r?\n/);
+	const newLeftover = parts.pop() || "";
+	for (const raw of parts) {
+		if (raw.trim().length === 0) continue;
+		dispatchRaw(raw, state, acc);
+	}
+	return newLeftover;
+}
+/**
+* POST to the CopilotKit endpoint and consume the SSE stream until it ends or
+* the budget elapses, accumulating the agent state.
+*/
+async function consumeCopilotkit(url, body, headers, options = {}) {
+	const { signal, timeoutMs = HTTP_TIMEOUT_MS, fetchImpl = fetch } = options;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("schematic-gen: the design agent did not finish within " + timeoutMs + "ms")), timeoutMs);
+	let onAbort = null;
+	if (signal) {
+		if (signal.aborted) controller.abort();
+		else {
+			onAbort = () => controller.abort();
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+	}
+	let res;
+	try {
+		res = await fetchImpl(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body),
+			signal: controller.signal
+		});
+	} catch (err) {
+		clearTimeout(timer);
+		if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+		throw new Error("schematic-gen: failed to reach the design API: " + String(err?.message || err));
+	}
+	if (!res || !res.ok) {
+		clearTimeout(timer);
+		if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+		if (res && res.status === 401) try {
+			options.onUnauthorized?.();
+		} catch {}
+		throw new Error("schematic-gen: the design API returned HTTP " + String(res && res.status) + " (expected 200 with an SSE stream)");
+	}
+	if (!res.body || typeof res.body.getReader !== "function") {
+		clearTimeout(timer);
+		if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+		throw new Error("schematic-gen: the design API response had no stream body");
+	}
+	const reader = res.body.getReader();
+	const decoder = new TextDecoder();
+	let buf = "";
+	const state = {};
+	const acc = {
+		text: "",
+		finished: false,
+		error: "",
+		trace: [],
+		onTrace: options.onTrace,
+		onState: options.onState,
+		onTodos: options.onTodos,
+		onNote: options.onNote,
+		tracker: options.toolCallTrace ? new ToolCallTracker() : void 0
+	};
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buf = feed(decoder.decode(value, { stream: true }), state, buf, acc);
+		}
+		if (buf.length > 0) dispatchRaw(buf, state, acc);
+	} finally {
+		clearTimeout(timer);
+		if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+		try {
+			await reader.cancel();
+		} catch {}
+	}
+	if (acc.error) throw new Error("schematic-gen: the design agent reported an error: " + acc.error + (acc.text ? " — " + acc.text.slice(0, 300) : ""));
+	return {
+		state,
+		finished: acc.finished,
+		text: acc.text,
+		trace: acc.trace
+	};
+}
+/**
+* POST the module graph to the production export-zip route and return the zip
+* as a Buffer. The route reads `req.json()` as the `MODULE_GRAPH` and responds
+* with `application/zip`.
+*/
+async function exportModuleGraphZip(exportZipUrl, moduleGraph, config, account, options = {}) {
+	const { signal, timeoutMs = HTTP_TIMEOUT_MS, fetchImpl = fetch } = options;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("schematic-gen: the export-zip service did not respond within " + timeoutMs + "ms")), timeoutMs);
+	let onAbort = null;
+	if (signal) {
+		if (signal.aborted) controller.abort();
+		else {
+			onAbort = () => controller.abort();
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+	}
+	let res;
+	try {
+		res = await fetchImpl(exportZipUrl, {
+			method: "POST",
+			headers: buildExportHeaders(config, account),
+			body: JSON.stringify(moduleGraph),
+			signal: controller.signal
+		});
+	} catch (err) {
+		clearTimeout(timer);
+		if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+		throw new Error("schematic-gen: failed to export the module graph to zip: " + String(err?.message || err));
+	} finally {
+		clearTimeout(timer);
+		if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+	}
+	if (!res || !res.ok) {
+		let detail = "";
+		try {
+			const j = await res.json();
+			detail = typeof j.error === "string" ? j.error : "";
+		} catch {}
+		throw new Error("schematic-gen: the export-zip service returned HTTP " + String(res && res.status) + (detail ? " — " + detail : ""));
+	}
+	const ab = await res.arrayBuffer();
+	return Buffer.from(ab);
+}
+//#endregion
+//#region src/tools.ts
+/**
+* `@huaqiu/dsh-tool-schematic-gen` — the two agent-visible tools.
+*
+* Faithful TypeScript port of the `hq-edge` plugin's tool bodies, adapted to
+* the published DSH plugin surface:
+*   - the eda.cn account always comes from the `huaqiuAuth` service (no demo
+*     credentials — migration plan review #9);
+*   - generated artifacts are stored in the `huaqiuArtifacts` service
+*     (in-process, not a loopback);
+*   - tools are `defineTool` with `output.schema = { type: 'json' }` and a
+*     structured (lossless-JSON) result.
+*
+* Tools:
+*   generate_schematic_from_description   description → KiCad schematic
+*   generate_system_module_graph          description → module graph → KiCad zip
+*
+* @module @huaqiu/dsh-tool-schematic-gen
+*/
+/** The normalized domain values are lossless-JSON plain objects except that
+*  optional fields are `undefined`, which fails DSH's lossless-JSON validation. */
+function asJson(value) {
+	return JSON.parse(JSON.stringify(value));
+}
+/** Console tag for log filtering. */
+const LOG_TAG$1 = "[dsh-schematic-gen]";
+/** Agent-facing timeout hints. */
+const TOOL_TIMEOUT_MS = {
+	generate_schematic_from_description: HTTP_TIMEOUT_MS,
+	generate_system_module_graph: HTTP_TIMEOUT_MS
+};
+function renderJson(_args, value) {
+	return [{
+		type: "text",
+		text: JSON.stringify(value)
+	}];
+}
+/** Resolve the eda.cn account from the auth capability (no baked-in creds). */
+async function resolveAccount(auth) {
+	if (!auth || typeof auth.getUserInfo !== "function") return null;
+	try {
+		const info = await auth.getUserInfo();
+		if (info && typeof info.id === "string" && typeof info.token === "string" && info.id.length > 0 && info.token.length > 0) return {
+			userId: info.id,
+			userToken: info.token
+		};
+		return null;
+	} catch (err) {
+		console.warn(LOG_TAG$1, "could not resolve the eda.cn account", String(err?.message || err));
+		return null;
+	}
+}
+/** Fresh run id, injectable for tests. */
+function newRunId(env) {
+	return typeof env.deps?.uuidImpl === "function" ? env.deps.uuidImpl() : randomUUID();
+}
+/**
+* Bind one tool invocation to the progress store.
+*
+* Every returned callback is a no-op when there is no store or no `callId`,
+* so a tool can call these unconditionally.
+*/
+function progressFor(env, exec, toolName, kind) {
+	const store = env.progress;
+	const callId = typeof exec?.callId === "string" && exec.callId.length > 0 ? exec.callId : "";
+	const live = store && callId ? {
+		store,
+		callId
+	} : null;
+	if (live) live.store.start(live.callId, toolName, kind);
+	return {
+		onTrace: (events) => {
+			if (live) live.store.pushTrace(live.callId, events);
+		},
+		onState: (state) => {
+			if (live) live.store.updateState(live.callId, state);
+		},
+		onTodos: (todos) => {
+			if (live) live.store.setTodos(live.callId, todos);
+		},
+		onNote: (note) => {
+			if (live) live.store.setNote(live.callId, note);
+		},
+		done: () => {
+			if (live) live.store.finish(live.callId);
+		},
+		failed: (message) => {
+			if (live) live.store.fail(live.callId, message);
+		}
+	};
+}
+/** Store a generated artifact in the user-wide preview store (in-process). */
+async function createPreviewArtifact(env, type, filename, content, contentEncoding) {
+	if (!env.artifacts || typeof env.artifacts.create !== "function") throw new Error("schematic-gen: huaqiuArtifacts service unavailable — cannot store preview artifact");
+	return env.artifacts.create({
+		type,
+		filename,
+		content,
+		contentEncoding
+	});
+}
+/**
+* Pull the schematic deliverable out of the final agent state. `schFiles`
+* carry the `.kicad_sch` content inline, so the text is returned verbatim.
+*/
+function extractSchematic(state) {
+	const schFiles = (Array.isArray(state.schFiles) ? state.schFiles : []).map((f) => {
+		const file = f && typeof f === "object" ? f : {};
+		return {
+			filename: typeof file.filename === "string" ? file.filename : "",
+			content: typeof file.content === "string" ? file.content : typeof file.content === "object" && file.content !== null ? JSON.stringify(file.content) : String(file.content ?? "")
+		};
+	}).filter((f) => f.filename.length > 0);
+	return {
+		outProject: typeof state.outProject === "string" ? state.outProject : "",
+		project_achieve_url: typeof state.project_achieve_url === "string" ? state.project_achieve_url : "",
+		kicadPro: typeof state.kicadPro === "string" ? state.kicadPro : "",
+		schFiles,
+		error: typeof state.error === "string" ? state.error : ""
+	};
+}
+/** Pull the module graph out of the final system-design state. */
+function extractModuleGraph(state) {
+	const mg = state && state.module_graph;
+	return mg && typeof mg === "object" ? mg : null;
+}
+/**
+* Store each `.kicad_sch` sheet as a preview artifact and return the
+* structured result. Artifact creation is BEST-EFFORT and non-fatal: on any
+* failure the raw content is preserved inline so the result card can still
+* render it.
+*/
+async function materializeSchematicArtifacts(env, schFiles) {
+	const outFiles = schFiles.map((f) => ({ filename: f.filename }));
+	const artifacts = [];
+	let anyFailed = false;
+	let errorNote = "";
+	for (let i = 0; i < schFiles.length; i++) {
+		const file = schFiles[i];
+		try {
+			const created = await createPreviewArtifact(env, "schematic", file.filename, file.content);
+			artifacts.push({
+				id: created.id,
+				type: created.type,
+				filename: created.filename,
+				size: created.size
+			});
+		} catch (storeErr) {
+			anyFailed = true;
+			outFiles[i].content = file.content;
+			const msg = String(storeErr?.message || storeErr);
+			errorNote += (errorNote ? "; " : "") + file.filename + ": " + msg;
+		}
+	}
+	const result = { schFiles: outFiles };
+	if (artifacts.length > 0) result.schArtifacts = artifacts;
+	if (anyFailed) {
+		result.note = "Preview artifact storage partially or fully unavailable (" + errorNote + ").";
+		result.agentNote = "Sheets without an artifact id still carry their source inline, so the result card can render them directly. Full source is always in the project zip/export.";
+	}
+	return result;
+}
+/**
+* Structured `needs_auth` result returned when the eda.cn login is missing —
+* the signal that makes login a human-in-the-loop step. The web client
+* (dsh-auth client half) renders a login card with an embedded auth.eda.cn
+* iframe for this result; the model asks the user to complete the login and
+* then retries the tool. Throwing here would hide that HIT surface.
+*/
+function needsAuth(kind) {
+	return {
+		status: "needs_auth",
+		kind,
+		hint: "This tool requires a Huaqiu EDA (eda.cn) login. The web client is showing a login card with an embedded eda.cn login iframe — ask the user to complete the login there (or use the 华秋EDA login button in the sidebar), then call this tool again."
+	};
+}
+/**
+* `generate_schematic_from_description` body — stream `schemagen`, extract the
+* inline `.kicad_sch` files, then store each sheet as a preview artifact.
+*/
+async function runGenerateSchematic(args, exec, env) {
+	const account = await resolveAccount(env.auth);
+	if (!account) return needsAuth("schematic");
+	const threadId = newRunId(env);
+	const body = buildRunBody(agentIds.SCHEMATIC, typeof args.description === "string" ? args.description : "", env.config, account, typeof args.user_language === "string" ? args.user_language : void 0, threadId);
+	const prog = progressFor(env, exec, "generate_schematic_from_description", "schematic");
+	let state;
+	let text;
+	try {
+		const res = await consumeCopilotkit(env.config.copilotkitUrl, body, buildHeaders(env.config, account, threadId), {
+			signal: exec?.signal,
+			timeoutMs: env.timeoutMs,
+			fetchImpl: env.deps?.fetchImpl,
+			onTrace: prog.onTrace,
+			onState: prog.onState,
+			onUnauthorized: () => {
+				env.auth.logout();
+			}
+		});
+		state = res.state;
+		text = res.text;
+	} catch (err) {
+		prog.failed(String(err?.message || err));
+		throw err;
+	}
+	const extracted = extractSchematic(state);
+	if (extracted.error) {
+		const message = "schematic-gen: the schematic agent finished with an error: " + extracted.error + (text ? " — " + text.slice(0, 300) : "");
+		prog.failed(message);
+		throw new Error(message);
+	}
+	if (extracted.schFiles.length === 0) {
+		const message = "schematic-gen: the schematic agent produced no .kicad_sch files." + (text ? " Assistant said: " + text.slice(0, 300) : "");
+		prog.failed(message);
+		throw new Error(message);
+	}
+	const materialized = await materializeSchematicArtifacts(env, extracted.schFiles);
+	const result = {
+		status: "generated",
+		kind: "schematic",
+		design_name: extracted.outProject || "",
+		schFiles: materialized.schFiles,
+		schArtifacts: materialized.schArtifacts,
+		kicadPro: extracted.kicadPro,
+		project_achieve_url: extracted.project_achieve_url
+	};
+	if (materialized.note) result.note = materialized.note;
+	if (materialized.agentNote) result.agentNote = materialized.agentNote;
+	prog.done();
+	return result;
+}
+/**
+* `generate_system_module_graph` body — stream `modular_circuit`, extract the
+* module graph, POST it to export-zip, return the KiCad project zip stored as
+* a `zip` preview artifact.
+*/
+async function runGenerateSystem(args, exec, env) {
+	const account = await resolveAccount(env.auth);
+	if (!account) return needsAuth("system");
+	const threadId = newRunId(env);
+	const body = buildRunBody(agentIds.SYSTEM, typeof args.description === "string" ? args.description : "", env.config, account, typeof args.user_language === "string" ? args.user_language : void 0, threadId);
+	const prog = progressFor(env, exec, "generate_system_module_graph", "system");
+	let state;
+	let text;
+	try {
+		const res = await consumeCopilotkit(env.config.copilotkitUrl, body, buildHeaders(env.config, account, threadId), {
+			signal: exec?.signal,
+			timeoutMs: env.timeoutMs,
+			fetchImpl: env.deps?.fetchImpl,
+			onTrace: prog.onTrace,
+			onState: prog.onState,
+			onTodos: prog.onTodos,
+			onNote: prog.onNote,
+			toolCallTrace: true,
+			onUnauthorized: () => {
+				env.auth.logout();
+			}
+		});
+		state = res.state;
+		text = res.text;
+	} catch (err) {
+		prog.failed(String(err?.message || err));
+		throw err;
+	}
+	const moduleGraph = extractModuleGraph(state);
+	if (!moduleGraph) {
+		const errState = typeof state.error === "string" && state.error ? state.error : "";
+		const message = "schematic-gen: the system design agent produced no module_graph." + (errState ? " Error: " + errState : "") + (text ? " Assistant said: " + text.slice(0, 300) : "");
+		prog.failed(message);
+		throw new Error(message);
+	}
+	const zipBuf = await exportModuleGraphZip(env.config.exportZipUrl, moduleGraph, env.config, account, {
+		signal: exec?.signal,
+		timeoutMs: env.timeoutMs,
+		fetchImpl: env.deps?.fetchImpl
+	}).catch((err) => {
+		prog.failed(String(err?.message || err));
+		throw err;
+	});
+	const designName = typeof state.design_name === "string" && state.design_name ? state.design_name : "circuit";
+	const connectionCount = typeof state.connection_count === "number" ? state.connection_count : Array.isArray(moduleGraph.connections) ? moduleGraph.connections.length : 0;
+	const moduleNames = Array.isArray(moduleGraph.modules) ? moduleGraph.modules.map((m) => m && typeof m.name === "string" ? m.name : "").filter((n) => n.length > 0) : [];
+	const result = {
+		status: "generated",
+		kind: "system",
+		design_name: designName,
+		module_count: moduleNames.length,
+		connection_count: connectionCount,
+		module_names: moduleNames,
+		zip_bytes: zipBuf.length
+	};
+	const notes = [];
+	let zipArtifact = null;
+	try {
+		const created = await createPreviewArtifact(env, "zip", sanitizeZipBaseName(designName) + ".zip", zipBuf.toString("base64"), "base64");
+		zipArtifact = {
+			id: created.id,
+			type: created.type,
+			filename: created.filename,
+			size: created.size
+		};
+	} catch (storeErr) {
+		notes.push("Could not store the project zip as an artifact (" + String(storeErr?.message || storeErr) + "); kept it in the result instead.");
+	}
+	if (zipArtifact) result.zipArtifact = zipArtifact;
+	else if (zipBuf.length <= 1e6) result.zip = "data:application/zip;base64," + zipBuf.toString("base64");
+	else {
+		const fileName = "hq-eda-" + sanitizeZipBaseName(designName) + "-" + newRunId(env).slice(0, 8) + ".zip";
+		const dir = env.deps?.tmpDirImpl && env.deps.tmpDirImpl() || tmpdir();
+		const filePath = join(dir, fileName);
+		try {
+			await (env.deps?.writeFileImpl || writeFile)(filePath, zipBuf);
+			result.zip_path = filePath;
+		} catch (err) {
+			result.zip = "data:application/zip;base64," + zipBuf.toString("base64");
+			notes.push("Could not write the zip to a temp file (" + String(err?.message || err) + "); returned inline instead.");
+		}
+	}
+	if (notes.length > 0) result.note = notes.join(" ");
+	prog.done();
+	return result;
+}
+/** Agent-awareness note about the eda.cn login gate, appended to both tool
+*  descriptions: a `needs_auth` result surfaces a login HIT (embedded eda.cn
+*  iframe card) — wait for the user to log in, then retry. Never invent
+*  credentials or fake success. */
+const AUTH_GATE_NOTE = "AUTH: This tool requires a Huaqiu EDA (eda.cn) account. If the result has status \"needs_auth\", the web client is showing a login card with an embedded eda.cn login iframe (the human-in-the-loop step). Ask the user to complete the login there or via the 华秋EDA login button in the sidebar (you may use ask_user_question to wait, offering a \"retry now that I have logged in\" option and a \"cancel\" option — phrase BOTH in the language the user is writing in), then call this tool again. Never invent credentials and never claim success when the result is needs_auth.";
+function createSchematicTool(env) {
+	return defineTool({
+		name: "generate_schematic_from_description",
+		description: "Generate a KiCad schematic (.kicad_sch files) from a natural-language description of a circuit or sub-circuit — e.g. \"design a 5V LM7805 linear regulator power supply with input and output filter capacitors\". Calls the online HQ-EDA schematic generation agent and returns schFiles (filename references), schArtifacts (preview artifact references with id/type/filename/size per sheet), kicadPro and project_achieve_url. Use this when the user asks to draw, generate or create a circuit schematic from a description (not from an image — for that use the symbol/footprint tools). IMPORTANT: The generated schematic renders automatically as a result card in the web client — an interactive canvas preview per sheet (multi-sheet results get a sheet tab bar) and a download button for the current sheet. Do NOT paste the schematic source, file URLs, or any fenced code block into your reply; just note in one line that the schematic was generated and how many sheets it has. " + AUTH_GATE_NOTE,
+		parameters: {
+			description: {
+				type: "string",
+				required: true,
+				description: "The circuit design prompt, in natural language. Be specific about components, voltages and any required behaviour."
+			},
+			user_language: {
+				type: "string",
+				description: "Optional language hint for the agent — pass the language the user is writing in (e.g. \"简体中文\" or \"English\"). Omit to use the deployment default."
+			}
+		},
+		output: {
+			schema: { type: "json" },
+			render: renderJson
+		},
+		async execute(args, exec) {
+			return asJson(await runGenerateSchematic(args, exec, env));
+		},
+		timeoutMs: TOOL_TIMEOUT_MS.generate_schematic_from_description
+	});
+}
+function createSystemTool(env) {
+	return defineTool({
+		name: "generate_system_module_graph",
+		description: "Generate a hardware system design (module graph) from a natural-language description — e.g. \"design a small smart alarm clock\". Calls the online HQ-EDA system-design agent, which plans the modules, searches/selects parts, wires the connections, and produces a module graph; the graph is then exported to a KiCad project zip. Returns: a zipArtifact reference (preview-artifact id of the full project zip — the zip is never inlined into the conversation) and a summary (design name, module count, connection count, module names). Use this when the user wants a whole system/module-level design, not a single schematic or symbol. IMPORTANT: The generated system design renders automatically as a result card in the web client — a canvas preview of the project root schematic (fetched from the zip artifact) and a Download button for the full project zip. Do NOT paste the schematic source, file URLs, or any fenced code block into your reply; just note in one line that the design was generated, its module count, and that the project zip is downloadable from the card. " + AUTH_GATE_NOTE,
+		parameters: {
+			description: {
+				type: "string",
+				required: true,
+				description: "The system design prompt, in natural language. Describe the product or function you want, e.g. \"an ESP32-C3 based smart fan\"."
+			},
+			user_language: {
+				type: "string",
+				description: "Optional language hint for the agent — pass the language the user is writing in (e.g. \"简体中文\" or \"English\"). Omit to use the deployment default."
+			}
+		},
+		output: {
+			schema: { type: "json" },
+			render: renderJson
+		},
+		async execute(args, exec) {
+			return asJson(await runGenerateSystem(args, exec, env));
+		},
+		timeoutMs: TOOL_TIMEOUT_MS.generate_system_module_graph
+	});
+}
+/** Build the two tool definitions against a runtime env. */
+function createSchematicGenTools(env) {
+	return [createSchematicTool(env), createSystemTool(env)];
+}
+//#endregion
+//#region src/progress.ts
+/**
+* `@huaqiu/dsh-tool-schematic-gen` — live run progress (node half).
+*
+* Long design runs take 10+ minutes. The tool body sits on the node half and
+* returns once, so the browser card would otherwise show a frozen label for
+* the whole run. This module is the node side of the fix:
+*
+*   tool body ──pushTrace/updateState──▶ ProgressStore (keyed by callId)
+*                                             │
+*                        ctx.webServer ◀──────┘  GET …/progress/<callId>
+*                                             │
+*                                    browser card polls
+*
+* **Why `callId` is the key.** `defineTool`'s second argument is a
+* `ToolRunContext`, which extends `ToolExecutionInput` and therefore carries
+* `callId`. The `tool.call.toolview` slot passes the very same string to the
+* browser component as `ToolCallOwnerProps.callId` — documented in DSH as
+* "stable across running and settled forms". So no hand-rolled correlation id
+* has to travel through the tool result.
+*
+* **Two independent progress signals**, because the backend is not guaranteed
+* to emit trace events:
+*   1. `frames` — a real call stack, when AG-UI `CUSTOM` trace events arrive.
+*   2. `stage`  — a coarse ladder derived from the agent's own state keys,
+*                 which always arrives via `STATE_SNAPSHOT`/`STATE_DELTA`.
+* The card renders the stack when it exists and the ladder otherwise, and
+* always shows the elapsed timer.
+*
+* @module @huaqiu/dsh-tool-schematic-gen
+*/
+/** A non-empty value: null/empty-string/empty-array/empty-object/false are not. */
+function filled(v) {
+	if (v === null || v === void 0 || v === false) return false;
+	if (typeof v === "string") return v.trim().length > 0;
+	if (Array.isArray(v)) return v.length > 0;
+	if (typeof v === "object") return Object.keys(v).length > 0;
+	return true;
+}
+/** Connections live one level down: `connect_result.connections`. */
+function connectionsFilled(state) {
+	const cr = state["connect_result"];
+	if (cr && typeof cr === "object") return filled(cr["connections"]);
+	return false;
+}
+/**
+* Stage ladders, ordered. Derived from the agent's own initial state
+* (`emptySchematicState` / `emptySystemState` in config.ts), so a stage is
+* "reached" exactly when the agent has written that part of the design.
+*/
+const STAGE_LADDERS = {
+	schematic: [
+		{
+			key: "requirement",
+			reached: (s) => filled(s["requirement"])
+		},
+		{
+			key: "architecture",
+			reached: (s) => filled(s["architecture"])
+		},
+		{
+			key: "circuit",
+			reached: (s) => filled(s["circuit"])
+		},
+		{
+			key: "report",
+			reached: (s) => filled(s["report"]) || filled(s["reportStage"])
+		},
+		{
+			key: "output",
+			reached: (s) => filled(s["schFiles"])
+		}
+	],
+	system: [
+		{
+			key: "plan",
+			reached: (s) => filled(s["design_plan"])
+		},
+		{
+			key: "search",
+			reached: (s) => filled(s["search_plan"])
+		},
+		{
+			key: "bom",
+			reached: (s) => filled(s["bom_list"])
+		},
+		{
+			key: "modules",
+			reached: (s) => filled(s["module_list"])
+		},
+		{
+			key: "connect",
+			reached: connectionsFilled
+		},
+		{
+			key: "erc",
+			reached: (s) => s["erc_passed"] === true
+		},
+		{
+			key: "export",
+			reached: (s) => filled(s["module_graph"])
+		}
+	]
+};
+/** Resolve how far a run has got, purely from the agent state snapshot. */
+function stageOf(kind, state) {
+	const ladder = STAGE_LADDERS[kind];
+	if (!ladder || ladder.length === 0) return null;
+	let reached = 0;
+	for (const spec of ladder) {
+		if (!spec.reached(state)) break;
+		reached += 1;
+	}
+	const index = Math.min(reached, ladder.length - 1);
+	return {
+		index,
+		total: ladder.length,
+		key: ladder[index].key
+	};
+}
+/**
+* In-memory progress registry. Deliberately NOT persisted: progress is only
+* meaningful while the run is live, and a stale doc after a restart would be
+* worse than none.
+*/
+var ProgressStore = class {
+	runs = /* @__PURE__ */ new Map();
+	ttlMs;
+	now;
+	constructor(options = {}) {
+		this.ttlMs = options.ttlMs ?? 18e5;
+		this.now = options.now ?? (() => Date.now());
+	}
+	/** Register a run. Safe to call twice for the same id (idempotent). */
+	start(callId, toolName, kind) {
+		if (!callId) return;
+		if (this.runs.has(callId)) return;
+		const ts = this.now();
+		this.runs.set(callId, {
+			doc: {
+				callId,
+				toolName,
+				kind,
+				status: "running",
+				startedAt: ts,
+				updatedAt: ts,
+				frames: [],
+				stage: null,
+				todos: null,
+				note: null,
+				error: null
+			},
+			events: [],
+			state: {}
+		});
+	}
+	/** Append trace events and re-pair the frame list. */
+	pushTrace(callId, events) {
+		const rec = this.runs.get(callId);
+		if (!rec || events.length === 0) return;
+		for (const ev of events) rec.events.push(ev);
+		if (rec.events.length > 2e3) rec.events.splice(0, rec.events.length - 2e3);
+		rec.doc.frames = pairTraceEvents(rec.events).slice(-500);
+		rec.doc.updatedAt = this.now();
+	}
+	/** Merge an agent state snapshot and re-evaluate the stage ladder. */
+	updateState(callId, state) {
+		const rec = this.runs.get(callId);
+		if (!rec) return;
+		Object.assign(rec.state, state);
+		rec.doc.stage = stageOf(rec.doc.kind, rec.state);
+		rec.doc.updatedAt = this.now();
+	}
+	/** Replace the todo list. Only ever set by the system-design agent. */
+	setTodos(callId, todos) {
+		const rec = this.runs.get(callId);
+		if (!rec) return;
+		rec.doc.todos = todos.map((todo) => ({ ...todo }));
+		rec.doc.updatedAt = this.now();
+	}
+	/** Record the latest stage announcement. */
+	setNote(callId, note) {
+		const rec = this.runs.get(callId);
+		if (!rec) return;
+		if (rec.doc.note && note.ts < rec.doc.note.ts) return;
+		rec.doc.note = { ...note };
+		rec.doc.updatedAt = this.now();
+		if (note.phase === "error" && rec.doc.status === "running") {
+			rec.doc.status = "failed";
+			rec.doc.error = note.message;
+		}
+	}
+	finish(callId) {
+		const rec = this.runs.get(callId);
+		if (!rec) return;
+		rec.doc.status = "completed";
+		rec.doc.updatedAt = this.now();
+		for (const f of rec.doc.frames) if (f.status === "running") {
+			f.status = "finished";
+			f.finishedAt = rec.doc.updatedAt;
+		}
+	}
+	fail(callId, message) {
+		const rec = this.runs.get(callId);
+		if (!rec) return;
+		rec.doc.status = "failed";
+		rec.doc.error = message;
+		rec.doc.updatedAt = this.now();
+		for (const f of rec.doc.frames) if (f.status === "running") {
+			f.status = "failed";
+			f.finishedAt = rec.doc.updatedAt;
+		}
+	}
+	/** Snapshot for the HTTP route, or `null` when unknown/expired. */
+	get(callId) {
+		const rec = this.runs.get(callId);
+		if (!rec) return null;
+		if (this.now() - rec.doc.updatedAt > this.ttlMs) {
+			this.runs.delete(callId);
+			return null;
+		}
+		return rec.doc;
+	}
+	/** Every live run. Used by the route when the caller has no callId. */
+	list() {
+		const out = [];
+		for (const callId of [...this.runs.keys()]) {
+			const doc = this.get(callId);
+			if (doc) out.push(doc);
+		}
+		return out;
+	}
+	delete(callId) {
+		this.runs.delete(callId);
+	}
+	/** Drop expired runs. Returns how many were removed. */
+	sweep() {
+		const now = this.now();
+		let removed = 0;
+		for (const [callId, rec] of [...this.runs]) if (now - rec.doc.updatedAt > this.ttlMs) {
+			this.runs.delete(callId);
+			removed += 1;
+		}
+		return removed;
+	}
+	get size() {
+		return this.runs.size;
+	}
+};
+//#endregion
+//#region src/routes.ts
+const PROGRESS_ROUTE_PREFIX = "/api/v1/huaqiu/schematic-gen/progress";
+function sendJson(res, status, body) {
+	const payload = JSON.stringify(body);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store"
+	});
+	res.end(payload);
+}
+/** Split the sub-path off the prefix. Returns `null` on a bad shape. */
+function parsePath(req) {
+	const url = req.url ?? "";
+	const q = url.indexOf("?");
+	const pathname = q >= 0 ? url.slice(0, q) : url;
+	if (!pathname.startsWith("/api/v1/huaqiu/schematic-gen/progress")) return null;
+	const rest = pathname.slice(37);
+	if (rest === "") return { callId: null };
+	if (!rest.startsWith("/")) return null;
+	const segs = rest.split("/").filter(Boolean);
+	if (segs.length !== 1) return null;
+	let callId;
+	try {
+		callId = decodeURIComponent(segs[0]);
+	} catch {
+		return null;
+	}
+	return { callId: callId.length > 0 ? callId : null };
+}
+function createProgressHandler(store) {
+	return (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			sendJson(res, 405, { error: "method not allowed" });
+			return;
+		}
+		const parsed = parsePath(req);
+		if (!parsed) {
+			sendJson(res, 404, { error: "not found" });
+			return;
+		}
+		if (parsed.callId === null) {
+			sendJson(res, 200, { runs: store.list() });
+			return;
+		}
+		const doc = store.get(parsed.callId);
+		if (!doc) {
+			sendJson(res, 404, { error: "no live run for this call id" });
+			return;
+		}
+		sendJson(res, 200, doc);
+	};
+}
+//#endregion
+//#region src/index.ts
+/** Plugin id — matches package.json. */
+const name = "@huaqiu/dsh-tool-schematic-gen";
+/**
+* Cordis services this half depends on.
+*
+* `webServer` carries the live-progress route that the browser card polls.
+* It is already transitively required, because `@huaqiu/dsh-artifacts`
+* (which we inject as `huaqiuArtifacts) declares it too.
+*/
+const inject = [
+	"tools",
+	"huaqiuAuth",
+	"huaqiuArtifacts",
+	"webServer"
+];
+/** Console tag for filtering in logs. */
+const LOG_TAG = "[dsh-schematic-gen]";
+/**
+* Host plugin body — register the two generation tools.
+*
+* @param ctx - real cordis context (node side).
+* @returns disposer — unregisters both tools on plugin dispose.
+*/
+function apply(ctx, config = {}) {
+	if (!ctx.tools || typeof ctx.tools.register !== "function") throw new Error("@huaqiu/dsh-tool-schematic-gen requires the DSH `tools` service (ctx.tools.register).");
+	if (!ctx.huaqiuAuth || !ctx.huaqiuAuth.auth || typeof ctx.huaqiuAuth.auth.getUserInfo !== "function") throw new Error("@huaqiu/dsh-tool-schematic-gen requires the `huaqiuAuth` service (provided by @huaqiu/dsh-auth) — the eda.cn account is never baked in.");
+	if (!ctx.huaqiuArtifacts || typeof ctx.huaqiuArtifacts.create !== "function") throw new Error("@huaqiu/dsh-tool-schematic-gen requires the `huaqiuArtifacts` service (provided by @huaqiu/dsh-artifacts).");
+	const auth = ctx.huaqiuAuth;
+	const artifacts = ctx.huaqiuArtifacts;
+	const configOverride = {};
+	if (config.copilotkitUrl) configOverride.HQ_EDA_COPILOTKIT_URL = config.copilotkitUrl;
+	if (config.exportZipUrl) configOverride.HQ_EDA_EXPORT_ZIP_URL = config.exportZipUrl;
+	const finalConfig = resolveConfig({
+		...typeof process !== "undefined" ? process.env : void 0,
+		...configOverride
+	});
+	const progress = new ProgressStore();
+	if (ctx.webServer && typeof ctx.webServer.register === "function") ctx.effect(() => ctx.webServer.register({
+		kind: "prefix",
+		path: PROGRESS_ROUTE_PREFIX,
+		handler: createProgressHandler(progress)
+	}));
+	else console.warn(LOG_TAG, "webServer unavailable — live progress reporting is disabled");
+	const disposers = createSchematicGenTools({
+		config: finalConfig,
+		auth: auth.auth,
+		artifacts,
+		timeoutMs: HTTP_TIMEOUT_MS,
+		progress,
+		deps: {}
+	}).map((tool) => ctx.tools.register(tool));
+	console.log(LOG_TAG, "registered agent tools", {
+		tools: disposers.length,
+		copilotkitUrl: finalConfig.copilotkitUrl,
+		exportZipUrl: finalConfig.exportZipUrl,
+		auth: "huaqiuAuth"
+	});
+	return function dispose() {
+		for (const disposeTool of disposers) try {
+			disposeTool();
+		} catch {}
+		progress.sweep();
+	};
+}
+//#endregion
+export { agentIds, apply, inject, name };