@indexnetwork/protocol 14.3.2-rc.477.1 → 16.1.1-rc.478.1

package/dist/enrichment/enrichment.tools.helpers.js

@@ -0,0 +1,234 @@
+/**
+ * Helpers shared by the enrichment tools.
+ *
+ * These were nested functions inside `createEnrichmentTools`, closing over the
+ * destructured host capabilities. They are top-level now, each taking the tool
+ * deps explicitly, so the three tool modules can share them.
+ */
+import { z } from "zod";
+import { requestContext } from "../shared/observability/request-context.js";
+import { protocolLogger } from "../shared/observability/protocol.logger.js";
+import { socialsToEnrichmentRequest } from "../shared/utils/social-label.js";
+import { normalizeTelegramHandle } from "../shared/utils/telegram-handle.js";
+import { focusedNetworkId } from "../shared/agent/tool.scope.js";
+export const logger = protocolLogger("ChatTools:Enrichment");
+export function isMeaningfulEnrichment(enrichment) {
+    return !!enrichment &&
+        enrichment.confidentMatch &&
+        (enrichment.identity.bio.trim().length > 0 ||
+            enrichment.narrative.context.trim().length > 0 ||
+            enrichment.attributes.skills.length > 0 ||
+            enrichment.attributes.interests.length > 0);
+}
+export const approvedProfileDraftSchema = z.object({
+    identity: z.object({ name: z.string(), bio: z.string(), location: z.string() }),
+    narrative: z.object({ context: z.string() }),
+    attributes: z.object({ interests: z.array(z.string()), skills: z.array(z.string()) }),
+});
+export function trimToUndefined(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+export function isPlaceholderName(value) {
+    const normalized = value.trim().toLowerCase();
+    return normalized === 'unknown' || normalized === 'user';
+}
+export async function enrichFromUserRecord(deps, user) {
+    const enrichmentSocials = socialsToEnrichmentRequest(user.socials);
+    return deps.enricher.enrichUserProfile({
+        name: trimToUndefined(user.name),
+        email: trimToUndefined(user.email),
+        linkedin: enrichmentSocials.linkedin || undefined,
+        twitter: enrichmentSocials.twitter || undefined,
+        github: enrichmentSocials.github || undefined,
+        telegram: enrichmentSocials.telegram || undefined,
+        websites: enrichmentSocials.websites?.length ? enrichmentSocials.websites : undefined,
+    });
+}
+export function selectProfileSeed(onboarding, networkId) {
+    const seeds = onboarding?.profileSeeds ?? [];
+    if (seeds.length === 0)
+        return undefined;
+    const scoped = networkId ? seeds.filter((seed) => seed.networkId === networkId) : seeds;
+    return scoped[scoped.length - 1];
+}
+export function normalizeSocialUpdate(label, value) {
+    const normalizedLabel = label.trim().toLowerCase();
+    if (!normalizedLabel)
+        return null;
+    const trimmedValue = value.trim();
+    if (!trimmedValue)
+        return null;
+    if (normalizedLabel === 'telegram') {
+        const handle = normalizeTelegramHandle(trimmedValue);
+        return handle ? { label: normalizedLabel, value: handle } : null;
+    }
+    return { label: normalizedLabel, value: trimmedValue };
+}
+export async function mergeUserSocials(deps, incoming) {
+    const normalizedIncoming = incoming
+        .map((social) => normalizeSocialUpdate(social.label, social.value))
+        .filter((social) => social !== null);
+    if (normalizedIncoming.length === 0)
+        return;
+    const existingSocials = await deps.userDb.getUserSocials();
+    const incomingLabels = new Set(normalizedIncoming.map((social) => social.label));
+    const kept = existingSocials
+        .filter((social) => !incomingLabels.has(social.label) || social.label === 'custom')
+        .map((social) => ({ label: social.label, value: social.value }));
+    const merged = incomingLabels.has('custom')
+        ? [...kept.filter((social) => social.label !== 'custom'), ...normalizedIncoming]
+        : [...kept, ...normalizedIncoming];
+    await deps.userDb.setUserSocials(merged);
+}
+export function socialsRecordToRows(socials) {
+    if (!socials)
+        return [];
+    return Object.entries(socials).map(([label, value]) => ({ label, value }));
+}
+export async function enqueueEnrichmentRun(deps, context, operation, input) {
+    if (!context.isMcp || !deps.enrichmentRuns || !deps.enrichmentRunQueue)
+        return null;
+    const run = await deps.enrichmentRuns.create({
+        userId: context.userId,
+        agentId: context.agentId ?? null,
+        operation,
+        input,
+        context: {
+            userId: context.userId,
+            userName: context.userName,
+            userEmail: context.userEmail,
+            ...(focusedNetworkId(context) ? { scopeType: 'network', scopeId: focusedNetworkId(context) } : {}),
+            ...(context.indexName ? { indexName: context.indexName } : {}),
+            ...(context.sessionId ? { sessionId: context.sessionId } : {}),
+            ...(context.agentId ? { agentId: context.agentId } : {}),
+        },
+    });
+    try {
+        await deps.enrichmentRunQueue.enqueue(run.id);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        await deps.enrichmentRuns.markFailed(run.id, message);
+        if (err instanceof Error)
+            throw err;
+        const wrapped = new Error(`Failed to enqueue profile run: ${message}`);
+        wrapped.cause = err;
+        throw wrapped;
+    }
+    return run.id;
+}
+export async function persistApprovedProfileContext(deps, profile, user, networkId) {
+    await deps.userDb.updateUser({
+        name: profile.identity.name,
+        intro: profile.identity.bio,
+        location: profile.identity.location,
+    });
+    const onboarding = user?.onboarding ?? undefined;
+    const seed = selectProfileSeed(onboarding, networkId);
+    if (!seed?.socials?.length)
+        return;
+    await mergeUserSocials(deps, seed.socials);
+}
+export async function markApprovedProfileConfirmed(deps, context) {
+    const latestUser = await deps.userDb.getUser();
+    const currentOnboarding = latestUser?.onboarding ?? context.user.onboarding ?? {};
+    await deps.userDb.updateUser({
+        onboarding: {
+            ...currentOnboarding,
+            profileConfirmedAt: currentOnboarding.profileConfirmedAt ?? new Date().toISOString(),
+            currentStep: currentOnboarding.completedAt
+                ? currentOnboarding.currentStep ?? 'complete'
+                : 'first_signal',
+        },
+    });
+}
+export function buildProfileInput(parts) {
+    const lines = [];
+    if (parts.name)
+        lines.push(`Name: ${parts.name}`);
+    if (parts.location)
+        lines.push(`Location: ${parts.location}`);
+    if (parts.bioOrDescription)
+        lines.push(parts.bioOrDescription);
+    if (parts.socials?.length) {
+        lines.push(`User-provided public links:\n${parts.socials.map((s) => `${s.label}: ${s.value}`).join('\n')}`);
+    }
+    return lines.filter((line) => line.trim().length > 0).join('\n\n');
+}
+export function toProfileSummary(profile) {
+    return {
+        name: profile.identity.name,
+        bio: profile.identity.bio,
+        location: profile.identity.location,
+        skills: profile.attributes.skills,
+        interests: profile.attributes.interests,
+    };
+}
+export function buildApprovedDraftProfileInput(draft) {
+    return [
+        draft.identity.name ? `My name is ${draft.identity.name}.` : '',
+        draft.identity.location ? `I am based in ${draft.identity.location}.` : '',
+        draft.identity.bio || '',
+        draft.narrative.context || '',
+        draft.attributes.skills.length ? `My skills include ${draft.attributes.skills.join(', ')}.` : '',
+        draft.attributes.interests.length ? `My interests include ${draft.attributes.interests.join(', ')}.` : '',
+    ].filter((part) => part.trim().length > 0).join('\n');
+}
+export async function decomposeApprovedDraftProfile(deps, profile) {
+    const input = buildApprovedDraftProfileInput(profile);
+    if (!input.trim())
+        return;
+    const traceEmitter = requestContext.getStore()?.traceEmitter;
+    const graphStart = Date.now();
+    traceEmitter?.({ type: "graph_start", name: "enrichment" });
+    try {
+        const graphInput = {
+            userId: profile.userId,
+            operationMode: 'write',
+            input,
+            forceUpdate: true,
+        };
+        // Always invoked as a background fire-and-forget task (see confirm_user_context
+        // call sites), so decomposition must outlive the originating request — invoke
+        // the graph directly and never bind the request abort signal, which would
+        // cancel it as soon as the web request completes.
+        const result = await deps.graphs.profile.invoke(graphInput);
+        if (result.error) {
+            const err = new Error(result.error);
+            logger.error('Approved draft premise decomposition failed', {
+                userId: profile.userId,
+                error: result.error,
+            });
+            deps.reportToolError?.(err, {
+                subsystem: 'enrichment',
+                operation: 'profile.confirm_draft_decompose',
+                toolName: 'confirm_user_context',
+                userId: profile.userId,
+                tags: { toolName: 'confirm_user_context', execution: 'background' },
+            });
+            return;
+        }
+        // The write graph's decompose → aggregate → generate → save_profile
+        // pipeline persists the aggregate profile. The approved draft was already
+        // saved before decomposition started, so the DB is consistent regardless
+        // of graph outcome.  Do not re-save here — the graph's save_profile is
+        // authoritative, and a concurrent user-driven profile update could race.
+    }
+    catch (err) {
+        logger.error('Approved draft premise decomposition failed', {
+            userId: profile.userId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        deps.reportToolError?.(err, {
+            subsystem: 'enrichment',
+            operation: 'profile.confirm_draft_decompose',
+            toolName: 'confirm_user_context',
+            userId: profile.userId,
+            tags: { toolName: 'confirm_user_context', execution: 'background' },
+        });
+    }
+    finally {
+        traceEmitter?.({ type: "graph_end", name: "enrichment", durationMs: Date.now() - graphStart });
+    }
+}