@huaqiu/dsh-eda-host 0.3.22 → 0.3.25

package/src/client.ts

@@ -1,17 +1,20 @@
 /**
- * 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
  */
 
-import { netlistUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
+import { DEFAULT_REQUEST_TIMEOUT_MS, hostUrlOf, netlistUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
 import {
   NetlistError,
+  type EdaHostCapability,
+  type EdaHostInfo,
   type SchematicNetlist,
 } from './types.js'
 
@@ -29,49 +32,201 @@ export interface EdaHostClientDeps {
   baseUrlResolver?: () => string | undefined
 }
 
+/** Per-call options. `signal` lets DSH cancel a request (see §6 of the task). */
+export interface EdaHostRequestOptions {
+  signal?: AbortSignal
+}
+
 export 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[]>
 }
 
-/** 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: number): NetlistError['kind'] {
   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: unknown): boolean {
+  const name = (err as Error | undefined)?.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: number, caller?: AbortSignal): AbortSignal | undefined {
+  const budget = deadlineMs > 0 ? AbortSignal.timeout(deadlineMs) : undefined
+  const signals = [caller, budget].filter((s): s is AbortSignal => Boolean(s))
+  if (signals.length === 0) return undefined
+  if (signals.length === 1) return signals[0]
+  const anyFn = (AbortSignal as unknown as { any?: (s: AbortSignal[]) => 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".
+ */
+export function parseNetlistBody(body: unknown): SchematicNetlist {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    throw new NetlistError('INTERNAL', 'eda-host: malformed netlist response from hq-edge')
+  }
+
+  let candidate: unknown = (body as { netlist?: unknown }).netlist
+
+  if (
+    candidate &&
+    typeof candidate === 'object' &&
+    !Array.isArray(candidate) &&
+    (candidate as { components?: unknown }).components === undefined &&
+    typeof (candidate as { netlist?: unknown }).netlist === 'object'
+  ) {
+    // Legacy double-nested envelope — unwrap exactly one level.
+    candidate = (candidate as { netlist: unknown }).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 as { components?: unknown; nets?: unknown }
+
+  // proto3 JSON omits empty arrays, so `undefined` is a legitimate empty list.
+  if (components !== undefined && !Array.isArray(components)) {
+    throw new NetlistError('INTERNAL', 'eda-host: netlist.components is not an array')
+  }
+  if (nets !== undefined && !Array.isArray(nets)) {
+    throw new NetlistError('INTERNAL', 'eda-host: netlist.nets is not an array')
+  }
+
+  return {
+    components: (components ?? []) as SchematicNetlist['components'],
+    nets: (nets ?? []) as SchematicNetlist['nets'],
+  }
+}
+
+function str(value: unknown): string {
+  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.
+ */
+export function parseEdaHostInfo(value: unknown): EdaHostInfo {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new NetlistError('INTERNAL', 'eda-host: malformed host info response from hq-edge')
+  }
+
+  const raw = value as {
+    identity?: { hostType?: unknown; hostName?: unknown; version?: unknown }
+    installation?: { applicationPath?: unknown; executables?: unknown }
+  }
+
+  const executables = Array.isArray(raw.installation?.executables)
+    ? (raw.installation?.executables as unknown[])
+        .filter((e): e is Record<string, unknown> => 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 as EdaHostInfo['identity']['hostType'])
+          : 'EDA_HOST_TYPE_UNSPECIFIED',
+      hostName: str(raw.identity?.hostName),
+      version: str(raw.identity?.version),
+    },
+    installation: {
+      applicationPath: str(raw.installation?.applicationPath),
+      executables,
+    },
+  }
+}
+
 export function createEdaHostClient(
   config: EdaHostConfig,
   deps: EdaHostClientDeps = {},
 ): EdaHostClient {
   const fetchImpl = deps.fetchImpl ?? globalThis.fetch
 
-  async function fetchScope(scope: NetlistScope): Promise<SchematicNetlist> {
-    // 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.
-    const baseUrl = deps.baseUrlResolver?.()?.trim()
-      ?? config.hqEdgeBaseUrl?.trim()
-      ?? ''
+  /**
+   * 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(): EdaHostConfig {
+    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.',
+        'eda-host: no hq-edge base URL configured (ctx.hqEdge.baseUrl / hqEdgeBaseUrl / ' +
+          'HQ_EDGE_BASE_URL) — EDA host tools require the hq-edge bridge.',
       )
     }
-    const url = netlistUrlOf({ ...config, hqEdgeBaseUrl: baseUrl }, scope)
+    return { ...config, hqEdgeBaseUrl: baseUrl }
+  }
+
+  /** Perform one GET and return the parsed JSON body, mapping failures. */
+  async function getJson(
+    url: string,
+    options: EdaHostRequestOptions | undefined,
+    what: string,
+  ): Promise<unknown> {
+    const signal = resolveSignal(config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, options?.signal)
 
     let response: Response
     try {
-      response = await fetchImpl(url, { method: 'GET', headers: { Accept: 'application/json' } })
+      response = await fetchImpl(url, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+        ...(signal ? { signal } : {}),
+      })
     } catch (err) {
+      // An aborted request is a timeout, never an empty result.
+      if (isAbortError(err)) {
+        throw new NetlistError(
+          'DEADLINE_EXCEEDED',
+          `eda-host: ${what} request exceeded its time budget at ${url}`,
+        )
+      }
       // Connection-level failure: host not running / unreachable.
       throw new NetlistError(
         'UNAVAILABLE',
@@ -89,25 +244,54 @@ export function createEdaHostClient(
       }
       throw new NetlistError(
         statusToKind(response.status),
-        `eda-host: netlist request failed (${response.status}${detail ? `: ${detail}` : ''})`,
+        `eda-host: ${what} request failed (${response.status}${detail ? `: ${detail}` : ''})`,
       )
     }
 
-    // Valid (possibly empty) result: { netlist: { components, nets } }.
-    const body = (await response.json()) as { netlist?: SchematicNetlist }
-    if (!body || typeof body.netlist !== 'object' || body.netlist === null) {
-      throw new NetlistError('INTERNAL', 'eda-host: malformed netlist response from hq-edge')
-    }
+    return response.json()
+  }
 
-    const netlist = body.netlist
-    netlist.components ??= []
-    netlist.nets ??= []
-    return netlist
+  async function fetchScope(
+    scope: NetlistScope,
+    options?: EdaHostRequestOptions,
+  ): Promise<SchematicNetlist> {
+    const resolved = resolveConfig()
+    const url = netlistUrlOf(resolved, scope)
+    return parseNetlistBody(await getJson(url, 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 resolved = resolveConfig()
+      const url = hostUrlOf(resolved, 'info')
+      const body = (await getJson(url, options, 'host info')) as { info?: unknown }
+
+      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 resolved = resolveConfig()
+      const url = hostUrlOf(resolved, 'capabilities')
+      const body = (await getJson(url, options, 'host capabilities')) as {
+        capabilities?: unknown
+      }
+
+      if (!body || !Array.isArray(body.capabilities)) {
+        throw new NetlistError(
+          'INTERNAL',
+          'eda-host: malformed host capabilities response from hq-edge',
+        )
+      }
+      return body.capabilities.filter(
+        (c): c is EdaHostCapability => typeof c === 'string',
+      )
+    },
   }
 }

package/src/config.ts

@@ -15,10 +15,25 @@ export 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
 }
 
 export const DEFAULT_NETLIST_PATH_PREFIX = '/api/v1/netlist'
 
+export const DEFAULT_HOST_PATH_PREFIX = '/api/v1/host'
+
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
+
 /** Scope → route suffix on the host netlist router. */
 export type NetlistScope = 'project' | 'selection' | 'active-page'
 
@@ -35,9 +50,16 @@ export function resolveEdaHostConfig(
   const baseUrl = config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? ''
   const pathPrefix =
     config?.netlistPathPrefix ?? env.HQ_EDGE_NETLIST_PATH ?? DEFAULT_NETLIST_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
+  const timeout = Number.parseInt(String(timeoutRaw ?? ''), 10)
   return {
     hqEdgeBaseUrl: baseUrl,
     netlistPathPrefix: pathPrefix,
+    hostPathPrefix: hostPrefix,
+    requestTimeoutMs:
+      Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS,
   }
 }
 
@@ -52,3 +74,18 @@ export function netlistUrlOf(config: EdaHostConfig, scope: NetlistScope): string
   const prefix = (config.netlistPathPrefix ?? DEFAULT_NETLIST_PATH_PREFIX).replace(/^\/+|\/+$/g, '')
   return `${base}/${prefix}${SCOPE_ROUTE[scope]}`
 }
+
+/** Host discovery route suffix. */
+export type HostRoute = 'info' | 'capabilities'
+
+const HOST_ROUTE: Record<HostRoute, string> = {
+  info: '/info',
+  capabilities: '/capabilities',
+}
+
+/** Build the absolute URL for one host discovery route. */
+export function hostUrlOf(config: EdaHostConfig, route: HostRoute): string {
+  const base = (config.hqEdgeBaseUrl ?? '').replace(/\/+$/, '')
+  const prefix = (config.hostPathPrefix ?? DEFAULT_HOST_PATH_PREFIX).replace(/^\/+|\/+$/g, '')
+  return `${base}/${prefix}${HOST_ROUTE[route]}`
+}

package/src/index.ts

@@ -2,11 +2,13 @@
  * `@huaqiu/dsh-eda-host` — node plugin entry.
  *
  * Provides the `edaHost` service (semantic EDA-host capability) and registers
- * three agent tools:
+ * five agent tools:
  *
  *   get_project_netlist      complete project netlist
  *   get_selection_netlist    currently selected components netlist
  *   get_active_page_netlist  active schematic page netlist
+ *   get_eda_host_info        which EDA host, version, installation
+ *   get_eda_host_capabilities  what the current host can actually do
  *
  * ── Architectural boundary (task: add-dsh-eda-host) ─────────────────────────
  * The ONLY production request path is DSH → dsh-eda-host → hq-edge → EDA host.
@@ -26,7 +28,7 @@ import type { Context } from '@deepseek-ai/cordis'
 import { getLogger } from '@huaqiu/dsh-plugin-log'
 import { createEdaHostClient, type EdaHostClient } from './client.js'
 import { hasHost, resolveEdaHostConfig, type EdaHostConfig } from './config.js'
-import { createNetListTools } from './tools.js'
+import { createEdaHostTools, createNetListTools } from './tools.js'
 
 /** Plugin id — matches package.json. */
 export const name = '@huaqiu/dsh-eda-host'
@@ -50,8 +52,14 @@ export const name = '@huaqiu/dsh-eda-host'
 export const inject = ['hqEdge', 'tools'] as const
 
 export type { EdaHostConfig } from './config.js'
-export type { EdaHostClient } from './client.js'
+export type { EdaHostClient, EdaHostRequestOptions } from './client.js'
 export type {
+  EdaHostCapability,
+  EdaHostExecutable,
+  EdaHostIdentity,
+  EdaHostInfo,
+  EdaHostInstallation,
+  EdaHostType,
   ElectricalNet,
   ElectricalType,
   NetlistErrorKind,
@@ -61,6 +69,7 @@ export type {
   SchematicNetlist,
 } from './types.js'
 export { NetlistError } from './types.js'
+export { parseNetlistBody } from './client.js'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -88,6 +97,12 @@ declare module '@deepseek-ai/cordis' {
 const COMPONENT = 'dsh-eda-host'
 const log = getLogger(COMPONENT)
 
+// 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
+// pending — which is otherwise completely silent.
+log.info('dsh-eda-host: module loaded (waiting for the hqEdge + tools services)')
+
 /**
  * Host plugin body — provide `edaHost` and register the three netlist tools.
  *
@@ -113,30 +128,61 @@ export function apply(ctx: Context, config: Partial<EdaHostConfig> = {}): () =>
 
   const resolved = resolveEdaHostConfig(config)
 
+  // ── Explicit bridge dependency ───────────────────────────────────────────
+  // `hqEdge` is a REQUIRED inject, so Cordis only calls `apply()` once the
+  // edge-bridge has provided it. That means a missing bridge would otherwise
+  // leave this plugin pending forever with the tools never registered and
+  // nothing logged. Two things make that diagnosable:
+  //
+  //   1. `apply()` asserts the bridge actually gave us a usable endpoint and
+  //      THROWS when it did not — a loud startup failure beats five tools that
+  //      fail one by one at call time.
+  //   2. The module-level marker below is emitted on import. If
+  //      "dsh-eda-host: module loaded" appears in the log but
+  //      "dsh-eda-host: node half ready" never does, the bridge never provided
+  //      `hqEdge` and this plugin is still pending.
+  //
+  // hq-edge is NOT optional here — this plugin must never become a standalone
+  // DSH plugin (docs/tasks/expose-capability.md §3, §7).
+  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.',
+    )
+  }
+
   // Late-bound host endpoint: prefer the edge-bridge service, then the overlay
   // config / env value. Consulted on every request (see client.ts).
   const getHqEdgeBaseUrl = (): string | undefined => {
-    const hq = ctx.hqEdge
-    return hq?.baseUrl && hq.baseUrl.trim().length > 0 ? hq.baseUrl : undefined
+    const current = ctx.hqEdge
+    return current?.baseUrl && current.baseUrl.trim().length > 0 ? current.baseUrl : undefined
   }
 
   log.info('applying dsh-eda-host node half', {
     hasConfigHost: hasHost(resolved),
     hqEdgeBaseUrlFromConfig: resolved.hqEdgeBaseUrl ?? null,
     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: Array<() => void> = []
   for (const tool of tools) {
     disposers.push(ctx.tools.register(tool))
   }
 
-  log.info('dsh-eda-host node half ready', { tools: 3, configHostMode: hasHost(resolved) })
+  log.info('dsh-eda-host node half ready', {
+    tools: tools.length,
+    configHostMode: hasHost(resolved),
+  })
 
   return () => {
     for (const dispose of disposers) {