Skip to content
19 changes: 11 additions & 8 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@
dialer's prospect is marked Do Not Contact.
- The decision engine reads the calls in their history. Someone who opted
out is always skipped; "not interested" on a recent call turns reach out
now into later; a wrong or bad number is no longer a way to reach them;
now into later; a wrong or bad number is no longer a way to reach them
for 90 days, unless their number has changed since;
and skipping someone who was interested goes to you to check.
- Quiz leads say how their last call went.
- **Calls at their hour.** A call sheet for a prospect, in the app and from
Expand All @@ -50,11 +51,12 @@
phone through ntfy within a minute of each qualified lead (several at once
come as one), tapping it opens the lead; it looks once a minute across
every server on the database, never pushes a lead twice, retries one that
failed, and never pushes leads from before it was set up. Settings, Lead
alerts sends a test. A lead who opted out anywhere, "do not call" on the
dialer included, is Do Not Contact: last on Calls, with no Call button,
and never pushed. Their answers read whether offer writes the JSON on one
line or several.
failed, never pushes leads from before it was set up, and takes more than
one look's 500 new leads over the next looks, oldest first, skipping
none. Settings, Lead alerts sends a test. A lead who opted out anywhere,
"do not call" on the dialer included, is Do Not Contact: last on Calls,
with no Call button, and never pushed. Their answers read whether offer
writes the JSON on one line or several.
- **Picking a dialer prospect fills the script in again.** Prospects from
`twenty:agencyProspects` and `twenty:agencyPeople` were never found by
their key in a call sheet or a research run, so the script kept its
Expand All @@ -65,8 +67,9 @@
delivered, and each watch is a prospect source, `listen:<watch>`: the
trigger line is the post itself, quoted, and a post on X carries its
author's handle for an X DM. **Save as a list** in Settings writes a
watch's matches to one of your own lists to fill in and research; saving
again only adds what is new. Prospect sources are defined once, so
watch's matches to one of your own lists to fill in and research, one
list per watch even when two share a name; saving again only adds what is
new. Prospect sources are defined once, so
research and campaigns accept the same ones.
- **X DMs go out from COLD.** Add your own X developer app in Settings
(`X_CLIENT_ID`, `X_CLIENT_SECRET`) and press **Connect X** for an account:
Expand Down
3 changes: 2 additions & 1 deletion docs/decision-engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,8 @@ about them.
The dialer's calls are part of what the model reads: each one in the history
with its outcome, the dialer's AI score and tone, and its summary. A wrong or
bad number stops counting the phone as a way to reach them, which lowers
their reach score.
their reach score: for 90 days, and only while their phone is still the number
that was dialed.

Anyone marked Do Not Contact, or who ever opted out, is never researched or
scored.
Expand Down
3 changes: 3 additions & 0 deletions src/domains/config/helpers/parseConfig.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
import { readFileSync } from "node:fs";
import path from "node:path";
import { parse } from "yaml";
import { DEFAULT_CALL_HOURS } from "../types";
import { DEFAULT_FOOTERS, parseConfig } from "./parseConfig";

const example = parse(readFileSync(path.resolve(import.meta.dir, "../../../../cold.example.yaml"), "utf8"));
Expand Down Expand Up @@ -31,6 +32,8 @@ describe("parseConfig", () => {

test("the calls section is optional: 8am to 9pm every day, in the prospect's time", () => {
expect(parseConfig(example, "x").config!.calls).toEqual({ start: "08:00", end: "21:00", days: ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] });
// Each config has its own copy of the default days: editing one never edits the defaults.
expect(parseConfig(example, "x").config!.calls.days).not.toBe(DEFAULT_CALL_HOURS.days);
const tuned = parseConfig({ ...example, calls: { start: "09:00", end: "18:30", days: ["Mon", "tue", "wed", "thu", "fri"] } }, "x");
expect(tuned.config!.calls).toEqual({ start: "09:00", end: "18:30", days: ["mon", "tue", "wed", "thu", "fri"] });
expect(parseConfig({ ...example, calls: { end: "20:00" } }, "x").config!.calls.start).toBe("08:00");
Expand Down
7 changes: 5 additions & 2 deletions src/domains/config/helpers/parseConfig.ts
Original file line number Diff line number Diff line change
Expand Up @@ -168,12 +168,15 @@ function isTimezone(name: string): boolean {
}
}

/** The default calling hours as a config's own copy, so nothing that edits one config's days edits the defaults. */
const defaultCallHours = (): CallHours => ({ ...DEFAULT_CALL_HOURS, days: [...DEFAULT_CALL_HOURS.days] });

/** The optional calls: section: when to call, in each prospect's own time. Every key has a default. */
function parseCalls(raw: unknown, errors: string[]): CallHours {
if (raw === undefined || raw === null) return { ...DEFAULT_CALL_HOURS, days: [...DEFAULT_CALL_HOURS.days] };
if (raw === undefined || raw === null) return defaultCallHours();
if (!isObject(raw)) {
errors.push("calls: must be a mapping (start, end, days)");
return { ...DEFAULT_CALL_HOURS };
return defaultCallHours();
}
for (const key of Object.keys(raw)) if (!["start", "end", "days"].includes(key)) errors.push(`calls.${key}: not a calls setting (start, end, days)`);
const start = text(raw.start) || DEFAULT_CALL_HOURS.start;
Expand Down
2 changes: 1 addition & 1 deletion src/domains/db/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -367,7 +367,6 @@ export function databaseFromEnv(env: Record<string, string | undefined> = proces
return undefined;
}

/** A value stored once and kept: the first call makes it, later calls read it. */
/**
* Claim a job that runs now and then (a look for new leads, logging calls)
* for every server on this database: true when it last ran at least
Expand All @@ -384,6 +383,7 @@ export async function claimRun(db: Db, key: string, now: Date, everyMs: number):
return changes > 0;
}

/** A value stored once and kept: the first call makes it, later calls read it. */
export async function metaValue(db: Db, key: string, make: () => string): Promise<string> {
const found = await db.get<{ value: string }>("SELECT value FROM meta WHERE key = ?", key);
if (found) return found.value;
Expand Down
16 changes: 13 additions & 3 deletions src/domains/decide/model.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ import type { Dossier } from "./diligence";
import { allowedAngles, combine, decisionState, outboundQuestions, reachableOn, scoreOf, tierOf, type DecisionInput } from "./model";
import type { Answer, DecisionResult } from "./types";

const NOW = new Date("2026-10-31T12:00:00Z");

const prospect = (extra: Partial<Prospect> = {}): Prospect => ({
key: "csv:1",
identities: ["csv:1", "email:[email protected]"],
Expand Down Expand Up @@ -93,7 +95,7 @@ describe("the questions", () => {
});

test("an email that bounced is not a way to reach them", () => {
expect(reachableOn(prospect(), [{ kind: "BOUNCED", channel: "EMAIL", prospectKey: "csv:1", occurredAt: "2026-10-01T10:00:00Z" } as Touch])).toEqual(["phone"]);
expect(reachableOn(prospect(), [{ kind: "BOUNCED", channel: "EMAIL", prospectKey: "csv:1", occurredAt: "2026-10-01T10:00:00Z" } as Touch], NOW)).toEqual(["phone"]);
});
});

Expand Down Expand Up @@ -128,12 +130,20 @@ describe("the decision", () => {
expect(notInterested.action).toBe("nurture");
expect(notInterested.reviewReasons[0]).toContain("they said they weren't interested on a call on 2026-10-20");
expect(combine(input({ history: [call("NOT_INTERESTED", "2026-06-01T15:00:00Z")] }), answers()).action).toBe("contact_now");
expect(reachableOn(prospect(), [call("WRONG_NUMBER", "2026-10-30T15:00:00Z")])).toEqual(["email"]);
expect(reachableOn(prospect(), [call("WRONG_NUMBER", "2026-10-28T15:00:00Z"), call("GOOD_NUMBER", "2026-10-30T15:00:00Z")])).toEqual(["email", "phone"]);
expect(reachableOn(prospect(), [call("WRONG_NUMBER", "2026-10-30T15:00:00Z")], NOW)).toEqual(["email"]);
expect(reachableOn(prospect(), [call("WRONG_NUMBER", "2026-10-28T15:00:00Z"), call("GOOD_NUMBER", "2026-10-30T15:00:00Z")], NOW)).toEqual(["email", "phone"]);
const interested = combine(input({ history: [call("INTERESTED", "2026-10-30T15:00:00Z")] }), answers({ action: choice("skip", 0.9) }));
expect(interested.reviewReasons).toContain('It says skip, but the dialer logged "interested" on a call on 2026-10-30.');
});

test("a wrong or bad number holds for 90 days, and only for the number that was dialed", () => {
const wrong = (at: string, toAddress?: string): Touch => ({ kind: "CALLED", channel: "CALL", templateId: "dialer:WRONG_NUMBER", prospectKey: "csv:1", occurredAt: at, toAddress });
expect(reachableOn(prospect(), [wrong("2026-10-30T15:00:00Z", "(512) 555-0101")], NOW)).toEqual(["email"]);
expect(reachableOn(prospect(), [wrong("2026-06-01T15:00:00Z", "(512) 555-0101")], NOW)).toEqual(["email", "phone"]);
expect(reachableOn(prospect(), [wrong("2026-10-30T15:00:00Z", "+1 512 555 0199")], NOW)).toEqual(["email", "phone"]);
expect(reachableOn(prospect(), [{ ...wrong("2026-10-30T15:00:00Z"), templateId: "dialer:BAD_NUMBER" }], NOW)).toEqual(["email"]);
});

test("an unsure call, a contradiction, or a decision on the list alone goes to you to check", () => {
expect(combine(input(), answers({ action: choice("contact_now", 0.5) })).reviewReasons).toEqual(["It isn't sure about the next step (confidence 50%)."]);
const contradiction = combine(input(), answers({ need: { type: "noul", noul: 0.05 }, timing: { type: "noul", noul: 0.05 }, authority: { type: "noul", noul: 0.1 }, fit: { type: "noul", noul: 0.4 } }));
Expand Down
27 changes: 21 additions & 6 deletions src/domains/decide/model.ts
Original file line number Diff line number Diff line change
Expand Up @@ -82,11 +82,26 @@ const day = (d: Date) => d.toISOString().slice(0, 10);
const pct = (x: number) => `${Math.round(x * 100)}%`;
const SHARED_INBOX = /^(info|hello|hi|contact|office|admin|sales|support|team|bookings?|enquiries|inquiries|service|mail|frontdesk|reception)@/i;

/** The channels a prospect can be reached on: an email that hasn't bounced, their profiles, a phone the dialer didn't find wrong. */
export function reachableOn(prospect: Prospect, history: Touch[]): Channel[] {
/** A dialed number and a phone, by their last ten digits: "(512) 555-0147" and "+1 512 555 0147" are one number. */
function sameNumber(dialed: string, phone: string | undefined): boolean {
const digits = (s: string | undefined) => (s ?? "").replace(/\D/g, "").slice(-10);
return !!digits(dialed) && digits(dialed) === digits(phone);
}

/**
* The channels a prospect can be reached on: an email that hasn't bounced,
* their profiles, and a phone, unless the dialer's latest call found that
* same number wrong or dead in the last 90 days.
*/
export function reachableOn(prospect: Prospect, history: Touch[], now: Date): Channel[] {
const bounced = history.some((t) => t.channel === "EMAIL" && (t.kind === "BOUNCED" || t.kind === "UNDELIVERABLE"));
const lastCall = latestCall(history);
const deadNumber = !!lastCall && DEAD_NUMBERS.has(lastCall.disposition);
const deadNumber =
!!lastCall &&
DEAD_NUMBERS.has(lastCall.disposition) &&
now.getTime() - Date.parse(lastCall.touch.occurredAt) < CALL_MEMORY_DAYS * 86_400_000 &&
// A call to a number they no longer have says nothing about the one they have now.
(!lastCall.touch.toAddress || sameNumber(lastCall.touch.toAddress, prospect.phone));
const found: Array<[Channel, unknown]> = [
["email", prospect.email && !bounced],
["linkedin", prospect.linkedinUrl],
Expand Down Expand Up @@ -134,7 +149,7 @@ export function decisionState(input: DecisionInput): Record<string, unknown> {
today: day(input.now),
seller: { sells_to: offer.audience, offers: offer.offer, outcome: offer.outcome, pain_it_removes: offer.pain, proof: offer.proof, writes_as: input.sender.voice === "company" ? "the company (we)" : "one person (I)" },
prospect: listFacts(input.prospect),
can_reach_them_by: reachableOn(input.prospect, input.history),
can_reach_them_by: reachableOn(input.prospect, input.history, input.now),
diligence: dossier && {
summary: dossier.summary,
offerings: short(dossier.offerings, 8),
Expand All @@ -157,7 +172,7 @@ const describeAngle = (a: Angle) => `${ANGLE_GUIDE[a].label}: ${ANGLE_GUIDE[a].w

/** The questions asked about every prospect: ten at most, so Jev answers them in one request. */
export function outboundQuestions(input: DecisionInput): Record<string, Question> {
const channels = reachableOn(input.prospect, input.history);
const channels = reachableOn(input.prospect, input.history, input.now);
const questions: Record<string, Question> = {
fit: {
type: "noul",
Expand Down Expand Up @@ -218,7 +233,7 @@ export function scoreOf(f: Record<Factor, number>): number {
*/
export function combine(input: DecisionInput, result: DecisionResult & { provider: "jev" | "claude" }, reviewBelow = REVIEW_BELOW): Decision {
const a = result.answers;
const channels = reachableOn(input.prospect, input.history);
const channels = reachableOn(input.prospect, input.history, input.now);
const budget = a.budget?.type === "score" ? a.budget.score / 3 : 0.5;
const factors: Decision["factors"] = {
fit: { value: noul(a.fit), reason: a.fit?.reason },
Expand Down
41 changes: 34 additions & 7 deletions src/domains/leads/index.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
import { DEFAULT_CALL_HOURS, type CallHours } from "../config";
import { claimRun, type Db } from "../db";
import { loadAgencyLeads } from "../prospects";
import { loadAgencyLeads, type Prospect } from "../prospects";
import type { Touch } from "../touches";
import { filterValue, type TwentyClient } from "../twenty";
import { filterAnd, filterValue, type TwentyClient, type TwentyRecord } from "../twenty";
import { countPush, lastCall, leadPush, quizLead, rankLeads, readNtfy, sendNtfy } from "./helpers";
import { LEAD_CHECK_MS, LEAD_WINDOW_DAYS, MAX_LEAD_PUSHES, MAX_LEADS_PER_CHECK, type LeadCheck, type NtfyTarget, type QuizLead } from "./types";

Expand Down Expand Up @@ -36,7 +36,9 @@ export interface LeadWatchOptions {
* they get a call while the quiz is fresh. It looks at most once a minute
* across every server on the database (the look is claimed in it), and only
* at leads newer than the last one it saw. The first look only marks the
* time: leads from before alerts were set up are never pushed.
* time: leads from before alerts were set up are never pushed. More new
* leads than one look reads come over the next looks, oldest first, and none
* is skipped.
*/
export class LeadWatch {
private nextAt = 0;
Expand Down Expand Up @@ -66,7 +68,7 @@ export class LeadWatch {
let found = 0;
try {
const hours = (await this.options.hours?.()) ?? DEFAULT_CALL_HOURS;
const rows = await loadAgencyLeads(client, { where: `createdAt[gt]:${filterValue(seen.value)}`, limit: MAX_LEADS_PER_CHECK });
const { rows, until } = await this.newLeads(client, seen.value);
// A log that can't be opened only leaves the opt-outs out, as on the Calls page.
const suppressions = rows.length ? ((await this.options.suppressions?.().catch(() => [])) ?? []) : [];
const leads = rows
Expand All @@ -76,9 +78,10 @@ export class LeadWatch {
found = leads.length;
const due = leads.filter((l) => l.qualified && !l.doNotContact);
const newest = leads.at(-1)?.createdAt;
const lots = rows.length >= MAX_LEADS_PER_CHECK;
if (due.length > MAX_LEAD_PUSHES || (lots && due.length)) {
await sendNtfy(target, countPush(due, this.options.appUrl, lots), this.options.fetch);
// More came in than one look reads: this look took the oldest of them, and the next look carries on.
const more = until !== undefined || rows.length >= MAX_LEADS_PER_CHECK;
if (due.length > MAX_LEAD_PUSHES || (more && due.length)) {
await sendNtfy(target, countPush(due, this.options.appUrl, more), this.options.fetch);
alerted = 1;
if (newest) await this.setSeen(newest);
return { looked: true, alerted, found };
Expand All @@ -97,6 +100,30 @@ export class LeadWatch {
}
}

/**
* The leads that came in after `after`: every one of them up to a time, so
* marking the newest seen never passes one that wasn't read. Twenty lists
* by id, not by time, so when more came in than one look reads, the window
* closes at the median time of what was read, again until it fits; `until`
* is where it closed, and the next look carries on from there.
*/
private async newLeads(client: TwentyClient, after: string): Promise<{ rows: Array<{ record: TwentyRecord; prospect: Prospect }>; until?: string }> {
let until: string | undefined;
for (;;) {
const where = filterAnd(`createdAt[gt]:${filterValue(after)}`, until ? `createdAt[lte]:${filterValue(until)}` : undefined);
const rows = await loadAgencyLeads(client, { where, limit: MAX_LEADS_PER_CHECK });
if (rows.length < MAX_LEADS_PER_CHECK) return { rows, until };
const times = rows
.map((r) => r.record.createdAt)
.filter((t): t is string => typeof t === "string" && t > after)
.sort();
const median = times[Math.floor((times.length - 1) / 2)];
// Hundreds of leads in one millisecond can't be told apart by time: take them as they are.
if (!median || (until !== undefined && median >= until)) return { rows, until };
until = median;
}
}

private async setSeen(at: string): Promise<void> {
await this.options.db.run("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value", SEEN_KEY, at);
}
Expand Down
41 changes: 36 additions & 5 deletions src/domains/leads/leads.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,22 @@ function fakeTwenty() {
const url = new URL(String(input));
const filter = url.searchParams.get("filter") ?? "";
const after = /createdAt\[(gt|gte)\]:"([^"]+)"/.exec(filter);
const upTo = /createdAt\[lte\]:"([^"]+)"/.exec(filter)?.[1];
const cursor = /(?:^|[(,])id\[gt\]:"([^"]+)"/.exec(filter)?.[1];
const ids = /id\[in\]:\[([^\]]*)\]/.exec(filter)?.[1]?.split(",").map((s) => s.replace(/"/g, ""));
const rows = (url.pathname === "/rest/agencyLeads" ? state.leads : state.prospects).filter((r) => {
if (ids && !ids.includes(r.id as string)) return false;
if (after) return after[1] === "gt" ? (r.createdAt as string) > after[2]! : (r.createdAt as string) >= after[2]!;
return true;
});
const limit = Number(url.searchParams.get("limit")) || Number.POSITIVE_INFINITY;
const rows = (url.pathname === "/rest/agencyLeads" ? state.leads : state.prospects)
.filter((r) => {
const at = r.createdAt as string;
if (ids && !ids.includes(r.id as string)) return false;
if (cursor && (r.id as string) <= cursor) return false;
if (upTo && at > upTo) return false;
if (after) return after[1] === "gt" ? at > after[2]! : at >= after[2]!;
return true;
})
// Like Twenty: in id order, a page at a time, as cold asks (order_by id, limit, id[gt] for the next page).
.sort((a, b) => ((a.id as string) < (b.id as string) ? -1 : (a.id as string) > (b.id as string) ? 1 : 0))
.slice(0, limit);
return Response.json({ data: { [url.pathname.slice(6)]: rows } });
}) as typeof fetch;
return { state, client: new TwentyClient({ baseUrl: "https://crm.example", apiKey: "k" }, fetchImpl) };
Expand Down Expand Up @@ -265,6 +275,27 @@ describe("LeadWatch", () => {
later(60);
expect((await w.tick()).alerted).toBe(0);
});

test("more new leads than one look reads come over the next looks, oldest first, and none is skipped", async () => {
const w = watch();
await w.tick();
later(90);
// 1,200 leads in the last minute whose ids sort in another order than their times, as Twenty's do.
const start = clock.getTime() - 60_000;
for (let i = 0; i < 1200; i++) {
twenty.state.leads.push({ id: `lead-${String((i * 7919) % 1200).padStart(4, "0")}`, contactName: `Lead ${i}`, note: note(`Lead ${i}`), qualificationStatus: "QUALIFIED", createdAt: new Date(start + i * 10).toISOString() });
}
const newest = new Date(start + 1199 * 10).toISOString();
let found = 0;
for (let look = 0; look < 10 && (await w.state()).seenUntil !== newest; look++) {
found += (await w.tick()).found;
later(90);
}
expect((await w.state()).seenUntil).toBe(newest);
expect(found).toBe(1200);
expect(ntfy.state.sent.length).toBeGreaterThan(1);
expect(ntfy.state.sent.every((s) => /^\d+\+? new quiz leads$/.test(s.body.title))).toBe(true);
});
});

describe("recentLeads", () => {
Expand Down
Loading
Loading