@zenalexa/unicli 0.220.0 → 0.221.0

package/src/adapters/epo/family.yaml

@@ -0,0 +1,69 @@
+# @owner       src::adapters::epo::family
+# @does        Fetch INPADOC simple family for a publication via EPO Open Patent Services v3.2.
+# @needs       src/engine/steps/oauth2-token.ts, src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on token failure, 404, 401/403, 5xx
+# @invariants  output rows are family members in PatentRecord shape with `family_id` populated
+# @side-effects reads EPO OAuth2 credentials; HTTPS to ops.epo.org
+# @perf        two HTTPS requests
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: epo
+name: family
+description: INPADOC simple family for an EPO publication
+domain: ops.epo.org
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  publication_number:
+    type: str
+    required: true
+    positional: true
+    description: Publication number in epodoc format
+
+pipeline:
+  - oauth2-token:
+      site: epo
+      token_url: https://ops.epo.org/3.2/auth/accesstoken
+      client_id_env: EPO_OPS_CLIENT_ID
+      client_secret_env: EPO_OPS_CLIENT_SECRET
+
+  - fetch:
+      url: "https://ops.epo.org/3.2/rest-services/family/publication/epodoc/${{ args.publication_number | urlencode }}"
+      method: GET
+      headers:
+        Authorization: "Bearer ${{ auth.bearer || '' }}"
+        Accept: application/xml
+
+  - select-xml:
+      xpath: "//ops:family-member"
+      namespaces:
+        ops: "http://ops.epo.org"
+
+  # Family endpoint returns ops:family-member nodes with publication-reference,
+  # application-reference, and a `@family-id` attribute on each.
+  - map:
+      publication_number: "${{ ((item['publication-reference'] && item['publication-reference']['document-id']) ? (item['publication-reference']['document-id'].country + '-' + item['publication-reference']['document-id']['doc-number'] + '-' + (item['publication-reference']['document-id'].kind || '')) : '') }}"
+      application_number: "${{ ((item['application-reference'] && item['application-reference']['document-id']) ? (item['application-reference']['document-id'].country + '-' + item['application-reference']['document-id']['doc-number'] + '-' + (item['application-reference']['document-id'].kind || '')) : '') }}"
+      kind_code: "${{ (item['publication-reference'] && item['publication-reference']['document-id']) ? (item['publication-reference']['document-id'].kind || '') : '' }}"
+      publication_date: "${{ (function(d){ if(!d) return ''; var s=String(d); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; })((item['publication-reference'] && item['publication-reference']['document-id']) ? item['publication-reference']['document-id'].date : '') }}"
+      filing_date: "${{ (function(d){ if(!d) return ''; var s=String(d); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; })((item['application-reference'] && item['application-reference']['document-id']) ? item['application-reference']['document-id'].date : '') }}"
+      family_id: "${{ item['@_family-id'] || '' }}"
+      source_adapter: epo
+      source_url: "${{ 'https://worldwide.espacenet.com/patent/search/family/' + (item['@_family-id'] || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, family_id]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.family"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/epo/get.yaml

@@ -0,0 +1,74 @@
+# @owner       src::adapters::epo::get
+# @does        Fetch DOCDB biblio for a single EPO publication number via Open Patent Services v3.2.
+# @needs       src/engine/steps/oauth2-token.ts, src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on token failure, 404 (unknown publication), 401/403, 5xx
+# @invariants  output row conforms to PatentRecord
+# @side-effects reads EPO OAuth2 credentials; HTTPS to ops.epo.org
+# @perf        two HTTPS requests (token + data); cached token
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: epo
+name: get
+description: Fetch EPO DOCDB biblio for a single publication number
+domain: ops.epo.org
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  publication_number:
+    type: str
+    required: true
+    positional: true
+    description: Publication number in epodoc format (e.g. EP.4123456.A1 or US.20240123456.A1)
+
+pipeline:
+  - oauth2-token:
+      site: epo
+      token_url: https://ops.epo.org/3.2/auth/accesstoken
+      client_id_env: EPO_OPS_CLIENT_ID
+      client_secret_env: EPO_OPS_CLIENT_SECRET
+
+  - fetch:
+      url: "https://ops.epo.org/3.2/rest-services/published-data/publication/epodoc/${{ args.publication_number | urlencode }}/biblio"
+      method: GET
+      headers:
+        Authorization: "Bearer ${{ auth.bearer || '' }}"
+        Accept: application/xml
+
+  - select-xml:
+      xpath: "//ops:exchange-document"
+      namespaces:
+        ops: "http://ops.epo.org"
+
+  # Same DOCDB envelope as search; richer biblio fields are present.
+  - map:
+      publication_number: "${{ ((item['bibliographic-data'] && item['bibliographic-data']['publication-reference'] && item['bibliographic-data']['publication-reference']['document-id']) ? (item['bibliographic-data']['publication-reference']['document-id'].country + '-' + item['bibliographic-data']['publication-reference']['document-id']['doc-number'] + '-' + (item['bibliographic-data']['publication-reference']['document-id'].kind || '')) : (args.publication_number || '')) }}"
+      application_number: "${{ ((item['bibliographic-data'] && item['bibliographic-data']['application-reference'] && item['bibliographic-data']['application-reference']['document-id']) ? (item['bibliographic-data']['application-reference']['document-id'].country + '-' + item['bibliographic-data']['application-reference']['document-id']['doc-number'] + '-' + (item['bibliographic-data']['application-reference']['document-id'].kind || '')) : '') }}"
+      title: "${{ (function(t){ if(!t) return ''; if(Array.isArray(t)){ var en=t.find(x=>x['@_lang']==='en'); return en ? (en['#text']||en) : (t[0]['#text']||t[0]); } return t['#text']||t; })(item['bibliographic-data'] ? item['bibliographic-data']['invention-title'] : null) }}"
+      abstract: "${{ (function(a){ if(!a) return ''; if(Array.isArray(a)){ var en=a.find(x=>x['@_lang']==='en'); return en ? ((en.p ? (en.p['#text']||en.p) : (en['#text']||en))) : ''; } return a.p ? (a.p['#text']||a.p) : (a['#text']||a); })(item.abstract) }}"
+      kind_code: "${{ (item['bibliographic-data'] && item['bibliographic-data']['publication-reference'] && item['bibliographic-data']['publication-reference']['document-id']) ? (item['bibliographic-data']['publication-reference']['document-id'].kind || '') : '' }}"
+      publication_date: "${{ (function(d){ if(!d) return ''; var s=String(d); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; })((item['bibliographic-data'] && item['bibliographic-data']['publication-reference'] && item['bibliographic-data']['publication-reference']['document-id']) ? item['bibliographic-data']['publication-reference']['document-id'].date : '') }}"
+      filing_date: "${{ (function(d){ if(!d) return ''; var s=String(d); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; })((item['bibliographic-data'] && item['bibliographic-data']['application-reference'] && item['bibliographic-data']['application-reference']['document-id']) ? item['bibliographic-data']['application-reference']['document-id'].date : '') }}"
+      priority_date: "${{ (function(){ var pc = item['bibliographic-data'] && item['bibliographic-data']['priority-claims']; if(!pc || !pc['priority-claim']) return ''; var arr = Array.isArray(pc['priority-claim']) ? pc['priority-claim'] : [pc['priority-claim']]; for (var i=0;i<arr.length;i++){ var did = arr[i]['document-id']; if(Array.isArray(did)){ for (var j=0;j<did.length;j++){ if(did[j].date){ var s=String(did[j].date); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; } } } else if(did && did.date){ var s=String(did.date); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; } } return ''; })() }}"
+      inventors: "${{ JSON.stringify((function(){ var p=item['bibliographic-data'] && item['bibliographic-data'].parties; if(!p || !p.inventors || !p.inventors.inventor) return []; var arr = Array.isArray(p.inventors.inventor) ? p.inventors.inventor : [p.inventors.inventor]; return arr.map(i => ({ name: (i['inventor-name'] && (i['inventor-name'].name || i['inventor-name']['#text'])) || '' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var p=item['bibliographic-data'] && item['bibliographic-data'].parties; if(!p || !p.applicants || !p.applicants.applicant) return []; var arr = Array.isArray(p.applicants.applicant) ? p.applicants.applicant : [p.applicants.applicant]; return arr.map(i => ({ name: (i['applicant-name'] && (i['applicant-name'].name || i['applicant-name']['#text'])) || '' })).filter(x => x.name); })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var bd = item['bibliographic-data']; if(!bd) return []; var out = []; var ipcr = bd['classifications-ipcr'] && bd['classifications-ipcr']['classification-ipcr']; if(ipcr){ var arr = Array.isArray(ipcr) ? ipcr : [ipcr]; for (var i=0;i<arr.length;i++) out.push({ scheme: 'ipc', code: arr[i].text || arr[i]['#text'] || '' }); } var pc = bd['patent-classifications'] && bd['patent-classifications']['patent-classification']; if(pc){ var arr2 = Array.isArray(pc) ? pc : [pc]; for (var i=0;i<arr2.length;i++){ var c=arr2[i]; var scheme=(c['classification-scheme'] && (c['classification-scheme']['@_scheme']||'')).toLowerCase()||'cpc'; var section=(c.section||'')+(c.class||'')+(c.subclass||''); var main=(c['main-group']||'')+(c['subgroup']?'/'+c.subgroup:''); out.push({ scheme: scheme, code: (section+main) }); } } return out.filter(x => x.code); })()) }}"
+      family_id: "${{ item['@_family-id'] || '' }}"
+      source_adapter: epo
+      source_url: "${{ 'https://worldwide.espacenet.com/patent/search/publication/' + (args.publication_number || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, title]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.get"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/epo/legal-status.yaml

@@ -0,0 +1,63 @@
+# @owner       src::adapters::epo::legal-status
+# @does        Fetch INPADOC legal-status events for a publication via EPO Open Patent Services v3.2.
+# @needs       src/engine/steps/oauth2-token.ts, src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on token failure, 404, 401/403, 5xx
+# @invariants  output rows are legal-status events in PatentRecord shape; legal_status holds the latest event code/description
+# @side-effects reads EPO OAuth2 credentials; HTTPS to ops.epo.org
+# @perf        two HTTPS requests
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: epo
+name: legal-status
+description: INPADOC legal-status events for an EPO publication
+domain: ops.epo.org
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  publication_number:
+    type: str
+    required: true
+    positional: true
+    description: Publication number in epodoc format
+
+pipeline:
+  - oauth2-token:
+      site: epo
+      token_url: https://ops.epo.org/3.2/auth/accesstoken
+      client_id_env: EPO_OPS_CLIENT_ID
+      client_secret_env: EPO_OPS_CLIENT_SECRET
+
+  - fetch:
+      url: "https://ops.epo.org/3.2/rest-services/legal/publication/epodoc/${{ args.publication_number | urlencode }}"
+      method: GET
+      headers:
+        Authorization: "Bearer ${{ auth.bearer || '' }}"
+        Accept: application/xml
+
+  - select-xml:
+      xpath: "//ops:legal"
+      namespaces:
+        ops: "http://ops.epo.org"
+
+  - map:
+      publication_number: "${{ args.publication_number || '' }}"
+      legal_status: "${{ (item['legal-event-code'] || '') + ' ' + (item['L007EP'] || item['L008EP'] || '') }}"
+      source_adapter: epo
+      source_url: "${{ 'https://worldwide.espacenet.com/patent/search/publication/' + (args.publication_number || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, legal_status]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.legal-status"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/epo/search.yaml

@@ -0,0 +1,84 @@
+# @owner       src::adapters::epo::search
+# @does        Search EPO Open Patent Services v3.2 published-data via CQL — returns DOCDB exchange-document records (St.36 XML).
+# @needs       src/engine/steps/oauth2-token.ts, src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts, src/engine/steps/limit.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on token-endpoint failure, 401/403 (auth) or 5xx; EPO OPS rate-limits free tier at 4 GB/week
+# @invariants  output rows conform to PatentRecord; publication_number is canonicalized to `<CC>-<doc>-<kind>`
+# @side-effects reads env EPO_OPS_CLIENT_ID / EPO_OPS_CLIENT_SECRET (or ~/.unicli/auth/epo.json); HTTPS to ops.epo.org
+# @perf        two HTTPS requests per call (token + data); token is cached via oauth2-cc broker
+# @concurrency safe; token cache deduplicates concurrent token fetches
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs EPO_OPS_CLIENT_ID / EPO_OPS_CLIENT_SECRET (free tier at developers.epo.org)
+site: epo
+name: search
+description: Search EPO published patents via Open Patent Services v3.2 (CQL)
+domain: ops.epo.org
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: EPO CQL query (e.g. "ti=quantum and pa=ibm")
+  limit:
+    type: int
+    default: 25
+    description: Maximum results (OPS caps at 100 per page)
+
+pipeline:
+  - oauth2-token:
+      site: epo
+      token_url: https://ops.epo.org/3.2/auth/accesstoken
+      client_id_env: EPO_OPS_CLIENT_ID
+      client_secret_env: EPO_OPS_CLIENT_SECRET
+
+  - fetch:
+      url: "https://ops.epo.org/3.2/rest-services/published-data/search?q=${{ args.query | urlencode }}&Range=1-${{ args.limit }}"
+      method: GET
+      headers:
+        Authorization: "Bearer ${{ auth.bearer || '' }}"
+        Accept: application/xml
+
+  - select-xml:
+      xpath: "//ops:exchange-document"
+      namespaces:
+        ops: "http://ops.epo.org"
+        exchange: "http://www.epo.org/exchange"
+
+  # Field mapping references the OPS v3.2 DOCDB schema (docs.epo.org).
+  # Every path below is a documented DOCDB element; arrays are JSON-serialised
+  # so they survive the template engine's string projection.
+  - map:
+      publication_number: "${{ ((item['bibliographic-data'] && item['bibliographic-data']['publication-reference'] && item['bibliographic-data']['publication-reference']['document-id']) ? (item['bibliographic-data']['publication-reference']['document-id'].country + '-' + item['bibliographic-data']['publication-reference']['document-id']['doc-number'] + '-' + (item['bibliographic-data']['publication-reference']['document-id'].kind || '')) : '') }}"
+      application_number: "${{ ((item['bibliographic-data'] && item['bibliographic-data']['application-reference'] && item['bibliographic-data']['application-reference']['document-id']) ? (item['bibliographic-data']['application-reference']['document-id'].country + '-' + item['bibliographic-data']['application-reference']['document-id']['doc-number'] + '-' + (item['bibliographic-data']['application-reference']['document-id'].kind || '')) : '') }}"
+      # DOCDB renders invention-title as one element per language; prefer EN.
+      title: "${{ (function(t){ if(!t) return ''; if(Array.isArray(t)){ var en=t.find(x=>x['@_lang']==='en'); return en ? (en['#text']||en) : (t[0]['#text']||t[0]); } return t['#text']||t; })(item['bibliographic-data'] ? item['bibliographic-data']['invention-title'] : null) }}"
+      abstract: "${{ (function(a){ if(!a) return ''; if(Array.isArray(a)){ var en=a.find(x=>x['@_lang']==='en'); return en ? ((en.p ? (en.p['#text']||en.p) : (en['#text']||en))) : ''; } return a.p ? (a.p['#text']||a.p) : (a['#text']||a); })(item.abstract) }}"
+      kind_code: "${{ (item['bibliographic-data'] && item['bibliographic-data']['publication-reference'] && item['bibliographic-data']['publication-reference']['document-id']) ? (item['bibliographic-data']['publication-reference']['document-id'].kind || '') : '' }}"
+      publication_date: "${{ (function(d){ if(!d) return ''; var s=String(d); return s.length===8 ? (s.slice(0,4)+'-'+s.slice(4,6)+'-'+s.slice(6,8)) : s; })((item['bibliographic-data'] && item['bibliographic-data']['publication-reference'] && item['bibliographic-data']['publication-reference']['document-id']) ? item['bibliographic-data']['publication-reference']['document-id'].date : '') }}"
+      # DOCDB `parties.inventors.inventor[]` carries `inventor-name.name`.
+      inventors: "${{ JSON.stringify((function(){ var p=item['bibliographic-data'] && item['bibliographic-data'].parties; if(!p || !p.inventors || !p.inventors.inventor) return []; var arr = Array.isArray(p.inventors.inventor) ? p.inventors.inventor : [p.inventors.inventor]; return arr.map(i => ({ name: (i['inventor-name'] && (i['inventor-name'].name || i['inventor-name']['#text'])) || '' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var p=item['bibliographic-data'] && item['bibliographic-data'].parties; if(!p || !p.applicants || !p.applicants.applicant) return []; var arr = Array.isArray(p.applicants.applicant) ? p.applicants.applicant : [p.applicants.applicant]; return arr.map(i => ({ name: (i['applicant-name'] && (i['applicant-name'].name || i['applicant-name']['#text'])) || '' })).filter(x => x.name); })()) }}"
+      # `classifications-ipcr.classification-ipcr[].text` is IPC; `patent-classifications.patent-classification[]` is CPC + others.
+      classifications: "${{ JSON.stringify((function(){ var bd = item['bibliographic-data']; if(!bd) return []; var out = []; var ipcr = bd['classifications-ipcr'] && bd['classifications-ipcr']['classification-ipcr']; if(ipcr){ var arr = Array.isArray(ipcr) ? ipcr : [ipcr]; for (var i=0;i<arr.length;i++) out.push({ scheme: 'ipc', code: arr[i].text || arr[i]['#text'] || '' }); } var pc = bd['patent-classifications'] && bd['patent-classifications']['patent-classification']; if(pc){ var arr2 = Array.isArray(pc) ? pc : [pc]; for (var i=0;i<arr2.length;i++){ var c=arr2[i]; var scheme=(c['classification-scheme'] && (c['classification-scheme']['@_scheme']||'')).toLowerCase()||'cpc'; var section=(c.section||'')+(c.class||'')+(c.subclass||''); var main=(c['main-group']||'')+(c['subgroup']?'/'+c.subgroup:''); out.push({ scheme: scheme, code: (section+main) }); } } return out.filter(x => x.code); })()) }}"
+      family_id: "${{ item['@_family-id'] || '' }}"
+      source_adapter: epo
+      source_url: "${{ 'https://worldwide.espacenet.com/patent/search?q=' + (args.query || '') }}"
+      retrieved_at: ""
+
+  - limit: "${{ args.limit }}"
+
+columns: [publication_number, title]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.search"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/espacenet/_shared.ts

@@ -0,0 +1,98 @@
+/**
+ * @owner       src::adapters::espacenet::_shared
+ * @does        Shared helpers for the Espacenet browser-driven adapter — distinct from the EPO OPS HTTP adapter (which lives at src/adapters/epo/*). Espacenet is the no-key public front end; EPO OPS is the keyed REST API.
+ * @needs       src/engine/transport/mcp-browser.ts, src/engine/normalizer/patent-envelope.ts, src/types/patent.ts
+ * @feeds       src/adapters/espacenet/*.ts
+ * @breaks      none — pure helpers
+ * @invariants  every transport gap surfaces as a PatentEnvelope row with adapter_path stamped
+ * @side-effects none
+ * @perf        n/a
+ * @concurrency safe
+ * @test        covered transitively
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification browser-only
+ */
+
+import {
+  TransportError,
+  initMcpBrowserTransport,
+  mcpBrowserEvaluate,
+  mcpBrowserNavigate,
+  type McpBrowserResult,
+} from "../../engine/transport/mcp-browser.js";
+import { buildPatentEnvelope } from "../../engine/normalizer/patent-envelope.js";
+import type { PatentEnvelope, PatentErrorCode } from "../../types/patent.js";
+
+export function espacenetEnvelope(
+  code: PatentErrorCode,
+  adapter_path: string,
+  step: string,
+  suggestion: string,
+  alternatives: string[] = [],
+): PatentEnvelope {
+  return buildPatentEnvelope({
+    code,
+    adapter_path,
+    step,
+    suggestion,
+    alternatives,
+    retryable: false,
+  });
+}
+
+export function transportErrorToEspacenetEnvelope(
+  err: TransportError,
+  adapter_path: string,
+  step: string,
+): PatentEnvelope {
+  if (err.code === "MCP_BUS_MISSING") {
+    return buildPatentEnvelope({
+      code: "PATENT_API_DEPRECATED",
+      adapter_path,
+      step,
+      suggestion:
+        "engine has no outbound MCP transport wired into the bus today; install an McpResolver before invoking espacenet browser adapter, or use EPO OPS (src/adapters/epo/*) which exposes a keyed API",
+      alternatives: ["epo", "uspto", "lens"],
+      retryable: false,
+    });
+  }
+  return buildPatentEnvelope({
+    code: "PATENT_API_DEPRECATED",
+    adapter_path,
+    step,
+    suggestion: `mcp-browser transport error (${err.code}): ${err.message}`,
+    alternatives: ["epo"],
+    retryable: false,
+  });
+}
+
+export async function espacenetNavigateAndExtract<T>(
+  url: string,
+  expression: string,
+): Promise<McpBrowserResult<T>> {
+  const init = await initMcpBrowserTransport();
+  if (init.active_server === "none") {
+    const code =
+      init.reason === "bus-missing" ? "MCP_BUS_MISSING" : "MCP_NO_SERVER";
+    throw new TransportError(code, `mcp-browser unavailable (${init.reason})`);
+  }
+  const navResult = await mcpBrowserNavigate({ url });
+  if (!navResult.ok) {
+    throw new TransportError(
+      navResult.code ?? "MCP_NAVIGATE_FAILED",
+      navResult.message ?? "navigate did not succeed",
+    );
+  }
+  const evalResult = await mcpBrowserEvaluate<T>({
+    expression,
+    tab: navResult.tab,
+  });
+  if (!evalResult.ok) {
+    throw new TransportError(
+      evalResult.code ?? "MCP_EVALUATE_FAILED",
+      evalResult.message ?? "evaluate did not succeed",
+    );
+  }
+  return evalResult;
+}

package/src/adapters/espacenet/family.ts

@@ -0,0 +1,161 @@
+/**
+ * @owner       src::adapters::espacenet::family
+ * @does        Browser-driven Espacenet family lookup — DOCDB simple-family rows visible on the family tab of the detail page; alternative to EPO OPS keyed family broker.
+ * @needs       src/engine/transport/mcp-browser.ts, src/adapters/espacenet/_shared.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.family)
+ * @breaks      PATENT_INVALID_NUMBER, PATENT_NOT_FOUND, PATENT_API_DEPRECATED (MCP_BUS_MISSING)
+ * @invariants  output rows carry publication_number + jurisdiction + relationship per PatentFamilyMember shape
+ * @side-effects controls Chrome via MCP
+ * @perf        single navigate + evaluate
+ * @concurrency safe
+ * @test        tests/unit/adapters/espacenet/search.test.ts (transport-error shared path)
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification browser-only
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { TransportError } from "../../engine/transport/mcp-browser.js";
+import {
+  espacenetEnvelope,
+  espacenetNavigateAndExtract,
+  transportErrorToEspacenetEnvelope,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/espacenet/family.ts";
+
+interface EspacenetFamilyExtract {
+  rows: Array<{
+    publication_number: string;
+    jurisdiction?: string;
+    publication_date?: string;
+  }>;
+}
+
+const FAMILY_EXTRACTOR = `(() => {
+  const rows = Array.from(
+    document.querySelectorAll('[data-test="family-row"], .familyRow, tr.family-member')
+  ).map((el) => {
+    const text = (sel) => {
+      const node = el.querySelector(sel);
+      return node ? (node.textContent || '').trim() : '';
+    };
+    return {
+      publication_number: text('[data-test="publication-number"], .publicationNumber'),
+      jurisdiction: text('[data-test="country"], .country'),
+      publication_date: text('[data-test="publication-date"], .publicationDate'),
+    };
+  });
+  return { rows };
+})()`;
+
+function familyUrlFor(pubNo: string): string {
+  return `https://worldwide.espacenet.com/patent/search/family/${encodeURIComponent(pubNo)}`;
+}
+
+export async function runEspacenetFamily(kwargs: {
+  publication_number: string;
+}): Promise<unknown[]> {
+  const pubNo = String(kwargs.publication_number ?? "").trim();
+  if (pubNo.length === 0) {
+    return [
+      {
+        envelope: espacenetEnvelope(
+          "PATENT_INVALID_NUMBER",
+          ADAPTER_PATH,
+          "validate",
+          "espacenet family requires a non-empty publication_number",
+        ),
+      },
+    ];
+  }
+  const url = familyUrlFor(pubNo);
+  let extract: EspacenetFamilyExtract;
+  try {
+    const result = await espacenetNavigateAndExtract<EspacenetFamilyExtract>(
+      url,
+      FAMILY_EXTRACTOR,
+    );
+    if (!result.data) {
+      return [
+        {
+          envelope: espacenetEnvelope(
+            "PATENT_SCHEMA_DRIFT",
+            ADAPTER_PATH,
+            "evaluate",
+            "espacenet family evaluate returned no data",
+          ),
+        },
+      ];
+    }
+    extract = result.data;
+  } catch (err) {
+    if (err instanceof TransportError) {
+      return [
+        {
+          envelope: transportErrorToEspacenetEnvelope(
+            err,
+            ADAPTER_PATH,
+            "navigate",
+          ),
+        },
+      ];
+    }
+    throw err;
+  }
+  if (extract.rows.length === 0) {
+    return [
+      {
+        envelope: espacenetEnvelope(
+          "PATENT_NOT_FOUND",
+          ADAPTER_PATH,
+          "evaluate",
+          `espacenet found no family members for "${pubNo}"`,
+          ["epo"],
+        ),
+      },
+    ];
+  }
+  return extract.rows
+    .filter((row) => row.publication_number)
+    .map((row) => ({
+      publication_number: row.publication_number,
+      jurisdiction:
+        row.jurisdiction || row.publication_number.slice(0, 2).toUpperCase(),
+      relationship: "simple_family",
+      publication_date: row.publication_date || undefined,
+      source_adapter: "espacenet",
+    }));
+}
+
+cli({
+  site: "espacenet",
+  name: "family",
+  description: "Espacenet DOCDB simple-family lookup (browser)",
+  domain: "worldwide.espacenet.com",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "publication_number",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "ST.16 publication number",
+    },
+  ],
+  columns: [
+    "publication_number",
+    "jurisdiction",
+    "relationship",
+    "publication_date",
+  ],
+  capabilities: [
+    "mcp-browser.navigate",
+    "mcp-browser.evaluate",
+    "patent.family",
+  ],
+  minimum_capability: "mcp-browser.evaluate",
+  func: async (_page, kwargs) =>
+    runEspacenetFamily(kwargs as { publication_number: string }),
+});