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
/**
* What a keep writes (design 4.9), for the TTY screen, `--yes` and
* `trail keep`, and `trail keep`'s CLI half.
*
* - A skill: on the TTY path, the skill compiled in this process (with the
* naming call's name and sentence, never its steps); on a relay path, only
* what `recompileInitSkill` gives again from the source transcript with
* the same `skillSha` (R24). Saved personal, `from: init`, consent `init`.
* - A guardrail: the catalog's template (`guardrailLearning`), every repo
* in `~/.trail/learnings/`, or this repo's personal folder.
* - A preference: the person's line read again by its pointer, sha checked,
* as the learning's body (P5); every repo, this repo, or the repo's
* committed `.trail/learnings/` after `r`.
* - A PR-review finding: phase 0's write, unchanged (TTY only: its words
* are model text and never relayed).
*
* Then the record: kept and closed ids, `recordInitClosed` for every closed
* skill (b4, R53), `pending` cleared (R66), and on the TTY path the D87
* notice of what was kept with its undo. No typed word goes into the record.
*/
import { readdirSync } from 'node:fs';
import { basename, join } from 'node:path';
import { writeEveryRepo } from '../notes/every-repo.js';
import { guardrailLearning } from '../notes/guardrails.js';
import { newLearningId } from '../notes/learning-fields.js';
import { writeNote, type WriteNoteInput } from '../notes/notes.js';
import { saveReviewFindings, type ReviewFinding } from '../notes/pr-reviews.js';
import { repoPlace } from '../notes/home.js';
import { trailHome } from '../notes/trail-home.js';
import { recordInitClosed } from '../skills/offers.js';
import { receiptTranscriptOk, receiptTranscriptRead } from '../skills/receipts.js';
import { localDate, readSettings } from '../skills/settings.js';
import { savePersonal } from '../skills/store.js';
import { stepsTotal } from '../skills/store-fs.js';
import type { KeepReceipt, Receipt } from '../skills/types.js';
import { trailPath, withLock, writePrivate } from '../util/private-fs.js';
import { track } from '../telemetry/track.js';
import { WALLS } from '../trace/walls.js';
import { readInitRecord, updateInitRecord, type KeptName, type PendingItem } from './init-record.js';
import { keepArgs, parseKeepAnswer, replyNamesList, withinAnswer } from './keep-answer.js';
import { pendingAsItem } from './handover.js';
import { afterList, linesFrom } from './keep-list.js';
import { markLookedBack } from './look-back.js';
import { readPlain } from './plain-file.js';
import { KEEP_LINE, RELAY_LINE } from './relay.js';
import { afterKeepLines, type ScreenFacts } from './review-screen.js';
import { applyName } from './name-call.js';
import { prefText } from './prefs.js';
import { lessonRefused, newLessonId, writeLesson } from '../skills/lessons.js';
import { onlyRepeats } from '../skills/follow-learnings.js';
import { recompileInitSkill, typedAt } from './replay-runs.js';
import { dayWords } from './review-screen.js';
import type { InitItem, KeepAnswer } from './types.js';
export { leadWords, parseKeepAnswer, replyNamesList } from './keep-answer.js';
export interface KeepResult {
kept: InitItem[]; notKept: InitItem[]; refused: Array<{ item: InitItem; why: string }>;
/** Part 7: kept preferences that only repeat a step of a skill kept with them, kept as a lesson on that skill instead. */
folded?: Array<{ item: InitItem; skill: string }>;
}
/** Where a keep writes: the checkout (phase 0's notes) and its repo key; the run it answers; PR-review findings in memory. */
export interface KeepPlace {
dir: string;
repoKey: string;
runId?: string | null;
reviews?: Map<string, ReviewFinding>;
}
const span = (c: InitItem['count']) => (c.from === c.to ? dayWords(c.from) : `${dayWords(c.from)} to ${dayWords(c.to)}`);
/** A learning mined from past sessions is dated the day it was first said or hit, never the day it was kept. */
const firstDay = (c: InitItem['count'], now: Date) => (/^\d{4}-\d{2}-\d{2}$/.test(c.from) ? c.from : localDate(now));
/** phase 0's `writeNote` resolves the Trail home from process.env: refuse rather than write another home than `env`'s. */
function sameHome(env: NodeJS.ProcessEnv): boolean {
return trailHome(env) === trailHome(process.env);
}
/** The person's line for a preference, whole, read again now; null when it changed or is gone. */
export function prefLine(item: Pick<InitItem, 'pref'>, env: NodeJS.ProcessEnv): string | null {
const ref = item.pref?.refs[0];
const text = ref ? typedAt(ref, env) : null;
const line = text ? prefText(text) : '';
return line || null;
}
const TITLE_MAX = 120;
/** A preference's title: its line, or over 120 characters cut after the last whole word that fits, with an ellipsis. */
export function prefTitle(line: string): string {
if (line.length <= TITLE_MAX) return line;
// Room for the ellipsis; a word that ends right at the cut is whole.
const fit = line.slice(0, TITLE_MAX - 1);
const at = /\s/.test(line[TITLE_MAX - 1]!) ? fit.length : fit.lastIndexOf(' ');
return `${(at > 0 ? fit.slice(0, at) : fit).replace(/[\s,.;:]+$/, '')}…`;
}
function keepSkill(item: InitItem, how: 'tty' | 'yes' | 'keep', place: KeepPlace, env: NodeJS.ProcessEnv, now: Date): { id: string; name: string; steps: string[] } | string {
const s = item.skill;
if (!s) return 'gone';
let compiled = s.compiled;
if (how === 'tty') {
if (!compiled) return 'gone';
if (item.title && item.title !== compiled.name) compiled = applyName(compiled, { title: item.title, description: item.description || compiled.description });
} else {
const again = recompileInitSkill(s.src, place.repoKey, env, now);
if (!again.ok) return again.why;
compiled = again.compiled;
}
try {
const ref = savePersonal(compiled, { from: 'init', runId: compiled.source.runId, consent: 'init', stepsVerified: stepsTotal(compiled), env, now });
track('skill_saved', { from: 'init', scope: 'personal' });
return { id: ref.id, name: compiled.name, steps: compiled.steps.map((s) => s.cmd) };
} catch (e) {
return e instanceof Error && /name|taken|exists/i.test(e.message) ? 'taken' : 'failed';
}
}
function keepGuardrail(item: InitItem, place: KeepPlace, env: NodeJS.ProcessEnv, now: Date): { id: string; name: string } | string {
const cls = item.guardrail?.cls;
const w = WALLS.find((x) => x.cls === cls);
if (!cls || !w?.guardrail) return 'gone';
const input = { ...guardrailLearning(cls, item.applies, `${w.words} on ${item.count.days} days, ${span(item.count)}`, now), date: firstDay(item.count, now) };
if (input.applies === 'every repo') {
const path = writeEveryRepo(input, w.guardrail.fileName, env);
return { id: newLearningId(basename(path)), name: item.plainName };
}
if (!sameHome(env)) return 'failed';
const n = writeNote(place.dir, { ...input, applies: place.repoKey } as WriteNoteInput, 'personal');
return { id: n.id ?? '', name: item.plainName };
}
function keepPreference(item: InitItem, place: KeepPlace, env: NodeJS.ProcessEnv, now: Date): { id: string; name: string } | string {
const line = prefLine(item, env);
if (!line) return 'gone';
const input: WriteNoteInput = {
title: prefTitle(line), body: line, author: '', date: firstDay(item.count, now), kind: 'preference', src: 'init-typed', standing: true,
evidence: `said on ${item.count.days} days, ${span(item.count)}`,
};
if (item.scope !== 'repo' && item.applies === 'every repo') {
const file = `pref-${item.key.replace(/^pref:/, '').replace(/[^a-z0-9]/g, '').slice(0, 16) || item.id.slice(2)}.md`;
const path = writeEveryRepo(input, file, env);
return { id: newLearningId(basename(path)), name: '' };
}
if (!sameHome(env)) return 'failed';
const n = writeNote(place.dir, item.scope === 'repo' ? input : { ...input, applies: place.repoKey }, item.scope === 'repo' ? 'repo' : 'personal');
return { id: n.id ?? '', name: '' };
}
/**
* Part 7: the skill kept here whose steps a preference only repeats ("run scripts/gen_schema.py" beside a skill whose
* step runs it), so the agent hears it once, with the skill. Only a preference for this repo just for the person: one
* for every repo or added to the repo says more than one skill's step, and keeps its own place.
*/
function foldInto(item: InitItem, skills: Array<{ name: string; steps: string[] }>, env: NodeJS.ProcessEnv): { name: string; line: string } | null {
if (item.scope === 'repo' || item.applies === 'every repo' || !skills.length) return null;
const line = prefLine(item, env);
if (!line || lessonRefused(line)) return null;
const s = skills.find((k) => onlyRepeats(line, k.steps));
return s ? { name: s.name, line } : null;
}
/** The preference as a lesson on the skill: the person's own words, dated the day they first said it. */
function keepAsLesson(item: InitItem, into: { name: string; line: string }, place: KeepPlace, env: NodeJS.ProcessEnv, now: Date): { id: string; name: string } {
const id = newLessonId();
writeLesson({ id, skill: into.name, at: firstDay(item.count, now), text: into.line, kind: 'lesson', src: 'correction', wall: null }, place.repoKey, env);
return { id, name: '' };
}
function keepReview(item: InitItem, place: KeepPlace): { id: string; name: string } | string {
const f = place.reviews?.get(item.id);
if (!f) return 'gone';
const [n] = saveReviewFindings(place.dir, [f]);
return n ? { id: n.id ?? '', name: '' } : 'failed';
}
/**
* Writes what the person picked: skills (savePersonal, consent 'init'), guardrails and preferences (every-repo.ts,
* or writeNote for one repo), PR-review findings (phase 0). `all` is every item shown; on 'tty' and 'keep' the
* shown items not kept are closed (a refused one is neither: it can come back), on 'yes' they stay pending.
*/
export function keepItems(picked: InitItem[], all: InitItem[], how: 'tty' | 'yes' | 'keep', env: NodeJS.ProcessEnv = process.env, now: Date = new Date(),
place?: KeepPlace): KeepResult {
const at = place ?? { dir: process.cwd(), repoKey: all[0]?.applies && all[0].applies !== 'every repo' ? all[0].applies : '' };
const kept: InitItem[] = [];
const refused: KeepResult['refused'] = [];
const names: KeptName[] = [];
// Part 7: skills first, so a preference that only repeats a step of one kept here goes into it as a lesson.
const skills: Array<{ name: string; steps: string[] }> = [];
const folded: NonNullable<KeepResult['folded']> = [];
for (const item of [...picked].sort((a, b) => Number(b.kind === 'skill') - Number(a.kind === 'skill'))) {
let r: { id: string; name: string } | string;
try {
const into = item.kind === 'preference' ? foldInto(item, skills, env) : null;
r = item.kind === 'skill' ? keepSkill(item, how, at, env, now)
: item.kind === 'guardrail' ? keepGuardrail(item, at, env, now)
: into ? keepAsLesson(item, into, at, env, now)
: item.kind === 'preference' ? keepPreference(item, at, env, now)
: keepReview(item, at);
if (typeof r !== 'string' && 'steps' in r) skills.push({ name: r.name, steps: r.steps as string[] });
if (into && typeof r !== 'string') folded.push({ item, skill: into.name });
} catch {
r = 'failed';
}
if (typeof r === 'string') {
refused.push({ item, why: r });
continue;
}
kept.push(item);
names.push({ kind: item.kind, name: r.name, id: r.id, forget: r.name || r.id });
}
const pickedIds = new Set(picked.map((i) => i.id));
const notKept = all.filter((i) => !pickedIds.has(i.id));
const closed = how === 'yes' ? [] : notKept;
for (const c of closed) if (c.kind === 'skill' && at.repoKey) {
try {
recordInitClosed(at.repoKey, c.key, env, now);
} catch { /* the record still closes it */ }
}
if (at.repoKey) {
updateInitRecord(at.repoKey, (r) => {
const keptIds = kept.map((i) => i.id);
const closedIds = closed.map((i) => i.id);
r.closed = [...new Set([...r.closed, ...closedIds])];
const done = new Set([...keptIds, ...closedIds]);
r.deferred = r.deferred.filter((id) => !done.has(id));
const run = r.runs.find((x) => x.id === (at.runId ?? r.pendingFrom));
if (run) {
run.kept = [...new Set([...run.kept, ...keptIds])];
run.closed = [...new Set([...run.closed, ...closedIds])];
}
if (how !== 'yes') {
r.pending = [];
r.pendingFrom = null;
r.handedAt = null;
r.handover = null;
} else {
const gone = new Set(keptIds);
r.pending = r.pending.filter((p) => !gone.has(p.id));
}
if (how === 'tty' && names.length) {
// A notice no session start has named yet keeps its items: each kept item is named once (D87, O8, b6 review).
const earlier = r.notice && r.notice.shownAt === null ? r.notice.items.filter((x) => !names.some((y) => y.id === x.id)) : [];
r.notice = { run: run?.id ?? at.runId ?? 'ir-0000', at: now.toISOString(), items: [...earlier, ...names].slice(-20), shownAt: null };
}
}, env);
}
track('cold_start', { source: how === 'keep' ? 'keep' : 'sessions', outcome: 'kept' });
return { kept, notKept, refused, ...(folded.length ? { folded } : {}) };
}
/* -------------------------------------------------------------------------- */
/* trail keep: the CLI half (4.9) */
/* -------------------------------------------------------------------------- */
/** A keep receipt older than this is stale (2.11). */
const FRESH_MS = 2 * 60 * 60_000;
const AHEAD_MS = 5_000;
export const KEEP_USAGE = 'trail keep <numbers> keeps items from the list trail init printed, after the person typed their numbers: trail keep 1 3, trail keep all, or trail keep none';
export const KEEP_HELD = "Nothing kept: Trail couldn't find the person's answer after the list.";
export const KEEP_AT_TTY = 'Pick in your terminal: trail init --look-back';
export const KEEP_NOTHING_WAITS = 'Nothing waits for an answer in this repo: run trail init to look back at your past sessions.';
function asKeepReceipt(v: unknown): KeepReceipt | null {
const r = v as KeepReceipt;
if (!r || typeof r !== 'object' || r.v !== 1 || r.kind !== 'keep' || typeof r.session !== 'string' || typeof r.transcriptPath !== 'string') return null;
if (!r.list || !Number.isSafeInteger(r.list.offset) || typeof r.list.initRunId !== 'string' || (r.list.via !== 'init-call' && r.list.via !== 'handover')) return null;
if (!r.typed || !Number.isSafeInteger(r.typed.offset) || typeof r.typed.lineSha !== 'string' || typeof r.replySha !== 'string' || typeof r.at !== 'string') return null;
if (r.verdict !== 'live' || (r.usedAt !== null && typeof r.usedAt !== 'string')) return null;
return r;
}
/** The newest unused, fresh keep receipt for this list (the record's `pendingFrom`), and its path. */
function findKeepReceipt(runId: string, env: NodeJS.ProcessEnv, now: Date): { path: string; r: KeepReceipt } | null {
const dir = trailPath(env, 'receipts');
let names: string[];
try {
names = readdirSync(dir).filter((n) => n.endsWith('.keep.json'));
} catch {
return null;
}
let best: { path: string; r: KeepReceipt } | null = null;
for (const n of names) {
const path = join(dir, n);
const text = readPlain(path, 64 * 1024);
let r: KeepReceipt | null = null;
try {
r = text === null ? null : asKeepReceipt(JSON.parse(text));
} catch { /* not a receipt */ }
if (!r || r.usedAt !== null || r.list.initRunId !== runId) continue;
const age = now.getTime() - Date.parse(r.at);
if (Number.isNaN(age) || age > FRESH_MS || age < -AHEAD_MS) continue;
if (!best || Date.parse(r.at) > Date.parse(best.r.at)) best = { path, r };
}
return best;
}
const sameNumbers = (a: KeepAnswer, b: KeepReceipt['numbers']) =>
'none' in a ? b === 'none' : 'all' in a ? b === 'all' : Array.isArray(b) && JSON.stringify([...b].sort((x, y) => x - y)) === JSON.stringify(a.numbers);
/** The list's text at the receipt's offset: the tool_result there must hold the relay and keep lines. */
function listTextAt(path: string, offset: number): string | null {
const [first] = linesFrom(path, { from: offset, bytes: 2 * 1024 * 1024 }) ?? [];
if (!first || first.offset !== offset) return null;
try {
const e = JSON.parse(first.line) as { type?: string; message?: { content?: unknown } };
if (e.type !== 'user' || !Array.isArray(e.message?.content)) return null;
for (const part of e.message!.content as Array<Record<string, unknown>>) {
if (part?.type !== 'tool_result') continue;
const c = part.content;
const text = typeof c === 'string' ? c : Array.isArray(c) ? c.map((x) => (typeof (x as { text?: unknown })?.text === 'string' ? (x as { text: string }).text : '')).join('\n') : '';
if (text.includes(RELAY_LINE) && text.includes(KEEP_LINE)) return text;
}
} catch { /* not a list */ }
return null;
}
/** A relayed item as keep needs it, rebuilt from the record: the person's line read again for a preference's title. */
/**
* The CLI half of `trail keep` (4.9). Always needs a KeepReceipt (R23): the PreToolUse half wrote it after it found
* the list, the agent's reply naming every item, and the person's typed numbers. Here everything is read again from
* the transcript, and only what still agrees is kept.
*/
export function keepCommand(args: string[], env: NodeJS.ProcessEnv, now: Date = new Date(),
opts: { dir?: string; tty?: boolean; onFound?: () => void } = {}): { code: 0 | 1; lines: string[] } {
if (args.some((a) => a === '--help' || a === '-h')) return { code: 0, lines: [KEEP_USAGE] };
const asked = keepArgs(args);
if (!asked) return { code: 1, lines: [KEEP_USAGE] };
const dir = opts.dir ?? process.cwd();
const repoKey = repoPlace(dir, env).key;
const record = readInitRecord(repoKey, env);
if (!record.pending.length || !record.pendingFrom) return { code: 1, lines: [KEEP_NOTHING_WAITS] };
const tty = opts.tty ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
const found = findKeepReceipt(record.pendingFrom, env, now);
if (!found) return { code: 1, lines: [tty ? KEEP_AT_TTY : KEEP_HELD] };
const r = found.r;
const held = { code: 1 as const, lines: [KEEP_HELD] };
const asReceipt = { ...r, host: 'claude', tier: 'A' } as unknown as Receipt;
if (!receiptTranscriptOk(asReceipt, env) || !receiptTranscriptRead(asReceipt, env)) return held;
const all = record.pending.map((p) => pendingAsItem(p, env));
const names = all.map((i) => ({ n: i.n, nameWords: i.nameWords }));
if (r.list.via === 'init-call') {
const text = listTextAt(r.transcriptPath, r.list.offset);
if (!text || !replyNamesList(text, names)) return held;
} else if (record.handover?.session !== r.session || record.handover.offset !== r.list.offset) return held;
const after = afterList(r.transcriptPath, r.list, env);
if (!after || after.tampered || !after.typed || after.replySha !== r.replySha) return held;
if (after.typed.offset !== r.typed.offset || after.typed.lineSha !== r.typed.lineSha || !replyNamesList(after.reply, names)) return held;
const typed = parseKeepAnswer(after.typed.text);
const listed = all.map((i) => i.n);
if (!typed || !sameNumbers(asked, r.numbers) || !withinAnswer(asked, typed, listed)) return held;
// Deferred items (B5): only when the person's typed numbers named them on this list.
const deferred = new Set(record.deferred);
const named = 'numbers' in typed ? new Set(typed.numbers) : new Set<number>();
const want = 'none' in asked ? [] : 'all' in asked ? listed : asked.numbers;
// A deferred item the typed numbers didn't name is neither kept nor closed: it waits for the person's own init.
const waits = new Set(all.filter((i) => deferred.has(i.id) && !named.has(i.n)).map((i) => i.id));
const picked = all.filter((i) => want.includes(i.n) && !waits.has(i.id));
opts.onFound?.();
// The receipt is claimed before anything is written: a second keep that found it too gets nothing (b6 review).
if (!claimKeep(found.path, r, now)) return held;
const result = keepItems(picked, all.filter((i) => !waits.has(i.id)), 'keep', env, now, { dir, repoKey, runId: record.pendingFrom });
markLookedBack(dir, now, env);
const s = readSettings(env);
const facts = { skills: s.skills === 'on', offers: s.offers, offersOffAt: s.offersOffAt } as ScreenFacts;
return { code: 0, lines: afterKeepLines({ ...result, how: 'keep' }, facts) };
}
/** Sets usedAt on the receipt under its lock; true only when it was still this one and unused (this keep owns it). */
function claimKeep(path: string, r: KeepReceipt, now: Date): boolean {
try {
const done = withLock(path, () => {
const text = readPlain(path, 64 * 1024);
const cur = text === null ? null : asKeepReceipt(JSON.parse(text));
if (!cur || cur.usedAt !== null || cur.at !== r.at || cur.typed.lineSha !== r.typed.lineSha) return false;
writePrivate(path, `${JSON.stringify({ ...cur, usedAt: now.toISOString() }, null, 2)}\n`);
return true;
}, 1000);
return done.ok && done.value === true;
} catch {
return false;
}
}