@huaqiu/dsh-eda-host 0.3.22 → 0.3.25

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 SchematicNetlist } from './types.js'
 
 /** Structural alias of the DSH `JsonValue`. */
 type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
@@ -48,24 +54,47 @@ 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 } }
+
+/**
+ * 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 +107,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 +120,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 +149,74 @@ 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_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

@@ -68,6 +68,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 +80,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
+}