@huaqiu/dsh-eda-host 0.4.5 → 0.4.7

package/lib/index.d.mts

@@ -18,6 +18,8 @@ interface EdaHostConfig {
   netlistPathPrefix?: string;
   /** Path prefix for PCB selection; default "/api/v1/pcb-selection". */
   pcbSelectionPathPrefix?: string;
+  /** Path prefix for the complete-board query; default "/api/v1/pcb-board". */
+  pcbBoardPathPrefix?: string;
   /** Path prefix for host discovery; default "/api/v1/host". */
   hostPathPrefix?: string;
   /**
@@ -71,12 +73,13 @@ interface SchematicNetlist {
   nets: ElectricalNet[];
 }
 /**
- * Semantic PCB selection types.
+ * Semantic PCB snapshot types.
  *
  * Self-contained structural mirror of `hq.pcb.v1` (the hq-edge-owned semantic
- * protobuf contract for `PcbSelectionService.GetSelection`). Units follow the
- * hq.pcb.v1 convention: positions/sizes/lengths in mm, rotations in degrees,
- * `id` is the KiCad native object identity.
+ * protobuf contract for `PcbQueryService.GetSelection` / `GetBoard`). The
+ * same PcbSnapshot shape backs both the current selection and the complete
+ * board. Units follow the hq.pcb.v1 convention: positions/sizes/lengths in mm,
+ * rotations in degrees, `id` is the KiCad native object identity.
  */
 interface PcbPoint {
   x: number;
@@ -174,7 +177,7 @@ interface PcbGroup {
   id: string;
   itemIds: string[];
 }
-interface PcbSelection {
+interface PcbSnapshot {
   footprints: PcbFootprint[];
   pads: PcbPad[];
   tracks: PcbTrack[];
@@ -294,11 +297,17 @@ interface EdaHostClient {
   /** Capabilities the host currently provides. */
   getEdaHostCapabilities(options?: EdaHostRequestOptions): Promise<EdaHostCapability[]>;
   /**
-   * Semantic PCB selection of the current PCB editor (hq.pcb.v1
-   * PcbSelectionService.GetSelection bridged through hq-edge). An empty
-   * selection resolves to an all-empty `PcbSelection` — never an error.
+   * Semantic PCB snapshot of the current PCB editor selection (hq.pcb.v1
+   * PcbQueryService.GetSelection bridged through hq-edge). An empty
+   * selection resolves to an all-empty `PcbSnapshot` — never an error.
    */
-  getPcbSelection(options?: EdaHostRequestOptions): Promise<PcbSelection>;
+  getPcbSelection(options?: EdaHostRequestOptions): Promise<PcbSnapshot>;
+  /**
+   * Semantic PCB snapshot of the complete board (hq.pcb.v1
+   * PcbQueryService.GetBoard bridged through hq-edge). An empty board
+   * resolves to an all-empty `PcbSnapshot` — never an error.
+   */
+  getPcbBoard(options?: EdaHostRequestOptions): Promise<PcbSnapshot>;
 }
 /**
  * Extract the semantic `SchematicNetlist` from an hq-edge netlist body.
@@ -373,4 +382,4 @@ declare module '@deepseek-ai/cordis' {
  */
 declare function apply(ctx: Context, config?: Partial<EdaHostConfig>): () => void;
 //#endregion
-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 PcbArc, type PcbDimension, type PcbFootprint, type PcbGroup, type PcbNetRef, type PcbPad, type PcbPoint, type PcbSegment, type PcbSelection, type PcbShape, type PcbText, type PcbTrack, type PcbVia, type PcbZone, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name, parseNetlistBody };
+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 PcbArc, type PcbDimension, type PcbFootprint, type PcbGroup, type PcbNetRef, type PcbPad, type PcbPoint, type PcbSegment, type PcbShape, type PcbSnapshot, type PcbText, type PcbTrack, type PcbVia, type PcbZone, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name, parseNetlistBody };

package/lib/index.mjs

@@ -10,6 +10,7 @@ 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 pcbSelectionPrefix = config?.pcbSelectionPathPrefix ?? env.HQ_EDGE_PCB_SELECTION_PATH ?? "/api/v1/pcb-selection";
+	const pcbBoardPrefix = config?.pcbBoardPathPrefix ?? env.HQ_EDGE_PCB_BOARD_PATH ?? "/api/v1/pcb-board";
 	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);
@@ -17,6 +18,7 @@ function resolveEdaHostConfig(config, env = process.env) {
 		hqEdgeBaseUrl: baseUrl,
 		netlistPathPrefix: pathPrefix,
 		pcbSelectionPathPrefix: pcbSelectionPrefix,
+		pcbBoardPathPrefix: pcbBoardPrefix,
 		hostPathPrefix: hostPrefix,
 		requestTimeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS
 	};
@@ -33,6 +35,10 @@ function netlistUrlOf(config, scope) {
 function pcbSelectionUrlOf(config) {
 	return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.pcbSelectionPathPrefix ?? "/api/v1/pcb-selection").replace(/^\/+|\/+$/g, "")}`;
 }
+/** Build the absolute URL for the complete-board query route. */
+function pcbBoardUrlOf(config) {
+	return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.pcbBoardPathPrefix ?? "/api/v1/pcb-board").replace(/^\/+|\/+$/g, "")}`;
+}
 const HOST_ROUTE = {
 	info: "/info",
 	capabilities: "/capabilities"
@@ -191,8 +197,8 @@ function createEdaHostClient(config, deps = {}) {
 	async function fetchScope(scope, options) {
 		return parseNetlistBody(await getJson(netlistUrlOf(resolveConfig(), scope), options, "netlist"));
 	}
-	function parsePcbSelection(value) {
-		if (!value || typeof value !== "object" || Array.isArray(value)) throw new NetlistError("INTERNAL", "eda-host: malformed PCB selection response from hq-edge");
+	function parsePcbSnapshot(value, what) {
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new NetlistError("INTERNAL", `eda-host: malformed ${what} response from hq-edge`);
 		const asArray = (v) => Array.isArray(v) ? v : [];
 		return {
 			footprints: asArray(value.footprints),
@@ -223,7 +229,10 @@ function createEdaHostClient(config, deps = {}) {
 			return body.capabilities.filter((c) => typeof c === "string");
 		},
 		getPcbSelection: async (options) => {
-			return parsePcbSelection(await getJson(pcbSelectionUrlOf(resolveConfig()), options, "pcb selection"));
+			return parsePcbSnapshot(await getJson(pcbSelectionUrlOf(resolveConfig()), options, "pcb selection"), "PCB selection");
+		},
+		getPcbBoard: async (options) => {
+			return parsePcbSnapshot(await getJson(pcbBoardUrlOf(resolveConfig()), options, "pcb board"), "PCB board");
 		}
 	};
 }
@@ -327,7 +336,7 @@ 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,
+			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\". When the host is KiCad, the executable list also carries \"kicad-python\" — the interpreter bundled with KiCad that owns the official kicad-python package (kipy); the dsh-kicad skills already run with it automatically. The returned information is authoritative host-provided ground truth. " + ERROR_SEMANTICS,
 			parameters: {},
 			output: {
 				schema: { type: "json" },
@@ -371,6 +380,29 @@ function createEdaHostTools(env) {
 				}
 			}
 		}),
+		defineTool({
+			name: "get_pcb_board",
+			description: "Read the COMPLETE semantic PCB board from the current PCB editor through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). Returns { ok, snapshot: { footprints[], pads[], tracks[], arcs[], vias[], zones[], shapes[], texts[], dimensions[], groups[], nets[] } } — the same shape as get_pcb_selection, but covering every object on the board regardless of selection. Each footprint has reference, value, footprint, position {x,y} in mm, rotationDeg and pads[] (pin, type, shape, position, widthMm, heightMm, rotationDeg, layer, net{name, code}); tracks have layer, start/end in mm, widthMm, lengthMm and net; vias have layers[], drillMm, viaType and start/end; zones have layer, net and outline segments. Every object carries id — the EDA-host native object identity. IMPORTANT: ok:true with all-empty arrays is a VALID empty board — do not treat it as a failure. " + 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,
+						snapshot: await env.client.getPcbBoard(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,
@@ -418,6 +450,30 @@ const name = "@huaqiu/dsh-eda-host";
 */
 const inject = ["hqEdge", "tools"];
 const log = getLogger("dsh-eda-host");
+/**
+* Env vars relevant to the hq-edge / DSH / KiCad integration, captured at
+* plugin apply() time so startup issues are diagnosable from the log.
+*
+* Values are logged verbatim EXCEPT `KICAD_API_TOKEN`, which is a live
+* credential KiCad injects for the IPC socket — only its presence is logged
+* (never the token itself).
+*/
+const DSH_ENV_LOG_KEYS = [
+	"DSH_KICAD_PYTHON",
+	"DSH_KICAD_SKILLS_DIR",
+	"DSH_HOME",
+	"HQ_EDGE_BASE_URL",
+	"KICAD_API_SOCKET",
+	"KICAD_API_TOKEN"
+];
+function envSnapshot() {
+	const snapshot = {};
+	for (const key of DSH_ENV_LOG_KEYS) {
+		const value = process.env[key];
+		snapshot[key] = key === "KICAD_API_TOKEN" ? value ? "<set>" : null : value ?? null;
+	}
+	return snapshot;
+}
 log.info("dsh-eda-host: module loaded (waiting for the hqEdge + tools services)");
 /**
 * Host plugin body — provide `edaHost` and register the three netlist tools.
@@ -449,7 +505,8 @@ function apply(ctx, config = {}) {
 		hqEdgeBaseUrlFromConfig: resolved.hqEdgeBaseUrl ?? null,
 		netlistPathPrefix: resolved.netlistPathPrefix,
 		hostPathPrefix: resolved.hostPathPrefix,
-		requestTimeoutMs: resolved.requestTimeoutMs
+		requestTimeoutMs: resolved.requestTimeoutMs,
+		env: envSnapshot()
 	});
 	const client = createEdaHostClient(resolved, { baseUrlResolver: getHqEdgeBaseUrl });
 	ctx.effect(() => ctx.provide("edaHost", client));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-eda-host",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "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.4.5"
+    "@huaqiu/dsh-plugin-log": "0.4.7"
   },
   "files": [
     "lib",

package/src/client.ts

@@ -10,12 +10,12 @@
  * @module
  */
 
-import { DEFAULT_REQUEST_TIMEOUT_MS, hostUrlOf, netlistUrlOf, pcbSelectionUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
+import { DEFAULT_REQUEST_TIMEOUT_MS, hostUrlOf, netlistUrlOf, pcbBoardUrlOf, pcbSelectionUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
 import {
   NetlistError,
   type EdaHostCapability,
   type EdaHostInfo,
-  type PcbSelection,
+  type PcbSnapshot,
   type SchematicNetlist,
 } from './types.js'
 
@@ -53,11 +53,17 @@ export interface EdaHostClient {
   /** Capabilities the host currently provides. */
   getEdaHostCapabilities(options?: EdaHostRequestOptions): Promise<EdaHostCapability[]>
   /**
-   * Semantic PCB selection of the current PCB editor (hq.pcb.v1
-   * PcbSelectionService.GetSelection bridged through hq-edge). An empty
-   * selection resolves to an all-empty `PcbSelection` — never an error.
+   * Semantic PCB snapshot of the current PCB editor selection (hq.pcb.v1
+   * PcbQueryService.GetSelection bridged through hq-edge). An empty
+   * selection resolves to an all-empty `PcbSnapshot` — never an error.
    */
-  getPcbSelection(options?: EdaHostRequestOptions): Promise<PcbSelection>
+  getPcbSelection(options?: EdaHostRequestOptions): Promise<PcbSnapshot>
+  /**
+   * Semantic PCB snapshot of the complete board (hq.pcb.v1
+   * PcbQueryService.GetBoard bridged through hq-edge). An empty board
+   * resolves to an all-empty `PcbSnapshot` — never an error.
+   */
+  getPcbBoard(options?: EdaHostRequestOptions): Promise<PcbSnapshot>
 }
 
 /** HTTP status → semantic error kind (see routes/edaHostStatus.ts on hq-edge). */
@@ -267,11 +273,11 @@ export function createEdaHostClient(
     return parseNetlistBody(await getJson(url, options, 'netlist'))
   }
 
-  function parsePcbSelection(value: unknown): PcbSelection {
+  function parsePcbSnapshot(value: unknown, what: string): PcbSnapshot {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
       throw new NetlistError(
         'INTERNAL',
-        'eda-host: malformed PCB selection response from hq-edge',
+        `eda-host: malformed ${what} response from hq-edge`,
       )
     }
 
@@ -290,7 +296,7 @@ export function createEdaHostClient(
       dimensions: asArray((value as Record<string, unknown>).dimensions),
       groups: asArray((value as Record<string, unknown>).groups),
       nets: asArray((value as Record<string, unknown>).nets),
-    } as PcbSelection
+    } as PcbSnapshot
   }
 
   return {
@@ -331,7 +337,14 @@ export function createEdaHostClient(
       const resolved = resolveConfig()
       const url = pcbSelectionUrlOf(resolved)
       const body = (await getJson(url, options, 'pcb selection')) as unknown
-      return parsePcbSelection(body)
+      return parsePcbSnapshot(body, 'PCB selection')
+    },
+
+    getPcbBoard: async (options) => {
+      const resolved = resolveConfig()
+      const url = pcbBoardUrlOf(resolved)
+      const body = (await getJson(url, options, 'pcb board')) as unknown
+      return parsePcbSnapshot(body, 'PCB board')
     },
   }
 }

package/src/config.ts

@@ -17,6 +17,8 @@ export interface EdaHostConfig {
   netlistPathPrefix?: string
   /** Path prefix for PCB selection; default "/api/v1/pcb-selection". */
   pcbSelectionPathPrefix?: string
+  /** Path prefix for the complete-board query; default "/api/v1/pcb-board". */
+  pcbBoardPathPrefix?: string
   /** Path prefix for host discovery; default "/api/v1/host". */
   hostPathPrefix?: string
   /**
@@ -34,6 +36,8 @@ export const DEFAULT_NETLIST_PATH_PREFIX = '/api/v1/netlist'
 
 export const DEFAULT_PCB_SELECTION_PATH_PREFIX = '/api/v1/pcb-selection'
 
+export const DEFAULT_PCB_BOARD_PATH_PREFIX = '/api/v1/pcb-board'
+
 export const DEFAULT_HOST_PATH_PREFIX = '/api/v1/host'
 
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
@@ -58,6 +62,10 @@ export function resolveEdaHostConfig(
     config?.pcbSelectionPathPrefix ??
     env.HQ_EDGE_PCB_SELECTION_PATH ??
     DEFAULT_PCB_SELECTION_PATH_PREFIX
+  const pcbBoardPrefix =
+    config?.pcbBoardPathPrefix ??
+    env.HQ_EDGE_PCB_BOARD_PATH ??
+    DEFAULT_PCB_BOARD_PATH_PREFIX
   const hostPrefix =
     config?.hostPathPrefix ?? env.HQ_EDGE_HOST_PATH ?? DEFAULT_HOST_PATH_PREFIX
   const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS
@@ -66,6 +74,7 @@ export function resolveEdaHostConfig(
     hqEdgeBaseUrl: baseUrl,
     netlistPathPrefix: pathPrefix,
     pcbSelectionPathPrefix: pcbSelectionPrefix,
+    pcbBoardPathPrefix: pcbBoardPrefix,
     hostPathPrefix: hostPrefix,
     requestTimeoutMs:
       Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS,
@@ -94,6 +103,16 @@ export function pcbSelectionUrlOf(config: EdaHostConfig): string {
   return `${base}/${prefix}`
 }
 
+/** Build the absolute URL for the complete-board query route. */
+export function pcbBoardUrlOf(config: EdaHostConfig): string {
+  const base = (config.hqEdgeBaseUrl ?? '').replace(/\/+$/, '')
+  const prefix = (config.pcbBoardPathPrefix ?? DEFAULT_PCB_BOARD_PATH_PREFIX).replace(
+    /^\/+|\/+$/g,
+    '',
+  )
+  return `${base}/${prefix}`
+}
+
 /** Host discovery route suffix. */
 export type HostRoute = 'info' | 'capabilities'
 

package/src/index.ts

@@ -72,7 +72,7 @@ export type {
   PcbPad,
   PcbPoint,
   PcbSegment,
-  PcbSelection,
+  PcbSnapshot,
   PcbShape,
   PcbText,
   PcbTrack,
@@ -112,6 +112,32 @@ declare module '@deepseek-ai/cordis' {
 const COMPONENT = 'dsh-eda-host'
 const log = getLogger(COMPONENT)
 
+/**
+ * Env vars relevant to the hq-edge / DSH / KiCad integration, captured at
+ * plugin apply() time so startup issues are diagnosable from the log.
+ *
+ * Values are logged verbatim EXCEPT `KICAD_API_TOKEN`, which is a live
+ * credential KiCad injects for the IPC socket — only its presence is logged
+ * (never the token itself).
+ */
+const DSH_ENV_LOG_KEYS = [
+  'DSH_KICAD_PYTHON',
+  'DSH_KICAD_SKILLS_DIR',
+  'DSH_HOME',
+  'HQ_EDGE_BASE_URL',
+  'KICAD_API_SOCKET',
+  'KICAD_API_TOKEN',
+] as const
+
+function envSnapshot(): Record<string, string | null> {
+  const snapshot: Record<string, string | null> = {}
+  for (const key of DSH_ENV_LOG_KEYS) {
+    const value = process.env[key]
+    snapshot[key] = key === 'KICAD_API_TOKEN' ? (value ? '<set>' : null) : (value ?? null)
+  }
+  return snapshot
+}
+
 // Emitted on import, before any Cordis dependency is resolved. Pairs with the
 // "node half ready" marker in apply(): if this line is logged but that one is
 // not, the edge-bridge never provided `hqEdge` and this plugin is still
@@ -182,6 +208,7 @@ export function apply(ctx: Context, config: Partial<EdaHostConfig> = {}): () =>
     netlistPathPrefix: resolved.netlistPathPrefix,
     hostPathPrefix: resolved.hostPathPrefix,
     requestTimeoutMs: resolved.requestTimeoutMs,
+    env: envSnapshot(),
   })
 
   const client = createEdaHostClient(resolved, { baseUrlResolver: getHqEdgeBaseUrl })

package/src/tools.ts

@@ -24,7 +24,7 @@
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { EdaHostClient, EdaHostRequestOptions } from './client.js'
-import { NetlistError, type EdaHostCapability, type EdaHostInfo, type PcbSelection, type SchematicNetlist } from './types.js'
+import { NetlistError, type EdaHostCapability, type EdaHostInfo, type PcbSnapshot, type SchematicNetlist } from './types.js'
 
 /** Structural alias of the DSH `JsonValue`. */
 type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
@@ -63,7 +63,11 @@ type HostCapabilitiesResult =
   | { ok: false; error: { kind: string; message: string } }
 
 type PcbSelectionResult =
-  | { ok: true; selection: PcbSelection }
+  | { ok: true; selection: PcbSnapshot }
+  | { ok: false; error: { kind: string; message: string } }
+
+type PcbBoardResult =
+  | { ok: true; snapshot: PcbSnapshot }
   | { ok: false; error: { kind: string; message: string } }
 
 /**
@@ -179,6 +183,9 @@ export function createNetListTools(env: NetlistToolEnv) {
          `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". ` +
+         `When the host is KiCad, the executable list also carries "kicad-python" — the ` +
+         `interpreter bundled with KiCad that owns the official kicad-python package ` +
+         `(kipy); the dsh-kicad skills already run with it automatically. ` +
          `The returned information is authoritative host-provided ground truth. ` +
          ERROR_SEMANTICS,
        parameters: {},
@@ -226,6 +233,37 @@ export function createNetListTools(env: NetlistToolEnv) {
        },
      }),
 
+     defineTool({
+       name: 'get_pcb_board',
+       description:
+         `Read the COMPLETE semantic PCB board from the current PCB editor through hq-edge ` +
+         `(DSH → dsh-eda-host → hq-edge → EDA host). Returns { ok, snapshot: { footprints[], ` +
+         `pads[], tracks[], arcs[], vias[], zones[], shapes[], texts[], dimensions[], groups[], ` +
+         `nets[] } } — the same shape as get_pcb_selection, but covering every object on the ` +
+         `board regardless of selection. ` +
+         `Each footprint has reference, value, footprint, position {x,y} in mm, rotationDeg and ` +
+         `pads[] (pin, type, shape, position, widthMm, heightMm, rotationDeg, layer, net{name, ` +
+         `code}); tracks have layer, start/end in mm, widthMm, lengthMm and net; vias have ` +
+         `layers[], drillMm, viaType and start/end; zones have layer, net and outline segments. ` +
+         `Every object carries id — the EDA-host native object identity. ` +
+         `IMPORTANT: ok:true with all-empty arrays is a VALID empty board — do not treat it as ` +
+         `a failure. ` +
+         ERROR_SEMANTICS,
+       parameters: {},
+       output: { schema: { type: 'json' }, render: renderJson },
+       async execute(_args: unknown, exec: ToolExecLike): Promise<Json> {
+         try {
+           const options: EdaHostRequestOptions = exec?.signal
+             ? { signal: exec.signal }
+             : {}
+           const snapshot = await env.client.getPcbBoard(options)
+           return asJson<PcbBoardResult>({ ok: true, snapshot })
+         } catch (err) {
+           return asJson<PcbBoardResult>({ ok: false, error: failureOf(err) })
+         }
+       },
+     }),
+
      defineTool({
        name: 'get_eda_host_capabilities',
        description:

package/src/types.ts

@@ -55,12 +55,13 @@ export interface SchematicNetlist {
 }
 
 /**
- * Semantic PCB selection types.
+ * Semantic PCB snapshot types.
  *
  * Self-contained structural mirror of `hq.pcb.v1` (the hq-edge-owned semantic
- * protobuf contract for `PcbSelectionService.GetSelection`). Units follow the
- * hq.pcb.v1 convention: positions/sizes/lengths in mm, rotations in degrees,
- * `id` is the KiCad native object identity.
+ * protobuf contract for `PcbQueryService.GetSelection` / `GetBoard`). The
+ * same PcbSnapshot shape backs both the current selection and the complete
+ * board. Units follow the hq.pcb.v1 convention: positions/sizes/lengths in mm,
+ * rotations in degrees, `id` is the KiCad native object identity.
  */
 
 export interface PcbPoint {
@@ -172,7 +173,7 @@ export interface PcbGroup {
   itemIds: string[]
 }
 
-export interface PcbSelection {
+export interface PcbSnapshot {
   footprints: PcbFootprint[]
   pads: PcbPad[]
   tracks: PcbTrack[]