portable-agent-layer 0.110.0 → 0.111.0

package/assets/skills/research-entity/SKILL.md

@@ -23,6 +23,7 @@ Research the company or person named in $ARGUMENTS and show a sourced profile. T
 1. Work out from $ARGUMENTS and the conversation:
    - the exact name;
    - whether it is a company or a person;
+   - for a company, its registered name with the legal form, not a brand or short name. The legal form is what routes it to its country's company register;
    - for a person, where they work;
    - one sentence of what the user said about them.
    If you cannot tell a company from a person, ask.
@@ -34,6 +35,11 @@ Research the company or person named in $ARGUMENTS and show a sourced profile. T
    ```bash
    pal cli knowledge research "<name>" --person --organization "<employer>" --context "<what the user said>"
    ```
+   When the legal form places the company in a country PAL has a register for, the command first reads that register directly, because web search does not index it. An exact registered-name match fills in the registration number, tax number, seat, main activity, managing directors and status, and the profile is kept even when the web finds nothing else. A brand name, a similar name, or a company from a country without a register goes through web search alone.
+
+   | Country | Legal forms | Register read |
+   | ------- | ----------- | ------------- |
+   | Hungary | Kft., Zrt., Nyrt., Bt., Kkt., or spelled out | ceginfo.hu for the registration number, nemzeticegtar.hu for the record |
    It takes one to several minutes. Add `--queue` when the user wants the profile saved; it then waits in the review queue.
 3. If the command exits 1, tell the user the reason it printed. Usual reasons:
    - the model found only namesakes (`match: unsure`): ask for something that tells them apart, such as an employer, a city or a website, and run it again with that in `--context` or `--organization`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.110.0",
+  "version": "0.111.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/knowledge-research.ts

@@ -3,6 +3,7 @@
  * the active agent, print the profile, and optionally queue it for review.
  */
 
+import { lookupCompanyRegister } from "../hooks/lib/company-register-router";
 import { loadKnownEntities, loadNameIndex } from "../hooks/lib/entity-cards";
 import { queueForReview } from "../hooks/lib/entity-extraction";
 import { lookupName } from "../hooks/lib/entity-names";
@@ -46,7 +47,11 @@ function targetFrom(name: string, values: ResearchValues): ResearchTarget {
 export async function researchFromCli(
   name: string | undefined,
   values: ResearchValues,
-  deps: ResearchDeps = { principal: identity().principal.name, infer: inference }
+  deps: ResearchDeps = {
+    principal: identity().principal.name,
+    infer: inference,
+    registry: lookupCompanyRegister,
+  }
 ): Promise<number> {
   if (!name?.trim()) throw new UsageError("name the person or company to research");
   const target = targetFrom(name.trim(), values);

package/src/hooks/handlers/entity-extraction.ts

@@ -6,6 +6,7 @@
  */
 
 import { ingestEntities } from "../../tools/knowledge/ingest";
+import { lookupCompanyRegister } from "../lib/company-register-router";
 import { excludedNames, loadKnownEntities, loadNameIndex } from "../lib/entity-cards";
 import {
   extractionSchema,
@@ -69,6 +70,7 @@ export async function extractSessionEntities(
     await researchNewEntities(newResearchTargets(plan.ingest, written), {
       principal: id.principal.name,
       infer: inference,
+      registry: lookupCompanyRegister,
     });
 }
 

package/src/hooks/lib/company-register-router.ts

@@ -0,0 +1,24 @@
+/**
+ * Official company registers, routed by country. A company is looked up only in the
+ * register of the country its name places it in; any other name goes to web search
+ * alone. To add a country, implement CompanyRegister in its own module and add it to
+ * REGISTERS.
+ */
+
+import type { CompanyRegister, Fetch, RegisterEntry } from "./company-register";
+import { hungarianRegister } from "./hungarian-registry";
+
+const REGISTERS: CompanyRegister[] = [hungarianRegister];
+
+/** Null when no register recognizes the name, and when its register has no exact match. */
+export async function lookupCompanyRegister(
+  name: string,
+  fetchImpl: Fetch = fetch,
+  registers: CompanyRegister[] = REGISTERS
+): Promise<RegisterEntry | null> {
+  const wanted = name.trim();
+  const register = registers.find((r) => r.recognizes(wanted));
+  if (!register) return null;
+  const company = await register.lookup(wanted, fetchImpl);
+  return company && { ...company, country: register.country };
+}

package/src/hooks/lib/company-register.ts

@@ -0,0 +1,25 @@
+/** What a country's company register implements to join the routing table in company-register-router.ts. */
+
+export interface RegisteredCompany {
+  name: string;
+  fullName: string;
+  number: string;
+  taxNumber: string;
+  seat: string;
+  status: string;
+  activity: string;
+  founded: string;
+  managers: string[];
+  url: string;
+  sources: string[];
+}
+
+export type RegisterEntry = RegisteredCompany & { country: string };
+
+export type Fetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface CompanyRegister {
+  country: string;
+  recognizes: (name: string) => boolean;
+  lookup: (name: string, fetchImpl: Fetch) => Promise<RegisteredCompany | null>;
+}

package/src/hooks/lib/entity-extraction.ts

@@ -49,6 +49,7 @@ export interface ResearchProfile {
     taxNumber: string;
     seat: string;
     status: string;
+    activity: string;
     managers: string[];
     url: string;
   };

package/src/hooks/lib/entity-research.ts

@@ -5,6 +5,7 @@
  */
 
 import type { IngestInput, IngestResult } from "../../tools/knowledge/ingest";
+import type { RegisterEntry } from "./company-register";
 import {
   closedObject,
   type ExtractedEntity,
@@ -27,6 +28,7 @@ export interface ResearchDeps {
   principal: string;
   infer: typeof inference;
   today?: string;
+  registry?: (name: string) => Promise<RegisterEntry | null>;
 }
 
 const MAX_TARGETS = 3;
@@ -83,6 +85,7 @@ export function researchSchema() {
       taxNumber: text,
       seat: text,
       status: text,
+      activity: text,
       managers: list(text),
       url: text,
     }),
@@ -96,7 +99,7 @@ const CHECKLIST = {
     "- website: the official website.",
     "- linkedin: the LinkedIn company page.",
     "- socials: other official accounts (X, Facebook, Instagram, YouTube, GitHub).",
-    "- registry: its entry in the official company register of its country: registered name, registration number, tax number, registered seat, status (active, in liquidation…), managing directors, and the URL you read it on. For a Hungarian company (Kft., Zrt., Bt., Nyrt., a .hu site) that is the cégjegyzék: e-cegjegyzek.hu, or public mirrors such as ceginformacio.hu, nemzeticegtar.hu or opten.hu.",
+    "- registry: its entry in the official company register of its country: registered name, registration number, tax number, registered seat, status (active, in liquidation…), main activity, managing directors, and the URL you read it on. For a Hungarian company (Kft., Zrt., Bt., Nyrt., a .hu site) that is the cégjegyzék: e-cegjegyzek.hu, or public mirrors such as ceginformacio.hu, nemzeticegtar.hu or opten.hu.",
     "- news: up to five news items or public statements from the last 12 months, newest first.",
     "- summary: two or three sentences on what the company does, its size and where it is based.",
   ],
@@ -124,13 +127,30 @@ export function researchSystem(principal: string, kind: ResearchTarget["kind"]):
   ].join("\n");
 }
 
-function researchUser(target: ResearchTarget, today: string): string {
+function registryFacts(entry: RegisterEntry): string {
+  return [
+    "The company register, already read: use it to tell this company from namesakes and do not search the register again.",
+    `registered name: ${entry.fullName || entry.name}`,
+    `registration number: ${entry.number}`,
+    entry.seat && `seat: ${entry.seat}`,
+    entry.activity && `main activity: ${entry.activity}`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function researchUser(
+  target: ResearchTarget,
+  today: string,
+  registry: RegisterEntry | null
+): string {
   return [
     `Today is ${today}.`,
     `${target.kind}: ${target.name}`,
     target.organization && `organization: ${target.organization}`,
     target.fact &&
       `what ${target.kind === "person" ? "was said about them" : "was said about it"}: ${target.fact}`,
+    registry && registryFacts(registry),
   ]
     .filter(Boolean)
     .join("\n");
@@ -166,13 +186,76 @@ export type ResearchOutcome =
   | { found: true; profile: ResearchProfile }
   | { found: false; reason: string };
 
+async function registryEntry(
+  target: ResearchTarget,
+  deps: ResearchDeps
+): Promise<RegisterEntry | null> {
+  if (target.kind !== "company" || !deps.registry) return null;
+  try {
+    return await deps.registry(target.name);
+  } catch (err) {
+    logError(`entity-research:registry:${target.name}`, err);
+    return null;
+  }
+}
+
+function registryOnlyProfile(entry: RegisterEntry): ResearchProfile {
+  const founded = entry.founded ? `, founded ${entry.founded}` : "";
+  const what = entry.activity || `company registered in ${entry.country}`;
+  return {
+    match: "sure",
+    summary: `${entry.name}: ${what}. Seat: ${entry.seat}${founded}.`,
+    role: "",
+    organization: "",
+    website: "",
+    linkedin: "",
+    socials: [],
+    registry: registryOf(entry),
+    news: [],
+    sources: [],
+  };
+}
+
+function registryOf(entry: RegisterEntry): ResearchProfile["registry"] {
+  return {
+    name: entry.fullName || entry.name,
+    number: entry.number,
+    taxNumber: entry.taxNumber,
+    seat: entry.seat,
+    status: entry.status,
+    activity: entry.activity,
+    managers: entry.managers,
+    url: entry.url,
+  };
+}
+
+/** What the register says replaces what the model read, and an exact register match is
+ *  enough to keep the profile even when the web turned up nothing. */
+function withRegistry(
+  profile: ResearchProfile | null,
+  entry: RegisterEntry
+): ResearchProfile {
+  const base =
+    profile?.match === "sure" ? withWebUrlsOnly(profile) : registryOnlyProfile(entry);
+  return {
+    ...base,
+    registry: registryOf(entry),
+    sources: [...new Set([...entry.sources, ...base.sources])],
+  };
+}
+
 export async function researchEntity(
   target: ResearchTarget,
   deps: ResearchDeps
 ): Promise<ResearchOutcome> {
+  const registry = await registryEntry(target, deps);
   const result = await deps.infer({
     system: researchSystem(deps.principal, target.kind),
-    user: researchUser(target, deps.today ?? new Date().toISOString().slice(0, 10)),
+    user: researchUser(
+      target,
+      deps.today ?? new Date().toISOString().slice(0, 10),
+      registry
+    ),
     tier: "medium",
     timeout: RESEARCH_TIMEOUT_MS,
     jsonSchema: researchSchema(),
@@ -180,6 +263,7 @@ export async function researchEntity(
     web: true,
   });
   const profile = result.success ? parseProfile(result.output) : null;
+  if (registry) return { found: true, profile: withRegistry(profile, registry) };
   if (!profile) return { found: false, reason: result.error ?? "no usable reply" };
   if (profile.match !== "sure")
     return { found: false, reason: `match: ${profile.match}. ${profile.summary}`.trim() };
@@ -243,6 +327,7 @@ function registryLines(r: ResearchProfile["registry"]): string[] {
     ["Tax number", r.taxNumber],
     ["Seat", r.seat],
     ["Status", r.status],
+    ["Main activity", r.activity],
     ["Managing directors", r.managers.join(", ")],
     ["Registry entry", r.url],
   ];

package/src/hooks/lib/hungarian-registry.ts

@@ -0,0 +1,194 @@
+/**
+ * The Hungarian company register, read directly. Web search does not index it, so a
+ * young or small Kft. is invisible to a search-only lookup. Only a name ending in a
+ * Hungarian legal form is recognized: ceginfo.hu resolves the exact name to its
+ * registration number, nemzeticegtar.hu shows the record for free.
+ */
+
+import type { CompanyRegister, Fetch, RegisteredCompany } from "./company-register";
+
+interface Page {
+  url: string;
+  html: string;
+}
+
+const CEGINFO = "https://ceginfo.hu/";
+const NEMZETICEGTAR = "https://www.nemzeticegtar.hu/";
+const USER_AGENT = "Mozilla/5.0 (compatible; PAL knowledge research)";
+const REQUEST_TIMEOUT_MS = 15_000;
+const MAX_REDIRECTS = 5;
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+const SEARCH_TOKEN_RE = /name="ceginfo_csrf_token" value="([^"]+)"/;
+const OFFICERS_RE = /Cégjegyzésre jogosultak<\/h3>([\s\S]*?)<\/ul>/;
+const PROCEEDINGS_RE = /<p[^>]*>([^<]*(?:felszámolási|végelszámolási)[^<]*)<\/p>/;
+
+const LONG_FORMS: Array<[RegExp, string]> = [
+  [/korlátolt felelősségű társaság$/i, "kft"],
+  [/zártkörűen működő részvénytársaság$/i, "zrt"],
+  [/nyilvánosan működő részvénytársaság$/i, "nyrt"],
+  [/betéti társaság$/i, "bt"],
+  [/közkereseti társaság$/i, "kkt"],
+];
+const SHORT_FORM_RE = /(?:^|\s)(?:kft|zrt|nyrt|bt|kkt|rt)\.?$/i;
+
+function isHungarianCompanyName(name: string): boolean {
+  return SHORT_FORM_RE.test(name) || LONG_FORMS.some(([re]) => re.test(name));
+}
+
+function comparable(name: string): string {
+  const short = LONG_FORMS.reduce((n, [re, form]) => n.replace(re, form), name);
+  return short.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+}
+
+const ENTITIES: Record<string, string> = { amp: "&", quot: '"', nbsp: " " };
+
+function decoded(html: string): string {
+  return html.replace(/&(#x?[0-9a-f]+|\w+);/gi, (whole, code: string) => {
+    if (code.startsWith("#x"))
+      return String.fromCodePoint(Number.parseInt(code.slice(2), 16));
+    if (code.startsWith("#")) return String.fromCodePoint(Number(code.slice(1)));
+    return ENTITIES[code] ?? whole;
+  });
+}
+
+function plainText(html: string): string {
+  return decoded(html.replace(/<[^>]+>/g, ""))
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function remember(response: Response, jar: Map<string, string>): void {
+  for (const cookie of response.headers.getSetCookie()) {
+    const [pair] = cookie.split(";");
+    const at = pair.indexOf("=");
+    jar.set(pair.slice(0, at), pair.slice(at + 1));
+  }
+}
+
+/** One browsing session: cookies carried across requests and redirects followed by hand,
+ *  because a search result lives in the session the search was posted from. */
+function session(fetchImpl: Fetch) {
+  const jar = new Map<string, string>();
+  return async (url: string, form?: URLSearchParams): Promise<Page> => {
+    let current = url;
+    let body = form;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+      const response = await fetchImpl(current, {
+        method: body ? "POST" : "GET",
+        body,
+        redirect: "manual",
+        headers: {
+          "user-agent": USER_AGENT,
+          cookie: [...jar].map(([k, v]) => `${k}=${v}`).join("; "),
+        },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+      remember(response, jar);
+      const location = response.headers.get("location");
+      if (location && REDIRECTS.has(response.status)) {
+        current = new URL(location, current).href;
+        body = undefined;
+        continue;
+      }
+      if (!response.ok) throw new Error(`${current}: HTTP ${response.status}`);
+      return { url: current, html: await response.text() };
+    }
+    throw new Error(`${url}: too many redirects`);
+  };
+}
+
+interface Hit {
+  name: string;
+  number: string;
+  slug: string;
+  url: string;
+}
+
+function searchHits(html: string): Hit[] {
+  const results = html.matchAll(
+    /<a href="([^"]*\/ceg-adatlap\/([a-z0-9-]+)-(\d{10})\.html)"[^>]*>[\s\S]*?<h2[^>]*>([\s\S]*?)<\/h2>/g
+  );
+  return Array.from(results, ([, url, slug, number, title]) => ({
+    name: plainText(title.replace(/<small[\s\S]*?<\/small>/g, "")),
+    number,
+    slug,
+    url: url.replace(/(?<!:)\/\//g, "/"),
+  }));
+}
+
+async function findRegistered(
+  name: string,
+  browse: ReturnType<typeof session>
+): Promise<Hit | null> {
+  const home = await browse(CEGINFO);
+  const token = SEARCH_TOKEN_RE.exec(home.html)?.[1];
+  if (!token) throw new Error("ceginfo.hu: the search form has no token");
+  const results = await browse(
+    `${CEGINFO}cegkereso/rapid`,
+    new URLSearchParams({ ceginfo_csrf_token: token, rapid: name })
+  );
+  const exact = searchHits(results.html).filter(
+    (hit) => comparable(hit.name) === comparable(name)
+  );
+  return exact.length === 1 ? exact[0] : null;
+}
+
+function field(html: string, label: string): string {
+  const value = new RegExp(
+    String.raw`<h6[^>]*>\s*${label}\s*</h6>\s*<p[^>]*>([\s\S]*?)</p>`,
+    "i"
+  ).exec(html)?.[1];
+  return value ? plainText(value) : "";
+}
+
+/** Names only: the register also prints each officer's mother's name and home address. */
+function managers(html: string): string[] {
+  const block = OFFICERS_RE.exec(html)?.[1] ?? "";
+  return Array.from(block.matchAll(/<strong[^>]*>([\s\S]*?)<\/strong>/g), ([, n]) =>
+    plainText(n)
+  );
+}
+
+function proceedings(html: string): string {
+  const sentence = PROCEEDINGS_RE.exec(html)?.[1];
+  return sentence ? plainText(sentence) : "";
+}
+
+function formattedNumber(digits: string): string {
+  return `${digits.slice(0, 2)}-${digits.slice(2, 4)}-${digits.slice(4)}`;
+}
+
+function entryFrom(hit: Hit, record: Page): RegisteredCompany {
+  const html = record.html;
+  return {
+    name: hit.name,
+    fullName: field(html, "Teljes név"),
+    number: formattedNumber(hit.number),
+    taxNumber: field(html, "Adószám"),
+    seat: field(html, "székhely"),
+    status: proceedings(html),
+    activity: field(html, "Főtevékenység"),
+    founded: field(html, "Alapítás éve"),
+    managers: managers(html),
+    url: record.url,
+    sources: [hit.url, record.url],
+  };
+}
+
+/** Null for anything but one exact match. */
+async function lookupHungarianCompany(
+  name: string,
+  fetchImpl: Fetch
+): Promise<RegisteredCompany | null> {
+  const browse = session(fetchImpl);
+  const hit = await findRegistered(name, browse);
+  if (!hit) return null;
+  const record = await browse(`${NEMZETICEGTAR}${hit.slug}-c${hit.number}.html`);
+  return entryFrom(hit, record);
+}
+
+export const hungarianRegister: CompanyRegister = {
+  country: "Hungary",
+  recognizes: isHungarianCompanyName,
+  lookup: lookupHungarianCompany,
+};