@huaqiu/dsh-eda-host 0.3.24 → 0.4.1

package/src/tools.ts

@@ -1,24 +1,30 @@
 /**
  * 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
  */
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { EdaHostClient } from './client.js'
-import { NetlistError, type SchematicNetlist } from './types.js'
+import type { EdaHostClient, EdaHostRequestOptions } from './client.js'
+import { NetlistError, type EdaHostCapability, type EdaHostInfo, type PcbSelection, type SchematicNetlist } from './types.js'
 
 /** Structural alias of the DSH `JsonValue`. */
 type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
@@ -48,24 +54,51 @@ type ScopeResult =
   | { ok: true; scope: NetlistScopeKind; netlist: SchematicNetlist }
   | { ok: false; scope: NetlistScopeKind; error: { kind: string; message: string } }
 
+type HostInfoResult =
+  | { ok: true; info: EdaHostInfo }
+  | { ok: false; error: { kind: string; message: string } }
+
+type HostCapabilitiesResult =
+  | { ok: true; capabilities: EdaHostCapability[] }
+  | { ok: false; error: { kind: string; message: string } }
+
+type PcbSelectionResult =
+  | { ok: true; selection: PcbSelection }
+  | { ok: false; error: { kind: string; message: string } }
+
+/**
+ * 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: unknown): { kind: string; message: string } {
+  const kind = err instanceof NetlistError ? err.kind : ('INTERNAL' as const)
+  return { kind, message: String((err as Error)?.message ?? err) }
+}
+
 async function runScope(
   env: NetlistToolEnv,
   scope: NetlistScopeKind,
+  exec?: ToolExecLike,
 ): Promise<ScopeResult> {
+  const options: EdaHostRequestOptions = exec?.signal ? { signal: exec.signal } : {}
   try {
     let netlist: SchematicNetlist
-    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, netlist }
   } catch (err) {
-    const kind =
-      err instanceof NetlistError
-        ? err.kind
-        : ('INTERNAL' as const)
-    const message = String((err as Error)?.message ?? err)
-    return { ok: false, scope, error: { kind, message } }
+    return { ok: false, scope, error: failureOf(err) }
   }
 }
 
@@ -78,12 +111,9 @@ function scopeDescription(scope: NetlistScopeKind, extra: string): string {
     `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.`
+    `IMPORTANT: ok:true with empty components/nets is a VALID empty design — do not ` +
+    `treat it as a failure. ` +
+    ERROR_SEMANTICS
   )
 }
 
@@ -94,8 +124,8 @@ export function createNetListTools(env: NetlistToolEnv) {
       description: desc,
       parameters: {},
       output: { schema: { type: 'json' }, render: renderJson },
-      async execute(_args: unknown, _exec: ToolExecLike) {
-        return asJson(await runScope(env, scope))
+      async execute(_args: unknown, exec: ToolExecLike) {
+        return asJson(await runScope(env, scope, exec))
       },
     })
 
@@ -123,9 +153,104 @@ export function createNetListTools(env: NetlistToolEnv) {
       '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".',
+        '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.
+  */
+ export function createEdaHostTools(env: NetlistToolEnv) {
+   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: unknown, exec: ToolExecLike): Promise<Json> {
+         try {
+           const options: EdaHostRequestOptions = exec?.signal
+             ? { signal: exec.signal }
+             : {}
+           const info = await env.client.getEdaHostInfo(options)
+           return asJson<HostInfoResult>({ ok: true, info })
+         } catch (err) {
+           return asJson<HostInfoResult>({ ok: false, error: failureOf(err) })
+         }
+       },
+     }),
+
+     defineTool({
+       name: 'get_pcb_selection',
+       description:
+         `Read the semantic PCB selection from the current PCB editor through hq-edge ` +
+         `(DSH → dsh-eda-host → hq-edge → EDA host). Returns { ok, selection: { footprints[], ` +
+         `pads[], tracks[], arcs[], vias[], zones[], shapes[], texts[], dimensions[], groups[], ` +
+         `nets[] } }. ` +
+         `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 selection (nothing selected) ` +
+         `— 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 selection = await env.client.getPcbSelection(options)
+           return asJson<PcbSelectionResult>({ ok: true, selection })
+         } catch (err) {
+           return asJson<PcbSelectionResult>({ 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: unknown, exec: ToolExecLike): Promise<Json> {
+         try {
+           const options: EdaHostRequestOptions = exec?.signal
+             ? { signal: exec.signal }
+             : {}
+           const capabilities = await env.client.getEdaHostCapabilities(options)
+           return asJson<HostCapabilitiesResult>({ ok: true, capabilities })
+         } catch (err) {
+           return asJson<HostCapabilitiesResult>({ ok: false, error: failureOf(err) })
+         }
+       },
+     }),
+   ]
+ }

package/src/types.ts

@@ -54,6 +54,138 @@ export interface SchematicNetlist {
   nets: ElectricalNet[]
 }
 
+/**
+ * Semantic PCB selection 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.
+ */
+
+export interface PcbPoint {
+  x: number
+  y: number
+}
+
+export interface PcbNetRef {
+  name: string
+  code: number
+}
+
+export interface PcbPad {
+  id: string
+  pin: string
+  type: string
+  shape: string
+  position?: PcbPoint
+  widthMm: number
+  heightMm: number
+  rotationDeg: number
+  layer: string
+  net?: PcbNetRef
+}
+
+export interface PcbFootprint {
+  id: string
+  reference: string
+  value: string
+  footprint: string
+  position?: PcbPoint
+  rotationDeg: number
+  pads: PcbPad[]
+}
+
+export interface PcbTrack {
+  id: string
+  layer: string
+  start?: PcbPoint
+  end?: PcbPoint
+  widthMm: number
+  lengthMm: number
+  net?: PcbNetRef
+}
+
+export interface PcbArc {
+  id: string
+  layer: string
+  start?: PcbPoint
+  end?: PcbPoint
+  mid?: PcbPoint
+  net?: PcbNetRef
+}
+
+export interface PcbVia {
+  id: string
+  layers: string[]
+  drillMm: number
+  viaType: string
+  start?: PcbPoint
+  end?: PcbPoint
+}
+
+export interface PcbSegment {
+  start?: PcbPoint
+  end?: PcbPoint
+}
+
+export interface PcbZone {
+  id: string
+  layer: string
+  net?: PcbNetRef
+  outline: PcbSegment[]
+}
+
+export interface PcbShape {
+  id: string
+  layer: string
+  shapeType: string
+  start?: PcbPoint
+  end?: PcbPoint
+  center?: PcbPoint
+  radiusMm: number
+  mid?: PcbPoint
+  widthMm: number
+}
+
+export interface PcbText {
+  id: string
+  layer: string
+  text: string
+  position?: PcbPoint
+  rotationDeg: number
+  hJustify: string
+  vJustify: string
+}
+
+export interface PcbDimension {
+  id: string
+  layer: string
+  start?: PcbPoint
+  end?: PcbPoint
+  value: string
+  dimType: string
+}
+
+export interface PcbGroup {
+  id: string
+  itemIds: string[]
+}
+
+export interface PcbSelection {
+  footprints: PcbFootprint[]
+  pads: PcbPad[]
+  tracks: PcbTrack[]
+  arcs: PcbArc[]
+  vias: PcbVia[]
+  zones: PcbZone[]
+  shapes: PcbShape[]
+  texts: PcbText[]
+  dimensions: PcbDimension[]
+  groups: PcbGroup[]
+  nets: PcbNetRef[]
+}
+
 /**
  * Semantic error categories for netlist retrieval. Mirrors the gRPC status
  * contract of `hq.ir.schematic.v1.NetListService` so an agent can distinguish
@@ -68,6 +200,8 @@ export type NetlistErrorKind =
   | 'INTERNAL'
   /** Host unavailable (connection refused). */
   | 'UNAVAILABLE'
+  /** The host did not answer within the request budget. */
+  | 'DEADLINE_EXCEEDED'
 
 export class NetlistError extends Error {
   readonly kind: NetlistErrorKind
@@ -78,3 +212,93 @@ export class NetlistError extends Error {
     this.kind = kind
   }
 }
+
+// ---------------------------------------------------------------------------
+// EDA host discovery — structural mirror of `hq.host.v1`
+// ---------------------------------------------------------------------------
+
+/**
+ * `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.
+ */
+export 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.
+ */
+export 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. */
+export 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. */
+export 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. */
+export 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.
+ */
+export interface EdaHostInfo {
+  identity: EdaHostIdentity
+  installation: EdaHostInstallation
+}