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
/**
* Moment 4 (design 4.14, J07): the person corrected a skill Trail brought
* in, within 2 typed prompts of its use, in a form Trail can read as a
* lesson ("no, it didn't push the tag"). At the Stop of that turn Trail
* offers to add the lesson to the skill, with its exact text in line 2.
*
* The prompt hook only records the correction's sha (`creditWindow`); the
* offer needs the fold to have found the person's own typed line with that
* sha (`corrected.offset`, `noteCorrectionLine`), so the hook's payload alone
* never makes an offer and the agent's text can't fill it (R27). The lesson
* starts from the person's words, read back by that pointer; the fix command
* is the first new step that worked after the correction, held to the rules
* every skill step and every repair delta meets (R27, D104).
*
* Nothing typed is written: the pending offer keeps the pointer, the fix
* command and the lesson's sha, and its lines are rebuilt by `offerLinesOf`.
*/
import { homedir } from 'node:os';
import { useFor } from '../trace/dialect.js';
import type { GateCtx } from '../trace/skill-session.js';
import type { PendingOffer, RunCall, SkillSessionState } from '../trace/types.js';
import { commandKind, relativizePaths, stepMatches } from '../trace/shell.js';
import { secretReason } from '../notes/secrets.js';
import { gatedKind } from './risk.js';
import { neverSave } from './never-save.js';
import { riskyCommand } from './risk-delta.js';
import { listAllPersonal, readSkill } from './store.js';
import { readLessons, lessonRefused, lessonSha, lessonText, correctionPhrase } from './lessons.js';
import { newOfferId, offerBudget } from './offers.js';
import { typedLineAt } from './offer-lines.js';
import type { OfferDue, OfferInput } from './offer-moment.js';
export { offerLinesOf, correctionLesson, correctionLines, typedLineAt, type OfferLinesIn } from './offer-lines.js';
/** A skill with this many lessons gets no more offers (4.14 step 4). */
export const MAX_LESSONS = 10;
/** A fix command longer than this is not used: the lesson is the phrase alone (4.14 step 3). */
const FIX_MAX = 300;
/** The calls the session still holds that came after `offset` in the transcript, in transcript order. */
function callsAfter(st: SkillSessionState, offset: number): RunCall[] {
const all = st.runs.flatMap((r) => (Array.isArray(r.calls) ? r.calls : []));
return all.filter((c) => Number.isInteger(c.src?.use) && c.src.use > offset).sort((a, b) => a.src.use - b.src.use);
}
/** A call that ran and worked, with its whole command: a result read, not failed, not in the background. */
const worked = (c: RunCall) => !c.failed && typeof c.cmd === 'string' && !c.truncated && !c.secret && c.bg !== true
&& (c.src?.result != null || c.fromMark === true);
/**
* 4.14 step 3: the first call after the correction that worked, is a step-kind call and matches no step of the
* skill, as the lesson holds it: params put back by `lessonText`, paths relativized here. Null (the phrase alone)
* when there is none, or it carries a secret, is on the never-save list, is gated, teaches a way around a check
* (D104) or runs past 300 characters. `id` is the call's, also when its command isn't used.
*/
export function fixCommand(st: SkillSessionState, offset: number, steps: string[], params: Record<string, string>,
where: { checkout: string; home: string }): { id: string | null; cmd: string | null } {
for (const c of callsAfter(st, offset)) {
if (!worked(c) || c.kind !== 'step' || commandKind(c.cmd!) !== 'step') continue;
if (steps.some((s) => stepMatches(s, c.cmd!, params))) continue;
const cmd = relativizePaths(c.cmd!, where.checkout, where.home).trim();
const bad = !cmd || cmd.length > FIX_MAX || secretReason(cmd) !== null || neverSave(cmd) !== null || gatedKind(cmd) !== null || riskyCommand(cmd);
return { id: c.id, cmd: bad ? null : cmd };
}
return { id: null, cmd: null };
}
type Why = 'learn' | 'pending' | 'no-watch' | 'no-line' | 'end' | 'skill' | 'lessons' | 'phrase' | 'refused' | `budget:${string}`;
/**
* Moment 4 (4.14). Called first by offerDue at Stop, inside the session lock. Due: the offer to hold as
* `pendingOffer`, its lines null (rebuilt by offerLinesOf). Writes nothing.
*/
export function lessonOfferDue(i: OfferInput & { ctx: OfferInput['ctx'] & Pick<GateCtx, 'transcriptPath'> }): OfferDue | { due: false; why: Why } {
const { run, verdict, st, ctx, channel } = i;
const env = ctx.env;
if (!ctx.learn) return { due: false, why: 'learn' };
if (st.pendingOffer) return { due: false, why: 'pending' };
const watch = st.lessonWatch;
if (!watch) return { due: false, why: 'no-watch' };
const credit = st.credit.find((c) => c.useId === watch.useId && c.skillId === watch.skillId && c.corrected?.sha === watch.typedSha);
const offset = credit?.corrected?.offset;
// R27: only once the fold met the person's own typed line with the hook's sha.
if (!credit || typeof offset !== 'number' || !ctx.transcriptPath) return { due: false, why: 'no-line' };
if (verdict.end === 'failure' || verdict.end === 'question') return { due: false, why: 'end' };
const ref = listAllPersonal(env).find((r) => r.id === watch.skillId);
const skill = ref ? readSkill(ref) : null;
if (!ref || !skill) return { due: false, why: 'skill' };
if (readLessons(ref.dir).length >= MAX_LESSONS) return { due: false, why: 'lessons' };
const typed = typedLineAt(ctx.transcriptPath, offset, watch.typedSha, env, useFor(st.host, st));
const phrase = typed === null ? null : correctionPhrase(typed);
if (!phrase) return { due: false, why: 'phrase' };
const repo = run.repoKey || ctx.repoKey;
const key = `${watch.skillId}|correction`;
// P18, R40: a pending offer this same correction withdrew frees the session's slot for this one offer only.
const freed = st.withdrewFor?.typedSha === watch.typedSha;
const budget = offerBudget({ repoKey: repo, key, sessionOfferUsed: st.offerUsed && !freed, now: ctx.now, env });
if (!budget.ok) return { due: false, why: `budget:${budget.why}` };
const inj = st.injected.find((x) => x.injId === credit.injId);
const params = inj && inj.params && typeof inj.params === 'object' ? inj.params : {};
const fix = fixCommand(st, offset, skill.steps.map((s) => s.cmd), params, { checkout: ctx.checkout, home: env.HOME || homedir() });
let text = lessonText(phrase, fix.cmd, params);
const alone = lessonText(phrase, null, params);
if (!text || !alone) return { due: false, why: 'phrase' };
// The fix as the lesson holds it (params put back), so offerLinesOf rebuilds this very text from the typed line.
let kept: string | null = fix.cmd && text.startsWith(`${alone}: `) ? text.slice(alone.length + 2) : null;
if (kept !== null && lessonText(phrase, kept, {}) !== text) kept = null;
if (kept === null || lessonRefused(text)) {
kept = null;
text = alone;
}
// D109: the final text is held to the run block's rule too (a skip-the-ask lesson is never offered).
if (lessonRefused(text)) return { due: false, why: 'refused' };
const offer: PendingOffer = {
offerId: newOfferId(), moment: 'correction', runId: credit.runId ?? run.id, name: skill.name, key, lines: null, channel,
shownAt: channel === 'post-tool' ? null : ctx.now.toISOString(), showMe: false, yes: null, typedAfter: [], repo,
correction: { skillId: watch.skillId, useId: watch.useId, typed: { offset, sha: watch.typedSha }, fixCallId: fix.id, lessonSha: lessonSha(text), fix: kept },
};
return { due: true, offer };
}