@harness-engineering/core 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { Result, SessionSectionName, SessionEntry, SessionSections, WorkflowStep, WorkflowStepResult, Workflow, WorkflowResult, SkillLifecycleHooks, SkillContext, SkillResult, TurnContext, CICheckName, CIFailOnSeverity, CICheckReport, Roadmap, FeatureStatus } from '@harness-engineering/types';
+import { Result, SessionSectionName, SessionEntry, SessionSections, WorkflowStep, WorkflowStepResult, Workflow, WorkflowResult, SkillLifecycleHooks, SkillContext, SkillResult, TurnContext, CICheckName, CIFailOnSeverity, CICheckReport, Roadmap, FeatureStatus, ModelPricing, UsageRecord, DailyUsage, SessionUsage } from '@harness-engineering/types';
 export * from '@harness-engineering/types';
 import { z } from 'zod';
 import { C as Collector, A as ArchConfig, a as ConstraintRule, M as MetricResult, b as ArchMetricCategory, c as ArchBaseline, d as ArchDiffResult, T as ThresholdConfig } from './matchers-D20x48U9.js';
 export { e as ArchBaselineSchema, f as ArchConfigSchema, g as ArchDiffResultSchema, h as ArchHandle, i as ArchMetricCategorySchema, j as ArchitectureOptions, k as CategoryBaseline, l as CategoryBaselineSchema, m as CategoryRegression, n as CategoryRegressionSchema, o as ConstraintRuleSchema, p as MetricResultSchema, q as ThresholdConfigSchema, V as Violation, r as ViolationSchema, s as archMatchers, t as archModule, u as architecture } from './matchers-D20x48U9.js';
+import Parser from 'web-tree-sitter';
 
 /**
  * Represents an error code for identifying specific error types.
@@ -293,6 +294,73 @@ interface ContextFilterResult {
 declare function contextFilter(phase: WorkflowPhase, maxCategories?: number, graphFilePaths?: string[]): ContextFilterResult;
 declare function getPhaseCategories(phase: WorkflowPhase): FileCategory[];
 
+/**
+ * Supported languages for AST code navigation.
+ */
+type SupportedLanguage = 'typescript' | 'javascript' | 'python';
+/**
+ * Kind of code symbol extracted from AST.
+ */
+type SymbolKind = 'function' | 'class' | 'interface' | 'type' | 'variable' | 'method' | 'property' | 'export' | 'import';
+/**
+ * A code symbol with its location and metadata.
+ */
+interface CodeSymbol {
+    name: string;
+    kind: SymbolKind;
+    file: string;
+    line: number;
+    endLine: number;
+    signature: string;
+    children?: CodeSymbol[];
+}
+/**
+ * Result of code_outline — structural skeleton of a file.
+ */
+interface OutlineResult {
+    file: string;
+    language: SupportedLanguage | 'unknown';
+    totalLines: number;
+    symbols: CodeSymbol[];
+    error?: string;
+}
+/**
+ * A single match from code_search.
+ */
+interface SearchMatch {
+    symbol: CodeSymbol;
+    context: string;
+}
+/**
+ * Result of code_search — cross-file symbol discovery.
+ */
+interface SearchResult {
+    query: string;
+    matches: SearchMatch[];
+    skipped: string[];
+}
+/**
+ * Result of code_unfold — AST-bounded code extraction.
+ */
+interface UnfoldResult {
+    file: string;
+    symbolName?: string;
+    startLine: number;
+    endLine: number;
+    content: string;
+    language: SupportedLanguage | 'unknown';
+    fallback: boolean;
+    warning?: string;
+}
+/**
+ * Map file extensions to supported languages.
+ */
+declare const EXTENSION_MAP: Record<string, SupportedLanguage>;
+/**
+ * Detect language from file extension.
+ */
+declare function detectLanguage(filePath: string): SupportedLanguage | null;
+
 /**
  * Abstract Syntax Tree representation
  */
@@ -361,6 +429,10 @@ interface LanguageParser {
     extractImports(ast: AST): Result<Import[], ParseError>;
     extractExports(ast: AST): Result<Export[], ParseError>;
     health(): Promise<Result<HealthCheckResult, ParseError>>;
+    /** Extract structural outline from a parsed AST. Optional — code-nav parsers implement this. */
+    outline?(filePath: string, ast: AST): OutlineResult;
+    /** Extract a specific symbol's full implementation. Optional — code-nav parsers implement this. */
+    unfold?(filePath: string, ast: AST, symbolName: string): UnfoldResult | null;
 }
 /**
  * Create a ParseError with standard structure
@@ -3520,6 +3592,24 @@ declare const DEFAULT_STATE: HarnessState;
 declare function loadState(projectPath: string, stream?: string, session?: string): Promise<Result<HarnessState, Error>>;
 declare function saveState(projectPath: string, state: HarnessState, stream?: string, session?: string): Promise<Result<void, Error>>;
 
+interface LearningsFrontmatter {
+    hash: string;
+    tags: string[];
+}
+interface LearningsIndexEntry {
+    hash: string;
+    tags: string[];
+    summary: string;
+    fullText: string;
+}
+/** Parse a frontmatter comment line: <!-- hash:XXXX tags:a,b --> */
+declare function parseFrontmatter(line: string): LearningsFrontmatter | null;
+/**
+ * Extract a lightweight index entry from a full learning entry.
+ * Summary = first line only. Tags extracted from [skill:X] and [outcome:Y] markers.
+ * Hash computed from full entry text.
+ */
+declare function extractIndexEntry(entry: string): LearningsIndexEntry;
 declare function clearLearningsCache(): void;
 declare function appendLearning(projectPath: string, learning: string, skillName?: string, outcome?: string, stream?: string, session?: string): Promise<Result<void, Error>>;
 /**
@@ -3545,6 +3635,7 @@ interface BudgetedLearningsOptions {
     skill?: string;
     session?: string;
     stream?: string;
+    depth?: 'index' | 'summary' | 'full';
 }
 /**
  * Load learnings with token budget, two-tier loading, recency sorting, and relevance filtering.
@@ -3556,6 +3647,14 @@ interface BudgetedLearningsOptions {
  * - Capped at tokenBudget (default 1000 tokens)
  */
 declare function loadBudgetedLearnings(projectPath: string, options: BudgetedLearningsOptions): Promise<Result<string[], Error>>;
+/**
+ * Load lightweight index entries from a learnings file.
+ * Returns summaries (first line) with hash and tags for each entry.
+ * Uses frontmatter when available; computes hash and extracts tags on-the-fly when not.
+ *
+ * This is Layer 1 of the progressive disclosure pipeline.
+ */
+declare function loadIndexEntries(projectPath: string, skillName?: string, stream?: string, session?: string): Promise<Result<LearningsIndexEntry[], Error>>;
 declare function loadRelevantLearnings(projectPath: string, skillName?: string, stream?: string, session?: string): Promise<Result<string[], Error>>;
 interface PruneResult {
     kept: number;
@@ -3577,6 +3676,26 @@ declare function archiveLearnings(projectPath: string, entries: string[], stream
  * Returns the prune result with pattern analysis and counts.
  */
 declare function pruneLearnings(projectPath: string, stream?: string): Promise<Result<PruneResult, Error>>;
+interface PromoteResult {
+    promoted: number;
+    skipped: number;
+}
+/**
+ * Promote generalizable session learnings to global learnings.md.
+ *
+ * Generalizable entries are those tagged with [outcome:gotcha],
+ * [outcome:decision], or [outcome:observation]. These represent
+ * reusable insights that apply beyond the current session.
+ *
+ * Task-specific entries (e.g., [outcome:success] completion summaries,
+ * or entries without outcome tags) stay in the session directory.
+ */
+declare function promoteSessionLearnings(projectPath: string, sessionSlug: string, stream?: string): Promise<Result<PromoteResult, Error>>;
+/**
+ * Count the number of learning entries in the global learnings.md file.
+ * Useful for checking if pruning should be suggested (threshold: 30).
+ */
+declare function countLearningEntries(projectPath: string, stream?: string): Promise<number>;
 
 declare function clearFailuresCache(): void;
 declare function appendFailure(projectPath: string, description: string, skillName: string, type: string, stream?: string, session?: string): Promise<Result<void, Error>>;
@@ -3753,6 +3872,88 @@ declare function updateSessionEntryStatus(projectPath: string, sessionSlug: stri
  */
 declare function archiveSession(projectPath: string, sessionSlug: string): Promise<Result<void, Error>>;
 
+/** Event types emitted at skill lifecycle points. */
+type EventType = 'phase_transition' | 'decision' | 'gate_result' | 'handoff' | 'error' | 'checkpoint';
+/** A structured skill lifecycle event. */
+interface SkillEvent {
+    timestamp: string;
+    skill: string;
+    session?: string;
+    type: EventType;
+    summary: string;
+    data?: Record<string, unknown>;
+    refs?: string[];
+    contentHash?: string;
+}
+/** Zod schema for validating SkillEvent objects. */
+declare const SkillEventSchema: z.ZodObject<{
+    timestamp: z.ZodString;
+    skill: z.ZodString;
+    session: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<["phase_transition", "decision", "gate_result", "handoff", "error", "checkpoint"]>;
+    summary: z.ZodString;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    refs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    contentHash: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "error" | "decision" | "phase_transition" | "gate_result" | "handoff" | "checkpoint";
+    timestamp: string;
+    skill: string;
+    summary: string;
+    session?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    refs?: string[] | undefined;
+    contentHash?: string | undefined;
+}, {
+    type: "error" | "decision" | "phase_transition" | "gate_result" | "handoff" | "checkpoint";
+    timestamp: string;
+    skill: string;
+    summary: string;
+    session?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    refs?: string[] | undefined;
+    contentHash?: string | undefined;
+}>;
+/** Input to emitEvent — timestamp and contentHash are computed automatically. */
+type EmitEventInput = Omit<SkillEvent, 'timestamp' | 'contentHash'>;
+interface EmitEventOptions {
+    session?: string;
+    stream?: string;
+}
+interface EmitEventResult {
+    written: boolean;
+    reason?: string;
+}
+/** Clear the known-hashes cache (for testing). */
+declare function clearEventHashCache(): void;
+/**
+ * Emit a structured event to the JSONL event log.
+ *
+ * - Appends one JSON line to events.jsonl (crash-safe via appendFileSync)
+ * - Born-deduplicated: same {skill, type, summary, session} tuple writes only once
+ * - Session-scoped when options.session is provided
+ * - Uses in-memory hash set for O(1) dedup checks after initial file load
+ */
+declare function emitEvent(projectPath: string, event: EmitEventInput, options?: EmitEventOptions): Promise<Result<EmitEventResult, Error>>;
+interface LoadEventsOptions {
+    session?: string | undefined;
+    stream?: string | undefined;
+}
+/**
+ * Load all events from the JSONL event log.
+ * Skips malformed lines gracefully.
+ */
+declare function loadEvents(projectPath: string, options?: LoadEventsOptions): Promise<Result<SkillEvent[], Error>>;
+/**
+ * Format events as a compact timeline for display in gather_context.
+ *
+ * Example output:
+ * - 10:30 [harness-execution] phase: PREPARE -> EXECUTE (12 tasks)
+ * - 10:45 [harness-execution] gate: passed (test Y, lint Y)
+ * - 11:02 [harness-execution] decision: Use polling over WebSocket
+ */
+declare function formatEventTimeline(events: SkillEvent[], limit?: number): string;
+
 type StepExecutor = (step: WorkflowStep, previousArtifact?: string) => Promise<WorkflowStepResult>;
 declare function executeWorkflow(workflow: Workflow, executor: StepExecutor): Promise<WorkflowResult>;
 
@@ -3776,7 +3977,7 @@ type TurnExecutor = (context: TurnContext) => Promise<{
 declare function runPipeline(initialContext: SkillContext, executor: SkillExecutor, options?: PipelineOptions): Promise<PipelineResult>;
 declare function runMultiTurnPipeline(initialContext: SkillContext, turnExecutor: TurnExecutor, options?: PipelineOptions): Promise<PipelineResult>;
 
-type SecurityCategory = 'secrets' | 'injection' | 'xss' | 'crypto' | 'network' | 'deserialization' | 'path-traversal';
+type SecurityCategory = 'secrets' | 'injection' | 'xss' | 'crypto' | 'network' | 'deserialization' | 'path-traversal' | 'agent-config' | 'mcp' | 'insecure-defaults' | 'sharp-edges';
 type SecuritySeverity = 'error' | 'warning' | 'info';
 type SecurityConfidence = 'high' | 'medium' | 'low';
 interface SecurityRule {
@@ -3814,6 +4015,12 @@ interface ScanResult {
     externalToolsUsed: string[];
     coverage: 'baseline' | 'enhanced';
 }
+interface SuppressionRecord {
+    ruleId: string;
+    file: string;
+    line: number;
+    justification: string | null;
+}
 type RuleOverride = 'off' | SecuritySeverity;
 interface SecurityConfig {
     enabled: boolean;
@@ -3832,14 +4039,32 @@ interface SecurityConfig {
 }
 declare const DEFAULT_SECURITY_CONFIG: SecurityConfig;
 
+interface SuppressionMatch {
+    ruleId: string;
+    justification: string | null;
+}
+declare function parseHarnessIgnore(line: string, ruleId: string): SuppressionMatch | null;
 declare class SecurityScanner {
     private registry;
     private config;
     private activeRules;
     constructor(config?: Partial<SecurityConfig>);
     configureForProject(projectRoot: string): void;
+    /**
+     * Scan raw content against all active rules. Note: this method does NOT apply
+     * fileGlob filtering — every active rule is evaluated regardless of filePath.
+     * If you are scanning a specific file and want fileGlob-based rule filtering,
+     * use {@link scanFile} instead.
+     */
     scanContent(content: string, filePath: string, startLine?: number): SecurityFinding[];
     scanFile(filePath: string): Promise<SecurityFinding[]>;
+    private scanContentForFile;
+    /**
+     * Core scanning loop shared by scanContent and scanContentForFile.
+     * Evaluates each rule against each line, handling suppression (FP gate)
+     * and pattern matching uniformly.
+     */
+    private scanLinesWithRules;
     scanFiles(filePaths: string[]): Promise<ScanResult>;
 }
 
@@ -3941,6 +4166,120 @@ declare const networkRules: SecurityRule[];
 
 declare const deserializationRules: SecurityRule[];
 
+declare const agentConfigRules: SecurityRule[];
+
+declare const mcpRules: SecurityRule[];
+
+declare const insecureDefaultsRules: SecurityRule[];
+
+declare const sharpEdgesRules: SecurityRule[];
+
+/**
+ * Sentinel Injection Pattern Engine
+ *
+ * Shared pattern library for detecting prompt injection attacks in text input.
+ * Used by sentinel hooks, MCP middleware, and the scan-config CLI.
+ *
+ * This engine DETECTS and REPORTS patterns. It does NOT strip them --
+ * the existing sanitizeExternalText() in ConnectorUtils.ts handles stripping.
+ */
+type InjectionSeverity = 'high' | 'medium' | 'low';
+interface InjectionFinding {
+    severity: InjectionSeverity;
+    ruleId: string;
+    match: string;
+    line?: number;
+}
+interface InjectionPattern {
+    ruleId: string;
+    severity: InjectionSeverity;
+    category: string;
+    description: string;
+    pattern: RegExp;
+}
+/**
+ * Scan text for prompt injection patterns.
+ *
+ * Returns an array of findings sorted by severity (high first).
+ * The caller decides how to act on findings based on severity:
+ * - HIGH/MEDIUM: Trigger taint (hooks and MCP middleware)
+ * - LOW: Informational only (logged to stderr, no taint)
+ */
+declare function scanForInjection(text: string): InjectionFinding[];
+/**
+ * Get all registered injection patterns.
+ * Useful for inspection, documentation, and testing.
+ */
+declare function getInjectionPatterns(): ReadonlyArray<InjectionPattern>;
+/**
+ * Bash command patterns that are blocked during tainted sessions.
+ * Used by sentinel hooks and MCP middleware — kept in one place to prevent drift.
+ * Hooks that cannot import from core at startup define their own inline copy with a sync comment.
+ */
+declare const DESTRUCTIVE_BASH: ReadonlyArray<RegExp>;
+
+/**
+ * Sentinel Taint State Management
+ *
+ * Session-scoped taint file read/write/check/clear/expire logic.
+ * Taint files live at `.harness/session-taint-{sessionId}.json`.
+ *
+ * The taint file is the single source of truth for enforcement.
+ * Hooks and MCP middleware read this file on every invocation.
+ */
+
+interface TaintFinding {
+    ruleId: string;
+    severity: string;
+    match: string;
+    source: string;
+    detectedAt: string;
+}
+interface TaintState {
+    sessionId: string;
+    taintedAt: string;
+    expiresAt: string;
+    reason: string;
+    severity: 'high' | 'medium';
+    findings: TaintFinding[];
+}
+interface TaintCheckResult {
+    tainted: boolean;
+    expired: boolean;
+    state: TaintState | null;
+}
+/**
+ * Get the taint file path for a given session.
+ */
+declare function getTaintFilePath(projectRoot: string, sessionId?: string): string;
+/**
+ * Read the taint state for a session.
+ * Returns null if no taint file exists or if the file is malformed (fail-open).
+ * If malformed, the file is deleted.
+ */
+declare function readTaint(projectRoot: string, sessionId?: string): TaintState | null;
+/**
+ * Check taint status for a session.
+ * Handles expiry: if taint has expired, deletes the file and returns expired=true.
+ */
+declare function checkTaint(projectRoot: string, sessionId?: string): TaintCheckResult;
+/**
+ * Write taint state for a session.
+ * Creates .harness/ directory if it doesn't exist.
+ * If taint already exists for this session, appends new findings and keeps the earlier taintedAt.
+ */
+declare function writeTaint(projectRoot: string, sessionId: string | undefined, reason: string, findings: InjectionFinding[], source: string): TaintState;
+/**
+ * Clear taint for a specific session or all sessions.
+ * Returns the number of taint files removed.
+ */
+declare function clearTaint(projectRoot: string, sessionId?: string): number;
+/**
+ * List all active taint sessions.
+ * Returns session IDs with active (non-expired) taint.
+ */
+declare function listTaintedSessions(projectRoot: string): string[];
+
 declare const nodeRules: SecurityRule[];
 
 declare const expressRules: SecurityRule[];
@@ -3949,6 +4288,34 @@ declare const reactRules: SecurityRule[];
 
 declare const goRules: SecurityRule[];
 
+/**
+ * Shared scan-config types and utilities.
+ * Used by both the CLI `harness scan-config` command and the orchestrator workspace scanner.
+ */
+
+interface ScanConfigFinding {
+    ruleId: string;
+    severity: 'high' | 'medium' | 'low';
+    message: string;
+    match: string;
+    line?: number;
+}
+interface ScanConfigFileResult {
+    file: string;
+    findings: ScanConfigFinding[];
+    overallSeverity: 'high' | 'medium' | 'low' | 'clean';
+}
+interface ScanConfigResult {
+    exitCode: number;
+    results: ScanConfigFileResult[];
+}
+declare function mapSecuritySeverity(severity: string): 'high' | 'medium' | 'low';
+declare function computeOverallSeverity(findings: ScanConfigFinding[]): 'high' | 'medium' | 'low' | 'clean';
+declare function computeScanExitCode(results: ScanConfigFileResult[]): number;
+declare function mapInjectionFindings(injectionFindings: InjectionFinding[]): ScanConfigFinding[];
+declare function isDuplicateFinding(existing: ScanConfigFinding[], secFinding: SecurityFinding): boolean;
+declare function mapSecurityFindings(secFindings: SecurityFinding[], existing: ScanConfigFinding[]): ScanConfigFinding[];
+
 interface RunCIChecksInput {
     projectRoot: string;
     config: Record<string, unknown>;
@@ -4738,8 +5105,18 @@ interface SyncOptions {
 /**
  * Scan execution state files and infer status changes for roadmap features.
  * Returns proposed changes without modifying the roadmap.
+ *
+ * Human-always-wins rule (directional): sync never regresses a feature's
+ * status (e.g. done → in-progress) unless forceSync is set. Forward
+ * progression (planned → in-progress → done) is always allowed regardless
+ * of manual edits.
  */
 declare function syncRoadmap(options: SyncOptions): Result<SyncChange[]>;
+/**
+ * Apply sync changes to a roadmap in-place and update lastSynced.
+ * Shared by manage_roadmap sync action and autoSyncRoadmap.
+ */
+declare function applySyncChanges(roadmap: Roadmap, changes: SyncChange[]): void;
 
 declare const InteractionTypeSchema: z.ZodEnum<["question", "confirmation", "transition"]>;
 declare const QuestionSchema: z.ZodObject<{
@@ -4968,6 +5345,146 @@ declare function spawnBackgroundCheck(currentVersion: string): void;
  */
 declare function getUpdateNotification(currentVersion: string): string | null;
 
+interface ParsedFile {
+    tree: Parser.Tree;
+    language: SupportedLanguage;
+    source: string;
+    filePath: string;
+}
+interface ParseFileError {
+    code: 'UNSUPPORTED_LANGUAGE' | 'FILE_NOT_FOUND' | 'PARSE_FAILED' | 'INIT_FAILED';
+    message: string;
+}
+/**
+ * Get or create a cached parser for the given language.
+ */
+declare function getParser(lang: SupportedLanguage): Promise<Parser>;
+/**
+ * Parse a file and return the tree-sitter tree with metadata.
+ */
+declare function parseFile(filePath: string): Promise<Result<ParsedFile, ParseFileError>>;
+/**
+ * Reset the parser cache (for testing).
+ */
+declare function resetParserCache(): void;
+
+/**
+ * Get structural outline for a single file.
+ */
+declare function getOutline(filePath: string): Promise<OutlineResult>;
+/**
+ * Format an outline result as the tree-style text format shown in the spec.
+ */
+declare function formatOutline(outline: OutlineResult): string;
+
+/**
+ * Search for symbols matching a query across files in a directory.
+ */
+declare function searchSymbols(query: string, directory: string, fileGlob?: string): Promise<SearchResult>;
+
+/**
+ * Extract a specific symbol's implementation from a file by name.
+ */
+declare function unfoldSymbol(filePath: string, symbolName: string): Promise<UnfoldResult>;
+/**
+ * Extract a range of lines from a file.
+ */
+declare function unfoldRange(filePath: string, startLine: number, endLine: number): Promise<UnfoldResult>;
+
+/** Shape of the LiteLLM pricing JSON (per-model entry). */
+interface LiteLLMModelEntry {
+    input_cost_per_token?: number;
+    output_cost_per_token?: number;
+    cache_read_input_token_cost?: number;
+    cache_creation_input_token_cost?: number;
+    mode?: string;
+    [key: string]: unknown;
+}
+/** Shape of the full LiteLLM pricing JSON file. */
+interface LiteLLMPricingData {
+    [modelName: string]: LiteLLMModelEntry;
+}
+/** Parsed pricing dataset keyed by model name. */
+type PricingDataset = Map<string, ModelPricing>;
+/** Shape of the disk cache file. */
+interface PricingCacheFile {
+    fetchedAt: string;
+    data: LiteLLMPricingData;
+}
+/** Shape of the fallback.json file. */
+interface FallbackPricingFile {
+    _generatedAt: string;
+    _source: string;
+    models: Record<string, ModelPricing>;
+}
+
+/**
+ * Parses LiteLLM's raw pricing JSON into a PricingDataset map.
+ * Only includes chat-mode models with valid input/output costs.
+ */
+declare function parseLiteLLMData(raw: LiteLLMPricingData): PricingDataset;
+/**
+ * Looks up pricing for a given model name.
+ * Returns null and logs a warning if the model is not found.
+ */
+declare function getModelPrice(model: string, dataset: PricingDataset): ModelPricing | null;
+
+/** Pinned LiteLLM pricing URL. */
+declare const LITELLM_PRICING_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+/** Cache time-to-live: 24 hours in milliseconds. */
+declare const CACHE_TTL_MS: number;
+/** Number of days after which fallback usage triggers a staleness warning. */
+declare const STALENESS_WARNING_DAYS = 7;
+/**
+ * Loads pricing data with the following priority:
+ * 1. Fresh disk cache (<24h old) — no network request
+ * 2. Network fetch from LiteLLM — writes to disk cache
+ * 3. Expired disk cache (any age) — when network fails
+ * 4. Bundled fallback.json — when no cache and no network
+ */
+declare function loadPricingData(projectRoot: string): Promise<PricingDataset>;
+
+/**
+ * Calculates the cost of a usage record in integer microdollars.
+ * Returns null if the model is unknown or not specified.
+ */
+declare function calculateCost(record: UsageRecord, dataset: PricingDataset): number | null;
+
+/**
+ * Aggregates an array of UsageRecords into per-session summaries.
+ *
+ * When records from both harness and Claude Code sources share a session ID:
+ * - Harness token counts are authoritative
+ * - CC data supplements the model field
+ * - The result is marked as 'merged'
+ */
+declare function aggregateBySession(records: UsageRecord[]): SessionUsage[];
+/**
+ * Aggregates an array of UsageRecords into per-day summaries.
+ * Groups by calendar date (UTC) derived from the record timestamp.
+ */
+declare function aggregateByDay(records: UsageRecord[]): DailyUsage[];
+
+/**
+ * Reads .harness/metrics/costs.jsonl and normalizes snake_case hook output
+ * to camelCase UsageRecord format.
+ *
+ * - Skips malformed lines with a warning to stderr
+ * - Handles legacy entries missing cache/model fields
+ * - Returns empty array if file does not exist
+ */
+declare function readCostRecords(projectRoot: string): UsageRecord[];
+
+/**
+ * Discovers and parses Claude Code JSONL files from ~/.claude/projects/ directories.
+ *
+ * Best-effort: the path is not a public API and may change across CC versions.
+ * - If ~/.claude/projects/ does not exist, returns empty array (no error)
+ * - Malformed entries are skipped with a console.warn
+ * - Each valid assistant entry with usage data maps to a UsageRecord tagged with _source: 'claude-code'
+ */
+declare function parseCCRecords(): UsageRecord[];
+
 /**
  * @harness-engineering/core
  *
@@ -4987,6 +5504,6 @@ declare function getUpdateNotification(currentVersion: string): string | null;
  * release. Kept only as a fallback for consumers that cannot resolve the CLI
  * package at runtime.
  */
-declare const VERSION = "0.14.0";
+declare const VERSION = "0.15.0";
 
-export { AGENT_DESCRIPTORS, ARCHITECTURE_DESCRIPTOR, type AST, type ActionContext, type ActionEvent, type ActionEventHandler, type ActionEventType, type ActionResult, type ActionSink, type ActionTracker, type ActionType, type AgentAction, AgentActionEmitter, type AgentExecutor, type AgentMapLink, type AgentMapSection, type AgentMapValidation, type AgentProcess, type AgentReviewResult, type AgentType, type AgentsMapConfig, ArchBaseline, ArchBaselineManager, ArchConfig, ArchDiffResult, ArchMetricCategory, BUG_DETECTION_DESCRIPTOR, type BaseError, type Baseline, BaselineManager, type BaselinesFile, type BenchmarkResult, type BenchmarkRunOptions, BenchmarkRunner, type BlueprintData, BlueprintGenerator, type BlueprintModule, type BlueprintOptions, type BoundaryDefinition, type BoundaryValidation, type BoundaryValidator, type BoundaryViolation, type BrokenLink, type BudgetedLearningsOptions, type Bundle, type BundleConstraints, BundleConstraintsSchema, BundleSchema, COMPLIANCE_DESCRIPTOR, type ChangeType, type ChangedFile, ChecklistBuilder, type CircularDependency, CircularDepsCollector, type CircularDepsResult, type CleanupFinding, type CodeBlock, type CodeChanges, type CodePattern, type CodeReference, type CodebaseSnapshot, Collector, type CommentedCodeBlock, type CommitFormat, type CommitHistoryEntry, type CommitValidation, ComplexityCollector, type ComplexityConfig, type ComplexityReport, type ComplexityThresholds, type ComplexityViolation, type ConfigError, type ConfigPattern, type Confirmation, ConfirmationSchema, type ConflictReport, ConsoleSink, type ConstraintError, type ConstraintNodeStore, ConstraintRule, type Content, ContentPipeline, type ContextBundle, type ContextError, type ContextFile, type ContextFilterResult, type ContextScopeOptions, type Contributions, ContributionsSchema, type Convention, CouplingCollector, type CouplingConfig, type CouplingReport, type CouplingThresholds, type CouplingViolation, type CoverageOptions, type CoverageReport, type CriticalPathEntry, CriticalPathResolver, type CriticalPathSet, type CustomRule, type CustomRuleResult, DEFAULT_PROVIDER_TIERS, DEFAULT_SECURITY_CONFIG, DEFAULT_STATE, DEFAULT_STREAM_INDEX, type DeadCodeConfig, type DeadCodeReport, type DeadExport, type DeadFile, type DeadInternal, type DeduplicateFindingsOptions, DepDepthCollector, type DependencyEdge, type DependencyGraph, type DependencyValidation, type DependencyViolation, type DetectStaleResult, type DiffInfo, type DocumentationDrift, type DocumentationFile, type DocumentationGap, type DriftConfig, type DriftReport, type EligibilityResult, type EmitInteractionInput, EmitInteractionInputSchema, EntropyAnalyzer, type EntropyConfig, EntropyConfigSchema, type EntropyError, type EntropyReport, type EvidenceCoverageReport, ExclusionSet, type ExecutorHealth, type Export, type ExportMap, type FailureEntry, FailureEntrySchema, type FanOutOptions, type FeedbackAgentConfig, type FeedbackConfig, type FeedbackError$1 as FeedbackError, type FileCategory, FileSink, type FindingSeverity, type Fix, type FixConfig, type FixResult, type FixType, ForbiddenImportCollector, type ForbiddenImportViolation, type ForbiddenPattern, type GateConfig, GateConfigSchema, type GateResult, GateResultSchema, type GenerationSection, type GitHubInlineComment, type GraphAdapter, type GraphComplexityData, type GraphCouplingData, type GraphCoverageData, type GraphCriticalPathData, type GraphDependencyData, type GraphHarnessCheckData, type GraphImpactData, type Handoff, HandoffSchema, type HarnessState, HarnessStateSchema, type HealthCheckResult, type Hotspot, type HotspotContext, type Import, type InlineReference, type IntegrityReport, type InteractionType, InteractionTypeSchema, type InternalSymbol, type JSDocComment, type LanguageParser, type Layer, type LayerConfig, LayerViolationCollector, type LearningPattern, type Lockfile, type LockfilePackage, LockfilePackageSchema, LockfileSchema, type LogEntry, type LogFilter, type Manifest, ManifestSchema, type MechanicalCheckOptions, type MechanicalCheckResult, type MechanicalCheckStatus, type MechanicalFinding, type MergeResult, type Metric, MetricResult, type ModelProvider, type ModelTier, type ModelTierConfig, type ModuleDependency, ModuleSizeCollector, NoOpExecutor, NoOpSink, NoOpTelemetryAdapter, type OrphanedDep, type ParseError, type PatternConfig, PatternConfigSchema, type PatternMatch, type PatternReport, type PatternViolation, type PeerReview, type PeerReviewOptions, type PipelineContext, type PipelineFlags, type PipelineOptions, type PipelineResult, type PrMetadata, type PriorReview, ProjectScanner, type ProviderDefaults, type PruneResult, type Question, QuestionSchema, REQUIRED_SECTIONS, type ReachabilityNode, RegressionDetector, type RegressionReport, type RegressionResult, type ReviewAgentDescriptor, type ReviewAssessment, type ReviewChecklist, type ReviewComment, type ReviewContext, type ReviewDomain, type ReviewFinding, type ReviewItem, type ReviewOutputOptions, type ReviewPipelineResult, type ReviewStrength, type RuleOverride, RuleRegistry, type RunCIChecksInput, type RunPipelineOptions, SECURITY_DESCRIPTOR, type SafetyLevel, type ScanResult, type SecurityCategory, type SecurityConfidence, type SecurityConfig, SecurityConfigSchema, type SecurityFinding, type SecurityRule, SecurityScanner, type SecuritySeverity, type SelfReviewConfig, type SessionSummaryData, SharableBoundaryConfigSchema, SharableForbiddenImportSchema, SharableLayerSchema, SharableSecurityRulesSchema, type SizeBudgetConfig, type SizeBudgetReport, type SizeBudgetViolation, type SkillExecutor, type SourceFile, type Span, type SpanEvent, type StaleConstraint, type StepExecutor, type StreamIndex, StreamIndexSchema, type StreamInfo, StreamInfoSchema, type StructureValidation, type Suggestion, type SuggestionReport, type SyncChange, type SyncOptions, type TelemetryAdapter, type TelemetryHealth, ThresholdConfig, type TimeRange, type TokenBudget, type TokenBudgetOverrides, type Trace, type Transition, TransitionSchema, type TurnExecutor, TypeScriptParser, type UnusedImport, type UpdateCheckState, VERSION, type ValidateFindingsOptions, type ValidationError, type WorkflowPhase, addProvenance, analyzeDiff, analyzeLearningPatterns, appendFailure, appendLearning, appendSessionEntry, applyFixes, applyHotspotDowngrade, archiveFailures, archiveLearnings, archiveSession, archiveStream, buildDependencyGraph, buildExclusionSet, buildSnapshot, checkDocCoverage, checkEligibility, checkEvidenceCoverage, classifyFinding, clearFailuresCache, clearLearningsCache, configureFeedback, constraintRuleId, contextBudget, contextFilter, createBoundaryValidator, createCommentedCodeFixes, createError, createFixes, createForbiddenImportFixes, createOrphanedDepFixes, createParseError, createSelfReview, createStream, cryptoRules, deduplicateCleanupFindings, deduplicateFindings, deepMergeConstraints, defaultCollectors, defineLayer, deserializationRules, detectChangeType, detectCircularDeps, detectCircularDepsInFiles, detectComplexityViolations, detectCouplingViolations, detectDeadCode, detectDocDrift, detectPatternViolations, detectSizeBudgetViolations, detectStack, detectStaleConstraints, determineAssessment, diff, executeWorkflow, expressRules, extractBundle, extractMarkdownLinks, extractSections, fanOutReview, formatFindingBlock, formatGitHubComment, formatGitHubSummary, formatTerminalOutput, generateAgentsMap, generateSuggestions, getActionEmitter, getExitCode, getFeedbackConfig, getPhaseCategories, getStreamForBranch, getUpdateNotification, goRules, injectionRules, isSmallSuggestion, isUpdateCheckEnabled, listActiveSessions, listStreams, loadBudgetedLearnings, loadFailures, loadHandoff, loadRelevantLearnings, loadSessionSummary, loadState, loadStreamIndex, logAgentAction, migrateToStreams, networkRules, nodeRules, parseDateFromEntry, parseDiff, parseManifest, parseRoadmap, parseSecurityConfig, parseSize, pathTraversalRules, previewFix, pruneLearnings, reactRules, readCheckState, readLockfile, readSessionSection, readSessionSections, removeContributions, removeProvenance, requestMultiplePeerReviews, requestPeerReview, resetFeedbackConfig, resolveFileToLayer, resolveModelTier, resolveRuleSeverity, resolveSessionDir, resolveStreamPath, resolveThresholds, runAll, runArchitectureAgent, runBugDetectionAgent, runCIChecks, runComplianceAgent, runMechanicalChecks, runMechanicalGate, runMultiTurnPipeline, runPipeline, runReviewPipeline, runSecurityAgent, saveHandoff, saveState, saveStreamIndex, scopeContext, secretRules, serializeRoadmap, setActiveStream, shouldRunCheck, spawnBackgroundCheck, syncConstraintNodes, syncRoadmap, tagUncitedFindings, touchStream, trackAction, updateSessionEntryStatus, updateSessionIndex, validateAgentsMap, validateBoundaries, validateCommitMessage, validateConfig, validateDependencies, validateFileStructure, validateFindings, validateKnowledgeMap, validatePatternConfig, violationId, writeConfig, writeLockfile, writeSessionSummary, xssRules };
+export { AGENT_DESCRIPTORS, ARCHITECTURE_DESCRIPTOR, type AST, type ActionContext, type ActionEvent, type ActionEventHandler, type ActionEventType, type ActionResult, type ActionSink, type ActionTracker, type ActionType, type AgentAction, AgentActionEmitter, type AgentExecutor, type AgentMapLink, type AgentMapSection, type AgentMapValidation, type AgentProcess, type AgentReviewResult, type AgentType, type AgentsMapConfig, ArchBaseline, ArchBaselineManager, ArchConfig, ArchDiffResult, ArchMetricCategory, BUG_DETECTION_DESCRIPTOR, type BaseError, type Baseline, BaselineManager, type BaselinesFile, type BenchmarkResult, type BenchmarkRunOptions, BenchmarkRunner, type BlueprintData, BlueprintGenerator, type BlueprintModule, type BlueprintOptions, type BoundaryDefinition, type BoundaryValidation, type BoundaryValidator, type BoundaryViolation, type BrokenLink, type BudgetedLearningsOptions, type Bundle, type BundleConstraints, BundleConstraintsSchema, BundleSchema, CACHE_TTL_MS, COMPLIANCE_DESCRIPTOR, type ChangeType, type ChangedFile, ChecklistBuilder, type CircularDependency, CircularDepsCollector, type CircularDepsResult, type CleanupFinding, type CodeBlock, type CodeChanges, type CodePattern, type CodeReference, type CodeSymbol, type CodebaseSnapshot, Collector, type CommentedCodeBlock, type CommitFormat, type CommitHistoryEntry, type CommitValidation, ComplexityCollector, type ComplexityConfig, type ComplexityReport, type ComplexityThresholds, type ComplexityViolation, type ConfigError, type ConfigPattern, type Confirmation, ConfirmationSchema, type ConflictReport, ConsoleSink, type ConstraintError, type ConstraintNodeStore, ConstraintRule, type Content, ContentPipeline, type ContextBundle, type ContextError, type ContextFile, type ContextFilterResult, type ContextScopeOptions, type Contributions, ContributionsSchema, type Convention, CouplingCollector, type CouplingConfig, type CouplingReport, type CouplingThresholds, type CouplingViolation, type CoverageOptions, type CoverageReport, type CriticalPathEntry, CriticalPathResolver, type CriticalPathSet, type CustomRule, type CustomRuleResult, DEFAULT_PROVIDER_TIERS, DEFAULT_SECURITY_CONFIG, DEFAULT_STATE, DEFAULT_STREAM_INDEX, DESTRUCTIVE_BASH, type DeadCodeConfig, type DeadCodeReport, type DeadExport, type DeadFile, type DeadInternal, type DeduplicateFindingsOptions, DepDepthCollector, type DependencyEdge, type DependencyGraph, type DependencyValidation, type DependencyViolation, type DetectStaleResult, type DiffInfo, type DocumentationDrift, type DocumentationFile, type DocumentationGap, type DriftConfig, type DriftReport, EXTENSION_MAP, type EligibilityResult, type EmitEventInput, type EmitEventOptions, type EmitEventResult, type EmitInteractionInput, EmitInteractionInputSchema, EntropyAnalyzer, type EntropyConfig, EntropyConfigSchema, type EntropyError, type EntropyReport, type EventType, type EvidenceCoverageReport, ExclusionSet, type ExecutorHealth, type Export, type ExportMap, type FailureEntry, FailureEntrySchema, type FallbackPricingFile, type FanOutOptions, type FeedbackAgentConfig, type FeedbackConfig, type FeedbackError$1 as FeedbackError, type FileCategory, FileSink, type FindingSeverity, type Fix, type FixConfig, type FixResult, type FixType, ForbiddenImportCollector, type ForbiddenImportViolation, type ForbiddenPattern, type GateConfig, GateConfigSchema, type GateResult, GateResultSchema, type GenerationSection, type GitHubInlineComment, type GraphAdapter, type GraphComplexityData, type GraphCouplingData, type GraphCoverageData, type GraphCriticalPathData, type GraphDependencyData, type GraphHarnessCheckData, type GraphImpactData, type Handoff, HandoffSchema, type HarnessState, HarnessStateSchema, type HealthCheckResult, type Hotspot, type HotspotContext, type Import, type InjectionFinding, type InjectionPattern, type InjectionSeverity, type InlineReference, type IntegrityReport, type InteractionType, InteractionTypeSchema, type InternalSymbol, type JSDocComment, LITELLM_PRICING_URL, type LanguageParser, type Layer, type LayerConfig, LayerViolationCollector, type LearningPattern, type LearningsFrontmatter, type LearningsIndexEntry, type LiteLLMModelEntry, type LiteLLMPricingData, type LoadEventsOptions, type Lockfile, type LockfilePackage, LockfilePackageSchema, LockfileSchema, type LogEntry, type LogFilter, type Manifest, ManifestSchema, type MechanicalCheckOptions, type MechanicalCheckResult, type MechanicalCheckStatus, type MechanicalFinding, type MergeResult, type Metric, MetricResult, type ModelProvider, type ModelTier, type ModelTierConfig, type ModuleDependency, ModuleSizeCollector, NoOpExecutor, NoOpSink, NoOpTelemetryAdapter, type OrphanedDep, type OutlineResult, type ParseError, type ParsedFile, type PatternConfig, PatternConfigSchema, type PatternMatch, type PatternReport, type PatternViolation, type PeerReview, type PeerReviewOptions, type PipelineContext, type PipelineFlags, type PipelineOptions, type PipelineResult, type PrMetadata, type PricingCacheFile, type PricingDataset, type PriorReview, ProjectScanner, type PromoteResult, type ProviderDefaults, type PruneResult, type Question, QuestionSchema, REQUIRED_SECTIONS, type ReachabilityNode, RegressionDetector, type RegressionReport, type RegressionResult, type ReviewAgentDescriptor, type ReviewAssessment, type ReviewChecklist, type ReviewComment, type ReviewContext, type ReviewDomain, type ReviewFinding, type ReviewItem, type ReviewOutputOptions, type ReviewPipelineResult, type ReviewStrength, type RuleOverride, RuleRegistry, type RunCIChecksInput, type RunPipelineOptions, SECURITY_DESCRIPTOR, STALENESS_WARNING_DAYS, type SafetyLevel, type ScanConfigFileResult, type ScanConfigFinding, type ScanConfigResult, type ScanResult, type SearchMatch, type SearchResult, type SecurityCategory, type SecurityConfidence, type SecurityConfig, SecurityConfigSchema, type SecurityFinding, type SecurityRule, SecurityScanner, type SecuritySeverity, type SelfReviewConfig, type SessionSummaryData, SharableBoundaryConfigSchema, SharableForbiddenImportSchema, SharableLayerSchema, SharableSecurityRulesSchema, type SizeBudgetConfig, type SizeBudgetReport, type SizeBudgetViolation, type SkillEvent, SkillEventSchema, type SkillExecutor, type SourceFile, type Span, type SpanEvent, type StaleConstraint, type StepExecutor, type StreamIndex, StreamIndexSchema, type StreamInfo, StreamInfoSchema, type StructureValidation, type Suggestion, type SuggestionReport, type SupportedLanguage, type SuppressionRecord, type SymbolKind, type SyncChange, type SyncOptions, type TaintCheckResult, type TaintFinding, type TaintState, type TelemetryAdapter, type TelemetryHealth, ThresholdConfig, type TimeRange, type TokenBudget, type TokenBudgetOverrides, type Trace, type Transition, TransitionSchema, type TurnExecutor, TypeScriptParser, type UnfoldResult, type UnusedImport, type UpdateCheckState, VERSION, type ValidateFindingsOptions, type ValidationError, type WorkflowPhase, addProvenance, agentConfigRules, aggregateByDay, aggregateBySession, analyzeDiff, analyzeLearningPatterns, appendFailure, appendLearning, appendSessionEntry, applyFixes, applyHotspotDowngrade, applySyncChanges, archiveFailures, archiveLearnings, archiveSession, archiveStream, buildDependencyGraph, buildExclusionSet, buildSnapshot, calculateCost, checkDocCoverage, checkEligibility, checkEvidenceCoverage, checkTaint, classifyFinding, clearEventHashCache, clearFailuresCache, clearLearningsCache, clearTaint, computeOverallSeverity, computeScanExitCode, configureFeedback, constraintRuleId, contextBudget, contextFilter, countLearningEntries, createBoundaryValidator, createCommentedCodeFixes, createError, createFixes, createForbiddenImportFixes, createOrphanedDepFixes, createParseError, createSelfReview, createStream, cryptoRules, deduplicateCleanupFindings, deduplicateFindings, deepMergeConstraints, defaultCollectors, defineLayer, deserializationRules, detectChangeType, detectCircularDeps, detectCircularDepsInFiles, detectComplexityViolations, detectCouplingViolations, detectDeadCode, detectDocDrift, detectLanguage, detectPatternViolations, detectSizeBudgetViolations, detectStack, detectStaleConstraints, determineAssessment, diff, emitEvent, executeWorkflow, expressRules, extractBundle, extractIndexEntry, extractMarkdownLinks, extractSections, fanOutReview, formatEventTimeline, formatFindingBlock, formatGitHubComment, formatGitHubSummary, formatOutline, formatTerminalOutput, generateAgentsMap, generateSuggestions, getActionEmitter, getExitCode, getFeedbackConfig, getInjectionPatterns, getModelPrice, getOutline, getParser, getPhaseCategories, getStreamForBranch, getTaintFilePath, getUpdateNotification, goRules, injectionRules, insecureDefaultsRules, isDuplicateFinding, isSmallSuggestion, isUpdateCheckEnabled, listActiveSessions, listStreams, listTaintedSessions, loadBudgetedLearnings, loadEvents, loadFailures, loadHandoff, loadIndexEntries, loadPricingData, loadRelevantLearnings, loadSessionSummary, loadState, loadStreamIndex, logAgentAction, mapInjectionFindings, mapSecurityFindings, mapSecuritySeverity, mcpRules, migrateToStreams, networkRules, nodeRules, parseCCRecords, parseDateFromEntry, parseDiff, parseFile, parseFrontmatter, parseHarnessIgnore, parseLiteLLMData, parseManifest, parseRoadmap, parseSecurityConfig, parseSize, pathTraversalRules, previewFix, promoteSessionLearnings, pruneLearnings, reactRules, readCheckState, readCostRecords, readLockfile, readSessionSection, readSessionSections, readTaint, removeContributions, removeProvenance, requestMultiplePeerReviews, requestPeerReview, resetFeedbackConfig, resetParserCache, resolveFileToLayer, resolveModelTier, resolveRuleSeverity, resolveSessionDir, resolveStreamPath, resolveThresholds, runAll, runArchitectureAgent, runBugDetectionAgent, runCIChecks, runComplianceAgent, runMechanicalChecks, runMechanicalGate, runMultiTurnPipeline, runPipeline, runReviewPipeline, runSecurityAgent, saveHandoff, saveState, saveStreamIndex, scanForInjection, scopeContext, searchSymbols, secretRules, serializeRoadmap, setActiveStream, sharpEdgesRules, shouldRunCheck, spawnBackgroundCheck, syncConstraintNodes, syncRoadmap, tagUncitedFindings, touchStream, trackAction, unfoldRange, unfoldSymbol, updateSessionEntryStatus, updateSessionIndex, validateAgentsMap, validateBoundaries, validateCommitMessage, validateConfig, validateDependencies, validateFileStructure, validateFindings, validateKnowledgeMap, validatePatternConfig, violationId, writeConfig, writeLockfile, writeSessionSummary, writeTaint, xssRules };