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 2 and the answers to it, in one place (design 3.2 steps 4 and 6.4,
* 3.4, 3.5 step 10, 4.12): when a repeated-job offer is due, what an answer
* to it leaves in the session, and what a save request leaves.
*
* `captureAnswer` is the only place a `yes` is recorded, and
* `noteSaveRequest` the only place a save request is: the save gate trusts
* nothing else. Both take the person's typed words from the prompt hook's
* payload; the gate then needs the same words, by hash, on a line the
* person typed in the transcript (4.9 step 5).
*
* Either order of the prompt hook and the transcript works. When Claude Code
* has written the typed line before the hook runs, the hook's own catch-up
* folds it before a save request exists, so `noteSaveRequest` takes the line
* from that catch-up (`fold.typed`); otherwise a later fold fills it in.
*/
import type { Host } from '../trace/host.js';
import { createHash } from 'node:crypto';
import { homedir } from 'node:os';
import type { CheckedVerdict, FoldResult } from '../trace/runs.js';
import type { GateCtx } from '../trace/skill-session.js';
import type { OfferChannel, PendingOffer, RunSheet, RunState, SkillSessionState, TypedAnswer } from '../trace/types.js';
import type { CompiledSkill, HookOut } from './types.js';
import { typedSha } from '../trace/typed.js';
import { OFFER_FAMILIES } from '../trace/jobs.js';
import { readPool, repeatedEnough } from '../trace/pool.js';
import { findPriorSheet, joinCarriedSheet, readRunSheet } from '../trace/runs.js';
import { compileRun } from './compile.js';
import { stableBranches } from './compile-words.js';
import { jobCovered, nameTaken } from './store.js';
import { stepsTotal } from './store-fs.js';
import { answerDirective, endsWithLine, newOfferId, offerBudget, offerLines, recordAnswer, recordNotShown } from './offers.js';
import { offerLinesOf, type OfferLinesIn } from './offer-lines.js';
import { isLessonOffer } from './offer-words-1b.js';
import { lessonOfferDue } from './offer-lesson.js';
import { repairOfferDue } from './offer-repair.js';
import { classifyFor } from './offer-answers.js';
import { updateOfferDue } from './offer-update.js';
import { driftOfferDue } from './offer-drift.js';
import { replyEndedWithOffer, retireOfferDue, retireSkill } from './offer-retire.js';
import { answer2 } from './offer-words-2.js';
import { skillOfOfferKey } from './offers.js';
import { runCheckout } from './run-checkout.js';
import { repoKnown } from '../trace/known-repo.js';
import type { FoldPlanner } from './offer-update.js';
import type { Fired, Settled } from './credit.js';
import { useFor, type DialectUse } from '../trace/dialect.js';
import { stepLearnings, withFollowLine } from './follow-learnings.js';
const SAME_LINE_MS = 5000;
/**
* What a yes to an offer agrees to: the skill's steps (the calls each was copied from, and its text with the
* skill's own name taken out) and its check. The gate saves only a skill with the same sha (4.9 step 5): steps run
* after the offer, or a run sheet changed since, are not what the person said yes to.
*/
export function skillSha(c: CompiledSkill): string {
const own = (t: string) => (c.name ? t.split(c.name).join('\u0000') : t);
const steps = c.steps.map((s) => [(s.from ?? []).join(','), own(s.cmd)]);
return createHash('sha256').update(JSON.stringify([steps, own(c.check), c.checkIsStep])).digest('hex');
}
/**
* The repo an offer is for: its `repo` (1b), else from its key, '<repoKey>|job:<job>' or '<repoKey>|wall:<cls>|<program>'.
* A skill-keyed offer ('<skillId>|correction', phase 2's update, drift and retire keys) names no repo: '' without
* `repo` (D126).
*/
export function offerRepo(o: Pick<PendingOffer, 'key'> & { repo?: unknown }): string {
if (typeof o.repo === 'string' && o.repo) return o.repo;
if (skillOfOfferKey(o.key) !== null) return '';
const i = o.key.lastIndexOf('|job:');
if (i >= 0) return o.key.slice(0, i);
const w = o.key.indexOf('|wall:');
return w < 0 ? o.key : o.key.slice(0, w);
}
export interface Captured {
/** Return this now (a directive for yes, show me or no); null: go on to 3.2 step 5. */
out: HookOut | null;
/** Going on: context to add first (the agent said the offer and the person moved on). */
extra?: string;
/** For telemetry `skill_answer`: the class, or why the offer was dropped unanswered; null with no offer, or for a
* second yes after the first (ignored, D70: nothing to send). */
answer: TypedAnswer | 'stale' | 'not-shown' | null;
/** Phase 2 (4.9): the prompt hook retired the skill on this answer (for telemetry `skill_changed{retire}`). */
changed?: 'retire';
}
/**
* 3.2 step 4, on the session state inside the prompt hook's lock. Only the first typed prompt after the offer
* answers it, or the second after one "show me". A `yes` sets `pendingOffer.yes` from this prompt's own words
* (hashed), which the gate later matches against the person's line in the transcript.
*/
export function captureAnswer(st: SkillSessionState, typed: string, env: NodeJS.ProcessEnv = process.env, now: Date = new Date(),
o: { transcriptPath?: string | null } = {}): Captured {
const po = st.pendingOffer;
if (!po) return { out: null, answer: null };
const repo = offerRepo(po);
const plain = { paused: false, firstNo: false };
if (po.yes) {
// D70: two quick yeses keep the save once. The first counts (its line is the consent); the second is
// ignored: no second directive, no answer recorded, the offer stays for the agent's add.
if (classifyFor(po.moment, typed, po.showMe) === 'yes') return { out: null, answer: null };
// Anything else: answered in an earlier prompt, and the agent had that turn to save.
st.pendingOffer = null;
return { out: null, answer: 'stale' };
}
if (po.shownAt === null) {
recordNotShown(po, repo, env, now);
st.pendingOffer = null;
return { out: null, answer: 'not-shown' };
}
// Phase 2 (4.10): by the offer's own words (drift's replace is its yes, retire is retire).
const said = classifyFor(po.moment, typed, po.showMe);
// 1b: a lesson offer asks yes or no; its whole text is already in line 2, so "show me" is no answer to it.
// Phase 2 (D72, R1): a retire moves the skill only after the agent's reply ended with the offer's line 2.
const a = said === 'show' && isLessonOffer(po) ? 'other'
: said === 'retire' && !(po.retire && replyEndedWithOffer(po, typed, o.transcriptPath ?? null, env, useFor(st.host, st))) ? 'other' : said;
switch (a) {
case 'retire': {
// 4.9, P12: the one write the prompt hook makes on an answer: a move `trail skills restore` undoes.
const r = retireSkill(po.retire!.name, 'retire-offer', env, now, po.retire!.skillId);
recordAnswer(po, repo, 'yes', env, now, 'retire');
st.pendingOffer = null;
return { out: answer2('retire', po, { ...plain, retired: r.ok ? po.retire!.name : null }, env, typed, st.host as Host), answer: 'retire', ...(r.ok ? { changed: 'retire' as const } : {}) };
}
case 'yes':
recordAnswer(po, repo, 'yes', env, now, po.fold?.op);
po.yes = { at: now.toISOString(), typedSha: typedSha(typed) };
return { out: answerDirective('yes', po, plain, env, typed, st.host as Host), answer: 'yes' };
case 'show':
recordAnswer(po, repo, 'show', env, now);
po.showMe = true;
return { out: answerDirective('show', po, plain, env, typed, st.host as Host), answer: 'show' };
case 'no': {
const c = recordAnswer(po, repo, 'no', env, now);
st.pendingOffer = null;
return { out: answerDirective('no', po, c, env, typed, st.host as Host), answer: 'no' };
}
case 'correction':
recordAnswer(po, repo, 'withdrawn', env, now);
st.pendingOffer = null;
// P18, R40: only the lesson offer for this same correction may use the slot it freed, at this turn's Stop. A
// withdrawn lesson offer frees nothing: the slot is for a pending offer of another moment (4.14, b4 review).
st.withdrewFor = po.moment === 'correction' ? null : { typedSha: typedSha(typed) };
return { out: null, answer: 'correction' };
default: {
recordAnswer(po, repo, 'none', env, now);
st.pendingOffer = null;
const d = answerDirective('other', po, plain, env, typed, st.host as Host);
return d.context ? { out: null, extra: d.context, answer: 'other' } : { out: null, answer: 'other' };
}
}
}
/**
* 3.2 step 6.4: the person asked to keep a run. Spends the session's offer, withdraws a pending one, and records
* the request with this prompt's words hashed. When this hook's catch-up already folded the typed line (Claude Code
* wrote it before the hook ran), its offset is taken from `fold.typed` now: the fold only fills `typed` for a line
* it meets after the request exists. `skill` is the skill compiled for this ask (3.2 step 6.3); its `skillSha` is
* kept (D73): the gate keeps only that skill, so steps run or written into the sheet after the ask are not what was
* asked for.
*/
export function noteSaveRequest(st: SkillSessionState, fold: Pick<FoldResult, 'typed'> | null,
req: { runId: string; typed: string; scope: NonNullable<SkillSessionState['saveRequest']>['scope']; skill: CompiledSkill },
env: NodeJS.ProcessEnv = process.env, now: Date = new Date()): void {
const sha = typedSha(req.typed);
const line = (fold?.typed ?? []).filter((t) => t.sha === sha && t.offset >= 0 && Date.parse(t.at) >= now.getTime() - SAME_LINE_MS).pop();
if (st.pendingOffer) {
recordAnswer(st.pendingOffer, offerRepo(st.pendingOffer), 'withdrawn', env, now);
st.pendingOffer = null;
}
st.saveRequest = {
runId: req.runId, at: now.toISOString(), typedSha: sha, scope: req.scope, typed: line ? { offset: line.offset, sha } : null, skillSha: skillSha(req.skill), name: req.skill.name,
};
st.offerUsed = true;
st.offerUsedBy = 'asked';
}
export interface OfferInput {
run: RunState;
/** checkedSuccess(run, lastAssistant) (Stop) or with lastAssistant null (post-tool, 3.4). */
verdict: CheckedVerdict;
/** The run's sheet as written for this verdict. */
sheet: RunSheet | null;
st: SkillSessionState;
/** 1b: Stop passes its whole GateCtx; moment 4 reads the transcript (no transcript: no moment 4). */
ctx: Pick<GateCtx, 'learn' | 'checkout' | 'repoKey' | 'env' | 'now'> & Partial<Pick<GateCtx, 'transcriptPath'>>;
channel: OfferChannel;
/** Phase 2 (moments 5 and 6): c2's foldInputFor and replan (update-gate.ts); without them neither is due. */
plan?: FoldPlanner;
/** Phase 2: the uses this Stop's settle flushed (moment 5 needs this run's, checked). */
settled?: Settled[];
/** Phase 2: the firings this Stop's settle wrote (the retire proposal needs a not-followed one). */
fired?: Fired[];
}
export type OfferDue =
| { due: true; offer: PendingOffer }
| { due: false; why: 'learn' | 'pending' | 'job' | 'skill' | 'not-checked' | 'family' | 'no-repo' | 'covered' | 'not-repeated' | 'no-sheet' | 'compile' | 'one-step' | 'unknown-repo' | `budget:${string}` };
/** Phase 2 (4.10, P18): the order offerDue tries the moments in; the first that is due is the offer. */
export const OFFER_ORDER = ['correction', 'drift', 'update', 'repaired', 'repeated', 'retire'] as const;
/**
* 1b (4.13, 4.14, 3.5 step 6), phase 2 (4.10, P18): moment 4, 6, 5, 3, 2, then the retire proposal, the first that is
* due. All but moment 2 are Stop's only (stop and notice channels, R13); none due, the answer is moment 2's. Writes
* nothing: the caller records it shown.
*/
export function offerDue(i: OfferInput): OfferDue {
// D117 (3), J16: no offer in a repo Trail doesn't know (no .trail/, not in the repo index).
if (!repoKnown(i.run.repoKey, i.run.checkout ?? (i.run.repoKey === i.ctx.repoKey ? i.ctx.checkout : ''), i.ctx.env)) return { due: false, why: 'unknown-repo' };
const atStop = i.channel !== 'post-tool' && i.ctx.learn && !i.st.pendingOffer;
if (atStop) {
const m4 = lessonOfferDue({ ...i, ctx: { ...i.ctx, transcriptPath: i.ctx.transcriptPath ?? null } });
if (m4.due) return m4;
const m6 = driftOfferDue(i);
if (m6.due) return m6;
const m5 = updateOfferDue(i);
if (m5.due) return m5;
const m3 = repairOfferDue(i);
if (m3.due) return m3;
}
const m2 = repeatedOfferDue(i);
if (m2.due || !atStop) return m2;
const retire = retireOfferDue(i, i.fired ?? []);
return retire.due ? retire : m2;
}
/** What compile makes of an offer's run, exactly as the save gate's compile of its yes will (moments 2 and 3, R58). */
export function compileOffered(sheet: RunSheet, st: SkillSessionState, ctx: OfferInput['ctx']): ReturnType<typeof compileRun> {
const env = ctx.env;
const scope = { repoKeys: [...new Set([...st.scopeKeys, sheet.repoKey])], checkout: ctx.checkout, env };
const read = (id: string) => readRunSheet(id, env);
// D93: the run's own checkout, as both halves of the save gate compile it.
const root = runCheckout(sheet, env, ctx.repoKey === sheet.repoKey ? ctx.checkout : '');
return compileRun(sheet, {
repoRoot: root, home: env.HOME || homedir(), platform: process.platform,
prior: findPriorSheet(sheet, env), moment: 'repeated', applies: sheet.repoKey, now: ctx.now, readSheet: read,
taken: (n) => nameTaken(n, { ...scope, checkout: root || scope.checkout }) !== null,
learnings: stepLearnings({ repoKeys: [sheet.repoKey], checkout: root, env }),
});
}
/**
* Moment 2: 4.12 conditions 1 to 6, in order. Due: the offer to hold as `pendingOffer` (shown now for `stop` and
* `notice`; `shownAt` null for `post-tool`, set when the reply carries it). Writes nothing.
*/
export function repeatedOfferDue(i: OfferInput): OfferDue {
const { run, verdict, st, ctx, channel } = i;
const env = ctx.env;
const now = ctx.now;
if (!ctx.learn) return { due: false, why: 'learn' };
if (st.pendingOffer) return { due: false, why: 'pending' };
const job = run.job;
const families = job ? OFFER_FAMILIES[job] : undefined;
if (!job || !families) return { due: false, why: 'job' };
if (run.skillId) return { due: false, why: 'skill' };
if (!verdict.checked || verdict.checkIndex === null) return { due: false, why: 'not-checked' };
const hit = run.calls[verdict.checkIndex]?.check;
if (!hit || !hit.passed || !families.includes(hit.family)) return { due: false, why: 'family' };
if (!run.repoKey) return { due: false, why: 'no-repo' };
const scope = { repoKeys: [...new Set([...st.scopeKeys, run.repoKey])], checkout: ctx.checkout, env };
if (jobCovered(job, scope)) return { due: false, why: 'covered' };
const key = `${run.repoKey}|job:${job}`;
const budget = offerBudget({ repoKey: run.repoKey, key, sessionOfferUsed: st.offerUsed, now, env });
if (!budget.ok) return { due: false, why: `budget:${budget.why}` };
const pool = readPool(run.repoKey, env).jobs[job];
const rep = pool ? repeatedEnough(pool, budget.extraDay, now) : null;
if (!rep || !rep.ok) return { due: false, why: 'not-repeated' };
const sheet = i.sheet;
if (!sheet || sheet.id !== run.id) return { due: false, why: 'no-sheet' };
const read = (id: string) => readRunSheet(id, env);
const compiled = compileOffered(sheet, st, ctx);
if (!compiled.ok) return { due: false, why: 'compile' };
// D70: a skill of one Run step is not offered; a one-command job is better kept as a lesson.
if (compiled.skill.steps.length < 2) return { due: false, why: 'one-step' };
const joined = joinCarriedSheet(sheet, read);
const ownDates = rep.dates === rep.sessionDays;
const seen = { n: ownDates ? rep.dates : rep.sessionDays, unit: ownDates ? 'day' as const : 'time' as const };
const lines = withFollowLine(offerLines({
job, check: hit, ordinal: seen.n, unit: seen.unit,
commands: joined.counts.commands, failed: joined.counts.failed, steps: stepsTotal(compiled.skill), where: 'this repo',
branches: job === 'ship' ? stableBranches(joined.calls, joined.jobWords) : [],
}), compiled.skill.followed);
return {
due: true,
offer: {
offerId: newOfferId(), moment: 'repeated', runId: run.id, name: compiled.skill.name, key, lines, channel,
shownAt: channel === 'post-tool' ? null : now.toISOString(), showMe: false, yes: null, typedAfter: [],
skillSha: skillSha(compiled.skill), seen,
},
};
}
/**
* For g7's Stop (3.5 steps 6 and 7): the agent's reply carried the offer, as its last line. A reply that adds a
* question of its own after the offer, or leaves it out, did not: the offer is recorded not shown and dropped, so
* the person's next yes can't be taken as a yes to the skill.
*/
export function offerEndsReply(o: OfferLinesIn, reply: string | null, transcriptPath: string | null = null, use?: DialectUse): boolean {
// 1b (R12): through offerLinesOf; an offer with no lines (a correction whose line is gone or changed) never ends a reply.
const l = reply === null ? null : offerLinesOf(o, transcriptPath, process.env, use);
return l !== null && endsWithLine(reply!, l[1]);
}