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 words of moments 5 and 6 and the retire proposal (phase 2 design 4.7
* to 4.9, R11, R19, R24): their two lines, the Stop reason and post-tool
* text around them, and what the agent reads on each answer. `offer-words.ts`
* hands moments update, drift and retire here; 1b's lesson and repair words
* never see them (R11: they would name `trail skills lesson` or `add`).
*
* D88, D101, D107: every text says it is from Trail, gives Trail's own
* reason, quotes the words the person typed when it answers them (in the
* hook output only, never on disk), says who checks the answer, and never
* tells the agent to recite, to skip asking, or what one yes covers.
* Commands in a line are the agent's own from this session (through
* compile's secret check), one line, cut at 60 characters, in single quotes
* (R24). Lines are counted facts; no model writes any of them (P16).
*
* Never "memory" or "remember", no em dashes: the words tests read this file.
*/
import type { PendingOffer, TypedAnswer } from '../trace/types.js';
import type { HookOut } from './types.js';
import type { Host } from '../trace/host.js';
import { flatLine } from '../notes/flatten.js';
import { JOB_CLASSES } from '../trace/jobs.js';
import { hostFacts } from './host-facts.js';
import { FROM_TRAIL, quoteOf } from './directive-words.js';
import { notSaved } from './offer-words.js';
/** Moment 5 (4.7). `line2*` end with the keys the person answers with. */
export const UPDATE_COPY = {
line1Update: '{check} This time step {step} of {name} failed and {cmds} worked instead.',
line1Preference: '{check} This time {steps} of {name} ran as {cmds}, the way {follows} says.',
line2Preference: 'Change {steps} of {name} to match? {size} (yes / show me / no)',
line1Extend: '{check} This time {name} also needed {cmds} {where}.',
line1Split: '{check} This time {name} ran only steps {from} to {to}, as it did last time.',
line2Lesson: 'Fold your {date} lesson into {name} as {steps}? {size} (yes / show me / no)',
line2TwoUses: 'Add {it} to {name} as {steps}? {They} ran in your last 2 {jobs}. {size} (yes / show me / no)',
line2Update: 'Change step {step} of {name} to the command that worked? {size} (yes / show me / no)',
line2Split: 'Keep steps {from} to {to} as their own skill, {new}, beside {name}? (yes / show me / no)',
size: '{n} line changes.',
handEdited: 'You changed {name} by hand, so Trail writes it beside your file for you to compare.',
reason: 'Skill {name} just ran and checked out, and this run did one thing differently; Trail offers once to change the skill to match.',
offered: 'Trail offered to change the skill {name} to match how this job just ran',
reasonSplit: 'A skill Trail brought in just ran only some of its steps, the same ones as last time; Trail offers once to keep those steps as a skill of their own, {name}.',
offeredSplit: 'Trail offered to keep steps of a skill as a skill of their own, {name}',
} as const;
/** Moment 6 (4.8, J15, P16). */
export const DRIFT_COPY = {
line1: '{check} {name} needs a fix, and this {job} went another way: {how}.',
line2: 'Replace {name} with the {k} steps that just worked, retire it, or leave it? (replace / retire / leave it)',
line2Hand: 'Write the {k} steps that just worked beside your edited {name}, retire it, or leave it? (replace / retire / leave it)',
reason: 'Skill {name} needs a fix, and this job just checked out another way; Trail offers once to replace it, retire it or leave it.',
offered: 'Trail offered to replace the skill {name} with the steps that just worked',
} as const;
/** The retire proposal (4.9, P13). */
export const RETIRE_COPY = {
line1: 'Trail brought in skill {name} {n} times lately, and its steps ran in {k} of them.',
line2: 'Retire it? trail skills restore {name} brings it back. (retire / keep it)',
reason: 'Trail brought in skill {name} for jobs here and its steps mostly did not run; it offers once, ever, to retire a skill like that.',
offered: 'Trail offered to retire the skill {name}',
retired: 'Trail retired {name}. Tell them in one line, with how to bring it back: trail skills restore {name}.',
busy: "Trail couldn't retire it just now: the person can run trail forget {name}. Tell them that in one line.",
} as const;
const LINE_MAX = 400;
const fill = (t: string, v: Record<string, string | number>) => t.replace(/\{(\w+)\}/g, (m, k: string) => (v[k] === undefined ? m : String(v[k])));
const one = (v: unknown, max = 60) => flatLine(v, max);
/** A command as a line shows it (R24): one line, at most 60 characters, its own single quotes made double, in single quotes. */
export const quoted = (cmd: string) => `'${one(String(cmd ?? '').replace(/'/g, '"'), 60)}'`;
const both = (items: string[]) => (items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`);
const nounOf = (job: string) => JOB_CLASSES.find((j) => j.job === job)?.noun ?? job ?? 'job';
const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
/** A lesson's local date ('2026-10-30') as 'Oct 30'; never shifted by the time zone. */
function dayWords(local: string | undefined): string {
const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(local ?? ''));
return m && MONTHS[Number(m[2]) - 1] ? `${MONTHS[Number(m[2]) - 1]} ${Number(m[3])}` : 'an earlier';
}
const pairOf = (a: string, b: string): [string, string] => [flatLine(a, LINE_MAX), flatLine(b, LINE_MAX)];
export interface UpdateFacts {
op: 'update' | 'extend' | 'split';
why?: 'failed-then-worked' | 'lesson' | 'two-uses' | 'preference';
/** Part 7, why 'preference': whose learning the steps followed ("your preference"), and every step it changes. */
follows?: string;
steps?: number[];
/** The job's check as 1a's `checkLine` says it ("Published 0.22.4: npm shows it."). */
check: string;
name: string;
job: string;
/** update: the step changed; extend: the skill step the new ones go after (0: before step 1). */
at: number;
/** The new or changed steps, filled with this run's values. */
cmds: string[];
/** Run lines the change touches (`runLinesChanged`). */
changes: number;
lessonDate?: string;
split?: { from: number; to: number; name: string };
handEdited: boolean;
}
/** 4.7: moment 5's two lines. */
export function updateLines(f: UpdateFacts): [string, string] {
const C = UPDATE_COPY;
const name = one(f.name);
const check = one(f.check, 160);
const cmds = both(f.cmds.slice(0, 2).map(quoted));
const size = f.handEdited ? fill(C.handEdited, { name }) : fill(C.size, { n: Math.max(0, Math.floor(f.changes)) });
if (f.op === 'split' && f.split) {
const s = { from: f.split.from, to: f.split.to };
return pairOf(fill(C.line1Split, { check, name, ...s }), fill(C.line2Split, { ...s, name, new: one(f.split.name) }));
}
if (f.op === 'update') {
if (f.why === 'preference' && f.follows) {
const ns = f.steps?.length ? f.steps : [f.at];
const steps = ns.length === 1 ? `step ${ns[0]}` : `steps ${both(ns.map(String))}`;
const all = f.cmds.map(quoted);
const ran = all.length > 2 ? `${all.slice(0, 2).join(', ')} and ${all.length - 2} more` : both(all);
return pairOf(fill(C.line1Preference, { check, name, steps, cmds: ran, follows: one(f.follows) }), fill(C.line2Preference, { steps, name, size }));
}
return pairOf(fill(C.line1Update, { check, name, step: f.at, cmds }), fill(C.line2Update, { step: f.at, name, size }));
}
const n = Math.min(2, Math.max(1, f.cmds.length));
const steps = n === 1 ? `step ${f.at + 1}` : `steps ${f.at + 1} and ${f.at + 2}`;
const where = f.at > 0 ? `after step ${f.at}` : 'before step 1';
const line1 = fill(C.line1Extend, { check, name, cmds, where });
const line2 = f.why === 'lesson'
? fill(C.line2Lesson, { date: dayWords(f.lessonDate), name, steps, size })
: fill(C.line2TwoUses, { it: n === 1 ? 'it' : 'them', They: n === 1 ? 'It' : 'They', name, steps, jobs: `${nounOf(f.job)}s`, size });
return pairOf(line1, line2);
}
export interface DriftFacts {
check: string; name: string; job: string;
/** Run steps of the fresh compile (the new version's). */
steps: number;
/** Skill steps that didn't run, and fresh steps that match no skill step, in order. */
skipped: Array<{ n: number; cmd: string }>;
ran: string[];
handEdited: boolean;
}
/** 4.8: moment 6's two lines; at most 2 named each way. */
export function driftLines(f: DriftFacts): [string, string] {
const C = DRIFT_COPY;
const name = one(f.name);
const skipped = both(f.skipped.slice(0, 2).map((s) => `${quoted(s.cmd)} (step ${s.n})`));
const ran = both(f.ran.slice(0, 2).map(quoted));
const how = skipped && ran ? `it skipped ${skipped} and ran ${ran}` : skipped ? `it skipped ${skipped}` : `it ran ${ran}`;
const line1 = fill(C.line1, { check: one(f.check, 160), name, job: nounOf(f.job), how });
return pairOf(line1, fill(f.handEdited ? C.line2Hand : C.line2, { name, k: Math.max(0, Math.floor(f.steps)) }));
}
export interface RetireFacts { name: string; fired: number; followed: number }
/** 4.9: the retire proposal's two lines. */
export function retireLines(f: RetireFacts): [string, string] {
const name = one(f.name);
return pairOf(fill(RETIRE_COPY.line1, { name, n: Math.floor(f.fired), k: Math.floor(f.followed) }), fill(RETIRE_COPY.line2, { name }));
}
/** Why the 2 lines end the reply (as 1a and 1b say it). */
const SO_THEY_ANSWER = 'so the person can answer (Trail reads their answer to the last line, so keep it as it is)';
const CHECKS = 'Trail checks their answer in this session before it changes anything';
const CHECKS_KEEP = 'Trail checks their answer in this session before it keeps anything';
const idOf = (o: PendingOffer) => one(o.offerId, 40);
const runOf = (o: PendingOffer) => one(o.runId, 40);
const isSplit = (o: PendingOffer) => o.moment === 'update' && o.fold?.op === 'split';
/** The skill an offer is about: its folder name. A split's offer names the new skill (its lines name the old one). */
const skillName = (o: PendingOffer) => one(o.name);
function reason(o: PendingOffer): string {
const name = skillName(o);
if (o.moment === 'drift') return fill(DRIFT_COPY.reason, { name });
if (o.moment === 'retire') return fill(RETIRE_COPY.reason, { name });
if (isSplit(o)) return fill(UPDATE_COPY.reasonSplit, { name });
return fill(UPDATE_COPY.reason, { name });
}
/** The command a yes runs (4.11): `trail skills update` for update, extend and replace; 1a's add for a split. */
export function yesCommand2(o: PendingOffer): string {
if (isSplit(o)) return `trail skills add ${one(o.fold?.splitName ?? o.name)} --run ${runOf(o)}`;
return `trail skills update ${one(o.name)} --offer ${idOf(o)}`;
}
/** After "show me": the draft, then the offer's own last line again, so Trail reads the answer to it (D72). */
const showStep = (o: PendingOffer) => `run trail skills draft ${runOf(o)} --print, paste what it prints as it is, then ask the last line again: "${one(o.lines?.[1] ?? '', 400)}"`;
function onAnswer(o: PendingOffer): string {
if (o.moment === 'retire') {
return 'If they answer retire, Trail retires it itself when it reads their answer, and tells you what to say. If they say keep it, Trail changes nothing.';
}
const checks = isSplit(o) ? CHECKS_KEEP : CHECKS;
const yesWord = o.moment === 'drift' ? 'replace' : 'yes';
const yes = `If they answer ${yesWord}, run: ${yesCommand2(o)} (${checks}), then tell them the line it prints. `;
const show = `If they say show me, ${showStep(o)}. `;
if (o.moment === 'drift') return `${yes}If they say retire, Trail retires it itself when it reads their answer. ${show}If they say leave it, Trail changes nothing.`;
return `${yes}${show}If they say no, Trail changes nothing.`;
}
/** 3.5 (R11): the Stop block's reason for moments 5, 6 and the retire proposal, given its 2 lines. */
export function blockReason2(o: PendingOffer, [a, b]: [string, string]): string {
return `[trail] ${FROM_TRAIL} ${reason(o)} When you finish this reply, end it with these 2 lines, ${SO_THEY_ANSWER}:\n${a}\n${b}\n${onAnswer(o)}`;
}
/** 3.4: the post-tool text, for completeness (these moments go out at Stop only, R13). */
export function postTool2(o: PendingOffer, [a, b]: [string, string]): string {
return `[trail] ${FROM_TRAIL} ${reason(o)} If this check finishes the job, end your reply with these 2 lines, ${SO_THEY_ANSWER}:\n${a}\n${b}\n`
+ "If the job isn't done yet, or you are about to ask the person something, leave them out.";
}
/** `[trail] From Trail, ... They typed "x" <tail>`: the D107 opening, quoting the person's words when there are any. */
function said(typed: string, tail: string): string {
const q = quoteOf(typed);
return ['[trail]', FROM_TRAIL, q ? `They typed "${q}"${tail.startsWith('to ') ? ' ' : '. '}${tail}` : tail].join(' ');
}
function offered(o: PendingOffer): string {
const name = skillName(o);
if (o.moment === 'drift') return fill(DRIFT_COPY.offered, { name });
if (o.moment === 'retire') return fill(RETIRE_COPY.offered, { name });
if (isSplit(o)) return fill(UPDATE_COPY.offeredSplit, { name });
return fill(UPDATE_COPY.offered, { name });
}
/**
* 4.7 to 4.10: what the agent reads on the person's answer, as context on the answering prompt (a bare no as a block
* where the host shows its reason). `c.retired`: the retire the prompt hook made (the folder name), or null when the
* store was busy and nothing moved.
*/
export function answer2(a: TypedAnswer, o: PendingOffer, c: { paused: boolean; firstNo: boolean; retired?: string | null }, env: NodeJS.ProcessEnv, typed: string, host?: Host): HookOut {
switch (a) {
case 'yes': {
const what = isSplit(o) ? 'to the new skill Trail showed,' : 'to the change Trail showed for';
const check = isSplit(o) ? CHECKS_KEEP : CHECKS;
const then = isSplit(o) ? ' Then tell them the line it prints.' : '';
return { context: said(typed, `${what} ${skillName(o)}. Run: ${yesCommand2(o)}. ${check}.${then}`) };
}
case 'show':
return { context: said(typed, `${offered(o)}, and they want to see it first. To show them, ${showStep(o)}, since Trail reads their answer to that question.`) };
case 'retire': {
const name = one(o.retire?.name ?? o.name);
return { context: said(typed, c.retired ? fill(RETIRE_COPY.retired, { name: one(c.retired) }) : fill(RETIRE_COPY.busy, { name })) };
}
case 'no': {
const say = notSaved(c).replace(/^OK, not saved\./, 'OK, nothing changed.');
if (hostFacts(env, host).promptBlockShown) return { block: `trail: ${say}` };
return { context: said(typed, `${offered(o)}, and they said no, so Trail changed nothing. Let them know: "${say}"`) };
}
default:
return o.channel === 'notice' ? {} : {
context: said(typed, `That isn't an answer to Trail's offer (${offered(o).replace(/^Trail offered /, '')}), so Trail dropped the offer and changed nothing. No need to bring the offer up again.`),
};
}
}