Agentic CRM wave: lifecycle specialists, hygiene, mailbox, observability

.env.example

@@ -120,6 +120,13 @@ GOOGLE_CLIENT_SECRET=""
 # already knows (your own email and calendar history) and simply reports what
 # it could not check. Each key you add unlocks one more place it can look, and
 # it tells you at startup which ones are on.
+#
+# Full agentic mode checklist (env names only; Context is Settings → General):
+#   RAPIDAPI_KEY
+#   PERPLEXITY_API_KEY
+#   BLOB_READ_WRITE_TOKEN
+#   AGENT_BRIDGE_SECRET   (same value for app + agent; see block above)
+#   Context key           (Settings → General — not a variable)
 
 # Perplexity — finds where a person lives on the web, and recent news worth
 # knowing before a call. https://perplexity.ai/settings/api

apps/agent/agent/lib/agent-manifest.ts

@@ -1,6 +1,7 @@
 import { CRM_EVENT_TYPES } from "@crm/db/crm-events";
 import { z } from "zod";
 import { AGENT_ACTION_TYPES } from "./agent-actions";
+import { LIFECYCLE_ROLES } from "./lifecycle-roles";
 
 const slackDestination = z.object({
 	kind: z.enum(["channel", "user"]),
@@ -65,6 +66,7 @@ export const agentManifestResource = z.object({
 export const agentManifest = z
 	.object({
 		description: z.string().optional(),
+		lifecycleRole: z.enum(LIFECYCLE_ROLES).optional(),
 		actions: z.array(agentManifestAction).min(1),
 		triggers: z.array(agentManifestTrigger).min(1),
 		dataScope: z.object({

apps/agent/agent/lib/approval.ts

@@ -27,3 +27,20 @@ export function sensitiveWrite(instead: string): Approval {
 				}
 			: "user-approval";
 }
+
+export function sensitiveWhen<TInput>(
+	needsApproval: (input: TInput | undefined) => boolean,
+	instead: string,
+): Approval<TInput> {
+	return ({ session, toolInput }) => {
+		if (!needsApproval(toolInput as TInput | undefined)) {
+			return "not-applicable";
+		}
+		return isAutomated(session)
+			? {
+					type: "denied" as const,
+					reason: `Not something to do unattended. ${instead}`,
+				}
+			: "user-approval";
+	};
+}

apps/agent/agent/lib/brand.ts

@@ -58,10 +58,10 @@ export async function runBrand({
 	if (!company) return { enriched: false, reason: "No such company." };
 
 	if (!(await contextDevEnabled())) {
-		const reason =
-			"Context.dev is not configured, so there is nowhere to look.";
-		await settle(companyId, EnrichmentStatus.SKIPPED, reason);
-		return { enriched: false, reason };
+		return {
+			enriched: false,
+			reason: "Context.dev is not configured, so there is nowhere to look.",
+		};
 	}
 
 	if (!company.domain) {

apps/agent/agent/lib/brief-identity.ts

@@ -0,0 +1,60 @@
+import { FactBand } from "@crm/db";
+import { type Evidence, type EvidenceKind, scoreEvidence } from "./evidence";
+import { isDerivedName } from "./names";
+
+export const IDENTITY_PROOF_KINDS = [
+	"profile.email-match",
+	"linkedin.employer-and-name",
+	"crm.thread-reply",
+	"crm.signature-block",
+	"github.account-identity",
+] as const satisfies readonly EvidenceKind[];
+
+const identityKinds = new Set<string>(IDENTITY_PROOF_KINDS);
+
+export type ContactIdentitySnapshot = {
+	email: string | null;
+	firstName: string;
+	lastName: string | null;
+	linkedinUrl: string | null;
+	hasAppliedName: boolean;
+};
+
+export function evidenceProvesIdentity(evidence: Evidence[]): boolean {
+	return evidence.some((item) => identityKinds.has(item.kind));
+}
+
+export function contactIdentityIsTrustworthy(
+	contact: ContactIdentitySnapshot,
+): boolean {
+	if (contact.linkedinUrl) return true;
+	if (contact.hasAppliedName) return true;
+	if (
+		contact.lastName &&
+		!isDerivedName(contact.email, contact.firstName, contact.lastName)
+	) {
+		return true;
+	}
+	return false;
+}
+
+export function refuseBriefReason(input: {
+	contact: ContactIdentitySnapshot;
+	evidence: Evidence[];
+}): string | null {
+	const identityOk =
+		contactIdentityIsTrustworthy(input.contact) ||
+		evidenceProvesIdentity(input.evidence);
+
+	if (!identityOk) {
+		return "Identity is not trustworthy yet. Identify them first, then write the brief.";
+	}
+
+	const scored = scoreEvidence(input.evidence);
+
+	if (scored.band === null || scored.band === FactBand.POSSIBLE) {
+		return "Nothing here is sourced well enough to put on the record.";
+	}
+
+	return null;
+}

apps/agent/agent/lib/builder-runtime.ts

@@ -8,6 +8,7 @@ import {
 import { readAgentModel } from "@crm/db/settings";
 import { WORKSPACE_ID } from "@crm/db/workspace";
 import { AGENT_ACTION_TYPES, actionDependency } from "./agent-actions";
+import type { LifecycleRole } from "./lifecycle-roles";
 import { requestStaleSlackInventorySync } from "./slack-people";
 
 const GMAIL_SCOPE = "https://www.googleapis.com/auth/gmail.readonly";
@@ -56,6 +57,7 @@ export type DraftAgentInput = {
 	name: string;
 	description: string;
 	instructions: string;
+	lifecycleRole?: LifecycleRole;
 	triggers: DraftTrigger[];
 	recordScope: "SELECTED" | "WORKSPACE";
 	resources: BuilderResource[];
@@ -232,6 +234,7 @@ export async function saveBuilderDraft(
 		kind: "crm-team-agent",
 		name: input.name,
 		description: input.description,
+		...(input.lifecycleRole ? { lifecycleRole: input.lifecycleRole } : {}),
 		triggers: manifestTriggers,
 		dataScope: {
 			mode: input.recordScope,

apps/agent/agent/lib/capabilities.ts

@@ -13,6 +13,50 @@ export type Capability = {
 	readonly from: string;
 };
 
+export type EnableChecklistItem = {
+	readonly id: string;
+	readonly label: string;
+	readonly source: string;
+	readonly kind: "env" | "setting";
+};
+
+export const FULL_AGENTIC_CHECKLIST: readonly EnableChecklistItem[] = [
+	{
+		id: "RAPIDAPI_KEY",
+		label: "LinkedIn",
+		source: "RAPIDAPI_KEY",
+		kind: "env",
+	},
+	{
+		id: "PERPLEXITY_API_KEY",
+		label: "Web research",
+		source: "PERPLEXITY_API_KEY",
+		kind: "env",
+	},
+	{
+		id: CONTEXT_DEV,
+		label: "Company brand data",
+		source: "Settings → General",
+		kind: "setting",
+	},
+	{
+		id: "BLOB_READ_WRITE_TOKEN",
+		label: "Picture storage",
+		source: "BLOB_READ_WRITE_TOKEN",
+		kind: "env",
+	},
+	{
+		id: "AGENT_BRIDGE_SECRET",
+		label: "Agent panel",
+		source: "AGENT_BRIDGE_SECRET",
+		kind: "env",
+	},
+] as const;
+
+export const FULL_AGENTIC_ENV_VARS = FULL_AGENTIC_CHECKLIST.filter(
+	(item) => item.kind === "env",
+).map((item) => item.source);
+
 export async function contextDevKey(): Promise<string | null> {
 	try {
 		return await readContextDevKey(db);
@@ -51,13 +95,14 @@ export function capabilitiesFrom(
 			...fromEnv("PERPLEXITY_API_KEY"),
 			label: "Web research",
 			gives:
-				"open-web context with citations, and the search that finds a LinkedIn slug in the first place",
+				"open-web context with citations for research, not for identity matching",
 		},
 		{
 			id: CONTEXT_DEV,
 			from: "Settings → General",
 			label: "Company brand data",
-			gives: "a company's logo, industry, location and socials from its domain",
+			gives:
+				"a company's logo, industry, location and socials from its domain, and Context web search that finds LinkedIn candidate slugs for identity matching",
 			enabled: contextDev !== null,
 		},
 		{
@@ -66,6 +111,12 @@ export function capabilitiesFrom(
 			gives:
 				"somewhere to keep a logo or a profile photo. Without it a record has no picture at all, because the URLs these sources hand back expire and are never stored as they are",
 		},
+		{
+			...fromEnv("AGENT_BRIDGE_SECRET"),
+			label: "Agent panel",
+			gives:
+				"a rep can open a contact, company or deal Agent tab and talk to you live, and the API can poke dispatch without waiting for the schedule",
+		},
 	];
 }
 
@@ -137,3 +188,29 @@ export function markdownFor(all: readonly Capability[]): string {
 
 	return lines.join("\n");
 }
+
+export function enableChecklistMarkdown(
+	all: readonly Capability[] = capabilitiesFrom(null),
+): string {
+	const byId = new Map(all.map((capability) => [capability.id, capability]));
+	const lines = [
+		"## Full agentic mode enable checklist",
+		"",
+		"Env vars only (names, never values). Same value for `AGENT_BRIDGE_SECRET` on the app and the agent.",
+		"",
+	];
+
+	for (const item of FULL_AGENTIC_CHECKLIST) {
+		if (item.kind === "env") {
+			const on = byId.get(item.id)?.enabled === true;
+			lines.push(`- [${on ? "x" : " "}] \`${item.source}\` — ${item.label}`);
+		} else {
+			const on = byId.get(item.id)?.enabled === true;
+			lines.push(
+				`- [${on ? "x" : " "}] Context key at \`${item.source}\` — ${item.label} (not an env var)`,
+			);
+		}
+	}
+
+	return lines.join("\n");
+}

apps/agent/agent/lib/crm.ts

@@ -381,3 +381,34 @@ export async function writeTimelineNote(
 
 	return activity.id;
 }
+
+export async function writeOwnerTask(
+	contactId: string,
+	subject: string,
+	body: string,
+	dueAt: Date,
+	meta: Record<string, unknown> = {},
+): Promise<string | null> {
+	const contact = await db.contact.findUnique({
+		where: { id: contactId },
+		select: { companyId: true, ownerId: true },
+	});
+	if (!contact?.ownerId) return null;
+
+	const activity = await db.activity.create({
+		data: {
+			type: "TASK",
+			subject,
+			body,
+			occurredAt: new Date(),
+			dueAt,
+			contactId,
+			companyId: contact.companyId,
+			createdById: contact.ownerId,
+			meta: { ...meta, agent: "people-research" },
+		},
+		select: { id: true },
+	});
+
+	return activity.id;
+}

apps/agent/agent/lib/deal-intelligence.ts

@@ -0,0 +1,90 @@
+import { db } from "@crm/db";
+import {
+	blankToNull,
+	clampDealScore,
+	DEAL_SCORE,
+	isValidDealScore,
+} from "@crm/db/deal-score";
+
+export type WriteDealIntelligenceInput = {
+	dealId: string;
+	score: number;
+	summary: string;
+	forecastContext: string;
+};
+
+export type WriteDealIntelligenceResult =
+	| {
+			written: true;
+			score: number;
+			scoredAt: string;
+	  }
+	| {
+			written: false;
+			reason: string;
+	  };
+
+export async function writeDealIntelligence(
+	input: WriteDealIntelligenceInput,
+): Promise<WriteDealIntelligenceResult> {
+	const score = clampDealScore(input.score);
+	if (!isValidDealScore(score)) {
+		return {
+			written: false,
+			reason: `Score must be an integer from ${DEAL_SCORE.min} to ${DEAL_SCORE.max}.`,
+		};
+	}
+
+	const summary = blankToNull(input.summary);
+	if (!summary) {
+		return {
+			written: false,
+			reason: "Score summary is required.",
+		};
+	}
+	if (summary.length > DEAL_SCORE.summaryMax) {
+		return {
+			written: false,
+			reason: `Score summary must be at most ${DEAL_SCORE.summaryMax} characters.`,
+		};
+	}
+
+	const forecastContext = blankToNull(input.forecastContext);
+	if (!forecastContext) {
+		return {
+			written: false,
+			reason: "Forecast context is required.",
+		};
+	}
+	if (forecastContext.length > DEAL_SCORE.forecastMax) {
+		return {
+			written: false,
+			reason: `Forecast context must be at most ${DEAL_SCORE.forecastMax} characters.`,
+		};
+	}
+
+	const deal = await db.deal.findUnique({
+		where: { id: input.dealId },
+		select: { id: true },
+	});
+	if (!deal) {
+		return { written: false, reason: "No such deal." };
+	}
+
+	const scoredAt = new Date();
+	await db.deal.update({
+		where: { id: input.dealId },
+		data: {
+			dealScore: score,
+			dealScoreSummary: summary,
+			dealScoredAt: scoredAt,
+			forecastContext,
+		},
+	});
+
+	return {
+		written: true,
+		score,
+		scoredAt: scoredAt.toISOString(),
+	};
+}