@seanxdo/superview 0.1.13

package/core/contextReplay.ts

@@ -0,0 +1,388 @@
+import type {
+  CodexHistoryPrompt,
+  ContextBlock,
+  ContextBlockState,
+  ContextBlockType,
+  ContextReplayResponse,
+  ContextSnapshot,
+  ContextSnapshotPhase,
+  ContextWarning,
+  EventEvidence,
+  TimelineEvent,
+  TaskJourneyDetail
+} from "./types";
+
+export function buildContextReplay({
+  detail,
+  evidenceByEventId,
+  historyPrompts = []
+}: {
+  detail: TaskJourneyDetail;
+  evidenceByEventId?: Record<string, EventEvidence>;
+  historyPrompts?: CodexHistoryPrompt[];
+}): ContextReplayResponse {
+  const evidence = evidenceByEventId ?? {};
+  const events = orderedJourneyEvents(detail);
+  const activeBlocks = new Map<string, ContextBlock>();
+  const finalBlocks = new Map<string, ContextBlock>();
+  const snapshots: ContextSnapshot[] = [];
+  const warnings: ContextWarning[] = [];
+
+  for (const [index, event] of events.entries()) {
+    if (index === 1 && historyPrompts.length > 0) {
+      const historyBlocks = historyPrompts.map((prompt, promptIndex) => historyPromptBlock(prompt, promptIndex, detail.journey.promptEventId));
+      addSnapshot({
+        snapshots,
+        activeBlocks,
+        finalBlocks,
+        event: events[0],
+        phase: "history",
+        title: "History context",
+        addedBlocks: historyBlocks,
+        warnings: warningsForSnapshot(warnings, historyBlocks, events[0].id)
+      });
+    }
+
+    const addedBlocks = blocksForEvent(event, evidence[event.id]);
+    const snapshotWarnings: ContextWarning[] = [];
+    const isFinalResponse = event.kind === "assistant_message" && index === events.length - 1;
+    if (isFinalResponse && !hasSuccessfulVerificationBefore(events, index)) {
+      snapshotWarnings.push({
+        id: "warning-unverified-final",
+        severity: "high",
+        title: "Unverified final response",
+        detail: "The final assistant response is observable, but no verification event appears before it in this task journey.",
+        blockIds: addedBlocks.map((block) => block.id),
+        eventIds: [event.id]
+      });
+    }
+
+    addSnapshot({
+      snapshots,
+      activeBlocks,
+      finalBlocks,
+      event,
+      phase: phaseForEvent(event),
+      title: event.title,
+      addedBlocks,
+      warnings: snapshotWarnings
+    });
+    pushUniqueWarnings(warnings, snapshotWarnings);
+  }
+
+  const finalEvent = events.at(-1);
+  if (finalEvent) {
+    const staleHistoryBlocks = Array.from(activeBlocks.values()).filter((block) => block.type === "history_prompt" && block.state !== "cited");
+    if (staleHistoryBlocks.length > 0) {
+      const staleWarning: ContextWarning = {
+        id: "warning-stale-history",
+        severity: "medium",
+        title: "Stale history context",
+        detail: "A history prompt entered the observable context but was not cited by later tool, file, verification, or response events.",
+        blockIds: staleHistoryBlocks.map((block) => block.id),
+        eventIds: [finalEvent.id]
+      };
+      pushUniqueWarnings(warnings, [staleWarning]);
+      const lastSnapshot = snapshots.at(-1);
+      if (lastSnapshot) {
+        const updatedBlocks = lastSnapshot.blocks.map((block) =>
+          staleHistoryBlocks.some((stale) => stale.id === block.id)
+            ? {
+                ...block,
+                state: "stale" as ContextBlockState,
+                confidence: "inferred" as const,
+                reason: "Potentially stale: history prompt is not cited by later observable events."
+              }
+            : block
+        );
+        lastSnapshot.blocks = updatedBlocks;
+        lastSnapshot.warnings = [...lastSnapshot.warnings, staleWarning];
+        for (const block of updatedBlocks) finalBlocks.set(block.id, block);
+      }
+    }
+  }
+
+  return {
+    journey: detail.journey,
+    snapshots,
+    blocks: Array.from(finalBlocks.values()),
+    evidenceByEventId: evidence,
+    warnings
+  };
+}
+
+function orderedJourneyEvents(detail: TaskJourneyDetail) {
+  const byId = new Map(detail.events.map((event) => [event.id, event]));
+  const ordered = detail.journey.eventIds.map((id) => byId.get(id)).filter((event): event is TimelineEvent => Boolean(event));
+  return ordered.length > 0 ? ordered : [...detail.events].sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
+}
+
+function addSnapshot({
+  snapshots,
+  activeBlocks,
+  finalBlocks,
+  event,
+  phase,
+  title,
+  addedBlocks,
+  warnings
+}: {
+  snapshots: ContextSnapshot[];
+  activeBlocks: Map<string, ContextBlock>;
+  finalBlocks: Map<string, ContextBlock>;
+  event: TimelineEvent;
+  phase: ContextSnapshotPhase;
+  title: string;
+  addedBlocks: ContextBlock[];
+  warnings: ContextWarning[];
+}) {
+  const addedBlockIds = addedBlocks.map((block) => block.id);
+  const retainedBlockIds: string[] = [];
+  const changedBlockIds: string[] = [];
+  const droppedBlockIds: string[] = [];
+
+  for (const [id, block] of activeBlocks.entries()) {
+    const next = nextBlockState(block, event, phase);
+    if (next.state === "cited" || next.state === "changed") changedBlockIds.push(id);
+    if (next.state === "dropped" || next.state === "stale" || next.state === "contradicted") droppedBlockIds.push(id);
+    if (next.state === "retained") retainedBlockIds.push(id);
+    activeBlocks.set(id, next);
+  }
+
+  for (const block of addedBlocks) {
+    activeBlocks.set(block.id, block);
+  }
+
+  const blocks = Array.from(activeBlocks.values()).map((block) => ({ ...block }));
+  for (const block of blocks) finalBlocks.set(block.id, block);
+
+  snapshots.push({
+    id: `context-snapshot-${event.id}-${phase}`,
+    phase,
+    timestamp: event.timestamp,
+    eventId: event.id,
+    title,
+    blocks,
+    addedBlockIds,
+    retainedBlockIds,
+    changedBlockIds,
+    droppedBlockIds,
+    warnings,
+    tokenUsage: event.tokenUsage ?? null
+  });
+}
+
+function nextBlockState(block: ContextBlock, event: TimelineEvent, phase: ContextSnapshotPhase): ContextBlock {
+  if (event.id === block.sourceEventId) return block;
+  if (referencesBlock(event, block)) {
+    return {
+      ...block,
+      state: "cited",
+      confidence: "inferred",
+      reason: `Cited by ${event.kind} event via observable text, file path, command, or phrase.`
+    };
+  }
+  if (phase === "response") {
+    if (block.type === "history_prompt") {
+      return {
+        ...block,
+        state: "stale",
+        confidence: "inferred",
+        reason: "Potentially stale: history prompt is not cited by the final response."
+      };
+    }
+    if (block.type !== "user_prompt" && block.type !== "verification_output") {
+      return {
+        ...block,
+        state: "dropped",
+        confidence: "inferred",
+        reason: `Dropped at final response: block content is not referenced by ${event.id}.`
+      };
+    }
+  }
+  if (block.state === "new") {
+    return {
+      ...block,
+      state: "retained",
+      reason: "Retained in the active observable journey window."
+    };
+  }
+  return block;
+}
+
+function blocksForEvent(event: TimelineEvent, evidence: EventEvidence | undefined): ContextBlock[] {
+  const blocks: ContextBlock[] = [];
+  const base = {
+    sourceEventId: event.id,
+    rawEventRefId: event.rawEventRefId,
+    timestamp: event.timestamp,
+    sourcePath: evidence?.rawEvent?.sourcePath ?? null,
+    lineNo: evidence?.rawEvent?.lineNo ?? null,
+    files: event.files,
+    skills: (event.skills ?? []).map((skill) => skill.name)
+  };
+
+  if (event.kind === "user_prompt") {
+    blocks.push(contextBlock(event, base, "user_prompt", event.title, event.detail ?? event.title, "User prompt directly entered the agent conversation."));
+  } else if (event.kind === "tool_call") {
+    blocks.push(contextBlock(event, base, "tool_input", event.toolName ?? event.title, event.detail ?? event.title, "Tool input was invoked by the agent."));
+  } else if (event.kind === "tool_result") {
+    const artifacts = evidence?.artifacts.length ? evidence.artifacts : [];
+    if (artifacts.length === 0) {
+      blocks.push(contextBlock(event, base, "tool_output", event.toolName ?? event.title, event.detail ?? event.title, "Tool output was returned to the agent."));
+    } else {
+      for (const [index, artifact] of artifacts.entries()) {
+        blocks.push(
+          contextBlock(
+            event,
+            { ...base, sourcePath: artifact.path ?? base.sourcePath, files: artifact.path ? [artifact.path, ...event.files] : event.files },
+            artifact.type === "file" ? "file_excerpt" : "tool_output",
+            artifact.path ?? `${event.title} artifact`,
+            artifact.excerpt,
+            "Artifact excerpt is stored as redacted observable evidence.",
+            index
+          )
+        );
+      }
+    }
+  } else if (event.kind === "file_change") {
+    for (const [index, file] of event.files.entries()) {
+      blocks.push(contextBlock(event, { ...base, sourcePath: file, files: [file] }, "file_reference", file, file, "File path changed during this task.", index));
+    }
+    if (event.detail) {
+      blocks.push(contextBlock(event, base, "file_excerpt", event.title, event.detail, "File change summary entered the observable context.", event.files.length));
+    }
+  } else if (event.kind === "verification") {
+    blocks.push(contextBlock(event, base, "verification_output", event.title, event.detail ?? event.title, "Verification output is observable evidence for the result."));
+  } else if (event.kind === "assistant_message") {
+    blocks.push(contextBlock(event, base, "final_response", event.title, event.detail ?? event.title, "Assistant response is the visible result of this task journey."));
+  } else if (event.kind === "reasoning_marker") {
+    blocks.push(contextBlock(event, base, "reasoning_summary", event.title, event.detail ?? event.title, "Reasoning summary marker was visible in the log."));
+  } else if (event.kind === "error") {
+    blocks.push(contextBlock(event, base, "error_output", event.title, event.detail ?? event.title, "Error output contradicted or interrupted the active path."));
+  }
+
+  for (const [index, skill] of (event.skills ?? []).entries()) {
+    blocks.push(
+      contextBlock(
+        event,
+        base,
+        "skill_instruction",
+        skill.name,
+        skill.excerpt || skill.command || skill.path || skill.name,
+        `Skill ${skill.name} was detected from ${skill.source}.`,
+        blocks.length + index
+      )
+    );
+  }
+
+  return blocks.filter((block) => block.excerpt.trim().length > 0);
+}
+
+function contextBlock(
+  event: TimelineEvent,
+  base: Pick<ContextBlock, "sourceEventId" | "rawEventRefId" | "timestamp" | "sourcePath" | "lineNo" | "files" | "skills">,
+  type: ContextBlockType,
+  title: string,
+  excerpt: string,
+  reason: string,
+  index = 0
+): ContextBlock {
+  return {
+    id: `context-block-${event.id}-${type}-${index}`,
+    type,
+    state: "new",
+    title,
+    excerpt: trimExcerpt(excerpt),
+    tokenEstimate: estimateTokens(excerpt),
+    confidence: "direct",
+    reason,
+    ...base
+  };
+}
+
+function historyPromptBlock(prompt: CodexHistoryPrompt, index: number, promptEventId: string): ContextBlock {
+  return {
+    id: `context-block-history-${index}`,
+    type: "history_prompt",
+    state: "new",
+    title: "History prompt",
+    excerpt: trimExcerpt(prompt.text),
+    sourceEventId: promptEventId,
+    rawEventRefId: null,
+    sourcePath: prompt.sourcePath,
+    lineNo: prompt.lineNo,
+    timestamp: prompt.ts,
+    tokenEstimate: estimateTokens(prompt.text),
+    confidence: "direct",
+    reason: "History prompt is observable from history.jsonl near this session.",
+    files: extractFilePaths(prompt.text),
+    skills: []
+  };
+}
+
+function phaseForEvent(event: TimelineEvent): ContextSnapshotPhase {
+  if (event.kind === "user_prompt") return "prompt";
+  if (event.kind === "tool_call") return "tool_call";
+  if (event.kind === "tool_result") return "tool_result";
+  if (event.kind === "file_change") return "file_change";
+  if (event.kind === "verification") return "verification";
+  if (event.kind === "assistant_message") return "response";
+  return "planning";
+}
+
+function referencesBlock(event: TimelineEvent, block: ContextBlock) {
+  const haystack = eventText(event);
+  if (!haystack) return false;
+  const needles = [
+    ...block.files,
+    block.sourcePath ?? "",
+    ...extractFilePaths(block.excerpt),
+    ...importantPhrases(block.excerpt),
+    block.title
+  ]
+    .map((item) => item.trim())
+    .filter((item) => item.length >= 4);
+  return needles.some((needle) => haystack.includes(needle.toLowerCase()));
+}
+
+function eventText(event: TimelineEvent) {
+  return [event.title, event.detail, event.toolName, event.callId, ...event.files].filter(Boolean).join("\n").toLowerCase();
+}
+
+function importantPhrases(text: string) {
+  const filePaths = extractFilePaths(text);
+  const compactNumbers = text.match(/\b\d+[-/]\d+\b/g) ?? [];
+  const distinctivePhrases = (text.match(/\b[A-Za-z0-9_.-]+(?:\s+[A-Za-z0-9_.-]+){2,5}\b/g) ?? [])
+    .map((phrase) => phrase.toLowerCase())
+    .filter((phrase) => phrase.length >= 24)
+    .slice(0, 4);
+  return [...filePaths, ...compactNumbers, ...distinctivePhrases];
+}
+
+function extractFilePaths(text: string) {
+  return text.match(/[A-Za-z0-9_.-]+\/[A-Za-z0-9_./-]+/g) ?? [];
+}
+
+function trimExcerpt(text: string) {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length > 360 ? `${normalized.slice(0, 357)}...` : normalized;
+}
+
+function estimateTokens(text: string) {
+  return Math.max(1, Math.ceil(text.trim().length / 4));
+}
+
+function hasSuccessfulVerificationBefore(events: TimelineEvent[], finalIndex: number) {
+  return events.slice(0, finalIndex).some((event) => event.kind === "verification" && event.status !== "failed");
+}
+
+function warningsForSnapshot(warnings: ContextWarning[], blocks: ContextBlock[], eventId: string) {
+  return warnings.filter((warning) => warning.eventIds.includes(eventId) || warning.blockIds.some((blockId) => blocks.some((block) => block.id === blockId)));
+}
+
+function pushUniqueWarnings(target: ContextWarning[], warnings: ContextWarning[]) {
+  for (const warning of warnings) {
+    if (!target.some((item) => item.id === warning.id)) target.push(warning);
+  }
+}

package/core/cost.ts

@@ -0,0 +1,125 @@
+import type { SessionRecord, TaskJourney, TokenUsage } from "./types";
+
+/** A single pricing tier matched by model name substring. */
+export interface ModelPricing {
+  id: string;
+  provider: "Anthropic" | "OpenAI" | "Other";
+  label: string;
+  test: RegExp;
+  inRate: number;   // $/1M input tokens
+  outRate: number;  // $/1M output tokens
+}
+
+/** Default pricing table (USD per 1M tokens, standard API tiers, June 2026). */
+export const DEFAULT_PRICING: ModelPricing[] = [
+  // Anthropic (Claude Code)
+  { id: "sonnet",  provider: "Anthropic", label: "Sonnet",       test: /sonnet/i,             inRate: 3,   outRate: 15  },
+  { id: "haiku45", provider: "Anthropic", label: "Haiku 4.5",    test: /haiku-?4-?5/i,        inRate: 1,   outRate: 5   },
+  { id: "haiku",   provider: "Anthropic", label: "Haiku (3.x)",  test: /haiku/i,              inRate: 0.8, outRate: 4   },
+  { id: "opus4x",  provider: "Anthropic", label: "Opus 4.5–4.8", test: /opus-?4-?(5|6|7|8)/i, inRate: 5,   outRate: 25  },
+  { id: "opus",    provider: "Anthropic", label: "Opus",         test: /opus/i,               inRate: 5,   outRate: 25  },
+
+  // OpenAI (Codex)
+  { id: "oMini",   provider: "OpenAI", label: "GPT mini",   test: /mini/i,               inRate: 0.45, outRate: 3.6  },
+  { id: "oGpt5",   provider: "OpenAI", label: "GPT-5",      test: /(gpt-?5|o3|o4)/i,     inRate: 2.5,  outRate: 15  },
+  { id: "o55",     provider: "OpenAI", label: "GPT-5.5",    test: /gpt-?5\.?5/i,         inRate: 5,    outRate: 30  },
+
+  // Fallback
+  { id: "unknown", provider: "Other", label: "Unknown", test: /.*/, inRate: 3, outRate: 15 },
+];
+
+export const CACHE_READ_MULT = 0.1;
+export const CACHE_WRITE_MULT = 1.25;
+
+/** Match a pricing tier from a model string. */
+export function matchPricing(model: string | null | undefined, pricing = DEFAULT_PRICING): ModelPricing {
+  const m = model ?? "";
+  for (const p of pricing) {
+    if (p.test.test(m)) return p;
+  }
+  return pricing[pricing.length - 1];
+}
+
+/** Estimate the cost of a single TokenUsage record. */
+export function estimateCost(
+  usage: TokenUsage | null | undefined,
+  model: string | null | undefined,
+  pricing = DEFAULT_PRICING
+): number {
+  if (!usage) return 0;
+  const p = matchPricing(model, pricing);
+  const inputCost = (usage.input ?? 0) * p.inRate / 1_000_000;
+  const outputCost = (usage.output ?? 0) * p.outRate / 1_000_000;
+  const cachedCost = (usage.cachedInput ?? 0) * p.inRate * CACHE_READ_MULT / 1_000_000;
+  return inputCost + outputCost + cachedCost;
+}
+
+/** Estimated total cost from a project's token usage. */
+export function estimateProjectCost(usage: TokenUsage | null | undefined, model?: string, pricing?: ModelPricing[]): number {
+  return estimateCost(usage, model ?? "sonnet", pricing);
+}
+
+/** Per-model cost breakdown for a set of task journeys. */
+export interface ModelCostBreakdown {
+  model: string;
+  label: string;
+  provider: string;
+  input: number;
+  output: number;
+  cachedInput: number;
+  messages: number;
+  cost: number;
+}
+
+/** Aggregate token usage and cost by model across journeys. */
+export function aggregateCostByModel(
+  journeys: TaskJourney[],
+  sessionMap: Map<string, SessionRecord>,
+  pricing = DEFAULT_PRICING
+): ModelCostBreakdown[] {
+  const byModel = new Map<string, {
+    label: string;
+    provider: string;
+    input: number;
+    output: number;
+    cachedInput: number;
+    messages: number;
+    cost: number;
+  }>();
+
+  for (const journey of journeys) {
+    const session = sessionMap.get(journey.sessionId);
+    const model = session?.modelProvider ?? null;
+    const pricingTier = matchPricing(model, pricing);
+
+    const key = pricingTier.id;
+    const entry = byModel.get(key) ?? {
+      label: pricingTier.label,
+      provider: pricingTier.provider,
+      input: 0,
+      output: 0,
+      cachedInput: 0,
+      messages: 0,
+      cost: 0,
+    };
+
+    entry.input += journey.tokenUsage?.input ?? 0;
+    entry.output += journey.tokenUsage?.output ?? 0;
+    entry.cachedInput += journey.tokenUsage?.cachedInput ?? 0;
+    entry.messages += 1;
+    entry.cost += estimateCost(journey.tokenUsage, model, pricing);
+    byModel.set(key, entry);
+  }
+
+  return [...byModel.entries()]
+    .map(([model, data]) => ({ model, ...data }))
+    .sort((a, b) => b.cost - a.cost);
+}
+
+/** Format a USD cost for display. */
+export function formatCost(value: number): string {
+  if (value >= 100) return `$${Math.round(value)}`;
+  if (value >= 1) return `$${value.toFixed(2)}`;
+  if (value >= 0.01) return `$${value.toFixed(4)}`;
+  return `$${value.toFixed(6)}`;
+}

package/core/hash.ts

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+
+export function sha256(input: string): string {
+  return createHash("sha256").update(input).digest("hex");
+}

package/core/history.ts

@@ -0,0 +1,96 @@
+import { redactString } from "./redactor";
+
+export interface CodexHistoryRecord {
+  sessionId: string;
+  ts: string;
+  text: string;
+  sourcePath: string;
+  lineNo: number;
+}
+
+export interface CodexHistoryBadLine {
+  sourcePath: string;
+  lineNo: number;
+  error: string;
+}
+
+export interface CodexHistoryParseResult {
+  records: CodexHistoryRecord[];
+  bySessionId: Map<string, CodexHistoryRecord[]>;
+  badLines: CodexHistoryBadLine[];
+}
+
+interface RawHistoryLine {
+  session_id?: unknown;
+  sessionId?: unknown;
+  ts?: unknown;
+  timestamp?: unknown;
+  text?: unknown;
+}
+
+export function parseCodexHistoryJsonlContent(content: string, sourcePath = "history.jsonl"): CodexHistoryParseResult {
+  const records: CodexHistoryRecord[] = [];
+  const badLines: CodexHistoryBadLine[] = [];
+
+  const lines = content.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index];
+    const lineNo = index + 1;
+    if (!raw.trim()) continue;
+
+    try {
+      const json = JSON.parse(raw) as RawHistoryLine;
+      const sessionId = typeof json.session_id === "string" ? json.session_id : typeof json.sessionId === "string" ? json.sessionId : null;
+      const ts = normalizeTimestamp(json.ts ?? json.timestamp);
+      const text = typeof json.text === "string" ? json.text : null;
+
+      if (!sessionId || !ts || text === null) {
+        badLines.push({ sourcePath, lineNo, error: "missing required history fields" });
+        continue;
+      }
+
+      records.push({
+        sessionId,
+        ts,
+        text: redactString(text),
+        sourcePath,
+        lineNo
+      });
+    } catch (error) {
+      badLines.push({
+        sourcePath,
+        lineNo,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  return { records, bySessionId: groupBySessionId(records), badLines };
+}
+
+export function groupBySessionId(records: CodexHistoryRecord[]): Map<string, CodexHistoryRecord[]> {
+  const bySessionId = new Map<string, CodexHistoryRecord[]>();
+  for (const record of records) {
+    const existing = bySessionId.get(record.sessionId);
+    if (existing) {
+      existing.push(record);
+    } else {
+      bySessionId.set(record.sessionId, [record]);
+    }
+  }
+  return bySessionId;
+}
+
+function normalizeTimestamp(value: unknown): string | null {
+  if (typeof value === "string" && value.trim()) {
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? value : date.toISOString();
+  }
+
+  if (typeof value === "number" && Number.isFinite(value)) {
+    const millis = value > 10_000_000_000 ? value : value * 1000;
+    return new Date(millis).toISOString();
+  }
+
+  return null;
+}

package/core/id.ts

@@ -0,0 +1,6 @@
+import { sha256 } from "./hash";
+
+export function stableId(prefix: string, ...parts: Array<string | number | null | undefined>): string {
+  const joined = parts.map((part) => String(part ?? "")).join("\u001f");
+  return `${prefix}_${sha256(joined).slice(0, 20)}`;
+}