Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* The pool (design 2.3): for one repo, the days each job came back, kept in
* `~/.trail/repos/<key>/pool.json` beside phase 0's repo folder. A day is a
* session-day: the local date a run started on and the session's hash, with
* whether that run cost much (5+ tool calls or a failure). Job words from a
* fixed vocabulary and days only: no prompt text, no commands.
*
* Only jobs that can reach moment 2 are counted (release, ship, tests,
* report). A job is due an offer on its 3rd session-day in the last 45 days
* counting today (the 4th under the governor), at least 2 of them costly.
* Days older than that are dropped on every write.
*/
import { readdirSync, statSync } from 'node:fs';
import { join, relative, sep } from 'node:path';
import { localDate, readSettings } from '../skills/settings.js';
import { readJsonSafe, trailPath, withLock, writePrivate } from '../util/private-fs.js';
import { OFFER_FAMILIES } from './jobs.js';
import type { JobClass, JobMatch } from './types.js';
export interface PoolDay { d: string; s: string; costly: boolean } // local date, session hash
export interface PoolEntry { words: string[]; days: PoolDay[]; lastGoodRun: string | null; lastSeen: string; shownAtInit: boolean }
export interface PoolFile { v: 1; jobs: Partial<Record<JobClass, PoolEntry>> }
export interface RepeatVerdict { ok: boolean; sessionDays: number; dates: number; costlyDays: number; need: number }
/** The window: today and the 44 days before it. */
const WINDOW_DAYS = 45;
const MAX_WORDS = 12;
const DATE = /^\d{4}-\d{2}-\d{2}$/;
/** The first local date inside the 45-day window that ends today. */
function windowStart(now: Date): string {
const d = new Date(now.getFullYear(), now.getMonth(), now.getDate() - (WINDOW_DAYS - 1), 12);
return localDate(d);
}
const offerJob = (job: string): job is JobClass => Object.prototype.hasOwnProperty.call(OFFER_FAMILIES, job);
/** join(trailHome, 'repos', ...repoKey.split('/'), 'pool.json'): the same folder as repoPlace(..).dir. */
export function poolPath(repoKey: string, env?: NodeJS.ProcessEnv): string {
const parts = String(repoKey).split('/').filter((p) => p && p !== '.' && p !== '..');
return trailPath(env, 'repos', ...parts, 'pool.json');
}
function cleanEntry(v: unknown): PoolEntry | null {
if (!v || typeof v !== 'object' || Array.isArray(v)) return null;
const e = v as Partial<PoolEntry>;
const days = Array.isArray(e.days)
? e.days.filter((d): d is PoolDay => !!d && typeof d.d === 'string' && DATE.test(d.d) && typeof d.s === 'string').map((d) => ({ d: d.d, s: d.s, costly: d.costly === true }))
: [];
return {
words: Array.isArray(e.words) ? e.words.filter((w): w is string => typeof w === 'string').slice(0, MAX_WORDS) : [],
days,
lastGoodRun: typeof e.lastGoodRun === 'string' ? e.lastGoodRun : null,
lastSeen: typeof e.lastSeen === 'string' ? e.lastSeen : days.map((d) => d.d).sort().at(-1) ?? '',
shownAtInit: e.shownAtInit === true,
};
}
function parsePool(raw: unknown): PoolFile {
const jobs: PoolFile['jobs'] = {};
const r = raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as { jobs?: unknown }) : {};
if (r.jobs && typeof r.jobs === 'object' && !Array.isArray(r.jobs)) {
for (const [job, v] of Object.entries(r.jobs as Record<string, unknown>)) {
const e = cleanEntry(v);
if (e && offerJob(job)) jobs[job] = e;
}
}
return { v: 1, jobs };
}
export function readPool(repoKey: string, env?: NodeJS.ProcessEnv): PoolFile {
return parsePool(readJsonSafe<unknown>(poolPath(repoKey, env)));
}
/** Adds or updates the (d, s) day for a job (costly OR-ed), prunes days older than 45 and entries unseen for 45 days. Locked; null when the lock timed out. */
export function notePoolDay(repoKey: string, m: JobMatch, day: PoolDay, goodRun: string | null, env?: NodeJS.ProcessEnv, now: Date = new Date()): PoolEntry | null {
if (!offerJob(m.job) || !DATE.test(day.d)) return null;
const path = poolPath(repoKey, env);
const from = windowStart(now);
const done = withLock(path, () => {
const raw = readJsonSafe<unknown>(path);
const keep = raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
const pool = parsePool(raw);
const e: PoolEntry = pool.jobs[m.job] ?? { words: [], days: [], lastGoodRun: null, lastSeen: day.d, shownAtInit: false };
for (const w of m.words) if (e.words.length < MAX_WORDS && !e.words.includes(w)) e.words.push(w);
const same = e.days.find((x) => x.d === day.d && x.s === day.s);
if (same) same.costly = same.costly || day.costly;
else e.days.push({ d: day.d, s: day.s, costly: day.costly });
e.days.sort((a, b) => (a.d < b.d ? -1 : a.d > b.d ? 1 : 0));
if (goodRun) e.lastGoodRun = goodRun;
if (day.d > e.lastSeen) e.lastSeen = day.d;
pool.jobs[m.job] = e;
for (const [job, entry] of Object.entries(pool.jobs) as Array<[JobClass, PoolEntry]>) {
entry.days = entry.days.filter((x) => x.d >= from);
if (!entry.days.length || entry.lastSeen < from) delete pool.jobs[job];
}
writePrivate(path, JSON.stringify({ ...keep, v: 1, jobs: pool.jobs }));
return pool.jobs[m.job] ?? null;
});
return done.ok ? done.value : null;
}
/** 3rd session-day in 45 days (4th when extraDay), at least 2 of them costly. */
export function repeatedEnough(e: PoolEntry, extraDay: boolean, now: Date = new Date()): RepeatVerdict {
const from = windowStart(now);
const today = localDate(now);
const days = e.days.filter((x) => x.d >= from && x.d <= today);
const sessionDays = new Set(days.map((x) => `${x.d}|${x.s}`)).size;
const costlyDays = new Set(days.filter((x) => x.costly).map((x) => `${x.d}|${x.s}`)).size;
const dates = new Set(days.map((x) => x.d)).size;
const need = extraDay ? 4 : 3;
return { ok: sessionDays >= need && costlyDays >= 2, sessionDays, dates, costlyDays, need };
}
/** The governor from the settings cache (4.13 step 7): 3 or more answers lately, fewer than 1 in 3 a yes. */
function governorOn(env?: NodeJS.ProcessEnv): boolean {
const nine = readSettings(env).lastNine;
return nine.length >= 3 && nine.filter((a) => a === 'yes').length * 3 < nine.length;
}
/** Every pool.json under `dir`, as repo keys (the folders between `repos/` and the file). */
function poolKeys(root: string, dir: string, depth: number, out: string[]): void {
if (depth > 6) return;
let names: string[];
try {
names = readdirSync(dir);
} catch {
return;
}
for (const name of names) {
const p = join(dir, name);
if (name === 'pool.json') out.push(relative(root, dir).split(sep).join('/'));
else if (!name.startsWith('.')) {
try {
if (statSync(p).isDirectory()) poolKeys(root, p, depth + 1, out);
} catch { /* gone */ }
}
}
}
/** Every job counted in the last 45 days, every repo, for `trail skills` (2.10). */
export function watching(env?: NodeJS.ProcessEnv, now: Date = new Date()): Array<{ repoKey: string; job: JobClass; sessionDays: number; costlyDays: number; need: number }> {
const root = trailPath(env, 'repos');
const keys: string[] = [];
poolKeys(root, root, 0, keys);
const extra = keys.length ? governorOn(env) : false;
const out: Array<{ repoKey: string; job: JobClass; sessionDays: number; costlyDays: number; need: number }> = [];
for (const repoKey of keys.filter(Boolean)) {
for (const [job, e] of Object.entries(readPool(repoKey, env).jobs) as Array<[JobClass, PoolEntry]>) {
const v = repeatedEnough(e, extra, now);
if (v.sessionDays > 0) out.push({ repoKey, job, sessionDays: v.sessionDays, costlyDays: v.costlyDays, need: v.need });
}
}
return out;
}