Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

15.9 KB
Raw Blame
/**
 * Settling credit for run blocks (design 3.5 step 5, 3.2 step 5, 4.8), for
 * Stop and the prompt hook alike, inside `withSkillSession`'s fn.
 *
 * A block's use is credited from the commands that ran after it came in and
 * flushed once, when its run closed or its check passed: one ledger `use`
 * line, one `recordUse`. The prompt hook settles too (D57): a run the next
 * typed ask closes is never seen open by a Stop, and once its sheet is
 * written the session drops its calls, so they are read from the sheet.
 *
 * A job a compaction cut and the agent carried on (D59a, `carriedFrom`) is
 * one use: the cut run's block and the compaction re-inject (same skill, the
 * carried run) are credited together over both halves' calls, oldest first,
 * joined the way g3 joins them for compile (`joinCarriedSheet`, so the same
 * links hold), and flushed together when the newest half closes or its check
 * passes. A cut run still waiting to be carried (`st.cut`) is not credited
 * alone.
 *
 * A block nothing ran from (no step ran or failed, the check never ran) is
 * settled without a use: the skill wasn't used.
 */
import type { CreditState, RunSheet, RunState, SkillInjection, SkillSessionState } from '../trace/types.js';
import type { LedgerUse, ParsedSkill, SkillState } from './types.js';
import { appendLedger, creditRun, newUseId, probeForm } from './ledger.js';
import { getSkillState, recordCorrected, recordUse } from './state.js';
import { listAllPersonal, readSkill } from './store.js';
import { readRunSheet } from '../trace/run-sheets.js';
import { joinCarriedSheet, MAX_CARRY_HOPS } from '../trace/run-join.js';
import { cueFlush } from './staleness.js';
import { useFacts } from './credit-facts.js';
import { noteFiring, type Fired } from './offer-retire.js';
import { readHanded } from '../trace/gate-file.js';
export type { Fired };

const MAX_CREDIT = 10;

export interface Settled {
  /** The blocks this use flushed (two for a job carried across a compaction). */
  injIds: string[];
  skillId: string;
  name: string;
  use: LedgerUse;
  outcome: 'checked' | 'failed' | 'unchecked';
  /** The skill's state after recordUse (undefined when it has none, or the state was busy). */
  state: SkillState | undefined;
}

export interface SettleCtx {
  host: string;
  env?: NodeJS.ProcessEnv;
  now?: Date;
  /**
   * The ready probes that failed for a block (their forms go in the use line, never their text; they never count
   * against the skill). Default: the injection's own `readyFailed`.
   */
  readyFailed?: (inj: SkillInjection) => string[];
  /** 1b (4.19): an asks phrase was dropped at this flush (for the caller's skill_stale{unfollowed}). */
  cueDropped?: (skillId: string, name: string) => void;
  /** Phase 2 (4.9): a firing was written at this flush (for the retire proposal, which needs a not-followed one). */
  fired?: (f: Fired) => void;
  /** c8 (D137): the session whose gate file holds the gated steps handed to the person since the last settle. */
  sessionId?: string;
}

const HANDED_SLACK_MS = 5_000;

/** D137: the gate file's hand-offs onto their blocks and the blocks' runs, so credit counts each step as handed. */
function pullHanded(st: SkillSessionState, sessionId: string, env?: NodeJS.ProcessEnv): void {
  let marks: ReturnType<typeof readHanded>;
  try {
    marks = readHanded(sessionId, env);
  } catch {
    return;
  }
  for (const m of marks) {
    const inj = st.injected.find((i) => i.injId === m.injId);
    if (!inj || m.n > inj.steps.length || !inj.gated.some((g) => g.step === m.n)) continue;
    // A hand-off from before the block's window (a re-arm for a new run) is that earlier run's, never this one's.
    if (!(Date.parse(m.at) >= Date.parse(inj.at) - HANDED_SLACK_MS)) continue;
    const list = (inj.handed ??= []);
    if (!list.some((h) => h.n === m.n)) list.push({ n: m.n, at: m.at });
    const run = inj.runId ? st.runs.find((r) => r.id === inj.runId) : undefined;
    if (run && !(Date.parse(run.handedAt ?? '') >= Date.parse(m.at))) run.handedAt = m.at;
  }
}


/** An injection's failed probes as the session file holds them: a list of strings, else none. */
export function injReadyFailed(inj: SkillInjection): string[] {
  const r: unknown = inj.readyFailed;
  return Array.isArray(r) ? r.filter((x): x is string => typeof x === 'string') : [];
}

/** A run the session still holds, as a sheet, so g3's join can link it like any other part. */
function stateSheet(run: RunState, st: SkillSessionState): RunSheet {
  return {
    v: 1, id: run.id, session: st.sessionHash, repoKey: run.repoKey, branch: run.branch, host: st.host, tier: st.tier, epoch: run.epoch,
    startedAt: run.startedAt, endedAt: run.lastAt, job: run.job, jobWords: run.jobWords, sharedWords: run.sharedWords, promptParams: run.promptParams,
    calls: run.calls, checkIndex: null, checked: false, end: run.end,
    counts: { commands: run.commands, failed: run.failedCount, toolCalls: run.toolCalls, edits: run.edits }, helpers: [], skillId: run.skillId ?? null,
    ...(run.carriedFrom ? { carriedFrom: run.carriedFrom } : {}),
  };
}

/**
 * A run of this session as a sheet: from the state while it holds the calls (open, or just closed inside the
 * hook's fn), else its run sheet when the sheet is this session's, else (closed with no step call, so no sheet)
 * the state's empty run, whose `carriedFrom` still links the parts on either side. Null for anything else.
 */
function partOf(id: string, st: SkillSessionState, env?: NodeJS.ProcessEnv): RunSheet | null {
  const run = st.runs.find((r) => r.id === id);
  if (run && (run.calls.length || !run.closed)) return stateSheet(run, st);
  const sheet = readRunSheet(id, env);
  if (sheet && sheet.session === st.sessionHash) return sheet;
  return run ? stateSheet({ ...run, calls: [] }, st) : null;
}

/** A job across compactions (D59a): its parts joined oldest first, the ids of the parts, and whether the newest closed. */
interface Job { sheet: RunSheet; ids: string[]; closed: boolean }

function joined(tail: RunSheet, st: SkillSessionState, env?: NodeJS.ProcessEnv): Job {
  const sheet = joinCarriedSheet(tail, (id) => partOf(id, st, env));
  const run = st.runs.find((r) => r.id === tail.id);
  return { sheet, ids: [...(sheet.joined ?? []).map((j) => j.id), tail.id], closed: run ? run.closed : true };
}

/**
 * The job a run belongs to: forward to the newest run carried from it (the session's runs, same job, at most
 * MAX_CARRY_HOPS), then back through `joinCarriedSheet`, which checks each link (same session and job, the epoch
 * before or the same, ended before the next began). When the join from that newest run doesn't reach this one,
 * the links don't hold and the run is its own job (joined back from itself).
 */
function jobOf(runId: string, st: SkillSessionState, env?: NodeJS.ProcessEnv): Job | null {
  const start = partOf(runId, st, env);
  if (!start) return null;
  let tail = start;
  for (let hop = 0; hop < MAX_CARRY_HOPS; hop++) {
    const next = st.runs.find((r) => r.carriedFrom === tail.id && r.job === tail.job);
    const part = next ? partOf(next.id, st, env) : null;
    if (!part) break;
    tail = part;
  }
  const job = joined(tail, st, env);
  return job.ids.includes(runId) ? job : joined(start, st, env);
}

/** The skill's SKILL.md as it is now (its version is the ledger's `v`, '1' when it can't be read), or null. */
function skillOf(skillId: string, name: string, env?: NodeJS.ProcessEnv): ParsedSkill | null {
  const refs = listAllPersonal(env);
  const ref = refs.find((r) => r.id === skillId && r.name === name) ?? refs.find((r) => r.id === skillId);
  return ref ? readSkill(ref) : null;
}

/** The credit entry for this block and run, made when missing. */
function entryFor(st: SkillSessionState, inj: SkillInjection, useId: string): CreditState {
  let c = st.credit.find((x) => x.injId === inj.injId && x.runId === inj.runId);
  if (!c) {
    c = { useId, injId: inj.injId, skillId: inj.skillId, epoch: inj.epoch, runId: inj.runId, stepsRan: [], failedStep: null, check: 'none', calls: 0, failed: 0, flushed: false, promptsAfter: 0 };
    // 1b (R30): the asks phrase a job cue fired on, as its sha.
    if (typeof inj.phraseSha === 'string' && /^[0-9a-f]{8}$/.test(inj.phraseSha)) c.phraseSha = inj.phraseSha;
    st.credit.push(c);
  }
  return c;
}

/** At most 10 entries, newest last: settled ones go first. */
function trimCredit(st: SkillSessionState): void {
  while (st.credit.length > MAX_CREDIT) {
    const i = st.credit.findIndex((c) => c.flushed);
    st.credit.splice(i >= 0 ? i : 0, 1);
  }
}

/**
 * Credits every block with a run (any epoch: a compaction may have closed it), and flushes each use that is done.
 * Changes `st.credit` and, on a passed check, the blocks' `live`. Returns the uses flushed now, for telemetry
 * `skill_used{outcome}` and the Stop use line.
 */
export function settleCredit(st: SkillSessionState, ctx: SettleCtx): Settled[] {
  const now = ctx.now ?? new Date();
  if (ctx.sessionId) pullHanded(st, ctx.sessionId, ctx.env);
  const groups = new Map<string, { injs: SkillInjection[]; job: Job }>();
  for (const inj of st.injected) {
    if (inj.cue === 'check' || !inj.runId) continue;
    const job = jobOf(inj.runId, st, ctx.env);
    if (!job) continue;
    const key = `${inj.skillId}|${job.ids[0]}`;
    const g = groups.get(key) ?? { injs: [], job };
    g.injs.push(inj);
    groups.set(key, g);
  }
  const out: Settled[] = [];
  for (const { injs, job } of groups.values()) {
    injs.sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
    const known = injs.map((i) => st.credit.find((c) => c.injId === i.injId && c.runId === i.runId)).filter((c): c is CreditState => !!c);
    const done = known.find((c) => c.flushed);
    if (done) {
      for (const i of injs) Object.assign(entryFor(st, i, done.useId), { flushed: true, useId: done.useId });
      continue;
    }
    const useId = known[0]?.useId ?? newUseId();
    const oldest = injs[0]!;
    const newest = injs[injs.length - 1]!;
    // D137: every block's hand-offs count for the use (a re-armed block keeps its first block's window and marks).
    const handedAll = injs.flatMap((i) => i.handed ?? []).filter((h) => h.n <= newest.steps.length);
    const credit = creditRun({ ...newest, at: oldest.at, cue: newest.cue === 'check' ? 'job' : newest.cue, handed: handedAll }, job.sheet.calls);
    const handed = [...new Set(handedAll.map((h) => h.n))].sort((a, b) => a - b);
    const entries = injs.map((i) => Object.assign(entryFor(st, i, useId), credit, { useId }));
    if (st.cut === job.sheet.id || !(job.closed || credit.check === 'passed')) continue;
    for (const e of entries) Object.assign(e, { flushed: true, promptsAfter: 0 });
    if (credit.check === 'passed') for (const i of injs) i.live = false;
    // 1b (4.19): a job cue's block whose steps never ran is a miss for its phrase; two in a row drop it. A block whose
    // ready probes failed is neither a miss nor a follow: not running it was right (J14c, review).
    const sha = entries.find((e) => typeof e.phraseSha === 'string')?.phraseSha ?? null;
    const notReady = injs.some((i) => (ctx.readyFailed ?? injReadyFailed)(i).length > 0);
    // Phase 2 (R27): a skill retired or forgotten while its block was live: the ledger keeps the use, nothing else moves.
    const gone = getSkillState(newest.skillId, ctx.env)?.status === 'retired';
    if (sha && !notReady && !gone) {
      try {
        if (cueFlush(newest.skillId, sha, credit.stepsRan.length > 0, ctx.env, now).dropped) ctx.cueDropped?.(newest.skillId, newest.name);
      } catch { /* the use still counts */ }
    }
    // Phase 2 (4.9): a job or name cue's settled block is a firing, followed when a step ran (P46: learning half).
    const followed = credit.stepsRan.length > 0;
    if (!notReady && !gone && (newest.cue === 'job' || newest.cue === 'name') && noteFiring(newest.skillId, followed, ctx.env, now)) {
      ctx.fired?.({ skillId: newest.skillId, name: newest.name, followed, runId: job.sheet.id, at: now.toISOString() });
    }
    // Nothing of the skill ran: settled, but it was not used.
    if (!credit.stepsRan.length && credit.failedStep === null && credit.check === 'none') continue;
    const skill = skillOf(newest.skillId, newest.name, ctx.env);
    const use: LedgerUse = {
      at: now.toISOString(), event: 'use', useId, skill: newest.skillId, v: skill?.meta.version || '1', host: ctx.host,
      cue: oldest.cue === 'check' ? 'job' : oldest.cue, repo: job.sheet.repoKey, stepsRan: credit.stepsRan, failedStep: credit.failedStep,
      readyFailed: [...new Set(injs.flatMap((i) => (ctx.readyFailed ?? injReadyFailed)(i)).map(probeForm))], check: credit.check, calls: credit.calls, failed: credit.failed,
      // Phase 2 (4.1): next-run fidelity, counts and 8-hex keys only.
      ...useFacts(skill, { ...newest, at: oldest.at, handed: handedAll }, job.sheet, ctx.env ?? process.env),
      ...(handed.length ? { handed } : {}),
    };
    try { appendLedger(newest.skillId, use, ctx.env); } catch { /* the state below still counts it */ }
    const state = gone ? undefined : recordUse(newest.skillId, use, ctx.env);
    out.push({
      injIds: injs.map((i) => i.injId), skillId: newest.skillId, name: newest.name, use, state,
      outcome: credit.check === 'passed' ? 'checked' : credit.failedStep !== null ? 'failed' : 'unchecked',
    });
  }
  trimCredit(st);
  return out;
}

/**
 * The 2-prompt correction window (3.2 step 5): each settled use counts this typed prompt; a correction within the
 * window is one ledger `corrected` line for that use (`recordCorrected`, which makes two in a row needs-fix), and
 * closes its window. Returns the use ids marked corrected now.
 *
 * 1b (R10, P17, 4.14 step 1): `correction` is the typed line's sha (`typedSha`), or null for any other prompt. A
 * use marked now gets `corrected = { offset: null, sha }` on its credit (the fold fills the offset from the person's
 * own line, noteCorrectionLine) and becomes the session's `lessonWatch`. Only the sha is kept, never the words. A 1a
 * caller's `true` still marks the use, with nothing watched.
 */
export function creditWindow(st: SkillSessionState, correction: { sha: string } | null, ctx: { env?: NodeJS.ProcessEnv; now?: Date }): string[] {
  const isCorrection = !!correction;
  const sha = correction && typeof correction === 'object' && typeof correction.sha === 'string' && /^[0-9a-f]{64}$/.test(correction.sha) ? correction.sha : null;
  const now = ctx.now ?? new Date();
  const marked: string[] = [];
  const seen = new Set<string>();
  for (const c of st.credit) {
    if (!c.flushed || c.promptsAfter >= 2) continue;
    const first = !seen.has(c.useId);
    seen.add(c.useId);
    if (!isCorrection) {
      c.promptsAfter += 1;
      continue;
    }
    c.promptsAfter = 2;
    if (first && getSkillState(c.skillId, ctx.env) && recordCorrected(c.skillId, c.useId, ctx.env, now)) {
      marked.push(c.useId);
      if (sha) st.lessonWatch = { skillId: c.skillId, useId: c.useId, typedSha: sha, at: now.toISOString() };
    }
  }
  if (sha) for (const c of st.credit) if (marked.includes(c.useId)) c.corrected = { offset: null, sha };
  return marked;
}

/**
 * 4.14 step 1: once the fold meets the person's own typed line whose sha a correction recorded, its offset goes on
 * the credit (a filled offset stays). `typed` is the fold's typed events (person-typed only, `FoldResult.typed`).
 * The prompt hook calls it right after creditWindow with its own catch-up (Claude Code writes the line before the
 * hook runs, so that fold has already met it and no later fold will); Stop calls it too, for a line written late.
 */
export function noteCorrectionLine(st: SkillSessionState, typed: Array<{ offset: number; sha: string }>): void {
  for (const c of st.credit) {
    if (!c.corrected || c.corrected.offset !== null) continue;
    // The newest line with the sha: the one the hook that recorded it saw (an older identical line came before the use).
    const hit = typed.filter((t) => t.sha === c.corrected!.sha && Number.isInteger(t.offset) && t.offset >= 0).pop();
    if (hit) c.corrected = { offset: hit.offset, sha: c.corrected.sha };
  }
}