Skip to content

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

20.3 KB
Raw Blame
/**
 * The shapes the trace layer folds a session into: runs of tool work that
 * serve one typed ask, their calls, the checks that prove a job worked, and
 * the per-session state the skills hooks keep under the `skills` key of
 * `~/.trail/sessions/<id>.json`.
 *
 * Types only (a type import of skills/types.ts for the fold ops). Typed text never appears here: a run carries job words from a
 * fixed vocabulary, parameter values of known shapes, counts, hashes of typed
 * lines, and the commands that ran (secret-checked).
 */

import type { FoldOp } from '../skills/types.js';

export type JobClass = 'release' | 'ship' | 'pr-green' | 'sweep' | 'run-local' | 'report' | 'tests';

export interface JobMatch {
  job: JobClass;
  /** Canonical vocabulary words that matched, e.g. ['push', 'beta', 'ff', 'prod']. Never raw text. */
  words: string[];
}

/** Parameter values of known shapes found in a typed ask. Values only, never the text around them. */
export type PromptParams = Partial<Record<'version' | 'sha' | 'pr' | 'port' | 'branch' | 'date', string>>;

/** What a Bash call is, decided at fold time from its raw command (4.1). */
export type CallKind = 'step' | 'look' | 'plumbing' | 'work';

export interface RunCall {
  /** tool_use id */
  id: string;
  at: string;
  /** The command after redactSecrets (4.10). null when it held a secret that could not be named, or ran over 2,000 characters (then `parts` holds it piece by piece, D58c). */
  cmd: string | null;
  /** For a call with `parts`, the worst of its pieces' (refused over named). */
  secret?: 'named' | 'refused';
  /** Repo key of the effective folder (4.1); null outside git. */
  key: string | null;
  /** Effective folder (4.1), relative to that checkout's root ('' = root); null outside git. A sheet stores null for calls in another repo than the run's. */
  cwd: string | null;
  /** tool_input.run_in_background === true, or the command ends in a top-level `&`. */
  bg: boolean;
  /** !ok from the trace: is_error, or failure text in head or tail. */
  failed: boolean;
  /** The host's own error flag only. */
  isError: boolean;
  /** errorLine(result), cleanLine(.., 160). */
  errorLine?: string;
  /** Last 200 chars of the result, cleanLine'd. Kept for check-family calls, polls, `git rev-parse`, `git push` and publish calls only. */
  tail?: string;
  check?: CheckHit;
  /** Raw command over 2,000 chars: never kept whole; its pieces are in `parts` (D58c). */
  truncated?: boolean;
  /** isMultiLine(raw command). */
  multiLine?: boolean;
  kind: CallKind;
  /** Byte offsets of the tool_use line and the tool_result line, for the gate (4.9). -1 / null when unknown. */
  src: { use: number; result: number | null };
  /** The outcome came from a PostToolUse(Failure) mark because the transcript had no result yet (3.4). A later transcript result replaces it. */
  fromMark?: true;
  /** Only when the raw command ran over 2,000 characters (then `cmd` is null and `truncated` set): its top-level pieces in order (D58c). */
  parts?: RunCallPart[];
  /**
   * Not a Bash call: a deployment status tool over MCP (D59b, `mcp__claude_ai_Vercel__get_deployment`). Then `cmd` is
   * null, `kind` is 'look', `key`/`cwd` are null, and `check` is the deploy check its result gave. Never a step,
   * never counted in `commands` or `failedCount`.
   */
  tool?: string;
  /**
   * D116 item 5: the call only fed keystrokes into a login (`... | script -q /dev/null npm login`): the service it logs
   * in to. Then `cmd` is the login alone (`npm login`): what was fed is never kept, and compile drops the step.
   */
  loginFeed?: string;
}

/**
 * One top-level piece of a call over 2,000 characters (D58c), as `splitTop` cuts it: a subshell, a loop or an `if`
 * is one piece, a heredoc body belongs to the piece that opened it. The call's `id` and `src` are every piece's
 * `from` (the save gate re-reads that one transcript line).
 */
export interface RunCallPart {
  /** Word for word what ran, after redactSecrets; null when it held a secret that could not be named, or is `long`. */
  cmd: string | null;
  /** The top-level separator after it; '' for the last. A newline reads as ';'. */
  sep: '&&' | '||' | ';' | '|' | '&' | '';
  /** 4.1 kinds for the piece alone; always 'work' when `long`. */
  kind: CallKind;
  secret?: 'named' | 'refused';
  /** The piece ran over 2,000 characters (a heredoc body, an inline edit): a work marker, never a step, never kept. */
  long?: true;
}

/** `push`: a `git push` whose output shows the remote ref moved (D56a); a step, like `tests` and `query`. */
export type CheckFamily = 'tests' | 'npm-view' | 'deploy' | 'gh-checks' | 'ls-remote' | 'query' | 'push';

export interface CheckHit {
  family: CheckFamily;
  passed: boolean;
  facts: {
    version?: string; sha?: string; state?: string; pr?: string;
    branch?: string; remote?: string; pkg?: string; passedCount?: number;
  };
}

export type RunEnd = 'done' | 'failure' | 'question' | 'open';

export interface RunState {
  id: string;                   // 'r-1027-3f9a'
  epoch: number;
  startedAt: string;
  lastAt: string;
  /** Repo key that most of the run's commands ran in (4.1). */
  repoKey: string;
  /** D93: the top of the checkout `repoKey` names, as the fold found it; absent when no call ran in it. */
  checkout?: string;
  /** gitBranch of its first step call; null when unknown. */
  branch: string | null;
  job: JobClass | null;
  jobWords: string[];
  promptParams: PromptParams;
  /** Words both in the typed ask and in the kept commands (moment 1 cue words when job is null). */
  sharedWords: string[];
  typedCount: number;
  toolCalls: number;            // every tool call except Trail's own commands
  edits: number;                // Edit, Write, MultiEdit, NotebookEdit
  commands: number;             // Bash calls, all of them (calls[] may hold fewer)
  failedCount: number;          // failed Bash calls
  stepCalls: number;            // Bash calls of kind 'step', ok or not
  /** Open run only, newest last, at most 200. Emptied when the run closes, after its sheet is written. */
  calls: RunCall[];
  closed: boolean;
  /** Recomputed at every Stop while the run is open (4.2), kept when it closes. */
  end: RunEnd;
  /** Set when a run block was injected for this run (not "from scratch"). */
  skillId?: string;
  /** The run a compaction cut before it checked out, whose job this run continues (D59a). The agent started it with no typed ask. */
  carriedFrom?: string;
  /**
   * D116 item 3: a go-ahead continued this run after a turn the agent ended in failure; this many calls had run then.
   * Only a check at or after that call can check the run out.
   */
  failedTurn?: number;
  sheet: 'none' | 'draft' | 'checked';
  checkIndex: number | null;
  poolNoted: boolean;
}

/** ~/.trail/runs/<id>.json. What compile copies from. */
export interface RunSheet {
  v: 1;
  id: string;
  session: string;              // sha256(sessionId).slice(0, 12)
  repoKey: string;
  /** D93: the checkout the run ran in (RunState.checkout). The save gate's halves read it, never their own cwd. */
  checkout?: string;
  branch: string | null;
  host: string;
  tier: 'A' | 'B' | 'C' | 'D';
  epoch: number;
  startedAt: string;
  endedAt: string;
  job: JobClass | null;
  jobWords: string[];
  sharedWords: string[];
  promptParams: PromptParams;
  calls: RunCall[];
  /** Index into calls of the passing check that made it a checked success, or null. */
  checkIndex: number | null;
  checked: boolean;
  end: RunEnd;
  counts: { commands: number; failed: number; toolCalls: number; edits: number };
  /** Absolute paths of helper scripts the run executed from scratch folders (4.5 step 7). */
  helpers: string[];
  /** The skill whose block drove this run, or null. */
  skillId: string | null;
  /** The run (and sheet) before the compaction that this one continues (D59a); its calls are the job's first part. */
  carriedFrom?: string;
  /** Set only by `joinCarriedSheet`: the earlier parts joined in, oldest first, and how many calls each brought (they come first). */
  joined?: Array<{ id: string; calls: number }>;
}

/** Phase 2: 'retire', the retire proposal's and drift's retire (4.10, classifyFor); 1a's classifyAnswer never gives it. */
export type TypedAnswer = 'yes' | 'no' | 'show' | 'correction' | 'retire' | 'other';

export type GatedKind = 'publish' | 'push-prod' | 'deploy' | 'merge' | 'migrate' | 'prune' | 'login';

export interface SkillInjection {
  injId: string;                // 'i-' + 6 hex
  skillId: string;
  name: string;
  epoch: number;
  at: string;
  cue: 'job' | 'name' | 'check' | 'compact';
  params: Record<string, string>;
  /** Steps with params filled, in order (step n = index + 1). [] for a check cue. */
  steps: string[];
  gated: Array<{ step: number; kind: GatedKind }>;
  check: string | null;
  /**
   * D66: the skill's `metadata.check-tool` (e.g. 'get_deployment') when its check is a deploy status read over MCP,
   * not a command. Credit then takes the check from that tool's result (READY passes). Absent for a command check.
   */
  checkTool?: string | null;
  /**
   * D106: the version a version check should show (the skill's `check-shows` is a `{version}` param, filled with a
   * literal version). Credit passes the check only when it shows this version. Absent otherwise.
   */
  checkVersion?: string;
  /**
   * The ready probes (their text, from the skill's `ready` line) that failed when the block came in. Credit puts
   * their forms in the use line; they never count against the skill (g4 open issue 4, D71 d). Absent when none failed.
   */
  readyFailed?: string[];
  /** Set by the fold: the run of the first typed event at or after `at` minus 5 s. */
  runId: string | null;
  /** Its gated ask applies (3.3). Ends per 3.1 step 3, 3.2 step 7 and 3.5 step 5. */
  live: boolean;
}

export type OfferChannel = 'stop' | 'notice' | 'post-tool';

export interface PendingOffer {
  offerId: string;
  moment: OfferMoment;
  runId: string;
  name: string;                 // proposed skill name
  key: string;                  // '<repoKey>|job:<class>'; 1b: '<repoKey>|wall:<cls>|<program>', '<skillId>|correction'
  /**
   * The 2 lines (4.12). 1b: null only for a 'correction' offer, rebuilt from the transcript (P17); every reader goes
   * through offerLinesOf (b4, R12). Until then each 1a reader treats null as no offer: never shown, answered or saved.
   */
  lines: [string, string] | null;
  channel: OfferChannel;
  shownAt: string | null;       // emitted (stop, notice), or seen in the reply (post-tool)
  showMe: boolean;              // 'show me' already answered once
  /** Set by the prompt hook from the UserPromptSubmit payload: the person's yes, as a hash. */
  yes: { at: string; typedSha: string } | null;
  /** Set by the fold: the first typed events after shownAt (at most 2: a 'show' then the answer). */
  typedAfter: Array<{ offset: number; sha: string; answer: TypedAnswer }>;
  /** g5 review: `skillSha` of the skill the offer counted (offerDue). The gate saves only that skill on its yes. */
  skillSha?: string;
  /** D101: how often the job worked out from scratch (line 1's count), for Trail's own reason in the Stop and post-tool text. */
  seen?: { n: number; unit: 'day' | 'time' };
}

export interface CreditState {
  useId: string;
  injId: string;
  skillId: string;
  epoch: number;
  runId: string | null;
  stepsRan: number[];
  failedStep: number | null;
  check: 'passed' | 'failed' | 'none';
  calls: number;
  failed: number;
  flushed: boolean;
  promptsAfter: number;         // typed prompts since flush, for the 2-prompt correction window
}

/** The `skills` key of ~/.trail/sessions/<id>.json. The `trace` key beside it is the catch-up cursor (0.1). */
export interface SkillSessionState {
  v: 1;
  sessionHash: string;
  host: string;
  tier: 'A' | 'B' | 'C' | 'D';
  /** GateCtx.learn when this state was made (0 rule 2). */
  learn: boolean;
  /** Repo keys in scope for recall: the cwd's key, plus child checkouts when cwd is not in git (3.1). */
  scopeKeys: string[];
  epoch: number;
  /** SessionStart(compact) bumped the epoch before the fold met the compaction line (4.1). */
  pendingBoundary: boolean;
  /** At most 20, open run last. */
  runs: RunState[];
  pendingOffer: PendingOffer | null;
  /** The one offer of this session is spent (an offer, an asked save, or the shim's install line, D27). */
  offerUsed: boolean;
  offerUsedBy: 'offer' | 'asked' | 'install-line' | null;
  /** typed: set by the fold when it meets the typed line with this typedSha at or after `at` minus 5 s. */
  saveRequest: { runId: string; at: string; typedSha: string; scope: 'this repo' | 'every repo' | 'repo' | 'team';
                 typed: { offset: number; sha: string } | null;
                 /** D73: `skillSha` of the skill compiled when the person asked. The gate saves only that skill; missing: refused. */
                 skillSha?: string;
                 /** The name Trail gave that skill (the add it told the agent to run). The gate keeps it under this name, or
                  *  a numbered one when it was taken since; missing: refused. */
                 name?: string } | null;
  /** All epochs this session, newest last, at most 20. */
  injected: SkillInjection[];
  /** Newest last, at most 10. */
  credit: CreditState[];
  /** The first call that wrote Trail's or the host's files (4.1), as '<tool> <path or program>'. Never cleared. */
  tampered: string | null;
  /**
   * The run the last compaction cut mid-job, before it checked out (D59a): the next run the agent starts with no
   * typed ask continues its job. Spent by that run; cleared by any typed line.
   */
  cut?: string;
  /**
   * D116 item 3: how the agent's last reply ended (4.3: failure first, then a question, else done), from the fold's
   * last assistant text before a typed line or a call; cleared by a call, a typed line and a compaction. Never text.
   */
  replyEnd?: 'failure' | 'question' | 'done';
  updatedAt: string;
  /**
   * What was already folded, so a block of history the transcript repeats, or a transcript read again from
   * the top, folds once (D56d): 10 hex of sha256 per tool_use id, typed line and compaction line, concatenated,
   * oldest first, at most 6,000. Never an id in the clear.
   */
  seen?: string;
}

/* -------------------------------------------------------------------------- */
/* Phase 1b (design 1.0). Fields 1b adds to a 1a interface sit in a second     */
/* declaration of it, which TypeScript merges with the first. They are         */
/* optional: a session or state file written by 1a doesn't have them, and an   */
/* absent one reads as null (or 0, {}).                                        */
/* -------------------------------------------------------------------------- */

/** The wall catalog's classes (spec 12). Closed: equal to telemetry's wall_hit.class values, in the catalog's order. */
export type WallClass =
  | 'timeout-missing' | 'zsh-no-match' | 'git-https-auth' | 'docker-rootless'
  | 'npm-e401-eotp' | 'claude-not-logged-in' | 'enospc';

/** What changed between a failing call and the retry that worked (4.12). */
export type FixDeltaKind = 'env' | 'flag' | 'wrapper' | 'enable-step';

export interface FixDelta {
  kind: FixDeltaKind;
  /** env: the variable name; flag: the flag; wrapper: the program put in front; enable-step: that call's program. */
  name: string;
  /** The text as it ran, secret-checked and relativized ($HOME, repo-relative). Never a typed word. */
  text: string;
  /** The tool_use id that carried it. */
  callId: string;
}

export interface RepairEvent {
  cls: WallClass;
  program: string;
  failCallId: string;
  /** The retry that worked. */
  fixCallId: string;
  /** Non-empty, else it is not a repair. */
  delta: FixDelta[];
  epoch: number;
  runId: string | null;
  at: string;
}

/** Phase 2: moment 5 'update', moment 6 'drift', and the retire proposal 'retire' (4.7 to 4.10). */
export type OfferMoment = 'repeated' | 'repaired' | 'correction' | 'update' | 'drift' | 'retire';

export interface RunCall {
  /** Set by run-calls.ts makeCall (b2, R8): matchWall(result text, command, failed). Kept in run sheets as a class name only. */
  wall?: WallClass;
  /** The run's Edit/Write tool calls before this one, when any (b2 review): an edit between a failure and its retry may be the fix, so no repair. */
  editsBefore?: number;
}

export interface RunState {
  /** Filled at run close (4.12): at most 5 per run. The wall hits themselves are RunCall.wall. */
  repairs?: RepairEvent[];
}

export interface PendingOffer {
  /** b4: the repo the offer is for (its `offers.jsonl` line's `repo`). A correction's key names the skill, not the repo. */
  repo?: string;
  /** Moment 3. as 'lesson': lessonSha is the sha256 of the lesson text line 2 shows (R26). */
  repair?: { cls: WallClass; program: string; nth: number; firstAt: string;
             as: 'skill' | 'lesson'; delta: FixDelta[]; lessonSha?: string };
  /** Moment 4: the person's correction line (offset and sha), the first new step that worked after it, the lesson as offered. */
  correction?: { skillId: string; useId: string; typed: { offset: number; sha: string }; fixCallId: string | null; lessonSha: string;
                 /** b4: the fix command as the lesson holds it (params put back, relativized, risk-checked), or null: the agent's
                  *  command, never the person's words, so line 2 is rebuilt from the typed line and this (P17). */
                 fix?: string | null };
}

export interface SkillInjection {
  /** 8 hex of sha256 of the asks phrase that fired a 'job' cue; null for name, check, compact. Never the phrase (D71 b, R30). */
  phraseSha?: string | null;
}

export interface CreditState {
  /** Copied from the injection. */
  phraseSha?: string | null;
  /** creditWindow sets sha; the fold fills offset from an origin-human typed line only. */
  corrected?: { offset: number | null; sha: string } | null;
}

export interface SkillSessionState {
  lessonWatch?: { skillId: string; useId: string; typedSha: string; at: string } | null;
  /** The correction that withdrew this session's offer: only the moment-4 offer for that same correction may use the freed slot (P18, R40). */
  withdrewFor?: { typedSha: string } | null;
  /** Lines of sessions/<id>.denied.jsonl Stop has counted (3.5 step 5). */
  deniedSeen?: number;
}

/* -------------------------------------------------------------------------- */
/* Phase 2 (design 1.0, c0). Fields phase 2 adds to a 1a interface sit in a    */
/* further declaration of it, and are optional: a session file written by 1a   */
/* or 1b reads unchanged, an absent one reads as null.                         */
/* -------------------------------------------------------------------------- */

/** The facts of a Codex rollout's first line (`session_meta`, 4.15), read once. No text but `cwd`. c6's `codexMeta` returns it. */
export interface CodexMeta {
  id: string;
  originator: string | null;
  source: string | null;
  cliVersion: string | null;
  cwd: string | null;
  historyMode: 'legacy' | 'paginated' | null;
}

export interface PendingOffer {
  /** Moments 5 and 6 (4.7, 4.8): the change shown, pinned to the file it was computed from and to the text it would write. */
  fold?: { op: FoldOp | 'replace'; skillId: string; baseHash: string; proposalSha: string; handEdited: boolean;
           splitName?: string; lessonIds?: string[]; version: number };
  /** The retire proposal and drift (4.9): the skill a 'retire' answer retires. */
  retire?: { skillId: string; name: string };
}

export interface SkillSessionState {
  /** c7: Codex only. The rollout's first line, read once (4.17), and the keyed hashes (HMAC with its own key file,
   *  state/typed-key, D138 (3); 16 hex, last 20) of prompts the prompt hook saw (P30, R7). Never a prompt. */
  codex?: { meta: CodexMeta | null; typedShas: string[] };
  /** c8 (4.9): not-followed firings the prompt hook's settle wrote, for the next Stop's retire proposal. At most 4. */
  firedLater?: Array<{ skillId: string; name: string; followed: boolean; runId: string; at: string }>;
}

/** Phase 2 c8 (D137): a gated step this session couldn't ask for was denied and handed to the person to run. */
export interface SkillInjection {
  /** The gated steps handed to the person (from the gate file's marks): credit counts each as handed, not failed. */
  handed?: Array<{ n: number; at: string }>;
}
export interface RunState {
  /** The newest hand-off of one of its block's gated steps: the person's next ask of the job continues this run. */
  handedAt?: string;
}