@huaqiu/dsh-eda-host 0.3.22 → 0.3.25

package/README.md

@@ -1,16 +1,30 @@
 # @huaqiu/dsh-eda-host
 
-DSH plugin exposing the current EDA host's schematic netlist to agents through
-hq-edge.
+DSH plugin exposing the current EDA host to agents through hq-edge: its
+schematic netlist, and — without reimplementing anything — the environment and
+capability facts the host already knows.
 
 ## What it provides
 
+Netlist:
+
 | Tool | Scope |
 |---|---|
 | `get_project_netlist` | complete logical netlist of the current project |
 | `get_selection_netlist` | netlist of the currently selected components |
 | `get_active_page_netlist` | netlist of the active schematic page |
 
+EDA host discovery:
+
+| Tool | Returns |
+|---|---|
+| `get_eda_host_info` | host identity, version, installation paths, `kicad-cli` path |
+| `get_eda_host_capabilities` | capabilities the *current* host can actually provide |
+
+Discovery is not implementation: a capability is advertised only when the host
+can already provide it, and never because the EDA application is generally
+known for it.
+
 Each tool returns lossless JSON:
 
 ```json
@@ -42,7 +56,12 @@ NOT an error. On failure the tool returns `ok: false` with a semantic
 - `UNIMPLEMENTED` — the host does not support this scope (e.g. active page on
   KiCad). Do not retry.
 - `UNAVAILABLE` — hq-edge host unreachable.
-- `INTERNAL` — host-side failure.
+- `DEADLINE_EXCEEDED` — the host did not answer within the request budget.
+- `INTERNAL` — host-side failure or a malformed response.
+
+`ok:true` with empty `components`/`nets` means exactly one thing: a genuinely
+empty design. It never means "the parse failed" or "the host is unavailable" —
+those are always `ok:false` with a `kind`.
 
 ## Architecture
 
@@ -58,9 +77,45 @@ EDA Host          (hq.ir.schematic.v1.NetListService — KiCad / HQ EDA)
 native EDA model
 ```
 
-- No `@hqedge/*` dependency: the base URL arrives as overlay config
-  (`hqEdgeBaseUrl`, delivered by the hq-edge supervisor) or `HQ_EDGE_BASE_URL`
-  env fallback.
+- No `@hqedge/*` dependency: the base URL is read from `ctx.hqEdge.baseUrl`
+  (provided by the edge-bridge), falling back to overlay config
+  (`hqEdgeBaseUrl`) or `HQ_EDGE_BASE_URL`.
 - No KiCad code, no schematic parsing, no host IPC in this package.
 - Errors are propagated with semantic kinds — never converted into fake empty
   netlists.
+
+## EDA host discovery
+
+Host info crosses the same boundary as the netlist, using the EDA-independent
+`hq.host.v1` contract — not KiCad-shaped messages:
+
+```text
+get_eda_host_info ─┐
+                   ├─→ hq-edge /api/v1/host/* ─→ hq.host.v1.EdaHostInfoService ─→ host
+get_eda_host_capabilities ─┘
+```
+
+The host adapts its native facts (version, install path, `kicad-cli` location,
+which editors are open) into that contract. hq-edge performs no host-specific
+translation, so KiCad and HQ EDA implement the same service.
+
+**`hq.host.v1` has no availability fields.** A host that answers is available,
+and every executable it lists is one it can run — so unavailability is never a
+flag to check, it is a failed request (`ok:false` with `UNAVAILABLE` /
+`FAILED_PRECONDITION` / `DEADLINE_EXCEEDED`). Because proto3 omits default
+values, a host reporting nothing arrives as `{}`; the client fills the proto3
+defaults so a missing field can never be misread as "unavailable". An empty
+executable `path` means the host did not resolve an absolute location, not that
+the tool is missing.
+
+## Request budget
+
+Every request has a single bounded budget (`requestTimeoutMs`, default 30 s),
+enforced here and mirrored by the KiCad UI-dispatch bound. A request that
+exceeds it fails with `DEADLINE_EXCEEDED`; it never returns an empty result.
+
+## Dependency boundary
+
+This plugin **requires hq-edge**. It is not a standalone DSH plugin: `hqEdge` is
+a required inject, and `apply()` throws if the bridge did not provide a usable
+endpoint. See `docs/tasks/expose-capability.md` in hq-edge.

package/lib/index.d.mts

@@ -16,6 +16,17 @@ interface EdaHostConfig {
   hqEdgeBaseUrl?: string;
   /** Path prefix on the host; default "/api/v1/netlist". */
   netlistPathPrefix?: string;
+  /** Path prefix for host discovery; default "/api/v1/host". */
+  hostPathPrefix?: string;
+  /**
+   * End-to-end budget for one EDA-host request, in milliseconds.
+   *
+   * This is the SINGLE request budget for the whole chain — the plugin does
+   * not define separate per-layer timeouts. It is enforced here (outermost)
+   * and mirrored by the KiCad UI-dispatch bound, so no agent request can wait
+   * indefinitely. See docs/tasks/expose-capability.md §6.
+   */
+  requestTimeoutMs?: number;
 }
 //#endregion
 //#region src/types.d.ts
@@ -70,21 +81,111 @@ type NetlistErrorKind =
 /** Host-side runtime failure. */
 'INTERNAL' |
 /** Host unavailable (connection refused). */
-'UNAVAILABLE';
+'UNAVAILABLE' |
+/** The host did not answer within the request budget. */
+'DEADLINE_EXCEEDED';
 declare class NetlistError extends Error {
   readonly kind: NetlistErrorKind;
   constructor(kind: NetlistErrorKind, message: string);
 }
+/**
+ * `hq.host.v1` carries **no availability flags**.
+ *
+ * A host that answers `GetEdaHostInfo` is, by definition, available, and every
+ * executable it lists is one it can actually run. Unavailability is therefore
+ * never a field to check — it is a failed request, surfaced as `ok:false` with
+ * `error.kind` `UNAVAILABLE` / `FAILED_PRECONDITION` / `DEADLINE_EXCEEDED`.
+ *
+ * Consequence for consumers: never infer "unavailable" from a missing or empty
+ * value. Absence of `identity`/`installation` just means proto3 omitted
+ * defaults (see `parseEdaHostInfo`), and empty `path` only means the host could
+ * not resolve an absolute location — the tool is still runnable by name.
+ */
+/**
+ * Which EDA application sits behind the semantic host boundary.
+ *
+ * Deliberately EDA-independent: a new host adds a value here rather than
+ * introducing host-specific messages or tools.
+ */
+type EdaHostType = 'EDA_HOST_TYPE_UNSPECIFIED' | 'EDA_HOST_TYPE_KICAD' | 'EDA_HOST_TYPE_HQ_EDA';
+/**
+ * A capability an EDA host may provide.
+ *
+ * A capability is advertised only when the host can actually provide it —
+ * discovering a capability is not the same as implementing it. Unknown values
+ * MUST be treated as "not supported" so a newer host cannot confuse an older
+ * plugin.
+ */
+type EdaHostCapability = 'EDA_HOST_CAPABILITY_UNSPECIFIED' | 'EDA_HOST_CAPABILITY_SCHEMATIC' | 'EDA_HOST_CAPABILITY_PCB' | 'EDA_HOST_CAPABILITY_NETLIST' | 'EDA_HOST_CAPABILITY_NETLIST_SELECTION' | 'EDA_HOST_CAPABILITY_NETLIST_ACTIVE_PAGE' | 'EDA_HOST_CAPABILITY_ERC' | 'EDA_HOST_CAPABILITY_DRC' | 'EDA_HOST_CAPABILITY_BOM' | 'EDA_HOST_CAPABILITY_PLACEMENT';
+/** A host-provided command line tool. */
+interface EdaHostExecutable {
+  /** Stable tool name, e.g. "kicad-cli". */
+  name: string;
+  /**
+   * Absolute path when the host could resolve one.
+   *
+   * Empty means "resolvable by name only" (e.g. found on `PATH` but the host
+   * did not report a location) — never "not installed" or "unusable".
+   */
+  path: string;
+}
+/** Where the host application lives on disk. */
+interface EdaHostInstallation {
+  applicationPath: string;
+  /**
+   * Executables the host can run. Being listed here IS the availability
+   * signal: there is no per-executable availability flag.
+   */
+  executables: EdaHostExecutable[];
+}
+/** Which EDA host is connected. */
+interface EdaHostIdentity {
+  hostType: EdaHostType;
+  hostName: string;
+  version: string;
+}
+/**
+ * EDA-independent description of the connected host.
+ *
+ * Answering this message is the host's way of saying it is available — there is
+ * no `available` field to inspect.
+ */
+interface EdaHostInfo {
+  identity: EdaHostIdentity;
+  installation: EdaHostInstallation;
+}
 //#endregion
 //#region src/client.d.ts
+/** Per-call options. `signal` lets DSH cancel a request (see §6 of the task). */
+interface EdaHostRequestOptions {
+  signal?: AbortSignal;
+}
 interface EdaHostClient {
   /** Netlist of the currently selected components. */
-  getSelectionNetlist(): Promise<SchematicNetlist>;
+  getSelectionNetlist(options?: EdaHostRequestOptions): Promise<SchematicNetlist>;
   /** Complete logical netlist for the current project. */
-  getProjectNetlist(): Promise<SchematicNetlist>;
+  getProjectNetlist(options?: EdaHostRequestOptions): Promise<SchematicNetlist>;
   /** Netlist of the current active schematic page. */
-  getActivePageNetlist(): Promise<SchematicNetlist>;
+  getActivePageNetlist(options?: EdaHostRequestOptions): Promise<SchematicNetlist>;
+  /**
+   * EDA-independent identity / installation of the host. Presence of a result
+   * is the availability signal — `hq.host.v1` has no availability field.
+   */
+  getEdaHostInfo(options?: EdaHostRequestOptions): Promise<EdaHostInfo>;
+  /** Capabilities the host currently provides. */
+  getEdaHostCapabilities(options?: EdaHostRequestOptions): Promise<EdaHostCapability[]>;
 }
+/**
+ * Extract the semantic `SchematicNetlist` from an hq-edge netlist body.
+ *
+ * hq-edge now emits a single-level body: `{ netlist: { components, nets } }`.
+ * Older hq-edge builds serialized the protobuf envelope
+ * (`GetNetListResponse.oneof result`), which produced a second `netlist` level
+ * and made every populated design look empty. That legacy shape is unwrapped
+ * EXPLICITLY — not silently — and anything else is a hard error, because
+ * "malformed" must never masquerade as "empty design".
+ */
+declare function parseNetlistBody(body: unknown): SchematicNetlist;
 //#endregion
 //#region src/index.d.ts
 /** Plugin id — matches package.json. */
@@ -147,4 +248,4 @@ declare module '@deepseek-ai/cordis' {
  */
 declare function apply(ctx: Context, config?: Partial<EdaHostConfig>): () => void;
 //#endregion
-export { type EdaHostClient, type EdaHostConfig, type ElectricalNet, type ElectricalType, NetlistError, type NetlistErrorKind, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name };
+export { type EdaHostCapability, type EdaHostClient, type EdaHostConfig, type EdaHostExecutable, type EdaHostIdentity, type EdaHostInfo, type EdaHostInstallation, type EdaHostRequestOptions, type EdaHostType, type ElectricalNet, type ElectricalType, NetlistError, type NetlistErrorKind, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name, parseNetlistBody };

package/lib/index.mjs

@@ -1,14 +1,22 @@
 import { getLogger } from "@huaqiu/dsh-plugin-log";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 const SCOPE_ROUTE = {
 	project: "/project",
 	selection: "/selection",
 	"active-page": "/active-page"
 };
 function resolveEdaHostConfig(config, env = process.env) {
+	const baseUrl = config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? "";
+	const pathPrefix = config?.netlistPathPrefix ?? env.HQ_EDGE_NETLIST_PATH ?? "/api/v1/netlist";
+	const hostPrefix = config?.hostPathPrefix ?? env.HQ_EDGE_HOST_PATH ?? "/api/v1/host";
+	const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS;
+	const timeout = Number.parseInt(String(timeoutRaw ?? ""), 10);
 	return {
-		hqEdgeBaseUrl: config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? "",
-		netlistPathPrefix: config?.netlistPathPrefix ?? env.HQ_EDGE_NETLIST_PATH ?? "/api/v1/netlist"
+		hqEdgeBaseUrl: baseUrl,
+		netlistPathPrefix: pathPrefix,
+		hostPathPrefix: hostPrefix,
+		requestTimeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS
 	};
 }
 /** True when a host base URL is available (host mode). */
@@ -19,6 +27,14 @@ function hasHost(config) {
 function netlistUrlOf(config, scope) {
 	return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.netlistPathPrefix ?? "/api/v1/netlist").replace(/^\/+|\/+$/g, "")}${SCOPE_ROUTE[scope]}`;
 }
+const HOST_ROUTE = {
+	info: "/info",
+	capabilities: "/capabilities"
+};
+/** Build the absolute URL for one host discovery route. */
+function hostUrlOf(config, route) {
+	return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.hostPathPrefix ?? "/api/v1/host").replace(/^\/+|\/+$/g, "")}${HOST_ROUTE[route]}`;
+}
 //#endregion
 //#region src/types.ts
 var NetlistError = class extends Error {
@@ -32,38 +48,128 @@ var NetlistError = class extends Error {
 //#endregion
 //#region src/client.ts
 /**
-* Netlist transport for `@huaqiu/dsh-eda-host`.
+* Transport for `@huaqiu/dsh-eda-host`.
 *
 * DSH → dsh-eda-host → hq-edge → EDA Host is the ONLY production path. This
-* module fetches the semantic netlist from the hq-edge netlist router and
-* maps the HTTP status back to the semantic gRPC error categories. It never
-* parses schematic files and never touches KiCad.
+* module fetches the semantic netlist and the EDA-independent host information
+* from hq-edge, maps HTTP statuses back to the semantic gRPC error categories,
+* and enforces the single end-to-end request budget. It never parses schematic
+* files and never touches KiCad.
 *
 * @module
 */
-/** HTTP status → semantic error kind (see routes/netlist.ts on hq-edge). */
+/** HTTP status → semantic error kind (see routes/edaHostStatus.ts on hq-edge). */
 function statusToKind(status) {
 	if (status === 412) return "FAILED_PRECONDITION";
 	if (status === 501) return "UNIMPLEMENTED";
 	if (status === 503) return "UNAVAILABLE";
+	if (status === 504) return "DEADLINE_EXCEEDED";
 	return "INTERNAL";
 }
+/** True when a thrown fetch error is an abort/timeout rather than a transport error. */
+function isAbortError(err) {
+	const name = err?.name;
+	return name === "AbortError" || name === "TimeoutError";
+}
+/**
+* Combine an optional caller signal with the plugin's own budget.
+*
+* `AbortSignal.any` is not available on every Node version DSH may run on, so
+* fall back to whichever signal exists — the budget is always present, which is
+* what guarantees no request can wait indefinitely.
+*/
+function resolveSignal(deadlineMs, caller) {
+	const signals = [caller, deadlineMs > 0 ? AbortSignal.timeout(deadlineMs) : void 0].filter((s) => Boolean(s));
+	if (signals.length === 0) return void 0;
+	if (signals.length === 1) return signals[0];
+	const anyFn = AbortSignal.any;
+	return typeof anyFn === "function" ? anyFn.call(AbortSignal, signals) : signals[0];
+}
+/**
+* Extract the semantic `SchematicNetlist` from an hq-edge netlist body.
+*
+* hq-edge now emits a single-level body: `{ netlist: { components, nets } }`.
+* Older hq-edge builds serialized the protobuf envelope
+* (`GetNetListResponse.oneof result`), which produced a second `netlist` level
+* and made every populated design look empty. That legacy shape is unwrapped
+* EXPLICITLY — not silently — and anything else is a hard error, because
+* "malformed" must never masquerade as "empty design".
+*/
+function parseNetlistBody(body) {
+	if (!body || typeof body !== "object" || Array.isArray(body)) throw new NetlistError("INTERNAL", "eda-host: malformed netlist response from hq-edge");
+	let candidate = body.netlist;
+	if (candidate && typeof candidate === "object" && !Array.isArray(candidate) && candidate.components === void 0 && typeof candidate.netlist === "object") candidate = candidate.netlist;
+	if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) throw new NetlistError("INTERNAL", "eda-host: malformed netlist response from hq-edge");
+	const { components, nets } = candidate;
+	if (components !== void 0 && !Array.isArray(components)) throw new NetlistError("INTERNAL", "eda-host: netlist.components is not an array");
+	if (nets !== void 0 && !Array.isArray(nets)) throw new NetlistError("INTERNAL", "eda-host: netlist.nets is not an array");
+	return {
+		components: components ?? [],
+		nets: nets ?? []
+	};
+}
+function str(value) {
+	return typeof value === "string" ? value : "";
+}
+/**
+* Extract a complete `EdaHostInfo` from an hq-edge host-info body.
+*
+* `hq.host.v1` has no availability flags, so the only way to distinguish "the
+* host is here" from "the host is not" is whether this call succeeded at all.
+* That makes the *shape* the contract: proto3 JSON omits default-valued fields,
+* so a host that legitimately reports nothing arrives as `{}`. Rather than let
+* a half-empty object reach the agent — where a missing field could be misread
+* as "not available" — absent values are filled with their proto3 defaults.
+*
+* Values that are present are never reinterpreted; unknown `hostType` strings
+* pass through so a newer host cannot be silently downgraded.
+*/
+function parseEdaHostInfo(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new NetlistError("INTERNAL", "eda-host: malformed host info response from hq-edge");
+	const raw = value;
+	const executables = Array.isArray(raw.installation?.executables) ? (raw.installation?.executables).filter((e) => Boolean(e) && typeof e === "object").map((e) => ({
+		name: str(e.name),
+		path: str(e.path)
+	})) : [];
+	return {
+		identity: {
+			hostType: typeof raw.identity?.hostType === "string" ? raw.identity.hostType : "EDA_HOST_TYPE_UNSPECIFIED",
+			hostName: str(raw.identity?.hostName),
+			version: str(raw.identity?.version)
+		},
+		installation: {
+			applicationPath: str(raw.installation?.applicationPath),
+			executables
+		}
+	};
+}
 function createEdaHostClient(config, deps = {}) {
 	const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
-	async function fetchScope(scope) {
+	/**
+	* Resolve the host endpoint per request. A resolver (ctx.hqEdge) wins over
+	* the static config/env value; if neither yields a URL we degrade to the
+	* same clear FAILED_PRECONDITION the standalone install path uses.
+	*/
+	function resolveConfig() {
 		const baseUrl = deps.baseUrlResolver?.()?.trim() ?? config.hqEdgeBaseUrl?.trim() ?? "";
-		if (baseUrl.length === 0) throw new NetlistError("FAILED_PRECONDITION", "eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — netlist tools require the hq-edge EDA host bridge.");
-		const url = netlistUrlOf({
+		if (baseUrl.length === 0) throw new NetlistError("FAILED_PRECONDITION", "eda-host: no hq-edge base URL configured (ctx.hqEdge.baseUrl / hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — EDA host tools require the hq-edge bridge.");
+		return {
 			...config,
 			hqEdgeBaseUrl: baseUrl
-		}, scope);
+		};
+	}
+	/** Perform one GET and return the parsed JSON body, mapping failures. */
+	async function getJson(url, options, what) {
+		const signal = resolveSignal(config.requestTimeoutMs ?? 3e4, options?.signal);
 		let response;
 		try {
 			response = await fetchImpl(url, {
 				method: "GET",
-				headers: { Accept: "application/json" }
+				headers: { Accept: "application/json" },
+				...signal ? { signal } : {}
 			});
 		} catch (err) {
+			if (isAbortError(err)) throw new NetlistError("DEADLINE_EXCEEDED", `eda-host: ${what} request exceeded its time budget at ${url}`);
 			throw new NetlistError("UNAVAILABLE", `eda-host: cannot reach hq-edge at ${url}: ${String(err?.message ?? err)}`);
 		}
 		if (!response.ok) {
@@ -72,19 +178,27 @@ function createEdaHostClient(config, deps = {}) {
 				const body = await response.json();
 				if (typeof body.detail === "string") detail = body.detail;
 			} catch {}
-			throw new NetlistError(statusToKind(response.status), `eda-host: netlist request failed (${response.status}${detail ? `: ${detail}` : ""})`);
+			throw new NetlistError(statusToKind(response.status), `eda-host: ${what} request failed (${response.status}${detail ? `: ${detail}` : ""})`);
 		}
-		const body = await response.json();
-		if (!body || typeof body.netlist !== "object" || body.netlist === null) throw new NetlistError("INTERNAL", "eda-host: malformed netlist response from hq-edge");
-		const netlist = body.netlist;
-		netlist.components ??= [];
-		netlist.nets ??= [];
-		return netlist;
+		return response.json();
+	}
+	async function fetchScope(scope, options) {
+		return parseNetlistBody(await getJson(netlistUrlOf(resolveConfig(), scope), options, "netlist"));
 	}
 	return {
-		getSelectionNetlist: () => fetchScope("selection"),
-		getProjectNetlist: () => fetchScope("project"),
-		getActivePageNetlist: () => fetchScope("active-page")
+		getSelectionNetlist: (options) => fetchScope("selection", options),
+		getProjectNetlist: (options) => fetchScope("project", options),
+		getActivePageNetlist: (options) => fetchScope("active-page", options),
+		getEdaHostInfo: async (options) => {
+			const body = await getJson(hostUrlOf(resolveConfig(), "info"), options, "host info");
+			if (!body || typeof body.info !== "object" || body.info === null) throw new NetlistError("INTERNAL", "eda-host: malformed host info response from hq-edge");
+			return parseEdaHostInfo(body.info);
+		},
+		getEdaHostCapabilities: async (options) => {
+			const body = await getJson(hostUrlOf(resolveConfig(), "capabilities"), options, "host capabilities");
+			if (!body || !Array.isArray(body.capabilities)) throw new NetlistError("INTERNAL", "eda-host: malformed host capabilities response from hq-edge");
+			return body.capabilities.filter((c) => typeof c === "string");
+		}
 	};
 }
 //#endregion
@@ -92,17 +206,23 @@ function createEdaHostClient(config, deps = {}) {
 /**
 * Agent tools for `@huaqiu/dsh-eda-host`.
 *
-* Three semantic operations, one per netlist scope:
+* Three semantic netlist operations, one per scope:
 *
 *   get_project_netlist     complete logical netlist of the current project
 *   get_selection_netlist   netlist of the currently selected components
 *   get_active_page_netlist netlist of the active schematic page
 *
-* The tools are pure pass-throughs: they call the hq-edge netlist router and
-* return the semantic `SchematicNetlist` as lossless JSON. Errors are
-* propagated with a semantic `kind` (FAILED_PRECONDITION / UNIMPLEMENTED /
-* INTERNAL / UNAVAILABLE) — never converted into a fake empty netlist. A
-* valid-but-empty netlist is `ok: true` with empty `components`/`nets`.
+* Two EDA host discovery operations:
+*
+*   get_eda_host_info          which host, which version, where it is installed
+*   get_eda_host_capabilities  what the current host can actually do
+*
+* The netlist tools are pure pass-throughs: they call the hq-edge netlist
+* router and return the semantic `SchematicNetlist` as lossless JSON. Errors
+* are propagated with a semantic `kind` (FAILED_PRECONDITION / UNIMPLEMENTED /
+* INTERNAL / UNAVAILABLE / DEADLINE_EXCEEDED) — never converted into a fake
+* empty netlist. A valid-but-empty netlist is `ok: true` with empty
+* `components`/`nets`.
 *
 * @module
 */
@@ -116,12 +236,25 @@ function renderJson(_args, value) {
 		text: JSON.stringify(value)
 	}];
 }
-async function runScope(env, scope) {
+/**
+* Every failure kind, and what the agent should do about it.
+*
+* Shared by all tools so the prompt contract cannot drift between them.
+*/
+const ERROR_SEMANTICS = "IMPORTANT SEMANTICS: on ok:false, error.kind distinguishes the cause: \"FAILED_PRECONDITION\" (no EDA host / no live editor — ask the user to open the design in the EDA editor first, then retry), \"UNIMPLEMENTED\" (this capability is not supported by the current host — do NOT retry; report it to the user), \"UNAVAILABLE\" (hq-edge / EDA host unreachable), \"DEADLINE_EXCEEDED\" (the host did not answer in time — retry once, then report), \"INTERNAL\" (host-side failure). Do NOT fabricate data.";
+function failureOf(err) {
+	return {
+		kind: err instanceof NetlistError ? err.kind : "INTERNAL",
+		message: String(err?.message ?? err)
+	};
+}
+async function runScope(env, scope, exec) {
+	const options = exec?.signal ? { signal: exec.signal } : {};
 	try {
 		let netlist;
-		if (scope === "project") netlist = await env.client.getProjectNetlist();
-		else if (scope === "selection") netlist = await env.client.getSelectionNetlist();
-		else netlist = await env.client.getActivePageNetlist();
+		if (scope === "project") netlist = await env.client.getProjectNetlist(options);
+		else if (scope === "selection") netlist = await env.client.getSelectionNetlist(options);
+		else netlist = await env.client.getActivePageNetlist(options);
 		return {
 			ok: true,
 			scope,
@@ -131,15 +264,12 @@ async function runScope(env, scope) {
 		return {
 			ok: false,
 			scope,
-			error: {
-				kind: err instanceof NetlistError ? err.kind : "INTERNAL",
-				message: String(err?.message ?? err)
-			}
+			error: failureOf(err)
 		};
 	}
 }
 function scopeDescription(scope, extra) {
-	return "Read the current schematic netlist from the EDA host through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). " + extra + " The result is a semantic netlist JSON: { ok, scope, netlist: { components[], nets[] } }. Each component has referenceDesignators[], value, manufacturerPartNumber, footprint, description and pins[] (pinNumber, pinName, electricalType); each net has name and pinReferences[] (referenceDesignator, pinNumber). IMPORTANT SEMANTICS: ok:true with empty components/nets is a VALID empty design — do not treat it as a failure. On ok:false, error.kind distinguishes the cause: \"FAILED_PRECONDITION\" (no EDA host / no live editor — ask the user to open the design in the EDA editor first, then retry), \"UNIMPLEMENTED\" (this scope is not supported by the current host — do NOT retry; report it to the user), \"UNAVAILABLE\" (hq-edge host unreachable), \"INTERNAL\" (host-side failure). Do NOT fabricate netlist data.";
+	return "Read the current schematic netlist from the EDA host through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). " + extra + " The result is a semantic netlist JSON: { ok, scope, netlist: { components[], nets[] } }. Each component has referenceDesignators[], value, manufacturerPartNumber, footprint, description and pins[] (pinNumber, pinName, electricalType); each net has name and pinReferences[] (referenceDesignator, pinNumber). IMPORTANT: ok:true with empty components/nets is a VALID empty design — do not treat it as a failure. IMPORTANT SEMANTICS: on ok:false, error.kind distinguishes the cause: \"FAILED_PRECONDITION\" (no EDA host / no live editor — ask the user to open the design in the EDA editor first, then retry), \"UNIMPLEMENTED\" (this capability is not supported by the current host — do NOT retry; report it to the user), \"UNAVAILABLE\" (hq-edge / EDA host unreachable), \"DEADLINE_EXCEEDED\" (the host did not answer in time — retry once, then report), \"INTERNAL\" (host-side failure). Do NOT fabricate data.";
 }
 function createNetListTools(env) {
 	const mkTool = (scope, name, desc) => defineTool({
@@ -150,16 +280,70 @@ function createNetListTools(env) {
 			schema: { type: "json" },
 			render: renderJson
 		},
-		async execute(_args, _exec) {
-			return asJson(await runScope(env, scope));
+		async execute(_args, exec) {
+			return asJson(await runScope(env, scope, exec));
 		}
 	});
 	return [
 		mkTool("project", "get_project_netlist", scopeDescription("project", "Returns the complete logical netlist for the current project (all sheets, all nets).")),
 		mkTool("selection", "get_selection_netlist", scopeDescription("selection", "Returns the netlist associated with the currently selected schematic components, including the nets they participate in (each net lists every connected pin, not only the selected ones).")),
-		mkTool("active_page", "get_active_page_netlist", scopeDescription("active_page", "Returns the netlist for the currently active schematic page. NOTE: KiCad host does not implement this scope — expect ok:false with error.kind \"UNIMPLEMENTED\"."))
+		mkTool("active_page", "get_active_page_netlist", scopeDescription("active_page", "Returns the netlist for the currently active schematic page. NOTE: the KiCad host does not implement this scope — expect ok:false with error.kind \"UNIMPLEMENTED\". Check get_eda_host_capabilities before relying on it."))
 	];
 }
+/**
+* EDA host discovery tools.
+*
+* These expose what the EDA host ALREADY knows and can ALREADY do — they
+* implement no EDA functionality themselves. A capability being advertised is
+* a claim that the host can provide it, nothing more.
+*/
+function createEdaHostTools(env) {
+	return [defineTool({
+		name: "get_eda_host_info",
+		description: "Describe the EDA host currently connected through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). Returns { ok, info: { identity: { hostType, hostName, version }, installation: { applicationPath, executables[]: { name, path } } } }. Use it when you need factual information about the current EDA environment, such as \"what EDA host am I connected to\", \"what version is it\", \"where is it installed\", or \"where is kicad-cli\". The returned information is authoritative host-provided ground truth. " + ERROR_SEMANTICS,
+		parameters: {},
+		output: {
+			schema: { type: "json" },
+			render: renderJson
+		},
+		async execute(_args, exec) {
+			try {
+				const options = exec?.signal ? { signal: exec.signal } : {};
+				return asJson({
+					ok: true,
+					info: await env.client.getEdaHostInfo(options)
+				});
+			} catch (err) {
+				return asJson({
+					ok: false,
+					error: failureOf(err)
+				});
+			}
+		}
+	}), defineTool({
+		name: "get_eda_host_capabilities",
+		description: "List the capabilities the CURRENT EDA host provides, using EDA-independent capability identifiers such as EDA_HOST_CAPABILITY_NETLIST, EDA_HOST_CAPABILITY_PCB or EDA_HOST_CAPABILITY_BOM. Returns { ok, capabilities: string[] }. This is DISCOVERY, not execution: it reports capabilities already provided by the connected EDA host. Treat the returned capability list as the authoritative runtime contract for the current host. Do not assume a capability is available merely because the EDA application is generally known to support it. Unknown capability identifiers MUST be treated as unsupported. " + ERROR_SEMANTICS,
+		parameters: {},
+		output: {
+			schema: { type: "json" },
+			render: renderJson
+		},
+		async execute(_args, exec) {
+			try {
+				const options = exec?.signal ? { signal: exec.signal } : {};
+				return asJson({
+					ok: true,
+					capabilities: await env.client.getEdaHostCapabilities(options)
+				});
+			} catch (err) {
+				return asJson({
+					ok: false,
+					error: failureOf(err)
+				});
+			}
+		}
+	})];
+}
 //#endregion
 //#region src/index.ts
 /** Plugin id — matches package.json. */
@@ -182,6 +366,7 @@ const name = "@huaqiu/dsh-eda-host";
 */
 const inject = ["hqEdge", "tools"];
 const log = getLogger("dsh-eda-host");
+log.info("dsh-eda-host: module loaded (waiting for the hqEdge + tools services)");
 /**
 * Host plugin body — provide `edaHost` and register the three netlist tools.
 *
@@ -201,22 +386,26 @@ const log = getLogger("dsh-eda-host");
 function apply(ctx, config = {}) {
 	if (!ctx.tools || typeof ctx.tools.register !== "function") throw new Error("@huaqiu/dsh-eda-host requires the DSH `tools` service (ctx.tools.register).");
 	const resolved = resolveEdaHostConfig(config);
+	const hq = ctx.hqEdge;
+	if (!hq || typeof hq.baseUrl !== "string" || hq.baseUrl.trim().length === 0) throw new Error("@huaqiu/dsh-eda-host requires a usable hq-edge context: the edge-bridge plugin did not provide ctx.hqEdge.baseUrl. EDA host tools cannot work without hq-edge — check that the bridge started and that the HQ Edge port is valid.");
 	const getHqEdgeBaseUrl = () => {
-		const hq = ctx.hqEdge;
-		return hq?.baseUrl && hq.baseUrl.trim().length > 0 ? hq.baseUrl : void 0;
+		const current = ctx.hqEdge;
+		return current?.baseUrl && current.baseUrl.trim().length > 0 ? current.baseUrl : void 0;
 	};
 	log.info("applying dsh-eda-host node half", {
 		hasConfigHost: hasHost(resolved),
 		hqEdgeBaseUrlFromConfig: resolved.hqEdgeBaseUrl ?? null,
-		netlistPathPrefix: resolved.netlistPathPrefix
+		netlistPathPrefix: resolved.netlistPathPrefix,
+		hostPathPrefix: resolved.hostPathPrefix,
+		requestTimeoutMs: resolved.requestTimeoutMs
 	});
 	const client = createEdaHostClient(resolved, { baseUrlResolver: getHqEdgeBaseUrl });
 	ctx.effect(() => ctx.provide("edaHost", client));
-	const tools = createNetListTools({ client });
+	const tools = [...createNetListTools({ client }), ...createEdaHostTools({ client })];
 	const disposers = [];
 	for (const tool of tools) disposers.push(ctx.tools.register(tool));
 	log.info("dsh-eda-host node half ready", {
-		tools: 3,
+		tools: tools.length,
 		configHostMode: hasHost(resolved)
 	});
 	return () => {
@@ -226,4 +415,4 @@ function apply(ctx, config = {}) {
 	};
 }
 //#endregion
-export { NetlistError, apply, inject, name };
+export { NetlistError, apply, inject, name, parseNetlistBody };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-eda-host",
-  "version": "0.3.22",
+  "version": "0.3.25",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -22,7 +22,7 @@
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.0"
   },
   "dependencies": {
-    "@huaqiu/dsh-plugin-log": "0.3.22"
+    "@huaqiu/dsh-plugin-log": "0.3.25"
   },
   "files": [
     "lib",