Skip to content

armgit / crm

Public Imported from GitHub
0

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.example
index 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.md
index 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 on
failed 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 model
a 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.md
index 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 t
right, and would have been just as confident had it been wrong. You cannot tell
the 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 strongest
evidence available anywhere — `crm.thread-reply` — and a signature block may
hand 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 correct
outcome 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; a
human settles that in three seconds, and the old rule — throw away anything
short of certain — meant we paid for that lookup every run and learned nothing
from it. A suggestion is not a failed match. It is the match, handed to the one
diff --git a/apps/agent/agent/tools/get_contact_work_history.ts b/apps/agent/agent/tools/get_contact_work_history.ts
index 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.ts
index 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.ts
index 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.json
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.json
index 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.ts
index 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.lock
index 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.md
index 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 N
minutes, the oldest ten contacts" belongs in a `dueAt`.
diff --git a/docs/environment.md b/docs/environment.md
index 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.md
index 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 CRM
actually 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 root
pipeline; `build` is `eve build`.
diff --git a/docs/telemetry.md b/docs/telemetry.md
index 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 id
has 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.ts
index 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.json
index 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",