Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

25.7 KB
Raw Blame
/**
 * Message-window scanner: the pure logic behind cursor pagination of
 * `GET /api/sessions/:id/messages` (TraceService.readMessagesPage).
 *
 * A window **unit** is one Task in the Web reducer's sense: it opens at a main-session
 * user prompt (text or image) and runs until the next such prompt. Cutting only at these
 * boundaries is what keeps every stream-model invariant intact inside a window — a
 * tool_call is never separated from its tool_call_output (outputs land before the next
 * user prompt), a compaction_begin/end span never splits (compaction-internal messages
 * stay skippable), a steering chip keeps the images that ride behind it, and a
 * mid-Task shard rotation (auto compaction with carry-over) stays glued to its Task.
 *
 * The scanner walks one shard's RAW messages (no subagent expansion — origin-carrying
 * messages never appear in a shard) and mirrors, decision for decision, the Web reducer
 * in web/src/lib/omni/stream-model.ts (pushMessage/startTask/finalizeOpenTask) plus the
 * outline-entry rule in web/src/features/chat/outline-model.ts (buildOutline) — the four
 * implementations of "what is one turn" (this file, stream-model, outline-model, and
 * trace-service.analyze) must stay in step; tests on both sides pin the shared cases.
 *
 * Two distinct counts come out of one pass:
 *   - **unit boundaries** — the safe cut points described above (banner-only prompts and
 *     goal-round re-sends included: they start Tasks in the reducer);
 *   - **outline turns** — the subset that opens an entry in the Web's conversation
 *     outline (`第 N 轮` numbering). Machine-only prompts (handoff / model-switch
 *     blocks), goal rounds past 1, steering chips and compaction injections do NOT open
 *     entries, and consecutive user messages of one send merge into one entry — the
 *     count must match buildOutline exactly, or a paginated outline would mis-number.
 *
 * The pass also accumulates the **prior stats** a partial window needs seeded into the
 * Web's stats tracker so header chips and per-turn cumulative rows keep telling the
 * truth (see task-stats.ts `seedPriorStats`): elapsed time of finished Tasks, subagent
 * token totals (via the caller-provided child expander), and the last main-session
 * session/context token readings.
 *
 * Scan state is carried across shards (a Task can span a rotation). Cached per-shard
 * prefix records (trace_files.page_stats) persist the carry so old shards are read at
 * most once ever; bump CACHE_VERSION whenever any rule in this file changes.
 */
import { parseUserSteeringText } from "@adelie/core";
import {
  parseBackgroundTaskDoneMessage,
  parseHandoffMessage,
  parseModelSwitchMessage,
} from "@adelie/core/markers";
import type { OmniMessage } from "@adelie/core";

/** Bump when any counting/boundary rule changes: cached page_stats records with an older version are recomputed. */
export const CACHE_VERSION = 4;

/** Cumulative totals at a point in the trace (all values are "before this point"). */
export interface WindowPriorStats {
  /** Outline entries opened before this point (the Web outline's global numbering offset). */
  turns: number;
  /** Sum of subagent token_usage request totals (all descendant sessions) before this point. */
  subagentTokens: number;
  /** Sum of finished Tasks' elapsed time before this point (the Web's sessionElapsedMs basis). */
  elapsedMs: number;
  /**
   * Sum of finished Tasks' model-API time before this point (the Web's sessionLlmMs basis):
   * paired request spans with the human approval wait deducted, compaction requests excluded —
   * the same scope `elapsedMs` uses, so the component and its total cover the same turns.
   */
  apiMs: number;
  /**
   * Sum of finished Tasks' tool wall time before this point (the Web's sessionToolMs basis):
   * per Task the union of its tool execution intervals, so parallel tools count once. Overlaps
   * `apiMs` when a tool runs on while the model decodes; the two never partition `elapsedMs`.
   */
  toolMs: number;
  /** The last main-session token_usage `session.total` seen before this point (0 = none). */
  sessionTokens: number;
  /** The last main-session NON-compaction token_usage `request.total` before this point (context occupancy basis). */
  contextTokens: number;
}

/** Open-Task bookkeeping carried across messages (mirrors StreamModel.task* fields). */
interface TaskCarry {
  open: boolean;
  /** Task first/latest message timestamps (ms; the degenerate-round elapsed fallback). */
  firstTsMs: number;
  lastTsMs: number;
  /** Last non-compaction request_end (ms); the Task's true end when present. */
  lastReqEndMs: number | null;
  /** Whether this Task saw main usage / non-blank assistant text — decides whether a stats row would be emitted at its close (which breaks a user-item run). */
  sawUsage: boolean;
  sawReply: boolean;
  /** Compaction usage held pending (committed to the Task by a later non-compaction request_end — mirrors task-stats.ts pendingCompaction*). */
  pendingCompactionUsage: boolean;
  /**
   * A tool output of the current turn has arrived and is still owed to the model (mirrors
   * StreamModel.turnToolOutputs: set by a complete tool_call_output, cleared when the next
   * request opens or a Task starts). A Task can never end in that window, so a background
   * completion notice landing there is in-task by position — the recognizer for notices
   * written by a pre-stamp core (see the user-text branch).
   */
  turnToolOutputs: boolean;
  /** Open Request's begin timestamp (ms), null between Requests (mirrors StreamModel.openRequestBeginMs). */
  reqBeginMs: number | null;
  /** Approval wait accumulated inside the open Request (ms), deducted at its end (mirrors StreamModel.openApprovalWaitMs). */
  reqApprovalWaitMs: number;
  /** This Task's model-API time so far (ms; mirrors task-stats taskLlmMs). */
  apiMs: number;
  /**
   * Tool executions still open, keyed by tool_call_id, holding each one's execution start (ms):
   * the tool_call's own timestamp, moved forward to the approval moment once one arrives. A
   * plain object rather than a Map because a shard is cached mid-Task and this state is JSON.
   */
  openTools: Record<string, number>;
  /** This Task's settled tool execution intervals (ms), unioned when it closes (mirrors task-stats taskToolIntervals). */
  toolIntervals: Array<[number, number]>;
}

/**
 * Total length of the **union** of the given intervals (ms): overlapping and nested runs count
 * once, so parallel tool calls yield wall time rather than a sum of durations. Shared with
 * trace-service, which decomposes finished Trace files the same way.
 */
export function mergedIntervalMs(intervals: ReadonlyArray<readonly [number, number]>): number {
  if (intervals.length === 0) return 0;
  const sorted = [...intervals].sort((a, b) => a[0] - b[0]);
  let total = 0;
  let [openStart, openEnd] = sorted[0]!;
  for (let i = 1; i < sorted.length; i++) {
    const [start, end] = sorted[i]!;
    if (start > openEnd) {
      total += openEnd - openStart;
      openStart = start;
      openEnd = end;
    } else if (end > openEnd) {
      openEnd = end;
    }
  }
  return total + (openEnd - openStart);
}

/** Full scanner state, serializable into a shard's cached prefix record. */
export interface ScanState {
  totals: WindowPriorStats;
  task: TaskCarry;
  /** Between a main-session compaction_begin and its compaction_end. */
  compactionActive: boolean;
  /** A steering chip is still collecting its trailing images (mirrors StreamModel.openSteering). */
  steeringOpen: boolean;
  /**
   * Inside an unbroken, entry-carrying run of user items — buildOutline's `lastWasUser`,
   * tracked at the item level: true after an entry-eligible user item, false after any
   * non-user item (a stats row included) AND after banner/goal-round texts (which open no
   * entry and break the run in buildOutline). Both the window-cut and the merge decision
   * key off it, so a cut can never split what the outline merges.
   */
  runOpen: boolean;
}

export function initialScanState(): ScanState {
  return {
    totals: {
      turns: 0,
      subagentTokens: 0,
      elapsedMs: 0,
      apiMs: 0,
      toolMs: 0,
      sessionTokens: 0,
      contextTokens: 0,
    },
    task: {
      open: false,
      firstTsMs: 0,
      lastTsMs: 0,
      lastReqEndMs: null,
      sawUsage: false,
      sawReply: false,
      pendingCompactionUsage: false,
      turnToolOutputs: false,
      reqBeginMs: null,
      reqApprovalWaitMs: 0,
      apiMs: 0,
      openTools: {},
      toolIntervals: [],
    },
    compactionActive: false,
    steeringOpen: false,
    runOpen: false,
  };
}

/** One safe cut point: `ordinal` indexes into the shard's parsed message array; `stats` is the cumulative prior AT the cut (the unit itself not included). */
export interface UnitBoundary {
  ordinal: number;
  stats: WindowPriorStats;
}

/**
 * Aggregate a subagent pointer's child subtree without materializing its messages:
 * the token sum feeds `subagentTokens`, the max timestamp advances the open Task's
 * lastTs exactly as routeNested's touchTask would for every expanded child message.
 * Null = child trace missing (the pointer event stays a plain event, contributing nothing).
 */
export interface ChildAggregate {
  requestTokens: number;
  maxTsMs: number | null;
}

function tsMs(timestamp: string): number | null {
  const ms = Date.parse(timestamp);
  return Number.isFinite(ms) ? ms : null;
}

/** Mirrors stream-model touchTask: advance the open Task's latest timestamp (compaction-internal messages excluded). */
function touchTask(state: ScanState, ms: number | null): void {
  if (!state.task.open || state.compactionActive || ms === null) return;
  if (ms > state.task.lastTsMs) state.task.lastTsMs = ms;
}

/** Mirrors stream-model finalizeOpenTask + task-stats endTask: settle the open Task's elapsed into the cumulative. */
function finalizeTask(state: ScanState): void {
  const t = state.task;
  if (!t.open) return;
  t.open = false;
  const endMs = t.lastReqEndMs ?? t.lastTsMs;
  state.totals.elapsedMs += Math.max(0, endMs - t.firstTsMs);
  // The elapsed breakdown folds on the same boundary as the total (mirrors task-stats endTask).
  // Tools still open at the close never finished within this trace and contribute nothing.
  state.totals.apiMs += t.apiMs;
  state.totals.toolMs += mergedIntervalMs(t.toolIntervals);
  t.pendingCompactionUsage = false;
}

/** Mirrors stream-model startTask: finalize the previous Task and open a new one at `ms`. */
function startTask(state: ScanState, ms: number | null): void {
  finalizeTask(state);
  const t = state.task;
  t.open = true;
  t.firstTsMs = ms ?? 0;
  t.lastTsMs = t.firstTsMs;
  t.lastReqEndMs = null;
  t.sawUsage = false;
  t.sawReply = false;
  t.pendingCompactionUsage = false;
  t.turnToolOutputs = false;
  t.reqBeginMs = null;
  t.reqApprovalWaitMs = 0;
  t.apiMs = 0;
  t.openTools = {};
  t.toolIntervals = [];
}

/** A non-user item entered the stream: the user-item run breaks (buildOutline's lastWasUser = false). */
function breakRuns(state: ScanState): void {
  state.runOpen = false;
}

/**
 * Handle one Task-starting user message (prompt text or non-steering image).
 * `entryEligible` says whether the message would open an outline entry (buildOutline's
 * rule); ineligible messages (banner blocks, harness-injected inputs) still start Tasks — and
 * still cut when the run is broken — but never count and always break the run, exactly
 * as buildOutline resets lastWasUser for them.
 */
function onTaskStart(
  state: ScanState,
  ms: number | null,
  entryEligible: boolean,
  onBoundary: (stats: WindowPriorStats) => void,
): void {
  // A stats row emitted while closing the previous Task lands BEFORE this user item and
  // breaks the item run (finalizeOpenTask inserts it ahead of the new prompt) — mirror
  // that so two sends merged by the outline are never cut apart, while two sends
  // separated by a stats row cut (and count) as two.
  if (state.task.open && (state.task.sawUsage || state.task.sawReply)) breakRuns(state);
  const boundary = !state.runOpen;
  startTask(state, ms);
  if (boundary) onBoundary({ ...state.totals });
  if (entryEligible) {
    if (boundary) state.totals.turns += 1;
    state.runOpen = true;
  } else {
    state.runOpen = false;
  }
}

/**
 * buildOutline's eligibility for a user prompt: machine-only source blocks and
 * harness-injected inputs (goal rounds, hook continues) open no entry. A background
 * completion notice shares the harness stamp but keeps its independent turn when it starts
 * a Task (`isNotice` — the caller already parsed it), matching the Web reducer.
 */
function outlineEligible(text: string, sender: string | undefined, isNotice: boolean): boolean {
  if (sender === "harness" && !isNotice) return false;
  return !parseHandoffMessage(text) && !parseModelSwitchMessage(text);
}

/**
 * Scan one shard's raw messages, mutating `state` in place and reporting every unit
 * boundary through `onBoundary` (with the cumulative priors AT the cut). `expandChild`
 * resolves a subagent pointer's aggregate (may hit a per-request memo); pass null to
 * skip child reads when the caller does not need subagent totals for this span.
 */
export async function scanMessages(
  state: ScanState,
  messages: readonly OmniMessage[],
  onBoundary: (ordinal: number, stats: WindowPriorStats) => void,
  expandChild: ((sessionId: string) => Promise<ChildAggregate | null>) | null,
  fromOrdinal = 0,
  toOrdinal = messages.length,
): Promise<void> {
  for (let i = fromOrdinal; i < toOrdinal; i++) {
    const msg = messages[i]!;
    // Shards never contain origin-carrying messages (core's Writer filters them);
    // defensively skip any that appear rather than mis-shaping the counts.
    if (msg.origin !== undefined && msg.origin.length > 0) continue;
    const ms = tsMs(msg.timestamp);
    const p = msg.payload as Record<string, unknown> & { type?: string; role?: string };

    // Mirrors pushMessage's first step: anything that is not a complete user image or video
    // closes the steering-images window (session_meta and events included).
    const isUserMedia =
      msg.type === "model_msg" && (p.type === "image_url" || p.type === "video_url");
    if (!isUserMedia) state.steeringOpen = false;

    if (msg.type === "model_msg") {
      // Compaction-internal model messages: never rendered, never counted (stream-model
      // returns before any item/Task logic; only touchTask advances).
      if (state.compactionActive) {
        touchTask(state, ms);
        continue;
      }
      if (p.type === "text" && p.role === "user" && typeof p.text === "string") {
        const text = p.text;
        // Compaction-summary injection: no item, no Task, no run change.
        if (text.startsWith("[context_summary]") || text.startsWith("<context_summary>")) {
          touchTask(state, ms);
          continue;
        }
        // Mid-run steering: rendered as a user_steering item (not user_text) — it breaks
        // the outline's user-item run but never starts a Task or cuts a window.
        if (parseUserSteeringText(text) !== null) {
          touchTask(state, ms);
          breakRuns(state);
          state.steeringOpen = true;
          continue;
        }
        // A background completion notice injected into the running Task rides inside it
        // like steering — a banner item, no Task start, no cut, no entry — but opens no
        // trailing-image window (notices carry none). Recognized by the delivery stamp,
        // or by POSITION for notices written by a pre-stamp core: a Task never ends while
        // this turn's tool outputs are still owed to the model (turnToolOutputs), so a
        // notice landing there is in-task even without the stamp — the same rule trace
        // analysis applies, and the same fallback the Web reducer applies (the two must
        // stay in step). An unstamped notice after a no-tool turn falls through to
        // onTaskStart: an idle-launched notice task keeps its independent turn.
        const notice = parseBackgroundTaskDoneMessage(text);
        if (
          notice !== null &&
          (notice.done.delivery === "steering" || state.task.turnToolOutputs)
        ) {
          touchTask(state, ms);
          breakRuns(state);
          continue;
        }
        onTaskStart(
          state,
          ms,
          outlineEligible(text, (p as { sender?: string }).sender, notice !== null),
          (stats) => onBoundary(i, stats),
        );
        continue;
      }
      if (p.type === "image_url" || p.type === "video_url") {
        // An image or video riding behind a steering chip folds into it: no item, no Task.
        if (state.steeringOpen) {
          touchTask(state, ms);
          continue;
        }
        onTaskStart(state, ms, true, (stats) => onBoundary(i, stats));
        continue;
      }
      if (p.type === "text" && p.role === "assistant" && typeof p.text === "string") {
        touchTask(state, ms);
        // Blank fidelity-only messages produce no item (stream-model discards them).
        if (p.text.trim() !== "") {
          state.task.sawReply = true;
          breakRuns(state);
        }
        continue;
      }
      if (p.type === "thinking") {
        touchTask(state, ms);
        if (typeof p.thinking === "string" && p.thinking.trim() !== "") breakRuns(state);
        continue;
      }
      if (p.type === "tool_call") {
        touchTask(state, ms);
        // Execution starts here unless an approval follows and moves it (mirrors
        // stream-model's settleToolDuration, which prefers approvalAtMs over callStartedAtMs).
        if (ms !== null && typeof p.tool_call_id === "string" && p.tool_call_id !== "") {
          state.task.openTools[p.tool_call_id] = ms;
        }
        breakRuns(state);
        continue;
      }
      if (p.type === "tool_call_output") {
        // Updates an existing card (no new item); the turn now owes the model its results
        // — the window a positionally-recognized notice keys on (see turnToolOutputs).
        touchTask(state, ms);
        if (ms !== null && typeof p.tool_call_id === "string") {
          const startMs = state.task.openTools[p.tool_call_id];
          if (startMs !== undefined) {
            delete state.task.openTools[p.tool_call_id];
            if (ms > startMs) state.task.toolIntervals.push([startMs, ms]);
          }
        }
        state.task.turnToolOutputs = true;
        continue;
      }
      // inline_* render nothing.
      touchTask(state, ms);
      continue;
    }

    if (msg.type === "event_msg") {
      touchTask(state, ms);
      const t = p.type;
      if (t === "compaction_begin") {
        state.compactionActive = true;
        breakRuns(state); // the compaction banner is an item
        continue;
      }
      if (t === "compaction_end") {
        // Closes the banner opened by the begin (no new item mid-window). A compaction the
        // user quit out of is closed as `failed` by the resume path before the session
        // appends anything else (see core's resumeSession), so a span is never left open
        // across the conversation that follows it.
        state.compactionActive = false;
        continue;
      }
      if (t === "abort") {
        breakRuns(state); // the interruption marker is an item
        continue;
      }
      if (t === "request_end") {
        // Pair with request_begin for this Task's API time, deducting the approval wait that
        // falls inside the span (core awaits approval inside the streaming loop). Settled
        // before the compaction guard below so a compaction Request still clears the pairing;
        // its time is excluded here exactly as it is from the Chat page's elapsed.
        const reqBeginMs = state.task.reqBeginMs;
        const reqWaitMs = state.task.reqApprovalWaitMs;
        state.task.reqBeginMs = null;
        state.task.reqApprovalWaitMs = 0;
        if (!state.compactionActive && reqBeginMs !== null && ms !== null) {
          state.task.apiMs += Math.max(0, ms - reqBeginMs - reqWaitMs);
        }
        if (state.compactionActive) continue; // compaction requests render nothing
        if (ms !== null) state.task.lastReqEndMs = ms;
        // Pending compaction usage commits at a later non-compaction request_end
        // (compaction mid-Task) — from then on the Task WILL show a stats row.
        if (state.task.pendingCompactionUsage) {
          state.task.sawUsage = true;
          state.task.pendingCompactionUsage = false;
        }
        const status = p.status;
        // A retryable end renders a reconnect-hint item. The legacy spellings
        // (failed/timeout/malformed) keep pre-convergence Traces rendering the same way.
        if (
          status === "retryable" ||
          status === "failed" ||
          status === "timeout" ||
          status === "malformed"
        ) {
          breakRuns(state);
        }
        continue;
      }
      if (t === "token_usage") {
        const request = p.request as { total?: number } | undefined;
        const session = p.session as { total?: number } | undefined;
        // The session cumulative tracks the provider even during compaction
        // (task-stats trackMainUsage does the same).
        if (typeof session?.total === "number") state.totals.sessionTokens = session.total;
        if (state.compactionActive) {
          state.task.pendingCompactionUsage = true;
        } else {
          if (typeof request?.total === "number") state.totals.contextTokens = request.total;
          state.task.sawUsage = true;
        }
        continue;
      }
      if (t === "subagent" && typeof p.session_id === "string" && expandChild !== null) {
        // The pointer expands to the child's messages in the served transcript: their
        // token_usage feeds the parent's subagent totals at every depth, and their
        // timestamps advance the open Task exactly as routeNested's touchTask would.
        const agg = await expandChild(p.session_id);
        if (agg !== null) {
          state.totals.subagentTokens += agg.requestTokens;
          touchTask(state, agg.maxTsMs);
        }
        continue;
      }
      if (t === "request_begin") {
        // No item, no run change — but a new request means the previous turn's tool
        // outputs have been sent with it (mirrors stream-model's request_begin reset;
        // compaction requests don't consume the pending turn state).
        if (!state.compactionActive) state.task.turnToolOutputs = false;
        if (ms !== null) state.task.reqBeginMs = ms;
        continue;
      }
      if (t === "approval_decision") {
        // The human wait ran inside the open Request (core awaits approval in the streaming
        // loop), so it is deducted from API time; execution only begins now, so the tool's
        // interval start moves here (mirrors stream-model noteApprovalWait + settleToolDuration).
        const id = (p as { tool_call_id?: unknown }).tool_call_id;
        if (ms !== null && typeof id === "string") {
          const calledMs = state.task.openTools[id];
          if (calledMs !== undefined) {
            if (ms > calledMs) state.task.reqApprovalWaitMs += ms - calledMs;
            state.task.openTools[id] = ms;
          }
        }
        continue;
      }
      // Unexpanded pointers: no items, no run change.
      continue;
    }
    // session_meta: no item (steering window already closed above).
  }
}

/** Finalize the trailing open Task (end of the whole trace): the cumulative then covers every finished Task. */
export function finalizeScan(state: ScanState): void {
  finalizeTask(state);
}

// ---------------------------------------------------------------------------
// Cursor encoding
// ---------------------------------------------------------------------------

/** A window cursor: shard file index + message ordinal within that shard's parsed array. */
export interface MessageCursor {
  fileIndex: number;
  ordinal: number;
}

/**
 * `<fileIndex>:<ordinal>` — stable across requests and compaction: rotation always
 * opens a NEW shard, closed shards are immutable, and the active shard is append-only,
 * so a (shard, ordinal) pair never moves.
 */
export function encodeCursor(c: MessageCursor): string {
  return `${c.fileIndex}:${c.ordinal}`;
}

/** Strict parse of a cursor string; null when malformed (callers turn that into a 400). */
export function decodeCursor(raw: string): MessageCursor | null {
  const m = /^(\d{1,9}):(\d{1,9})$/.exec(raw);
  if (!m) return null;
  return { fileIndex: Number(m[1]), ordinal: Number(m[2]) };
}

// ---------------------------------------------------------------------------
// Cached per-shard prefix records
// ---------------------------------------------------------------------------

/**
 * The persisted shape of trace_files.page_stats: the scan state at the END of a shard
 * (cumulative from the very beginning of the session). Only immutable shards are cached
 * — the newest shard still grows. `v` gates rule evolution: a record from an older
 * CACHE_VERSION is recomputed as if absent.
 */
export interface ShardPrefixRecord {
  v: number;
  state: ScanState;
}

export function serializePrefix(state: ScanState): string {
  return JSON.stringify({ v: CACHE_VERSION, state } satisfies ShardPrefixRecord);
}

/** Parse a cached record; null when absent, unparseable, or from another CACHE_VERSION. */
export function deserializePrefix(raw: string | null): ScanState | null {
  if (raw === null) return null;
  try {
    const rec = JSON.parse(raw) as ShardPrefixRecord;
    if (rec.v !== CACHE_VERSION || typeof rec.state !== "object" || rec.state === null) {
      return null;
    }
    return rec.state;
  } catch {
    return null;
  }
}

/** Deep-copy a scan state (cached records must not be mutated by a later scan). */
export function cloneScanState(state: ScanState): ScanState {
  return {
    totals: { ...state.totals },
    task: { ...state.task },
    compactionActive: state.compactionActive,
    steeringOpen: state.steeringOpen,
    runOpen: state.runOpen,
  };
}