@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.334

package/packages/typescript/src/utils/text-normalize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Text normalization helpers for prompt/context assembly.
+ *
+ * WHY: Several runtime paths need to turn mixed nested values into stable,
+ * human-readable text blocks. Keeping this logic in one place makes prompt
+ * construction more predictable and avoids each caller inventing slightly
+ * different null/array/object coercion rules.
+ */
+/**
+ * Flatten a mixed nested value into text fragments.
+ *
+ * - Arrays are recursively flattened
+ * - Empty/nullish values are dropped
+ * - Strings are trimmed
+ * - Objects become `key: value` fragments
+ * - Scalars are stringified
+ */
+export declare function flattenTextValues(value: unknown): string[];
+/**
+ * Convert a mixed nested value into a multi-line text block.
+ */
+export declare function toMultilineText(value: unknown): string;
+//# sourceMappingURL=text-normalize.d.ts.map

package/packages/typescript/src/utils/text-normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-normalize.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/text-normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAwB1D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD"}

package/packages/typescript/src/utils/text-normalize.js

@@ -0,0 +1,42 @@
+/**
+ * Text normalization helpers for prompt/context assembly.
+ *
+ * WHY: Several runtime paths need to turn mixed nested values into stable,
+ * human-readable text blocks. Keeping this logic in one place makes prompt
+ * construction more predictable and avoids each caller inventing slightly
+ * different null/array/object coercion rules.
+ */
+/**
+ * Flatten a mixed nested value into text fragments.
+ *
+ * - Arrays are recursively flattened
+ * - Empty/nullish values are dropped
+ * - Strings are trimmed
+ * - Objects become `key: value` fragments
+ * - Scalars are stringified
+ */
+export function flattenTextValues(value) {
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => flattenTextValues(item));
+    }
+    if (value == null) {
+        return [];
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : [];
+    }
+    if (typeof value === "object") {
+        return Object.entries(value).flatMap(([key, inner]) => {
+            const innerText = flattenTextValues(inner).join(", ");
+            return innerText ? [`${key}: ${innerText}`] : [];
+        });
+    }
+    return [String(value)];
+}
+/**
+ * Convert a mixed nested value into a multi-line text block.
+ */
+export function toMultilineText(value) {
+    return flattenTextValues(value).join("\n");
+}

package/packages/typescript/src/utils/text-splitting.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Splits text into the first sentence and the rest of the text.
+ * Handles common abbreviations to avoid false positives.
+ */
+export declare function extractFirstSentence(text: string): {
+    first: string;
+    rest: string;
+};
+/**
+ * Checks if the text likely contains a complete first sentence.
+ * Useful for streaming to know when to call extractFirstSentence.
+ */
+export declare function hasFirstSentence(text: string): boolean;
+//# sourceMappingURL=text-splitting.d.ts.map

package/packages/typescript/src/utils/text-splitting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-splitting.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/text-splitting.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACb,CAiEA;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGtD"}

package/packages/typescript/src/utils/text-splitting.js

@@ -0,0 +1,66 @@
+/**
+ * Splits text into the first sentence and the rest of the text.
+ * Handles common abbreviations to avoid false positives.
+ */
+export function extractFirstSentence(text) {
+    // Regex for finding sentence boundaries.
+    // Looks for a period, question mark, or exclamation mark followed by a space or end of string.
+    const abbreviations = [
+        "Mr",
+        "Mrs",
+        "Ms",
+        "Dr",
+        "Prof",
+        "Sr",
+        "Jr",
+        "St",
+        "vs",
+        "etc",
+        "e.g",
+        "i.e",
+    ];
+    let boundaryIndex = -1;
+    // Simple iteration to find the first valid boundary
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (".?!".includes(char)) {
+            // Check if it's followed by a space or end of string
+            const nextChar = text[i + 1];
+            if (nextChar === undefined ||
+                /\s/.test(nextChar) ||
+                nextChar === '"' ||
+                nextChar === "'") {
+                // Potential boundary. Check prior context for abbreviations.
+                // We look at the word preceding the punctuation.
+                const preText = text.substring(0, i);
+                const lastWordMatch = preText.match(/\b(\w+)$/);
+                let isAbbreviation = false;
+                if (lastWordMatch) {
+                    const lastWord = lastWordMatch[1];
+                    // Case insensitive check
+                    if (abbreviations.some((abbr) => abbr.toLowerCase() === lastWord.toLowerCase())) {
+                        isAbbreviation = true;
+                    }
+                }
+                if (!isAbbreviation) {
+                    boundaryIndex = i + 1;
+                    break;
+                }
+            }
+        }
+    }
+    if (boundaryIndex !== -1) {
+        const first = text.substring(0, boundaryIndex).trim();
+        const rest = text.substring(boundaryIndex).trim();
+        return { first, rest };
+    }
+    return { first: text.trim(), rest: "" };
+}
+/**
+ * Checks if the text likely contains a complete first sentence.
+ * Useful for streaming to know when to call extractFirstSentence.
+ */
+export function hasFirstSentence(text) {
+    const { rest } = extractFirstSentence(text);
+    return rest.length > 0;
+}

package/packages/typescript/src/utils/toon.d.ts

@@ -0,0 +1,8 @@
+import type { ActionParameters } from "../types";
+export declare function tryParseToonValue(text: string): unknown | null;
+export declare function tryParseLooseToonRecord(text: string): Record<string, unknown> | null;
+export declare function encodeToonValue(value: unknown): string;
+export declare function normalizeStructuredRecord(value: unknown): Record<string, unknown> | null;
+export declare function mergeStructuredRecords(primary: Record<string, unknown> | null, secondary: Record<string, unknown> | null): Record<string, unknown> | null;
+export declare function parseToonActionParams(input: unknown): Map<string, ActionParameters>;
+//# sourceMappingURL=toon.d.ts.map

package/packages/typescript/src/utils/toon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toon.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/toon.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAwB,MAAM,UAAU,CAAC;AAsGvE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAW9D;AAED,wBAAgB,uBAAuB,CACtC,IAAI,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAuChC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED,wBAAgB,yBAAyB,CACxC,KAAK,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAuKhC;AA2DD,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAUhC;AA4BD,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,OAAO,GACZ,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAwB/B"}

package/packages/typescript/src/utils/toon.js

@@ -0,0 +1,346 @@
+import { decode as decodeToon, encode as encodeToon } from "@toon-format/toon";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const INDEXED_TOON_KEY_RE = /^([A-Za-z_][A-Za-z0-9_.-]*)(?:\[(\d+)\])(?:\{([^}]*)\})?$/;
+function stripFencedBlock(text) {
+    const trimmed = text.trim();
+    const fenced = trimmed.match(/^```(?:toon|json)?\s*([\s\S]*?)\s*```$/i);
+    return fenced?.[1]?.trim() ?? trimmed;
+}
+function stripOptionalToonLabel(text) {
+    const lines = text.trim().split(/\r?\n/);
+    if (lines.length < 2) {
+        return text.trim();
+    }
+    const [firstLine, ...rest] = lines;
+    if (!/^TOON(?:\s+DOCUMENT)?[:\s-]*$/i.test(firstLine.trim())) {
+        return text.trim();
+    }
+    return rest.join("\n").trim();
+}
+function resolveToonCandidate(text) {
+    const trimmed = stripOptionalToonLabel(stripFencedBlock(text));
+    if (looksLikeToonDocument(trimmed)) {
+        return trimmed;
+    }
+    const lines = trimmed.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index]?.trim() ?? "";
+        if (!line ||
+            (!/^TOON(?:\s+DOCUMENT)?[:\s-]*$/i.test(line) &&
+                !SIMPLE_TOON_KEY_RE.test(line))) {
+            continue;
+        }
+        const candidate = lines.slice(index).join("\n").trim();
+        const normalizedCandidate = stripOptionalToonLabel(candidate);
+        if (looksLikeToonDocument(normalizedCandidate)) {
+            return normalizedCandidate;
+        }
+    }
+    return trimmed;
+}
+function looksLikeToonDocument(text) {
+    if (!text)
+        return false;
+    if (text.includes("<response>") || text.includes("</response>"))
+        return false;
+    const lines = text
+        .trim()
+        .split(/\r?\n/)
+        .filter((line) => line.trim().length > 0);
+    if (lines.length === 0) {
+        return false;
+    }
+    const firstLine = lines[0]?.trim() ?? "";
+    if (/^TOON(?:\s+DOCUMENT)?[:\s-]*$/i.test(firstLine)) {
+        return lines.slice(1).some((line) => SIMPLE_TOON_KEY_RE.test(line.trim()));
+    }
+    if (!SIMPLE_TOON_KEY_RE.test(firstLine)) {
+        return false;
+    }
+    if (lines.length === 1) {
+        const [, value = ""] = firstLine.split(/:(.*)/s);
+        const trimmedValue = value.trim();
+        return !(trimmedValue.startsWith("{") && trimmedValue.endsWith("}"));
+    }
+    let structuredFieldCount = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (SIMPLE_TOON_KEY_RE.test(trimmed)) {
+            structuredFieldCount += 1;
+            continue;
+        }
+        if (/^[\t ]+/.test(line)) {
+            continue;
+        }
+        return false;
+    }
+    return structuredFieldCount > 0;
+}
+const SIMPLE_TOON_KEY_RE = /^([A-Za-z_][A-Za-z0-9_.-]*(?:\[[^\]\n]*\])?(?:\{[^\n]*\})?):(?:\s?(.*))?$/;
+export function tryParseToonValue(text) {
+    const trimmed = resolveToonCandidate(text);
+    if (!looksLikeToonDocument(trimmed)) {
+        return null;
+    }
+    try {
+        return decodeToon(trimmed);
+    }
+    catch {
+        return null;
+    }
+}
+export function tryParseLooseToonRecord(text) {
+    const trimmed = resolveToonCandidate(text);
+    if (!looksLikeToonDocument(trimmed)) {
+        return null;
+    }
+    const result = {};
+    let currentKey = null;
+    let parsedAnyField = false;
+    for (const line of trimmed.split(/\r?\n/)) {
+        const match = line.match(SIMPLE_TOON_KEY_RE);
+        if (match) {
+            const [, key, value = ""] = match;
+            currentKey = key.trim();
+            result[currentKey] = value.trim();
+            parsedAnyField = true;
+            continue;
+        }
+        if (!currentKey) {
+            if (!line.trim()) {
+                continue;
+            }
+            return null;
+        }
+        const previousValue = typeof result[currentKey] === "string"
+            ? result[currentKey]
+            : "";
+        const continuation = line.trimEnd();
+        result[currentKey] =
+            previousValue.length > 0
+                ? `${previousValue}\n${continuation}`
+                : continuation;
+    }
+    return parsedAnyField ? result : null;
+}
+export function encodeToonValue(value) {
+    return encodeToon(value);
+}
+export function normalizeStructuredRecord(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const result = {};
+    const trimOuterQuotes = (input) => {
+        const trimmed = input.trim();
+        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+            return trimmed.slice(1, -1);
+        }
+        return trimmed;
+    };
+    const dedentStructuredBlock = (input) => {
+        const lines = input.split(/\r?\n/);
+        const nonEmptyLines = lines.filter((line) => line.trim().length > 0);
+        if (nonEmptyLines.length === 0) {
+            return input.trim();
+        }
+        const minIndent = nonEmptyLines.reduce((smallest, line) => {
+            const indent = line.match(/^\s*/)?.[0].length ?? 0;
+            return Math.min(smallest, indent);
+        }, Number.POSITIVE_INFINITY);
+        return lines
+            .map((line) => line.trim().length === 0
+            ? ""
+            : line.slice(Math.min(minIndent, line.length)))
+            .join("\n")
+            .trim();
+    };
+    const splitCsvFields = (input) => {
+        const fields = [];
+        let current = "";
+        let quote = null;
+        for (let index = 0; index < input.length; index++) {
+            const char = input[index] ?? "";
+            if (quote) {
+                if (char === "\\" && index + 1 < input.length) {
+                    current += input[index + 1] ?? "";
+                    index += 1;
+                    continue;
+                }
+                if (char === quote) {
+                    quote = null;
+                    continue;
+                }
+                current += char;
+                continue;
+            }
+            if (char === '"' || char === "'") {
+                quote = char;
+                continue;
+            }
+            if (char === ",") {
+                fields.push(current.trim());
+                current = "";
+                continue;
+            }
+            current += char;
+        }
+        fields.push(current.trim());
+        return fields;
+    };
+    const normalizeIndexedValue = (rawValue, fieldSpec) => {
+        if (fieldSpec) {
+            const fieldNames = fieldSpec
+                .split(",")
+                .map((field) => field.trim())
+                .filter(Boolean);
+            const rawFields = typeof rawValue === "string" ? splitCsvFields(rawValue) : [];
+            return Object.fromEntries(fieldNames.map((fieldName, index) => [
+                fieldName,
+                trimOuterQuotes(rawFields[index] ?? ""),
+            ]));
+        }
+        if (typeof rawValue === "string") {
+            const normalizedBlock = dedentStructuredBlock(rawValue);
+            const nestedRecord = tryParseLooseToonRecord(normalizedBlock);
+            if (nestedRecord) {
+                return (normalizeStructuredRecord(nestedRecord) ??
+                    trimOuterQuotes(normalizedBlock));
+            }
+            return trimOuterQuotes(normalizedBlock);
+        }
+        if (Array.isArray(rawValue)) {
+            return rawValue.map((entry) => isRecord(entry) ? (normalizeStructuredRecord(entry) ?? entry) : entry);
+        }
+        if (isRecord(rawValue)) {
+            return normalizeStructuredRecord(rawValue) ?? rawValue;
+        }
+        return rawValue;
+    };
+    for (const [key, rawValue] of Object.entries(value)) {
+        const indexedMatch = key.match(INDEXED_TOON_KEY_RE);
+        if (indexedMatch) {
+            const [, baseKey, indexText, fieldSpec] = indexedMatch;
+            const index = Number.parseInt(indexText, 10);
+            const existingValues = Array.isArray(result[baseKey])
+                ? [...result[baseKey]]
+                : [];
+            existingValues[index] = normalizeIndexedValue(rawValue, fieldSpec);
+            result[baseKey] = existingValues;
+            continue;
+        }
+        if (key === "actions" || key === "providers" || key === "evaluators") {
+            if (Array.isArray(rawValue)) {
+                result[key] = rawValue.map((entry) => typeof entry === "string" ? entry.trim() : entry);
+                continue;
+            }
+            if (typeof rawValue === "string") {
+                result[key] =
+                    rawValue.trim().length > 0
+                        ? rawValue
+                            .split(",")
+                            .map((entry) => entry.trim())
+                            .filter(Boolean)
+                        : [];
+                continue;
+            }
+        }
+        if (key === "simple") {
+            result[key] =
+                rawValue === true ||
+                    (typeof rawValue === "string" &&
+                        rawValue.trim().toLowerCase() === "true");
+            continue;
+        }
+        result[key] = rawValue;
+    }
+    return Object.keys(result).length > 0 ? result : null;
+}
+function isEmptyStructuredValue(value) {
+    if (value == null) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return (value.length === 0 ||
+            value.every((entry) => isEmptyStructuredValue(entry)));
+    }
+    if (isRecord(value)) {
+        const entries = Object.values(value);
+        return (entries.length === 0 ||
+            entries.every((entry) => isEmptyStructuredValue(entry)));
+    }
+    if (typeof value === "string") {
+        return value.trim().length === 0;
+    }
+    return false;
+}
+function mergeStructuredValues(primary, secondary) {
+    if (isEmptyStructuredValue(primary)) {
+        return secondary;
+    }
+    if (isEmptyStructuredValue(secondary)) {
+        return primary;
+    }
+    if (Array.isArray(primary) && Array.isArray(secondary)) {
+        const merged = Array.from({ length: Math.max(primary.length, secondary.length) }, (_, index) => mergeStructuredValues(primary[index], secondary[index])).filter((entry) => entry !== undefined);
+        return merged;
+    }
+    if (isRecord(primary) && isRecord(secondary)) {
+        const keys = new Set([...Object.keys(primary), ...Object.keys(secondary)]);
+        return Object.fromEntries(Array.from(keys).map((key) => [
+            key,
+            mergeStructuredValues(primary[key], secondary[key]),
+        ]));
+    }
+    return primary;
+}
+export function mergeStructuredRecords(primary, secondary) {
+    if (!primary) {
+        return secondary;
+    }
+    if (!secondary) {
+        return primary;
+    }
+    return mergeStructuredValues(primary, secondary);
+}
+function toActionParameterValue(value) {
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        value === null) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => toActionParameterValue(entry));
+    }
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            toActionParameterValue(entry),
+        ]));
+    }
+    return value === undefined ? null : String(value);
+}
+export function parseToonActionParams(input) {
+    const parsed = typeof input === "string" ? tryParseToonValue(input) : (input ?? null);
+    if (!isRecord(parsed)) {
+        return new Map();
+    }
+    const candidate = isRecord(parsed.params) ? parsed.params : parsed;
+    const result = new Map();
+    for (const [actionName, paramsValue] of Object.entries(candidate)) {
+        if (!isRecord(paramsValue))
+            continue;
+        const params = {};
+        for (const [paramName, paramValue] of Object.entries(paramsValue)) {
+            params[paramName] = toActionParameterValue(paramValue);
+        }
+        if (Object.keys(params).length > 0) {
+            result.set(actionName.trim().toUpperCase(), params);
+        }
+    }
+    return result;
+}

package/packages/typescript/src/utils/type-guards.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Type guard utilities for runtime type checking
+ * These functions help TypeScript narrow types safely
+ */
+/**
+ * Check if a value is a plain object (not a special object type)
+ * Type guard that narrows the type to Record<string, unknown>
+ *
+ * A plain object is one created via {} or new Object(), not a built-in
+ * or custom class instance.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object
+ *
+ * @example
+ * ```typescript
+ * const data: unknown = { name: 'test' };
+ * if (isPlainObject(data)) {
+ *   // TypeScript knows data is Record<string, unknown>
+ *   console.log(data.name);
+ * }
+ * ```
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=type-guards.d.ts.map

package/packages/typescript/src/utils/type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/type-guards.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8BH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,OAAO,GACZ,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2BlC"}

package/packages/typescript/src/utils/type-guards.js

@@ -0,0 +1,73 @@
+/**
+ * Type guard utilities for runtime type checking
+ * These functions help TypeScript narrow types safely
+ */
+/**
+ * Set of built-in object constructors that should not be considered plain objects
+ */
+const NON_PLAIN_CONSTRUCTORS = new Set([
+    Array,
+    Date,
+    RegExp,
+    Map,
+    Set,
+    WeakMap,
+    WeakSet,
+    Error,
+    Promise,
+    ArrayBuffer,
+    DataView,
+    Int8Array,
+    Uint8Array,
+    Uint8ClampedArray,
+    Int16Array,
+    Uint16Array,
+    Int32Array,
+    Uint32Array,
+    Float32Array,
+    Float64Array,
+    BigInt64Array,
+    BigUint64Array,
+]);
+/**
+ * Check if a value is a plain object (not a special object type)
+ * Type guard that narrows the type to Record<string, unknown>
+ *
+ * A plain object is one created via {} or new Object(), not a built-in
+ * or custom class instance.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object
+ *
+ * @example
+ * ```typescript
+ * const data: unknown = { name: 'test' };
+ * if (isPlainObject(data)) {
+ *   // TypeScript knows data is Record<string, unknown>
+ *   console.log(data.name);
+ * }
+ * ```
+ */
+export function isPlainObject(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    // Check constructor - plain objects have Object or null prototype
+    const proto = Object.getPrototypeOf(value);
+    if (proto === null) {
+        return true; // Object.create(null)
+    }
+    if (proto.constructor === Object) {
+        return true;
+    }
+    // Explicitly exclude known built-in types
+    if (NON_PLAIN_CONSTRUCTORS.has(proto.constructor)) {
+        return false;
+    }
+    // Check for Buffer (Node.js specific)
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(value)) {
+        return false;
+    }
+    // If it's a custom class instance, it's not a plain object
+    return false;
+}

package/packages/typescript/src/utils/union-find.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Generic union-find (disjoint-set) data structure.
+ *
+ * Used to compute connected components from pairwise edges. The relationships
+ * graph builds identity clusters (members of the same person across platforms)
+ * by unioning entities that share a confirmed identity link or a normalized
+ * cross-platform handle. Both the runtime-level
+ * `agent/src/services/relationships-graph.ts` clusterer and the
+ * service-level `RelationshipsService` cluster lookup share this structure
+ * to guarantee the same notion of cluster membership.
+ *
+ * Path compression on find() keeps amortised cost near O(α(n)).
+ */
+export declare class UnionFind<T> {
+    private readonly parent;
+    constructor(initial?: Iterable<T>);
+    /** Idempotently register a node so it has a parent pointer. */
+    add(value: T): void;
+    /** True if the value is known to the structure. */
+    has(value: T): boolean;
+    /** Find the canonical root of `value`. Adds the node lazily. */
+    find(value: T): T;
+    /** Merge the components containing `left` and `right`. */
+    union(left: T, right: T): void;
+    /** Return all components as arrays of members keyed by root. */
+    groups(): Map<T, T[]>;
+    /** Return the members of the component containing `value`. */
+    componentOf(value: T): T[];
+}
+//# sourceMappingURL=union-find.d.ts.map

package/packages/typescript/src/utils/union-find.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"union-find.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/union-find.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAS,CAAC,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;gBAE9B,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IAQjC,+DAA+D;IAC/D,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAMnB,mDAAmD;IACnD,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO;IAItB,gEAAgE;IAChE,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC;IAWjB,0DAA0D;IAC1D,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAQ9B,gEAAgE;IAChE,MAAM,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAcrB,8DAA8D;IAC9D,WAAW,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE;CAa1B"}