Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.
TypeScript
feat(agent): read people from Context.dev instead of RapidAPI (CMP-86) (#158)
github-actions[bot]7b9288b024f8
diff --git a/.env.example b/.env.exampleindex 3be3f9fb..12fac543 100644--- a/.env.example+++ b/.env.example@@ -125,10 +125,6 @@ GOOGLE_CLIENT_SECRET=""# knowing before a call. https://perplexity.ai/settings/api# PERPLEXITY_API_KEY=""-# LinkDAPI via RapidAPI — LinkedIn profiles: name, title, employer, tenure.-# https://rapidapi.com/linkdapi/api/linkdapi-best-unofficial-linkedin-api-# RAPIDAPI_KEY=""-# GitHub — raises the rate limit when matching contacts to GitHub profiles.# Any classic token with no scopes will do.# GITHUB_TOKEN=""diff --git a/README.md b/README.mdindex b61dda71..c761ebff 100644--- a/README.md+++ b/README.md@@ -105,18 +105,20 @@ has, so it plans around what it actually has rather than discovering the gaps onfailed call at a time, and it prints the list at startup:```-[agent] on LinkedIn (RAPIDAPI_KEY)[agent] off Web research (PERPLEXITY_API_KEY)-[agent] off Company brand data (Settings → General)+[agent] on Company brand data (Settings → General)+[agent] on LinkedIn (Settings → General)```-**Company brand data is [Context](https://link.context.dev/crm)** — the logo, the-colours, the industry and the real name behind a domain, which is the difference-between an account that arrives as itself and one that arrives as a grey square with-its initials in it. It is the one key that is asked for rather than configured: it-lives in a row, the onboarding asks for it, and **Settings → General** changes it-afterwards, because a self-hoster's admin cannot redeploy to set an environment-variable.+**Company brand data and LinkedIn are both [Context](https://link.context.dev/crm)**,+and both come from the same key. The first is the logo, the colours, the industry and+the real name behind a domain, which is the difference between an account that arrives+as itself and one that arrives as a grey square with its initials in it. The second+reads a person back from a LinkedIn URL already on their record — their real name,+current title, employer and every earlier role — which is what settles who an address+belongs to. It is the one key that is asked for rather than configured: it lives in a+row, the onboarding asks for it, and **Settings → General** changes it afterwards,+because a self-hoster's admin cannot redeploy to set an environment variable.**The sandbox has no network and no database.** Turning it on is what gives the modela shell — the difference between a tool-caller and something that can keep a dossier,@@ -309,7 +311,6 @@ short version:| --- | --- || `API_URL` / `APP_URL` | Where the two halves are served. Only needed off localhost. || `PERPLEXITY_API_KEY` | Lets the agent search the open web, with citations. |-| `RAPIDAPI_KEY` | Lets the agent read LinkedIn profiles for identity. || `AGENT_BRIDGE_SECRET` | Lets a rep talk to the agent from a contact's **Agent** tab. || `REDIS_URL` | A shared cache. Without it, per-instance and in-memory. || `CRON_SECRET` | Guards the mailbox sync route. Required to use it. |diff --git a/apps/agent/agent/lib/capabilities.ts b/apps/agent/agent/lib/capabilities.tsindex 6660bf77..2e587e95 100644--- a/apps/agent/agent/lib/capabilities.ts+++ b/apps/agent/agent/lib/capabilities.ts@@ -5,6 +5,10 @@ import { readContextDevKey } from "@crm/db/settings";export const CONTEXT_DEV = "CONTEXT_DEV";+export const CONTEXT_DEV_PEOPLE = "CONTEXT_DEV_PEOPLE";++export const CONTEXT_DEV_SOURCE = "Context.dev key (Settings → General)";+export type Capability = {readonly id: string;readonly label: string;@@ -41,12 +45,6 @@ export function capabilitiesFrom(});return [- {- ...fromEnv("RAPIDAPI_KEY"),- label: "LinkedIn",- gives:- "a person's real name, current title, employer and tenure, self-reported, and so authoritative on identity",- },{...fromEnv("PERPLEXITY_API_KEY"),label: "Web research",@@ -60,6 +58,14 @@ export function capabilitiesFrom(gives: "a company's logo, industry, location and socials from its domain",enabled: contextDev !== null,},+ {+ id: CONTEXT_DEV_PEOPLE,+ from: "Settings → General",+ label: "LinkedIn",+ gives:+ "a person read back from a LinkedIn URL you already hold — their real name, bio, current title and employer, every earlier role with its dates, their education and their other public profiles, all self-reported and so authoritative on identity",+ enabled: contextDev !== null,+ },{...fromEnv("BLOB_READ_WRITE_TOKEN"),label: "Picture storage",diff --git a/apps/agent/agent/lib/context-config.ts b/apps/agent/agent/lib/context-config.tsnew file mode 100644index 00000000..9e3693bd--- /dev/null+++ b/apps/agent/agent/lib/context-config.ts@@ -0,0 +1,13 @@+const SECOND_MS = 1_000;++export const CONTEXT = {+ timeoutMs: 60 * SECOND_MS,+ verifyTimeoutMs: 15 * SECOND_MS,++ people: {+ matchFloor: 70,+ enrichCost: 2,+ },++ avatarHosts: ["brand.dev", "licdn.com"],+} as const;diff --git a/apps/agent/agent/lib/context-dev.ts b/apps/agent/agent/lib/context-dev.tsindex cd981fe9..7fa9448c 100644--- a/apps/agent/agent/lib/context-dev.ts+++ b/apps/agent/agent/lib/context-dev.ts@@ -2,6 +2,7 @@ import ContextDev from "context.dev";import { APIError } from "context.dev/core/error";import { z } from "zod";import { contextDevKey } from "./capabilities";+import { CONTEXT } from "./context-config";export type JsonSchema = {type?:@@ -64,11 +65,9 @@ export type SearchResult = {markdown: string | null;};-const TIMEOUT_MS = 60_000;-let client: { key: string; api: ContextDev } | null = null;-async function contextDev(): Promise<ContextDev | null> {+export async function contextDev(): Promise<ContextDev | null> {const key = await contextDevKey();if (!key) {@@ -99,8 +98,6 @@ export type KeyCheck =*/const PROBE_EMAIL = "[email protected]";-const VERIFY_TIMEOUT_MS = 15_000;-export async function verifyKey(key: string): Promise<KeyCheck> {const api = new ContextDev({ apiKey: key });@@ -108,7 +105,7 @@ export async function verifyKey(key: string): Promise<KeyCheck> {await api.brand.retrieve({type: "by_email",email: PROBE_EMAIL,- timeoutMS: VERIFY_TIMEOUT_MS,+ timeoutMS: CONTEXT.verifyTimeoutMs,});return { outcome: "valid" };@@ -143,14 +140,14 @@ export async function brandByDomain(const params = {type: "by_domain",domain,- timeoutMS: TIMEOUT_MS,+ timeoutMS: CONTEXT.timeoutMs,} as const;return lookup(maxAgeMs === undefined ? params : { ...params, maxAgeMs });}export async function brandByEmail(email: string): Promise<LookupResult> {- return lookup({ type: "by_email", email, timeoutMS: TIMEOUT_MS });+ return lookup({ type: "by_email", email, timeoutMS: CONTEXT.timeoutMs });}export async function prefetch(domain: string): Promise<void> {@@ -180,7 +177,7 @@ export async function extract(schema,instructions,maxPages: 8,- timeoutMS: TIMEOUT_MS,+ timeoutMS: CONTEXT.timeoutMs,});return { outcome: "found", data: response.data };} catch (error) {@@ -313,7 +310,7 @@ function recognisedKeyFailure(error: APIError): boolean {);}-function describe(cause: unknown): string {+export function describe(cause: unknown): string {if (cause instanceof APIError) {return `${cause.status ?? "?"} ${errorCode(cause) ?? cause.message}`;}diff --git a/apps/agent/agent/lib/identity.ts b/apps/agent/agent/lib/identity.tsnew file mode 100644index 00000000..7ad4f118--- /dev/null+++ b/apps/agent/agent/lib/identity.ts@@ -0,0 +1,58 @@+import {+ looksLikeSameCompany,+ nameMatchesLocalPart,+ sameDomain,+} from "./names";+import type { Person } from "./people";++export type IdentityClaim = {+ email: string;+ companyName: string;+ companyDomain: string;+};++export type IdentityVerdict = {+ emailMatches: boolean;+ employerMatches: boolean;+ nameMatches: boolean;+ isSamePerson: boolean;+ confidence: "high" | "medium" | "low";+};++export function verdictFor(+ person: Person,+ claim: IdentityClaim,+): IdentityVerdict {+ const local = claim.email.split("@")[0] ?? "";++ const emailMatches = sameEmail(person.email, claim.email);+ const employerMatches = person.currentRoles.some(+ (role) =>+ sameDomain(role.organisation.domain, claim.companyDomain) ||+ looksLikeSameCompany(+ role.organisation.name ?? "",+ claim.companyName,+ claim.companyDomain,+ ),+ );+ const nameMatches = nameMatchesLocalPart(person, local);+ const isSamePerson = emailMatches || (employerMatches && nameMatches);++ return {+ emailMatches,+ employerMatches,+ nameMatches,+ isSamePerson,+ confidence: isSamePerson+ ? "high"+ : employerMatches || nameMatches+ ? "medium"+ : "low",+ };+}++function sameEmail(left: string | null, right: string): boolean {+ if (!left) return false;++ return left.trim().toLowerCase() === right.trim().toLowerCase();+}diff --git a/apps/agent/agent/lib/linkdapi.ts b/apps/agent/agent/lib/linkdapi.tsdeleted file mode 100644index aab557d1..00000000--- a/apps/agent/agent/lib/linkdapi.ts+++ /dev/null@@ -1,290 +0,0 @@-import { z } from "zod";--const HOST = "linkdapi-best-unofficial-linkedin-api.p.rapidapi.com";-const TIMEOUT_MS = 20_000;--const json = z.json();-const text = z.string().trim().min(1).nullable().catch(null);-const rawText = z.string().nullable().catch(null);-const count = z.number().nullable().catch(null);-const fields = z.record(z.string(), json).catch({});-const optionalFields = z.record(z.string(), json).nullable().catch(null);-const rows = z.array(json).nullable().catch(null);--const envelope = z- .object({- success: z.boolean().nullable().catch(null),- data: json.catch(null),- })- .catch({ success: null, data: null });--const experienceEnvelope = z- .object({ experience: rows, experiences: rows })- .catch({ experience: null, experiences: null });--const companyLookup = z.object({ companies: rows }).catch({ companies: null });--type Json = z.infer<typeof json>;--export type LinkedinFields = z.infer<typeof fields>;--export type Profile = {- slug: string;- profileUrl: string;- fullName: string | null;- firstName: string | null;- lastName: string | null;- headline: string | null;- location: string | null;- urn: string | null;- followerCount: number | null;- connectionsCount: number | null;- photoUrl: string | null;- positions: { name: string; url: string | null }[];-};--export type Company = {- id: string | null;- name: string | null;- universalName: string | null;- tagline: string | null;- description: string | null;- linkedinUrl: string | null;-};--export type Experience = {- title: string | null;- company: string | null;- dateRange: string | null;- location: string | null;-};--type Outcome<T> =- | { ok: true; data: T }- | { ok: false; missing: true }- | { ok: false; missing: false; reason: string };--function key(): string | null {- return process.env.RAPIDAPI_KEY ?? null;-}--export function linkedinEnabled(): boolean {- return key() !== null;-}--export function slugFromProfileUrl(raw: string | null): string | null {- if (!raw) return null;-- try {- const url = new URL(raw.trim());-- const host = url.hostname.toLowerCase();- if (host !== "linkedin.com" && !host.endsWith(".linkedin.com")) return null;-- const [section, slug] = url.pathname.split("/").filter(Boolean);- if (section !== "in" || !slug) return null;-- return decodeURIComponent(slug);- } catch {- return null;- }-}--export async function getProfile(slug: string): Promise<Outcome<Profile>> {- const result = await call("/api/v1/profile/overview", { username: slug });- if (!result.ok) return result;-- const d = fields.parse(result.data);- return {- ok: true,- data: {- slug,- profileUrl: `https://www.linkedin.com/in/${slug}`,- fullName: text.parse(d.fullName),- firstName: text.parse(d.firstName),- lastName: text.parse(d.lastName),- headline: text.parse(d.headline),- location: text.parse(d.location),- urn: text.parse(d.urn),- followerCount: count.parse(d.followerCount),- connectionsCount: count.parse(d.connectionsCount),- photoUrl: profilePhotoUrl(d),- positions: (rows.parse(d.CurrentPositions) ?? []).flatMap((entry) => {- const position = fields.parse(entry);- const name = rawText.parse(position.name);- return name ? [{ name, url: text.parse(position.url) }] : [];- }),- },- };-}--export async function getExperience(- urn: string,-): Promise<Outcome<Experience[]>> {- const result = await call("/api/v1/profile/full-experience", { urn });- if (!result.ok) return result;-- return { ok: true, data: experienceRows(result.data).map(toExperience) };-}--function experienceRows(payload: Json): Json[] {- if (Array.isArray(payload)) return payload;-- const envelope = experienceEnvelope.parse(payload);- return envelope.experience ?? envelope.experiences ?? [];-}--function toExperience(row: Json): Experience {- const entry = fields.parse(row);- return {- title: text.parse(entry.title),- company: text.parse(entry.companyName ?? entry.company),- dateRange: text.parse(entry.dateRange ?? entry.duration),- location: text.parse(entry.location),- };-}--export async function lookupCompany(- query: string,-): Promise<Outcome<{ id: string; displayName: string }[]>> {- const result = await call("/api/v1/companies/name-lookup", { query });- if (!result.ok) return result;-- const companies = companyLookup.parse(result.data).companies ?? [];- return {- ok: true,- data: companies.flatMap((entry) => {- const company = fields.parse(entry);- const id = rawText.parse(company.id);- return id- ? [{ id, displayName: rawText.parse(company.displayName) ?? id }]- : [];- }),- };-}--export async function getCompany(nameOrId: string): Promise<Outcome<Company>> {- const numeric = /^\d+$/.test(nameOrId);- const result = await call("/api/v1/companies/company/info", {- [numeric ? "id" : "name"]: nameOrId,- });- if (!result.ok) return result;-- const d = fields.parse(result.data);- return {- ok: true,- data: {- id: text.parse(d.id),- name: text.parse(d.name),- universalName: text.parse(d.universalName),- tagline: text.parse(d.tagline),- description: text.parse(d.description),- linkedinUrl: text.parse(d.linkedinUrl),- },- };-}--async function call(- path: string,- params: Record<string, string>,-): Promise<Outcome<Json>> {- const apiKey = key();- if (!apiKey) return { ok: false, missing: false, reason: "No RAPIDAPI_KEY." };-- const url = new URL(`https://${HOST}${path}`);- for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);-- const controller = new AbortController();- const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);-- try {- const response = await fetch(url, {- headers: { "x-rapidapi-host": HOST, "x-rapidapi-key": apiKey },- signal: controller.signal,- });-- if (!response.ok) {- return { ok: false, missing: false, reason: `HTTP ${response.status}` };- }-- const body = envelope.parse(await response.json());-- if (body.success !== true || body.data === null) {- return { ok: false, missing: true };- }-- return { ok: true, data: body.data };- } catch (cause) {- const aborted = cause instanceof Error && cause.name === "AbortError";- return {- ok: false,- missing: false,- reason: aborted- ? `Timed out after ${TIMEOUT_MS}ms.`- : cause instanceof Error- ? cause.message- : String(cause),- };- } finally {- clearTimeout(timer);- }-}--const PHOTO_KEYS = [- "profilePictureURL",- "profilePicture",- "profilePictureUrl",- "profilePicUrl",- "profilePic",- "profilePicHighQuality",- "profilePhotoUrl",- "profilePhoto",- "pictureUrl",- "avatarUrl",- "avatar",-];--export function profilePhotoUrl(raw: LinkedinFields): string | null {- const byLowerKey = new Map<string, Json>();- for (const [key, value] of Object.entries(raw)) {- byLowerKey.set(key.toLowerCase(), value);- }-- for (const key of PHOTO_KEYS) {- const url = firstUrl(byLowerKey.get(key.toLowerCase()));- if (!url) continue;-- try {- const { protocol, hostname } = new URL(url);- if (protocol !== "https:") continue;- if (hostname !== "licdn.com" && !hostname.endsWith(".licdn.com"))- continue;- return url;- } catch {}- }-- return null;-}--function firstUrl(value: Json | undefined): string | null {- if (Array.isArray(value)) {- for (const entry of [...value].reverse()) {- const found = firstUrl(entry);- if (found) return found;- }- return null;- }-- const direct = text.parse(value);- if (direct) return direct;-- const nested = optionalFields.parse(value);- if (nested) {- for (const key of ["url", "displayUrl", "src", "large", "original"]) {- const found = firstUrl(nested[key]);- if (found) return found;- }- }-- return null;-}diff --git a/apps/agent/agent/lib/names.ts b/apps/agent/agent/lib/names.tsindex d5761b73..d7b71f16 100644--- a/apps/agent/agent/lib/names.ts+++ b/apps/agent/agent/lib/names.ts@@ -91,6 +91,23 @@ export function domainOf(email: string): string | null {return at > 0 ? email.slice(at + 1).toLowerCase() : null;}+export function hostOf(value: string): string {+ const trimmed = value.trim().toLowerCase();+ if (trimmed === "") return "";++ const withoutScheme = trimmed.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");+ const host = withoutScheme.split("/")[0]?.split("@").pop() ?? "";++ return host.replace(/^www\./, "").replace(/\.$/, "");+}++export function sameDomain(left: string | null, right: string): boolean {+ if (!left) return false;++ const a = hostOf(left);+ return a !== "" && a === hostOf(right);+}+export function namesMatch(a: string | null, b: string | null): boolean {const left = words(a);const right = words(b);diff --git a/apps/agent/agent/lib/people.ts b/apps/agent/agent/lib/people.tsnew file mode 100644index 00000000..98313e37--- /dev/null+++ b/apps/agent/agent/lib/people.ts@@ -0,0 +1,357 @@+import { APIError } from "context.dev/core/error";+import type {+ PersonEnrichParams,+ PersonEnrichResponse,+} from "context.dev/resources/people";+import { z } from "zod";+import { CONTEXT } from "./context-config";+import { contextDev, describe } from "./context-dev";++export type EnrichedMatch = PersonEnrichResponse["match"];++export const MATCH_FLOOR = CONTEXT.people.matchFloor;++export type Organisation = {+ name: string | null;+ domain: string | null;+};++export type Role = {+ title: string | null;+ organisation: Organisation;+ startDate: string | null;+ endDate: string | null;+ location: string | null;+ description: string | null;+ isCurrent: boolean;+};++export type Study = {+ institution: Organisation;+ degree: string | null;+ fieldOfStudy: string | null;+ startDate: string | null;+ endDate: string | null;+};++export type Person = {+ firstName: string | null;+ lastName: string | null;+ fullName: string | null;+ bio: string | null;+ location: string | null;+ email: string | null;+ photoUrl: string | null;+ profileUrl: string | null;+ socialUrls: string[];+ websiteUrls: string[];+ skills: string[];+ currentRoles: Role[];+ experience: Role[];+ education: Study[];+};++export type PersonMatch =+ | { outcome: "found"; person: Person }+ | { outcome: "skipped"; reason: string }+ | { outcome: "failed"; reason: string; retryable: boolean };++const text = z.string().trim().min(1).nullable().catch(null);+const flag = z.boolean().nullable().catch(null);+const number = z.number().nullable().catch(null);+const list = z.array(text).catch([]);++const EMPTY_ORGANISATION = { name: null, domain: null };++const organisation = z+ .object({ name: text, domain: text })+ .catch(EMPTY_ORGANISATION);++const partialDate = z+ .object({ year: z.number(), month: number, day: number })+ .nullable()+ .catch(null);++const roleShape = z.object({+ title: text,+ organization: organisation,+ start_date: partialDate,+ end_date: partialDate,+ location: text,+ description: text,+ is_current: flag,+});++const EMPTY_ROLE = {+ title: null,+ organization: EMPTY_ORGANISATION,+ start_date: null,+ end_date: null,+ location: null,+ description: null,+ is_current: null,+};++const educationShape = z.object({+ institution: organisation,+ degree: text,+ field_of_study: text,+ start_date: partialDate,+ end_date: partialDate,+});++const EMPTY_EDUCATION = {+ institution: EMPTY_ORGANISATION,+ degree: null,+ field_of_study: null,+ start_date: null,+ end_date: null,+};++const personShape = z.object({+ name: z+ .object({ first: text, last: text, full: text })+ .catch({ first: null, last: null, full: null }),+ email: text,+ avatar_url: text,+ bio: text,+ location: z+ .object({ display: text, city: text, region: text, country: text })+ .catch({ display: null, city: null, region: null, country: null }),+ social_urls: list,+ website_urls: list,+ skills: list,+ current_role: roleShape.nullable().catch(null),+ experience: z.array(roleShape.catch(EMPTY_ROLE)).catch([]),+ education: z.array(educationShape.catch(EMPTY_EDUCATION)).catch([]),+});++const candidateShape = z.object({+ status: z.literal("candidate"),+ score: z.number(),+ person: personShape,+});++export async function personByProfileUrl(+ profileUrl: string,+): Promise<PersonMatch> {+ const api = await contextDev();+ if (!api) {+ return { outcome: "skipped", reason: "Context.dev is not configured." };+ }++ try {+ const response = await api.people.enrich({+ social_urls: [profileUrl],+ timeoutMS: CONTEXT.timeoutMs,+ });++ return matchFrom(response.match);+ } catch (error) {+ return classify(error);+ }+}++export type IdentityClues = {+ email: string;+ firstName: string | null;+ lastName: string | null;+ companyName: string | null;+ companyDomain: string | null;+};++export async function personByClues(+ clues: IdentityClues,+): Promise<PersonMatch> {+ const api = await contextDev();+ if (!api) {+ return { outcome: "skipped", reason: "Context.dev is not configured." };+ }++ const params: PersonEnrichParams = {+ email: clues.email,+ timeoutMS: CONTEXT.timeoutMs,+ };++ if (clues.firstName) params.name = { first: clues.firstName };+ if (clues.lastName) params.name = { ...params.name, last: clues.lastName };+ if (clues.companyName) params.company = { name: clues.companyName };+ if (clues.companyDomain) {+ params.company = { ...params.company, domain: clues.companyDomain };+ }++ try {+ return matchFrom((await api.people.enrich(params)).match);+ } catch (error) {+ return classify(error);+ }+}++export function matchFrom(match: EnrichedMatch): PersonMatch {+ const candidate = candidateShape.safeParse(match);++ if (!candidate.success) {+ return { outcome: "skipped", reason: "No person matched that profile." };+ }++ if (candidate.data.score < MATCH_FLOOR) {+ return {+ outcome: "skipped",+ reason:+ "Context could not tie a person to that profile firmly enough to be worth reading.",+ };+ }++ return { outcome: "found", person: toPerson(candidate.data.person) };+}++function toPerson(raw: z.infer<typeof personShape>): Person {+ const socialUrls = raw.social_urls.flatMap((url) => (url ? [url] : []));+ const profileUrl = socialUrls.find((url) => slugFromProfileUrl(url) !== null);+ const current = raw.current_role ? [toRole(raw.current_role)] : [];+ const experience = raw.experience.map(toRole);++ return {+ firstName: raw.name.first,+ lastName: raw.name.last,+ fullName: raw.name.full,+ bio: raw.bio,+ location: raw.location.display ?? placeOf(raw.location),+ email: raw.email,+ photoUrl: photoUrl(raw.avatar_url),+ profileUrl: profileUrl ?? null,+ socialUrls,+ websiteUrls: raw.website_urls.flatMap((url) => (url ? [url] : [])),+ skills: raw.skills.flatMap((skill) => (skill ? [skill] : [])),+ currentRoles: current.concat(+ experience.filter(+ (role) =>+ role.isCurrent && !current.some((held) => sameRole(held, role)),+ ),+ ),+ experience,+ education: raw.education.map(toStudy),+ };+}++function sameRole(held: Role, role: Role): boolean {+ return (+ held.organisation.name === role.organisation.name &&+ held.title === role.title &&+ held.startDate === role.startDate &&+ held.endDate === role.endDate+ );+}++function toRole(raw: z.infer<typeof roleShape>): Role {+ return {+ title: raw.title,+ organisation: raw.organization,+ startDate: dateOf(raw.start_date),+ endDate: dateOf(raw.end_date),+ location: raw.location,+ description: raw.description,+ isCurrent: raw.is_current ?? raw.end_date === null,+ };+}++function toStudy(raw: z.infer<typeof educationShape>): Study {+ return {+ institution: raw.institution,+ degree: raw.degree,+ fieldOfStudy: raw.field_of_study,+ startDate: dateOf(raw.start_date),+ endDate: dateOf(raw.end_date),+ };+}++function placeOf(location: {+ city: string | null;+ region: string | null;+ country: string | null;+}): string | null {+ const parts = [location.city, location.region, location.country].flatMap(+ (part) => (part ? [part] : []),+ );++ return parts.length > 0 ? parts.join(", ") : null;+}++function dateOf(date: z.infer<typeof partialDate>): string | null {+ if (!date) return null;++ const year = String(date.year).padStart(4, "0");+ if (date.month === null) return year;++ const month = String(date.month).padStart(2, "0");+ if (date.day === null) return `${year}-${month}`;++ return `${year}-${month}-${String(date.day).padStart(2, "0")}`;+}++export function photoUrl(raw: string | null): string | null {+ if (!raw) return null;++ try {+ const url = new URL(raw.trim());+ if (url.protocol !== "https:") return null;++ const host = url.hostname.toLowerCase();+ const trusted = CONTEXT.avatarHosts.some(+ (allowed) => host === allowed || host.endsWith(`.${allowed}`),+ );++ return trusted ? url.toString() : null;+ } catch {+ return null;+ }+}++export function slugFromProfileUrl(raw: string | null): string | null {+ if (!raw) return null;++ try {+ const url = new URL(raw.trim());++ const host = url.hostname.toLowerCase();+ if (host !== "linkedin.com" && !host.endsWith(".linkedin.com")) return null;++ const [section, slug] = url.pathname.split("/").filter(Boolean);+ if (section !== "in" || !slug) return null;++ return decodeURIComponent(slug);+ } catch {+ return null;+ }+}++function classify(cause: unknown): PersonMatch {+ if (!(cause instanceof APIError)) {+ return { outcome: "failed", reason: describe(cause), retryable: true };+ }++ if (cause.status === 400 || cause.status === 404) {+ return { outcome: "skipped", reason: "No person matched that profile." };+ }++ if (cause.status === 422) {+ return {+ outcome: "skipped",+ reason: "Context will not look that identifier up.",+ };+ }++ if (cause.status === 401 || cause.status === 403) {+ return { outcome: "failed", reason: describe(cause), retryable: false };+ }++ if (cause.status === 408 || cause.status === 429) {+ return { outcome: "failed", reason: describe(cause), retryable: true };+ }++ return {+ outcome: "failed",+ reason: describe(cause),+ retryable: (cause.status ?? 500) >= 500,+ };+}diff --git a/apps/agent/agent/lib/portrait-sources.ts b/apps/agent/agent/lib/portrait-sources.tsindex d56ea6f9..6b74d85d 100644--- a/apps/agent/agent/lib/portrait-sources.ts+++ b/apps/agent/agent/lib/portrait-sources.ts@@ -1,7 +1,8 @@import { z } from "zod";+import { CONTEXT } from "./context-config";import { extract, type JsonSchema } from "./context-dev";-import { getProfile, slugFromProfileUrl } from "./linkdapi";import { namesMatch } from "./names";+import { personByProfileUrl, slugFromProfileUrl } from "./people";export type PortraitSource = "linkedin" | "github" | "employer-site";@@ -22,27 +23,34 @@ export type PortraitSubject = {export async function findPortrait(subject: PortraitSubject,spend: (units?: number) => { ok: boolean; reason?: string },+ contextReady = true,): Promise<| { found: true; candidate: PortraitCandidate }| { found: false; tried: string[]; reason?: string }> {const tried: string[] = [];- if (subject.linkedinUrl) {+ if (subject.linkedinUrl && !contextReady) {+ tried.push("Context.dev is not connected, so LinkedIn was not read");+ }++ if (subject.linkedinUrl && contextReady) {const slug = slugFromProfileUrl(subject.linkedinUrl);if (slug) {- const charge = spend();+ const charge = spend(CONTEXT.people.enrichCost);if (!charge.ok) return { found: false, tried, reason: charge.reason };- const result = await getProfile(slug);- if (result.ok && result.data.photoUrl) {+ const result = await personByProfileUrl(+ `https://www.linkedin.com/in/${slug}`,+ );+ if (result.outcome === "found" && result.person.photoUrl) {return {found: true,- candidate: { source: "linkedin", url: result.data.photoUrl },+ candidate: { source: "linkedin", url: result.person.photoUrl },};}tried.push(- result.ok+ result.outcome === "found"? "LinkedIn profile has no picture": "LinkedIn profile could not be read",);@@ -60,7 +68,13 @@ export async function findPortrait(};}- if (subject.companyDomain && subject.name) {+ if (subject.companyDomain && subject.name && !contextReady) {+ tried.push(+ "Context.dev is not connected, so the company site was not read",+ );+ }++ if (subject.companyDomain && subject.name && contextReady) {const charge = spend(2);if (!charge.ok) return { found: false, tried, reason: charge.reason };diff --git a/apps/agent/agent/lib/portrait.ts b/apps/agent/agent/lib/portrait.tsindex 090ec3dc..fc5f4009 100644--- a/apps/agent/agent/lib/portrait.ts+++ b/apps/agent/agent/lib/portrait.ts@@ -1,5 +1,6 @@import { db } from "@crm/db";import { blobEnabled, isMirrored, mirror } from "@crm/db/blob";+import { CONTEXT_DEV_PEOPLE, enabled } from "./capabilities";import { findPortrait, type PortraitSource } from "./portrait-sources";export type PortraitResult = {@@ -140,6 +141,7 @@ export async function runPortrait({companyDomain: contact.company?.domain ?? null,},spend,+ await enabled(CONTEXT_DEV_PEOPLE),);if (!found.found) {diff --git a/apps/agent/agent/skills/identity-matching.md b/apps/agent/agent/skills/identity-matching.mdindex e5ff9f66..30ff6ca8 100644--- a/apps/agent/agent/skills/identity-matching.md+++ b/apps/agent/agent/skills/identity-matching.md@@ -16,12 +16,12 @@ Asking a model what it stands for produces "Paula Marchetti" — which happens tright, and would have been just as confident had it been wrong. You cannot tellthe difference afterwards, which is why guessing is banned outright.-What works is decomposition: `pmarchetti` contains the surname `marchetti`, and-searching *that* alongside the company returns `linkedin.com/in/paulamarchetti`-as the first result. The guess went into the **query**, and the answer came from-the profile.+What works is handing over every clue you already hold — the address itself, the+name on the record, the employer and its domain — and letting the resolver match+them against real profiles. The clues go into the **query**, and the answer comes+from the profile.-That is the shape of every match: guess where to look, never what you will find.+That is the shape of every match: say where to look, never what you will find.## The procedure@@ -29,20 +29,30 @@ That is the shape of every match: guess where to look, never what you will find.have ever replied to us from that address, you already have the strongestevidence available anywhere — `crm.thread-reply` — and a signature block mayhand you their title as well. Start every match here, not at a search engine.-1. **`resolve_linkedin_profile`** with the email and company. It decomposes the- local part and returns candidate slugs. These are leads, not answers.-2. **`get_linkedin_profile`** on each candidate, passing the email, company name- and domain — **and the `contactId`**. It returns the profile *and a verdict*.- Passing the id is what lets it copy their photograph, which it does only if- the verdict comes back positive, in code, without asking you. Leaving it out- costs the contact their picture and saves nothing.-3. **Read the verdict, not the profile.** It checks two things:+1. **`resolve_linkedin_profile`** when the record holds no LinkedIn URL. Pass the+ email, the company name and domain, and any first and last name the CRM has.+ It returns one candidate and a verdict. A candidate is a lead, not an answer.+2. **`get_linkedin_profile`** when the record already holds a LinkedIn URL, or to+ check a candidate at a different URL. Pass the email, company name+ and domain — **and the `contactId`**. It returns the profile, their full work+ history *and a verdict*, in one lookup. Passing the id is what lets it copy+ their photograph, which it does only if the verdict comes back positive, in+ code, without asking you. Leaving it out costs the contact their picture and+ saves nothing.++ Both calls cost the same, and they are the most expensive you have. Two or+ three lookups is the whole budget for a contact, so do not run both when one+ answers. A record with a LinkedIn URL needs step 2 only.+3. **Read the verdict, not the profile.** It checks three things:+ - `emailMatches` — the profile lists the address we are identifying.- `employerMatches` — a current position matches the company we have.- `nameMatches` — the real name is consistent with the email local part(`y` + `okonkwo` → Tomi Okonkwo).-4. **Both, or it is not them.** One of the two is not a weaker match, it is a- different person who happens to share something.-5. If no candidate passes, **stop**. Leaving "Pmarchetti" in the CRM is the correct+4. **`emailMatches` settles it on its own.** The person put that address on their+ own profile. Nothing else you can observe is stronger.+5. **Otherwise both, or it is not them.** One of the other two is not a weaker+ match, it is a different person who happens to share something.+6. If no candidate passes, **stop**. Leaving "Pmarchetti" in the CRM is the correctoutcome when you do not know.Somebody whose LinkedIn URL is **already on the record** has been through all of@@ -55,12 +65,17 @@ Call `identify_contact` with what you actually saw:| What you have | Evidence to record | What happens || --- | --- | --- |-| Both checks pass | `linkedin.employer-and-name` | Written to the record. |+| `emailMatches` is true | `profile.email-match` | Written to the record. |+| Employer and name both pass | `linkedin.employer-and-name` | Written to the record. || They replied from that address | `crm.thread-reply` | Written to the record. || One check passes | `employer-only`, or the profile as `search.cites-profile` | Offered to a rep as a suggestion. || Sources disagree | add a `contradiction` entry | Held. Nobody is shown a guess. |-The middle row is the case this exists for. Four Marchettis work at Fernhill; a+The `sourceUrl` to cite is the one the tool hands back — the profile URL the+person's own record lists. A lookup that comes back with no source is a lookup+you cannot write a fact from.++The `One check passes` row is the case this exists for. Four Marchettis work at Fernhill; ahuman settles that in three seconds, and the old rule — throw away anythingshort of certain — meant we paid for that lookup every run and learned nothingfrom it. A suggestion is not a failed match. It is the match, handed to the onediff --git a/apps/agent/agent/tools/get_contact_work_history.ts b/apps/agent/agent/tools/get_contact_work_history.tsindex f297748d..93799021 100644--- a/apps/agent/agent/tools/get_contact_work_history.ts+++ b/apps/agent/agent/tools/get_contact_work_history.ts@@ -1,18 +1,24 @@import { defineTool } from "eve/tools";import { z } from "zod";-import { enabled, unavailable } from "../lib/capabilities";+import {+ CONTEXT_DEV_PEOPLE,+ CONTEXT_DEV_SOURCE,+ enabled,+ unavailable,+} from "../lib/capabilities";import { contactProfileSlug } from "../lib/crm";-import { getExperience, getProfile } from "../lib/linkdapi";+import { spend } from "../lib/focus";+import { personByProfileUrl } from "../lib/people";export default defineTool({description:- "Read the LinkedIn profile already on a CRM contact — headline, current roles and full work history. For writing a summary of somebody already identified. Cannot be used to identify anyone: use resolve_linkedin_profile and get_linkedin_profile for that.",+ "Read the LinkedIn profile already on a CRM contact — bio, current role and full work history. For writing a summary of somebody already identified. Cannot be used to identify anyone: use resolve_linkedin_profile and get_linkedin_profile for that.",inputSchema: z.object({contactId: z.string(),}),async execute({ contactId }) {- if (!(await enabled("RAPIDAPI_KEY"))) {- return { found: false as const, ...unavailable("RAPIDAPI_KEY") };+ if (!(await enabled(CONTEXT_DEV_PEOPLE))) {+ return { found: false as const, ...unavailable(CONTEXT_DEV_SOURCE) };}const profileRef = await contactProfileSlug(contactId);@@ -23,21 +29,17 @@ export default defineTool({};}- const result = await getProfile(profileRef.slug);- if (!result.ok) {- return {- found: false as const,- reason: result.missing ? "No such profile." : result.reason,- };- }+ const charge = spend(2);+ if (!charge.ok) return { found: false as const, reason: charge.reason };- const profile = result.data;- const history = profile.urn ? await getExperience(profile.urn) : null;+ const result = await personByProfileUrl(profileRef.profileUrl);+ if (result.outcome !== "found") {+ return { found: false as const, reason: result.reason };+ }return {found: true as const,- profile,- experience: history?.ok ? history.data : null,+ profile: result.person,sourceUrl: profileRef.profileUrl,note: "Everything here is self-reported by the person. Write only what it says.",};diff --git a/apps/agent/agent/tools/get_linkedin_profile.ts b/apps/agent/agent/tools/get_linkedin_profile.tsindex f52e2175..92ebd7cc 100644--- a/apps/agent/agent/tools/get_linkedin_profile.ts+++ b/apps/agent/agent/tools/get_linkedin_profile.ts@@ -1,23 +1,24 @@import { defineTool } from "eve/tools";import { z } from "zod";-import { enabled, unavailable } from "../lib/capabilities";+import {+ CONTEXT_DEV_PEOPLE,+ CONTEXT_DEV_SOURCE,+ enabled,+ unavailable,+} from "../lib/capabilities";import { spend } from "../lib/focus";-import { getExperience, getProfile } from "../lib/linkdapi";-import { looksLikeSameCompany, nameMatchesLocalPart } from "../lib/names";+import { verdictFor } from "../lib/identity";+import { personByProfileUrl } from "../lib/people";import { storePortrait } from "../lib/portrait";export default defineTool({description:- "Read a LinkedIn profile by slug and check whether it is really the person behind an email address. Returns the profile plus an explicit verdict.",+ "Read a LinkedIn profile by slug and check whether it is really the person behind an email address. Returns the profile, their full work history, and an explicit verdict.",inputSchema: z.object({slug: z.string().describe("The linkedin.com/in/<slug> handle."),email: z.string().describe("The address we are trying to identify."),companyName: z.string(),companyDomain: z.string(),- includeHistory: z- .boolean()- .default(false)- .describe("Also fetch full work history — costs an extra call."),contactId: z.string().optional()@@ -25,66 +26,39 @@ export default defineTool({"The CRM contact this candidate is for. Supply it and their photo is copied automatically if — and only if — the profile turns out to be them.",),}),- async execute({- slug,- email,- companyName,- companyDomain,- includeHistory,- contactId,- }) {- if (!(await enabled("RAPIDAPI_KEY"))) {- return { found: false as const, ...unavailable("RAPIDAPI_KEY") };+ async execute({ slug, email, companyName, companyDomain, contactId }) {+ if (!(await enabled(CONTEXT_DEV_PEOPLE))) {+ return { found: false as const, ...unavailable(CONTEXT_DEV_SOURCE) };}- const charge = spend(includeHistory ? 2 : 1);+ const charge = spend(2);if (!charge.ok) return { found: false as const, reason: charge.reason };- const result = await getProfile(slug);- if (!result.ok) {- return result.missing- ? { found: false as const, reason: "No such profile." }- : { found: false as const, reason: result.reason };- }-- const profile = result.data;- const local = email.split("@")[0] ?? "";+ const requestedUrl = `https://www.linkedin.com/in/${slug}`;+ const result = await personByProfileUrl(requestedUrl);- const employerMatches = profile.positions.some((position) =>- looksLikeSameCompany(position.name, companyName, companyDomain),- );- const nameMatches = nameMatchesLocalPart(profile, local);-- const history =- includeHistory && profile.urn ? await getExperience(profile.urn) : null;+ if (result.outcome !== "found") {+ return { found: false as const, reason: result.reason };+ }- const isSamePerson = employerMatches && nameMatches;+ const person = result.person;+ const verdict = verdictFor(person, { email, companyName, companyDomain });const portrait =- contactId && isSamePerson+ contactId && verdict.isSamePerson? await storePortrait({contactId,- sourceUrl: profile.photoUrl,+ sourceUrl: person.photoUrl,verified: true,}): null;return {found: true as const,- profile,- experience: history?.ok ? history.data : null,+ profile: person,+ sourceUrl: person.profileUrl ?? requestedUrl,photo: portrait ?? undefined,- verdict: {- employerMatches,- nameMatches,- isSamePerson,- confidence:- employerMatches && nameMatches- ? ("high" as const)- : employerMatches || nameMatches- ? ("medium" as const)- : ("low" as const),- },+ verdict,};},});diff --git a/apps/agent/agent/tools/resolve_linkedin_profile.ts b/apps/agent/agent/tools/resolve_linkedin_profile.tsindex b1432146..b300a57f 100644--- a/apps/agent/agent/tools/resolve_linkedin_profile.ts+++ b/apps/agent/agent/tools/resolve_linkedin_profile.ts@@ -1,33 +1,69 @@import { defineTool } from "eve/tools";import { z } from "zod";-import { enabled, unavailable } from "../lib/capabilities";+import {+ CONTEXT_DEV_PEOPLE,+ CONTEXT_DEV_SOURCE,+ enabled,+ unavailable,+} from "../lib/capabilities";+import { CONTEXT } from "../lib/context-config";import { spend } from "../lib/focus";-import { searchTerms } from "../lib/names";-import { findProfileUrls } from "../lib/perplexity";+import { verdictFor } from "../lib/identity";+import { personByClues } from "../lib/people";export default defineTool({description:- "Find candidate LinkedIn profile slugs for a work email address. Returns CANDIDATES ONLY — you must verify each with get_linkedin_profile before believing any of them.",+ "Find the person behind a work email address when the CRM holds no LinkedIn URL for them. Sends the name and employer as clues, then returns the profile it resolved with a verdict on whether it is really them. Use get_linkedin_profile instead when the record already carries a LinkedIn URL.",inputSchema: z.object({email: z.string().describe("The contact's work email address."),companyName: z.string().describe("The company the CRM has them at."),+ companyDomain: z+ .string()+ .describe("The company's own domain, for checking the employer."),+ firstName: z+ .string()+ .optional()+ .describe("The first name, if the CRM holds one."),+ lastName: z+ .string()+ .optional()+ .describe("The last name, if the CRM holds one."),}),- async execute({ email, companyName }) {- if (!(await enabled("PERPLEXITY_API_KEY"))) {- return { candidateSlugs: [], ...unavailable("PERPLEXITY_API_KEY") };+ async execute({ email, companyName, companyDomain, firstName, lastName }) {+ if (!(await enabled(CONTEXT_DEV_PEOPLE))) {+ return { found: false as const, ...unavailable(CONTEXT_DEV_SOURCE) };}- const charge = spend();- if (!charge.ok) return { candidateSlugs: [], note: charge.reason };+ const charge = spend(CONTEXT.people.enrichCost);+ if (!charge.ok) return { found: false as const, reason: charge.reason };- const local = email.split("@")[0] ?? "";- const terms = searchTerms(local);- const slugs = await findProfileUrls(terms, companyName);+ const result = await personByClues({+ email,+ firstName: firstName ?? null,+ lastName: lastName ?? null,+ companyName,+ companyDomain,+ });++ if (result.outcome !== "found") {+ return { found: false as const, reason: result.reason };+ }++ const person = result.person;+ if (!person.profileUrl) {+ return {+ found: false as const,+ reason:+ "Somebody matched, but no LinkedIn profile came back with them. There is nothing to cite.",+ };+ }return {- searchedFor: terms,- candidateSlugs: slugs.slice(0, 5),- note: "Unverified. Each slug must be checked with get_linkedin_profile.",+ found: true as const,+ profile: person,+ sourceUrl: person.profileUrl,+ verdict: verdictFor(person, { email, companyName, companyDomain }),+ note: "One candidate, not proof. Read the verdict before you write anything.",};},});diff --git a/apps/agent/package.json b/apps/agent/package.jsonindex 37aaa7cc..2360a75a 100644--- a/apps/agent/package.json+++ b/apps/agent/package.json@@ -23,7 +23,7 @@"@crm/env": "workspace:*","@crm/telemetry": "workspace:*","@crm/validation": "workspace:*",- "context.dev": "^2.7.0",+ "context.dev": "2.10.0","eve": "^0.29.4","zod": "^4.4.3"},diff --git a/apps/agent/test/capabilities.spec.ts b/apps/agent/test/capabilities.spec.tsindex 7b4ee8b9..db3dd6cf 100644--- a/apps/agent/test/capabilities.spec.ts+++ b/apps/agent/test/capabilities.spec.ts@@ -1,17 +1,15 @@import { afterEach, beforeEach, describe, expect, it } from "bun:test";import {CONTEXT_DEV,+ CONTEXT_DEV_PEOPLE,+ CONTEXT_DEV_SOURCE,capabilitiesFrom,enabled,markdownFor,unavailable,} from "../agent/lib/capabilities";-const KEYS = [- "RAPIDAPI_KEY",- "PERPLEXITY_API_KEY",- "BLOB_READ_WRITE_TOKEN",-] as const;+const KEYS = ["PERPLEXITY_API_KEY", "BLOB_READ_WRITE_TOKEN"] as const;const saved: Record<string, string | undefined> = {};@@ -32,25 +30,25 @@ afterEach(() => {describe("capabilities", () => {it("reports everything off on a bare install", async () => {expect(capabilitiesFrom(null).every((c) => !c.enabled)).toBe(true);- expect(await enabled("RAPIDAPI_KEY")).toBe(false);+ expect(await enabled("PERPLEXITY_API_KEY")).toBe(false);});it("turns one on without turning on the others", async () => {process.env.PERPLEXITY_API_KEY = "pplx-test";expect(await enabled("PERPLEXITY_API_KEY")).toBe(true);- expect(await enabled("RAPIDAPI_KEY")).toBe(false);+ expect(await enabled("BLOB_READ_WRITE_TOKEN")).toBe(false);});it("treats blank and whitespace as unset", async () => {- process.env.RAPIDAPI_KEY = " ";- expect(await enabled("RAPIDAPI_KEY")).toBe(false);+ process.env.PERPLEXITY_API_KEY = " ";+ expect(await enabled("PERPLEXITY_API_KEY")).toBe(false);});it("is read live, so a late-configured process is not stuck off", async () => {- expect(await enabled("RAPIDAPI_KEY")).toBe(false);- process.env.RAPIDAPI_KEY = "key";- expect(await enabled("RAPIDAPI_KEY")).toBe(true);+ expect(await enabled("PERPLEXITY_API_KEY")).toBe(false);+ process.env.PERPLEXITY_API_KEY = "key";+ expect(await enabled("PERPLEXITY_API_KEY")).toBe(true);});it("is unknown for a variable that is not a capability", async () => {@@ -85,14 +83,37 @@ describe("the Context key is a setting, never a variable", () => {});});+describe("reading a person comes from the same Context key", () => {+ const people = (stored: string | null) =>+ capabilitiesFrom(stored).find((c) => c.id === CONTEXT_DEV_PEOPLE);++ it("is on when a key is stored and off when it is not", () => {+ expect(people("ctx")?.enabled).toBe(true);+ expect(people(null)?.enabled).toBe(false);+ });++ it("points at the settings page rather than a variable name", () => {+ expect(people(null)?.from).toBe("Settings → General");+ });++ it("turns on and off with the brand lookup, because it is one key", () => {+ for (const stored of ["ctx", null]) {+ expect(people(stored)?.enabled).toBe(+ capabilitiesFrom(stored).find((c) => c.id === CONTEXT_DEV)?.enabled ===+ true,+ );+ }+ });+});+describe("the unavailable result", () => {it("says retrying will not help", () => {- const result = unavailable("RAPIDAPI_KEY");+ const result = unavailable(CONTEXT_DEV_SOURCE);expect(result.ok).toBe(false);expect(result.configured).toBe(false);expect(result.reason).toContain("retrying will not help");- expect(result.reason).toContain("RAPIDAPI_KEY");+ expect(result.reason).toContain(CONTEXT_DEV_SOURCE);});});@@ -105,8 +126,7 @@ describe("the capability briefing", () => {});it("lists what is on and what is off, separately", () => {- process.env.RAPIDAPI_KEY = "key";- const markdown = markdownFor(capabilitiesFrom(null));+ const markdown = markdownFor(capabilitiesFrom("ctx"));expect(markdown).toContain("Available:");expect(markdown).toContain("LinkedIn");@@ -115,7 +135,7 @@ describe("the capability briefing", () => {});it("counts a stored Context key as configured", () => {- process.env.RAPIDAPI_KEY = "key";+ process.env.PERPLEXITY_API_KEY = "key";const markdown = markdownFor(capabilitiesFrom("ctx"));diff --git a/apps/agent/test/identity.spec.ts b/apps/agent/test/identity.spec.tsnew file mode 100644index 00000000..f74f024e--- /dev/null+++ b/apps/agent/test/identity.spec.ts@@ -0,0 +1,99 @@+import { describe, expect, it } from "bun:test";+import { verdictFor } from "../agent/lib/identity";+import type { Person, Role } from "../agent/lib/people";++const CLAIM = {+ email: "[email protected]",+ companyName: "Fernhill",+ companyDomain: "fernhill.com",+};++function role(name: string, domain: string | null): Role {+ return {+ title: "Head of Revenue",+ organisation: { name, domain },+ startDate: null,+ endDate: null,+ location: null,+ description: null,+ isCurrent: true,+ };+}++function person(overrides: Partial<Person> = {}): Person {+ return {+ firstName: "Paula",+ lastName: "Marchetti",+ fullName: "Paula Marchetti",+ bio: null,+ location: null,+ email: null,+ photoUrl: null,+ profileUrl: null,+ socialUrls: [],+ websiteUrls: [],+ skills: [],+ currentRoles: [role("Fernhill", "fernhill.com")],+ experience: [],+ education: [],+ ...overrides,+ };+}++describe("verdictFor", () => {+ it("settles on the address the person published themselves", () => {+ const verdict = verdictFor(+ person({ email: "[email protected]", currentRoles: [] }),+ CLAIM,+ );++ expect(verdict.emailMatches).toBe(true);+ expect(verdict.isSamePerson).toBe(true);+ expect(verdict.confidence).toBe("high");+ });++ it("accepts employer and name together", () => {+ const verdict = verdictFor(person(), CLAIM);++ expect(verdict.employerMatches).toBe(true);+ expect(verdict.nameMatches).toBe(true);+ expect(verdict.isSamePerson).toBe(true);+ });++ it("refuses a hyphenated domain that is not the employer", () => {+ const verdict = verdictFor(+ person({ currentRoles: [role("Acme", "fern-hill.com")] }),+ CLAIM,+ );++ expect(verdict.employerMatches).toBe(false);+ expect(verdict.isSamePerson).toBe(false);+ });++ it("offers a suggestion when only one check passes", () => {+ const verdict = verdictFor(+ person({ firstName: "Antonio", lastName: "Fontana", fullName: null }),+ CLAIM,+ );++ expect(verdict.employerMatches).toBe(true);+ expect(verdict.nameMatches).toBe(false);+ expect(verdict.isSamePerson).toBe(false);+ expect(verdict.confidence).toBe("medium");+ });++ it("refuses a stranger outright", () => {+ const verdict = verdictFor(+ person({+ firstName: "Antonio",+ lastName: "Fontana",+ fullName: null,+ currentRoles: [role("Brightwater", "brightwater.example")],+ }),+ CLAIM,+ );++ expect(verdict.isSamePerson).toBe(false);+ expect(verdict.confidence).toBe("low");+ });+});diff --git a/apps/agent/test/images.spec.ts b/apps/agent/test/images.spec.tsindex aef9e8e0..adc590bf 100644--- a/apps/agent/test/images.spec.ts+++ b/apps/agent/test/images.spec.ts@@ -1,48 +1,29 @@import { describe, expect, it } from "bun:test";-import { profilePhotoUrl, slugFromProfileUrl } from "../agent/lib/linkdapi";+import { photoUrl, slugFromProfileUrl } from "../agent/lib/people";import { findPortrait } from "../agent/lib/portrait-sources";-const OVERVIEW = {- firstName: "Kelly",- lastName: "Wiarda",- fullName: "Kelly Wiarda",- publicIdentifier: "kellywiarda",- backgroundImageURL:- "https://media.licdn.com/dms/image/v2/D4D16AQHJgcgf0YCwWA/profile-displaybackgroundimage-shrink_350_1400/0/1673558147641?e=1787184000",- profilePictureURL:- "https://media.licdn.com/dms/image/v2/D5603AQGOxXbMuQk4jw/profile-displayphoto-shrink_100_100/0/1738873240305?e=1787184000",-};--describe("profilePhotoUrl", () => {- it("reads the key the API actually uses", () => {- expect(profilePhotoUrl(OVERVIEW)).toContain("profile-displayphoto");- });+const AVATAR =+ "https://media.licdn.com/dms/image/v2/D5603AQGOxXbMuQk4jw/profile-displayphoto-shrink_100_100/0/1738873240305?e=1787184000";- it("never takes the background banner for a face", () => {- const { profilePictureURL, ...noPhoto } = OVERVIEW;- expect(profilePhotoUrl(noPhoto)).toBe(null);+describe("photoUrl", () => {+ it("keeps the avatar the enrichment returned", () => {+ expect(photoUrl(AVATAR)).toBe(AVATAR);});- it("tolerates the vendor recasing the key", () => {- expect(- profilePhotoUrl({ profilePictureUrl: OVERVIEW.profilePictureURL }),- ).toBe(OVERVIEW.profilePictureURL);+ it("refuses a face served over anything but https", () => {+ expect(photoUrl("http://media.licdn.com/x.jpg")).toBe(null);+ expect(photoUrl("ftp://media.licdn.com/x.jpg")).toBe(null);+ expect(photoUrl("javascript:alert(1)")).toBe(null);});- it("refuses a photo that is not on LinkedIn's CDN", () => {- expect(- profilePhotoUrl({ profilePictureURL: "https://evil.example/x.jpg" }),- ).toBe(null);- expect(- profilePhotoUrl({ profilePictureURL: "http://media.licdn.com/x.jpg" }),- ).toBe(null);- expect(- profilePhotoUrl({ profilePictureURL: "https://licdn.com.evil/x.jpg" }),- ).toBe(null);+ it("refuses anything that is not an absolute URL", () => {+ expect(photoUrl("/dms/image/x.jpg")).toBe(null);+ expect(photoUrl("media.licdn.com/x.jpg")).toBe(null);+ expect(photoUrl(" ")).toBe(null);});- it("is null for a profile with no picture, which is ordinary", () => {- expect(profilePhotoUrl({ firstName: "Nathan" })).toBe(null);+ it("is null for a person with no picture, which is ordinary", () => {+ expect(photoUrl(null)).toBe(null);});});diff --git a/apps/agent/test/names.spec.ts b/apps/agent/test/names.spec.tsindex fc475b15..c27fa7c8 100644--- a/apps/agent/test/names.spec.ts+++ b/apps/agent/test/names.spec.ts@@ -3,6 +3,7 @@ import { describe, expect, it } from "bun:test";import {looksLikeSameCompany,nameMatchesLocalPart,+ sameDomain,searchTerms,} from "../agent/lib/names";@@ -81,3 +82,28 @@ describe("nameMatchesLocalPart", () => {).toBe(false);});});++describe("sameDomain", () => {+ it("keeps two hyphenated domains apart", () => {+ expect(sameDomain("foo-bar.com", "foobar.com")).toBe(false);+ expect(sameDomain("the-hub.io", "thehub.io")).toBe(false);+ });++ it("matches the same host however it is written", () => {+ expect(sameDomain("https://www.Fernhill.com/careers", "fernhill.com")).toBe(+ true,+ );+ expect(sameDomain("fernhill.com.", "FERNHILL.COM")).toBe(true);+ });++ it("keeps different companies apart", () => {+ expect(sameDomain("fernhill.com", "brightwater.example")).toBe(false);+ expect(sameDomain("mail.fernhill.com", "fernhill.com")).toBe(false);+ });++ it("refuses an empty or missing domain", () => {+ expect(sameDomain(null, "fernhill.com")).toBe(false);+ expect(sameDomain("", "fernhill.com")).toBe(false);+ expect(sameDomain("fernhill.com", "")).toBe(false);+ });+});diff --git a/apps/agent/test/people.spec.ts b/apps/agent/test/people.spec.tsnew file mode 100644index 00000000..1d8b79af--- /dev/null+++ b/apps/agent/test/people.spec.ts@@ -0,0 +1,240 @@+import { describe, expect, it } from "bun:test";+import {+ type EnrichedMatch,+ MATCH_FLOOR,+ matchFrom,+} from "../agent/lib/people";++type Candidate = Extract<EnrichedMatch, { status: "candidate" }>;++const PROFILE = "https://www.linkedin.com/in/paulamarchetti";++const PERSON: Candidate["person"] = {+ name: { first: "Paula", last: "Marchetti", full: "Paula Marchetti" },+ email: "[email protected]",+ avatar_url: "https://media.licdn.com/dms/image/v2/photo.jpg",+ bio: "Building the revenue team at Fernhill.",+ location: { display: "Milan, Italy", city: "Milan", country: "Italy" },+ social_urls: ["https://x.com/pmarchetti", PROFILE],+ website_urls: ["https://paulamarchetti.example"],+ skills: ["Enterprise sales", "Forecasting"],+ current_role: {+ title: "Head of Revenue",+ organization: { name: "Fernhill", domain: "fernhill.com" },+ start_date: { year: 2022, month: 3 },+ location: "Milan, Italy",+ description: "Owns new business.",+ is_current: true,+ },+ experience: [+ {+ title: "Account Director",+ organization: { name: "Brightwater", domain: "brightwater.example" },+ start_date: { year: 2018, month: 1, day: 15 },+ end_date: { year: 2022, month: 2 },+ is_current: false,+ },+ ],+ education: [+ {+ institution: { name: "Politecnico di Milano" },+ degree: "MSc",+ field_of_study: "Management Engineering",+ end_date: { year: 2017 },+ },+ ],+};++const candidate = (person: Candidate["person"], score = 92): EnrichedMatch => ({+ status: "candidate",+ score,+ person,+});++describe("reading a person out of an enrichment", () => {+ it("parses the profile, the roles and the dates", () => {+ const result = matchFrom(candidate(PERSON));++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ const person = result.person;+ expect(person.firstName).toBe("Paula");+ expect(person.lastName).toBe("Marchetti");+ expect(person.bio).toContain("Fernhill");+ expect(person.location).toBe("Milan, Italy");+ expect(person.photoUrl).toContain("media.licdn.com");+ expect(person.skills).toEqual(["Enterprise sales", "Forecasting"]);+ expect(person.currentRoles).toHaveLength(1);+ expect(person.currentRoles[0]?.title).toBe("Head of Revenue");+ expect(person.currentRoles[0]?.organisation.domain).toBe("fernhill.com");+ expect(person.currentRoles[0]?.startDate).toBe("2022-03");+ expect(person.experience[0]?.startDate).toBe("2018-01-15");+ expect(person.experience[0]?.endDate).toBe("2022-02");+ expect(person.experience[0]?.isCurrent).toBe(false);+ expect(person.education[0]?.endDate).toBe("2017");+ });++ it("takes the LinkedIn URL as the profile, not the first social link", () => {+ const result = matchFrom(candidate(PERSON));++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ expect(result.person.profileUrl).toBe(PROFILE);+ });++ it("never treats another social page as the profile", () => {+ const result = matchFrom(+ candidate({ ...PERSON, social_urls: ["https://x.com/pmarchetti"] }),+ );++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ expect(result.person.profileUrl).toBe(null);+ expect(result.person.socialUrls).toEqual(["https://x.com/pmarchetti"]);+ });++ it("has no profile at all when nothing points anywhere", () => {+ const result = matchFrom(candidate({ ...PERSON, social_urls: [] }));++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ expect(result.person.profileUrl).toBe(null);+ });++ it("counts a current earlier role among the current ones", () => {+ const result = matchFrom(+ candidate({+ ...PERSON,+ current_role: null,+ experience: [+ {+ title: "Adviser",+ organization: { name: "Fernhill", domain: "fernhill.com" },+ start_date: { year: 2022 },+ is_current: true,+ },+ ...PERSON.experience,+ ],+ }),+ );++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ expect(result.person.currentRoles.map((role) => role.title)).toEqual([+ "Adviser",+ ]);+ });++ it("refuses a face that is not served over https", () => {+ const result = matchFrom(+ candidate({ ...PERSON, avatar_url: "http://media.licdn.com/photo.jpg" }),+ );++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ expect(result.person.photoUrl).toBe(null);+ });++ it("refuses a face served from a host we do not trust", () => {+ const result = matchFrom(+ candidate({ ...PERSON, avatar_url: "https://evil.example/x.jpg" }),+ );++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ expect(result.person.photoUrl).toBe(null);+ });++ it("keeps the face Context actually serves", () => {+ const url = "https://media.brand.dev/pfp/2a3c58be-678b-5530-acc8.png";+ const result = matchFrom(candidate({ ...PERSON, avatar_url: url }));++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ expect(result.person.photoUrl).toBe(url);+ });++ it("keeps both current roles held at one employer", () => {+ const result = matchFrom(+ candidate({+ ...PERSON,+ experience: [+ {+ title: "Board member",+ organization: { name: "Fernhill", domain: "fernhill.com" },+ start_date: { year: 2023 },+ is_current: true,+ },+ ...PERSON.experience,+ ],+ }),+ );++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ expect(result.person.currentRoles.map((role) => role.title)).toEqual([+ "Head of Revenue",+ "Board member",+ ]);+ });++ it("survives a profile with nothing on it", () => {+ const result = matchFrom(+ candidate({+ education: [],+ experience: [],+ skills: [],+ social_urls: [],+ website_urls: [],+ }),+ );++ expect(result.outcome).toBe("found");+ if (result.outcome !== "found") return;++ expect(result.person.fullName).toBe(null);+ expect(result.person.location).toBe(null);+ expect(result.person.photoUrl).toBe(null);+ expect(result.person.profileUrl).toBe(null);+ expect(result.person.currentRoles).toEqual([]);+ expect(result.person.experience).toEqual([]);+ });+});++describe("a match nobody should act on", () => {+ it("treats not_found as an ordinary empty answer", () => {+ const result = matchFrom({+ status: "not_found",+ score: null,+ person: null,+ });++ expect(result.outcome).toBe("skipped");+ });++ it("throws away a match Context itself is unsure of", () => {+ const result = matchFrom(candidate(PERSON, MATCH_FLOOR - 1));++ expect(result.outcome).toBe("skipped");+ });++ it("keeps a match that just clears the floor", () => {+ expect(matchFrom(candidate(PERSON, MATCH_FLOOR)).outcome).toBe("found");+ });++ it("never hands the score on, so it cannot be read as proof", () => {+ const result = matchFrom(candidate(PERSON));++ expect(JSON.stringify(result)).not.toContain("92");+ expect(Object.keys(result)).toEqual(["outcome", "person"]);+ });+});diff --git a/apps/agent/turbo.json b/apps/agent/turbo.jsonindex 534a71b7..6432b123 100644--- a/apps/agent/turbo.json+++ b/apps/agent/turbo.json@@ -20,8 +20,7 @@"BLOB_READ_WRITE_TOKEN","DATABASE_URL","GITHUB_TOKEN",- "PERPLEXITY_API_KEY",- "RAPIDAPI_KEY"+ "PERPLEXITY_API_KEY"]},"dev:headless": {@@ -34,8 +33,7 @@"BLOB_READ_WRITE_TOKEN","DATABASE_URL","GITHUB_TOKEN",- "PERPLEXITY_API_KEY",- "RAPIDAPI_KEY"+ "PERPLEXITY_API_KEY"]},/**diff --git a/apps/api/src/telemetry/rollup.service.ts b/apps/api/src/telemetry/rollup.service.tsindex 20ee5b66..c53b77a4 100644--- a/apps/api/src/telemetry/rollup.service.ts+++ b/apps/api/src/telemetry/rollup.service.ts@@ -148,7 +148,6 @@ export class RollupService {postgres_version: postgres,members_bucket: bucket(members),- cap_rapidapi: isSet("RAPIDAPI_KEY"),cap_perplexity: isSet("PERPLEXITY_API_KEY"),cap_context_dev: Boolean(contextKey?.contextDevApiKey?.trim()),cap_blob: isSet("BLOB_READ_WRITE_TOKEN"),diff --git a/bun.lock b/bun.lockindex f3d583b6..3176e6ce 100644--- a/bun.lock+++ b/bun.lock@@ -21,7 +21,7 @@"@crm/env": "workspace:*","@crm/telemetry": "workspace:*","@crm/validation": "workspace:*",- "context.dev": "^2.7.0",+ "context.dev": "2.10.0","eve": "^0.29.4","zod": "^4.4.3",},@@ -1329,7 +1329,7 @@"content-type": ["[email protected]", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],- "context.dev": ["[email protected]", "", {}, "sha512-FuonQNWVxHNixuTPQmcWc1D9qPnqfD/MurXiOo12jEGK8zeZ4TvYRCZP67XRkUZwjah0niklnrBJj+QCDwohSw=="],+ "context.dev": ["[email protected]", "", {}, "sha512-hTymKw2SrPXWt+1JSPceQcbIgnX32PdSzR9qvAMXWK5qwDTB/kJE1YK5IIXkBUUzZG2rT5QQqwYAGFooYQ8Yow=="],"convert-source-map": ["[email protected]", "", {}, "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg=="],diff --git a/docs/agent.md b/docs/agent.mdindex 3dd8e33c..e1fc9835 100644--- a/docs/agent.md+++ b/docs/agent.md@@ -222,6 +222,10 @@ resolver, and `lib/context-dev.ts` memoises its client on the key string.## Budget and scheduling- `lib/focus.ts` — per-session budget in `defineState`; running out is a normal ending.+ **A unit is one metered vendor call, not one credit.** `spend(2)` is what a+ billable lookup costs: a brand lookup is 10 Context credits, a person enrich is+ 20. Both charge 2, because the budget rations calls per contact and a session+ with a budget of 4 must still be able to make two of them.- `lib/tasks.ts` — `claimDue` leases with `FOR UPDATE SKIP LOCKED`.- **`schedules/dispatch.ts` is the only schedule and decides nothing.** "Every Nminutes, the oldest ten contacts" belongs in a `dueAt`.diff --git a/docs/environment.md b/docs/environment.mdindex aca35018..22417c60 100644--- a/docs/environment.md+++ b/docs/environment.md@@ -112,7 +112,6 @@ single place that knows what is set.| Variable | What it adds || --- | --- || `PERPLEXITY_API_KEY` | Open-web research with citations; finds a LinkedIn slug |-| `RAPIDAPI_KEY` | LinkedIn profiles via LinkDAPI || `GITHUB_TOKEN` | Raises the GitHub rate limit from 60/hour || `BLOB_READ_WRITE_TOKEN` | Mirrors logos and photos into Blob || `AI_GATEWAY_API_KEY` | The model. Not needed on Vercel (OIDC) |@@ -128,6 +127,9 @@ excluded — recognising our URL for the image optimizer needs no token.in `AppSetting`, is asked for at `/onboarding/research`, and changes on Settings →General — an admin who cannot redeploy cannot set a variable.+- **It buys two places to look, not one.** Company brand data by domain, and a person+ read back from a LinkedIn URL already on their record. Both capabilities in+ `agent/lib/capabilities.ts` turn on and off with this one key.- **An install that had the variable is asked again**: no migration, no fallback, and**the gate cannot be dismissed**.- **Nothing is lost while waiting.** A keyless `brand` task settles `SKIPPED` *before*diff --git a/docs/plan/people-enrichment-agent.md b/docs/plan/people-enrichment-agent.mdindex b13dc687..7f8908d8 100644--- a/docs/plan/people-enrichment-agent.md+++ b/docs/plan/people-enrichment-agent.md@@ -3,6 +3,12 @@An [eve](https://eve.dev/docs) agent that works out who the people in the CRMactually are, using real profile data rather than inference.+**Historical.** The agent this planned is built and [`agent.md`](../agent.md)+describes what it does now. One decision below did not survive: LinkedIn no+longer comes from a third-party LinkedIn API of its own. Context's people enrich+endpoint reads a person back from a URL, under the same key that already buys+company brand data, so there is one vendor and one key rather than two.+Read it with [`AGENTS.md`](../../AGENTS.md), [`api.md`](../api.md),[`design.md`](../design.md) and[`gmail-calendar-plan.md`](./gmail-calendar-plan.md), whose sync is what puts@@ -158,7 +164,7 @@ markets, and anyone who does not keep a profile. §5.| --- | --- | --- || Framework | eve, `apps/agent`, own Vercel project | Durable sessions, approval gating, schedules and evals are all things we would otherwise hand-roll. || Model | `anthropic/claude-sonnet-5` via AI Gateway | The default. Routes over project OIDC, so no provider key to manage. Matching is not a frontier-model problem; revisit if eval scores say otherwise. |-| LinkedIn access | LinkDAPI over RapidAPI, **profile + company endpoints only** | Its people *search* is broken — §0. Profile-by-slug and company-by-name are excellent. |+| LinkedIn access | LinkDAPI, **profile + company endpoints only** | Its people *search* is broken — §0. Profile-by-slug and company-by-name are excellent. Superseded: Context's people enrich reads the same profile under the key we already hold. || Finding the person | Context.dev web search resolves the LinkedIn slug | §0. The one thing LinkDAPI cannot do, and the thing a real search engine is good at. || Tool surface | Curated tools, not an OpenAPI connection | Not cost — *predictability*. Half the advertised endpoints do not exist under the documented names (§0), so the surface has to be pinned to what is verified. || CRM access | `@crm/db` directly | Already a workspace package. A second internal API would be plumbing with no reader. |@@ -225,7 +231,7 @@ key to rotate. Note that `eve dev` never fires schedules on their cadence —there is a dispatch route for triggering one while iterating.**Monorepo wiring.** `apps/agent` joins the bun workspace and gets a-`turbo.json` declaring `passThroughEnv` for `DATABASE_URL` and the RapidAPI key,+`turbo.json` declaring `passThroughEnv` for `DATABASE_URL` and the vendor keys,matching how `apps/api` does it. `check-types` and `lint` join the rootpipeline; `build` is `eve build`.diff --git a/docs/telemetry.md b/docs/telemetry.mdindex b89a9cdf..6e1ed36a 100644--- a/docs/telemetry.md+++ b/docs/telemetry.md@@ -96,7 +96,7 @@ whose event never arrived, which cannot be recovered.#### Capabilities — booleans, never values-`cap_rapidapi`, `cap_perplexity`, `cap_context_dev`, `cap_blob`, `cap_github`, `cap_redis`,+`cap_perplexity`, `cap_context_dev`, `cap_blob`, `cap_github`, `cap_redis`,`cap_agent_bridge`, `cap_cron_secret`, `cap_ai_gateway`, `cap_google_oauth`, `cap_sso_provider`,`cap_tracking`, `is_marketing`.@@ -104,6 +104,9 @@ Each is only whether the key is set. `cap_context_dev` is whether an `AppSetting`cap_sso_provider` whether an `ssoProvider` row exists, `cap_tracking` whether a tracking site idhas been minted — never the id itself. No key, value or last-four is sent.+`cap_context_dev` covers both of the agent's Context capabilities: company brand data by domain,+and reading a person off a LinkedIn URL. They are one key, so they are one boolean.+#### The agent| Property | What it is |diff --git a/packages/telemetry/src/allowlist.ts b/packages/telemetry/src/allowlist.tsindex d2881bb1..5880dc2b 100644--- a/packages/telemetry/src/allowlist.ts+++ b/packages/telemetry/src/allowlist.ts@@ -9,7 +9,6 @@ export const ALLOWED_PROPERTIES = ["postgres_version","seed_only",- "cap_rapidapi","cap_perplexity","cap_context_dev","cap_blob",diff --git a/turbo.json b/turbo.jsonindex 4e650884..bdfff23f 100644--- a/turbo.json+++ b/turbo.json@@ -54,7 +54,6 @@"PORT","PRISMA_LOG_QUERIES","PERPLEXITY_API_KEY",- "RAPIDAPI_KEY","GITHUB_TOKEN","BLOB_READ_WRITE_TOKEN","AI_GATEWAY_API_KEY",