@ohos-perf/core 0.22.3 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.ts +269 -8
  2. package/dist/index.js +541 -123
  3. package/package.json +48 -48
package/dist/index.d.ts CHANGED
@@ -2584,7 +2584,7 @@ declare function loadCases(cases: readonly DiscoveredCase[]): CaseLoad[];
2584
2584
 
2585
2585
  /**
2586
2586
  * The HapRay parity ledger: one row per capability in the source-level
2587
- * inventory of ArkAnalyzer-HapRay rev `9386e4e`.
2587
+ * inventory of ArkAnalyzer-HapRay rev `bd5c98a` (2026-11-18).
2588
2588
  *
2589
2589
  * This exists because the claim drifted. The README said "18 ported / 9
2590
2590
  * partial / 8 missing" long after six releases had moved rows, and nothing
@@ -2595,6 +2595,12 @@ declare function loadCases(cases: readonly DiscoveredCase[]): CaseLoad[];
2595
2595
  * The numbering is the inventory's own (`gap-analysis.md`), and it is what
2596
2596
  * the README and the site quote. Each `reason` for a non-ported row names what
2597
2597
  * is absent, so "not worth it" and "not done" are distinguishable.
2598
+ *
2599
+ * **Re-pinned from `9386e4e` to `bd5c98a`** in 0.23.0. The 428 commits between
2600
+ * them added three actions (`build`, `root-cause`, and an LLM exploration
2601
+ * strategy inside `haptest`) and a thermal collector. Rows 1–35 keep their
2602
+ * numbers; the new capabilities are appended so a reader can tell the original
2603
+ * inventory from what followed it.
2598
2604
  */
2599
2605
  /** How much of one HapRay capability this package implements. */
2600
2606
  type ParityStatus = 'ported' | 'partial' | 'missing' | 'out';
@@ -4917,12 +4923,19 @@ declare function writeRunFiles(outDir: string, result: RunResult): void;
4917
4923
  * completion claim carries an expectation, the expectation is evaluated
4918
4924
  * against a fresh dump, and a claim the screen contradicts is recorded as
4919
4925
  * `unverified` — a failure with the clause that failed named.
4920
- * 2. **The safety rule lives only in the prompt.** HapRay tells the model to
4921
- * avoid payment, ordering and transfers; a model that ignores the sentence
4922
- * acts anyway. Here the guard reads the node the tap lands on and refuses
4923
- * the gesture outright. An irreversible action stops the run: a model that
4924
- * reached for a payment button has lost the thread of the task, and asking
4925
- * it again spends steps on the one thing that must not happen.
4926
+ * 2. **The safety rule is mostly in the prompt.** HapRay adds one sentence to
4927
+ * the task prompt — avoid login, payment, ordering, transfer, posting — and
4928
+ * that is the only layer that applies to every gesture. `phone_agent` does
4929
+ * ship a `confirmation_callback`, but it fires only when the model itself
4930
+ * labels the tap (`do(action="Tap", element=[x,y], message="重要操作")`), so
4931
+ * a plain `Tap` is performed with no check; it covers `Tap` alone, leaving
4932
+ * long press, double tap, swipe and text entry unguarded; and HapRay passes
4933
+ * no callback, so the default is a blocking `input()` that raises `EOFError`
4934
+ * in a batch run and is recorded as a failed step with the run continuing.
4935
+ * Here the guard reads the node the tap lands on and refuses the gesture
4936
+ * outright. An irreversible action stops the run: a model that reached for
4937
+ * a payment button has lost the thread of the task, and asking it again
4938
+ * spends steps on the one thing that must not happen.
4926
4939
  * 3. **The log cannot be replayed.** HapRay records `{action, thinking,
4927
4940
  * message}` as prose, so two runs of the same task are two unrelated logs.
4928
4941
  * Here every step records the gesture and the screen hash either side of
@@ -5375,6 +5388,21 @@ declare function measureNaming(bytes: Uint8Array, answer: NamingAnswer): Promise
5375
5388
 
5376
5389
  /** The slice of `fetch` this client needs. Injected, never imported. */
5377
5390
  type AgentFetch = (url: string, init: RequestInit) => Promise<Response>;
5391
+ /**
5392
+ * How a turn is rendered into a request, and how the answer is read back.
5393
+ *
5394
+ * The two travel together because they are one contract: a prompt that asks for
5395
+ * an evidence citation cannot be read by a parser that insists on a gesture.
5396
+ * The GUI agent is the default; anything else supplies its own pair.
5397
+ */
5398
+ interface AgentTurnShape {
5399
+ /** The user message for one turn. */
5400
+ prompt(turn: AgentTurn): string;
5401
+ /** The answer as a decision, or a refusal naming what came back. */
5402
+ parse(content: string): AgentDecision;
5403
+ }
5404
+ /** The GUI-driving shape: a screen to act on, an action or a verified `done`. */
5405
+ declare const GUI_TURN: AgentTurnShape;
5378
5406
  interface HttpAgentModelOptions {
5379
5407
  /** The endpoint root, without `/chat/completions`. */
5380
5408
  readonly baseUrl: string;
@@ -5383,6 +5411,16 @@ interface HttpAgentModelOptions {
5383
5411
  readonly fetch: AgentFetch;
5384
5412
  /** Request timeout in ms. Defaults to 60 s. */
5385
5413
  readonly timeoutMs?: number;
5414
+ /**
5415
+ * How a turn becomes a request and how its answer is read. Defaults to
5416
+ * {@link GUI_TURN}.
5417
+ *
5418
+ * A caller whose turn is not a screen to drive — the root-cause report, whose
5419
+ * turn carries the evidence — supplies its own shape. Without this the model
5420
+ * would be told to answer with a gesture and an `expect` block, and a
5421
+ * correct answer would then be rejected for having neither.
5422
+ */
5423
+ readonly shape?: AgentTurnShape;
5386
5424
  }
5387
5425
  interface AgentConfig {
5388
5426
  readonly baseUrl: string;
@@ -7076,4 +7114,227 @@ interface FlamegraphPageInput {
7076
7114
  */
7077
7115
  declare function renderFlamegraphHtml(input: FlamegraphPageInput): string;
7078
7116
 
7079
- export { ANIMATION_BANDS, type ActionContext, type ActionDevice, type ActionOutcome, type ActiveAlloc, type AddressRef, type AgentConfig, type AgentDecision, type AgentDevice, type AgentFetch, type AgentHistoryEntry, type AgentModel, type AgentOptions, type AgentResult, type AgentStatus, type AgentStep, type AgentStepStatus, type AgentTranscript, type AgentTurn, type AnalyzeContext, type AnalyzeResult, type Analyzer, type AnalyzerRun, type AnalyzerSection, type AnimationAnalysis, type AnimationLabel, type AnimationSeverity, type AppIdentity, BUNDLE_RENDERED_FILES, type BaselineComparison, type BelowThresholdPattern, type BinaryFacts, type BinaryInput, type BinaryReport, type BinderAnalysis, BinderAnalyzer, type BinderEndpoint, type BinderEvent, type BinderInterfaceStat, type BinderProcessStat, BinderQuery, type BinderThreadStat, type BinderTransaction, type BundleRerenderInput, CATEGORY_EXTENSIONS, CATEGORY_MAX_BYTES, COLLECTOR_NAMES, type CallchainSample, type CallstackEvent, type CallstackEventWithArgs, CallstackQuery, type CapabilityId, type CapabilityInputs, CapabilityMatrix, type CapabilityState, type CaseLoad, type CategoryTotal, type CollectOptions, type CollectSession, type Collector, type CollectorName, type CompiledRule, type ComponentReuse, ComponentReuseAnalyzer, type ConnectOptions, type ContentPattern, CoverageAnalyzer, type CoverageCounts, type CoverageFile, type CoverageRatio, type CoverageReport, type CreateEmulatorRequest, DEFAULT_HILOG_RULES, DEFAULT_QUERY_LIMIT, DEVICE_PERF_PATH, DEVICE_SCREENSHOT_PATH, DEVICE_UI_PATH, type DeltaStatus, type DepGraph, type DepGraphEdge, type DepGraphFile, Device, type DeviceDeps, type DeviceIdentity, DeviceNotFoundError, type DiscoveredCase, type DrillDownHandle, type DuplicateGroup, EM_AARCH64, EXCLUDE_PATTERNS, type ElfFile, type ElfSection, type ElfSymbol, EmptyFrameAnalyzer, type EmptyFrameFilter, type EmulatorBackend, EmulatorClient, type EmulatorClientOptions, EmulatorCommandError, type EmulatorImage, EmulatorImageMissingError, type EmulatorInstance, EmulatorLifecycle, type EmulatorLifecycleOptions, EmulatorNotFoundError, type EmulatorStartResult, type EmulatorStopResult, type Env, type Evidence, type EvidenceKind, type ExpectPresent, type ExpectationOutcome, type ExplorationAction, type ExplorationClock, type ExplorationDevice, type ExplorationDeviceOptions, type ExplorationHost, type ExplorationOptions, type ExplorationOutcome, type ExplorationResult, type ExplorationState, type ExplorationStep, type ExplorationStrategy, type ExplorationTargetDevice, FLAMEGRAPH_FILES, FPS_COMMAND, FTRACE_CATEGORIES, FaultTreeAnalyzer, type FaultTreeSignals, type Fidelity, type FileCategory, type FileRule, FlamegraphAnalyzer, type FlamegraphPageInput, type FoldedStack, type FpsBucket, type FpsWindow, type Frame, FrameAnalyzer, type FrameFlag, FrameLoadAnalyzer, FrameLoadIndex, type FrameLoadIndexInput, type FrameLoadThread, FrameQuery, type FrameStats, type FrameType, type FtraceOptions, type FunctionRange, GEOMETRY_TOLERANCE_PX, GcAnalyzer, type GcSignals, type Gesture, GestureDriver, type GestureResult, HILOG_COMMAND, HIPROFILER_PLUGIN_NAMES, HITCH_COMMAND, HITRACE_DEFAULT_CATEGORIES, type HapAnalysis, type HapPackage, type HarEdge, Hdc, HdcNotFoundError, type HdcOptions, type HdcResult, type HdcSlice, type HdcTarget, type HidumperCapture, HidumperCollector, type HidumperSnapshot, HilogAnalyzer, HilogCollector, type HilogLevel, type HilogLine, type HilogMatch, type HilogParseOptions, type HilogRule, type HiperfCapture, type HiperfCollectOptions, HiperfCollector, type HiprofilerCollectOptions, type HiprofilerCollectRequest, HiprofilerCollector, type HiprofilerConfigOptions, type HiprofilerPlugin, type HiprofilerPluginName, HitraceCollector, type HttpAgentModelOptions, IGNORED_ATTRIBUTES, IRREVERSIBLE_PATTERNS, type ImageComparison, IngestError, InstantQuery, type InstructionClass, type InstructionCounts, type InventoryFile, type IrreversiblePattern, type JsheapCapture, JsheapCollector, MAX_QUERY_LIMIT, METRIC_DIRECTIONS, MIN_BUFFER_PAGES, MIN_HASH_PIXELS, MemMeasureQuery, MemoryAnalyzer, MemoryMeasureAnalyzer, type MemoryPluginOptions, type MetadataPattern, type Metric, type MetricDelta, type MetricDirection, type MetricUnit, type ModuleDecl, type NamedQueryDefinition, type NamedQueryInfo, type NamedQueryResult, type NamingAnswer, type NamingCase, type NamingQuestion, type NamingReport, type NativeCategory, type NativeEventKind, type NativeHookEvent, type NativeHookFrame, NativeHookQuery, type NativeHookStatistic, NativeMemoryAnalyzer, type NativeMemoryResult, type NativeNames, type NativeTimelineBucket, type NativehookOptions, OhosPerfError, type OptimizationAnalysis, type OptimizationBasis, type OptimizationLevel, type OptimizationPotential, type OptimizationVerdict, type OversizedFile, PARITY_ROWS, PLANE_A_PLUGINS, type ParityRow, type ParityStatus, type PerfCallchain, type PerfFileAttribution, type PerfFunction, type PerfLeafAttribution, PerfQuery, type PerfSampleRow, type PerfThread, type PixelOnlyChange, type ProbeResult, type ProbeRunner, type ProbeSnapshot, type ProcessInfo, type ProcessMeasure, type ProcessMeasureFilter, ProcessQuery, ProcfsCollector, type ProcfsSample, type ProcfsStatus, type Provenance, type QueryArgument, type QueryContext, type QueryHandle, REPORT_SCHEMA_VERSION, type RecoveredSymbol, type RecoveryResult, type Rect, type RedundancyLevel, type RedundancyType, RedundantFileAnalyzer, type RedundantFileEntry, type RedundantFileReport, type RedundantThreadPattern, type RedundantThreadsSummary, type RegionPixelChange, RenderAnalyzer, type ReplayResult, type ReportGenerator, type ReportInput, type ReportModel, type ReportScenario, type ReportSection, type ReportSummary, type ReportTotals, type RgbaImage, RsSkipAnalyzer, type RsSkipFrame, type RsSkipResult, type RsSkipTraceMethod, type RuleMatch, type RuleMatchKind, type RunOptions, type RunResult, type RunStepResult, type RunnerCollectOptions, type RunnerDevice, SECTION_TITLES, type Scenario, type ScenarioAction, ScenarioRunner, type ScenarioStep, Scene, type SceneLayout, type SceneMetadata, type SceneStep, type SceneStepRef, type ScenesComparison, SchedQuery, type SchedSlice, type ScreenshotCapture, ScreenshotCollector, type Selector, type SelectorRect, type SmapsRollup, StartupAnalyzer, StartupQuery, type StartupRecord, type StepCapture, type StepComparison, type StepExpectation, type StepStatus, Streamer, StreamerNotFoundError, type StreamerOptions, type SymbolStat, SymbolsAnalyzer, TECH_RULES, type TechRule, type ThreadAnalysis, type ThreadAnalysisSummary, ThreadAnalyzer, type ThreadInfo, ThreadQuery, type ThreadState, ThreadStateQuery, type ThreadWakeupResult, type ThreadWakeupThread, type TimeRange, type TimingCycle, type TraceCollectOptions, type Trend, type TrendOrder, type TrendPoint, type TrendRun, type TrendSeries, UI_DIFF_FILES, UiAnalyzer, type UiCompareOptions, type UiDiff, type UiDiffSide, type UiNode, type UiTreeDiff, type UiTreeDifference, UitestCollector, type UnmeasuredRegion, type UnreleasedRow, type UnresolvedAddress, type VsyncAnalysis, VsyncAnalyzer, type VsyncPeriod, type VsyncPeriodKind, type VsyncSeverity, type WakeupEvent, type WindowHitches, type ZipArchive, type ZipEntry, addressOfOffset, agentPrompt, aggregateUnreleased, analyseAnimations, analyzeBinaries, analyzeHap, analyzeThreadWakeup, animationSeverity, buildDepGraph, buildHiprofilerConfig, buildInventory, buildMatrix, buildNativeTimeline, buildReport, buildTrend, categorize, classifyInstruction, classifyNativePath, classifyOptimization, compareImages, compareRegion, compareResults, compareSceneDirs, compareScenes, compileRules, computeBinderAnalysis, computeComponentReuse, computeFaultTree, computeFpsWindows, computeGc, computeRsSkip, computeThreadAnalysis, computeVsyncAnomalies, connect, countInstructions, createSceneLayout, cropRegion, decodePng, defaultAnalyzers, describeDecision, deviceExplorationHost, dhash, diffTrees, discoverCases, encodePng, escapeHtml, evaluateExpectation, evidence, executeAction, explorationDevice, explore, extractBinaries, filterEmptyFrames, flattenUiTree, ftracePlugin, functionAt, gpuPlugin, hapSection, hashTree, hiperfRecordCommand, httpAgentModel, ingestScene, inspectBinary, irreversibleReason, isUnresolvedSymbol, isZip, loadCases, lookupQuery, markRegions, matchHapRules, matchRules, matchSelector, measureNaming, memoryPlugin, metric, nativeEventKind, nativehookPlugin, nodeIdentity, normaliseName, openDb, openZip, optimizationSection, pairNativeMemory, paritySummary, parseBounds, parseCoverageReport, parseDecision, parseFpsCounts, parseHilogLine, parseHilogText, parseHiperfSummary, parseHitches, parseProcfsStatus, parseRedundantFile, parseScenario, parseSelector, parseSmapsRollup, planNextAction, queryDefinitions, readAgentConfig, readElf, readHidumperCapture, readHilogText, readJsheapSnapshot, readProcfsSamples, readSceneMetadata, readUiTree, recoverSymbols, renderBundle, renderEvidenceCsv, renderFlamegraphHtml, renderFlamegraphSvg, renderMetricsCsv, renderReportHtml, renderReportJson, renderReportXlsx, renderScenesComparison, renderSummaryJson, renderTree, renderTrendHtml, renderTrendJson, renderUiDiffHtml, replayAgent, resolveAppIdentity, resolveAppIpids, resolveQueryLimit, resolveSelector, round2HalfEven, runAgent, runAnalyzerSections, runAnalyzers, runDrillDown, runNamedQuery, runProbe, sortSteps, summarizeReport, symbolIndex, tableRowCounts, trendRunFromReport, unknownQueryError, validateRules, writeProcfsSamples, writeRunFiles, writeSceneMetadata, xpowerPlugin };
7117
+ /**
7118
+ * The root-cause document (HapRay parity row 36).
7119
+ *
7120
+ * HapRay's `root-cause` reads its own report JSON files, hands them to a model,
7121
+ * and writes Markdown. The artifact is empty without an endpoint: `--skip-llm`
7122
+ * writes "Pending Agent Inference" placeholders, so a run with no model produces
7123
+ * nothing a reader can use.
7124
+ *
7125
+ * This module is the half that does not need a model. It ranks the evidence the
7126
+ * analyzers already produced — by *our* severities, in a total order — and
7127
+ * states a verdict from the highest one. The model, when there is one, adds a
7128
+ * `suspects` array on top; it never supplies the ranking.
7129
+ *
7130
+ * That split is the point. A model asked "what is the root cause" answers with
7131
+ * prose that cannot be checked. A model asked "here are 14 evidence items, cite
7132
+ * the ids you are reasoning from" can have its citations verified, which is what
7133
+ * {@link RootCauseSuspect.ungrounded} records.
7134
+ */
7135
+ /** The root-cause document schema. A change to any shape below bumps this. */
7136
+ declare const ROOT_CAUSE_SCHEMA_VERSION = 1;
7137
+ /** Who produced the document; the version is the CLI package version. */
7138
+ interface RootCauseGenerator {
7139
+ name: string;
7140
+ version: string;
7141
+ }
7142
+ /** The scene the document describes. Inputs are copied, never referenced. */
7143
+ interface RootCauseScene {
7144
+ app: string;
7145
+ device: string;
7146
+ window: TimeRange;
7147
+ }
7148
+ /** One evidence item, restated so a reader needs no other file. */
7149
+ interface RootCauseObservation {
7150
+ /** The `Evidence.id` this restates; the model cites these. */
7151
+ evidenceId: string;
7152
+ kind: EvidenceKind;
7153
+ severity: 'info' | 'warn' | 'critical';
7154
+ /** The analyzer's own sentence, verbatim. */
7155
+ explain: string;
7156
+ subject: {
7157
+ process: string;
7158
+ thread?: string;
7159
+ frameNo?: number;
7160
+ };
7161
+ /** The measured facts, copied verbatim from the evidence item. */
7162
+ signals: Record<string, number | string | readonly string[]>;
7163
+ }
7164
+ /** One cause a model proposed, with the citations that back it. */
7165
+ interface RootCauseSuspect {
7166
+ /** 1-based, in the order the model returned them. */
7167
+ rank: number;
7168
+ /** The evidence ids the model cited that this run actually produced. */
7169
+ evidenceIds: string[];
7170
+ rootCause: string;
7171
+ fix: string;
7172
+ confidence: 'high' | 'medium' | 'low';
7173
+ /**
7174
+ * Names the model cited that no evidence carried. A non-empty list means the
7175
+ * suspect is *not* grounded in this run: the reader is told rather than being
7176
+ * shown an invented file, symbol or thread as though it were measured.
7177
+ */
7178
+ ungrounded: string[];
7179
+ triggerChain?: string;
7180
+ }
7181
+ /** The model's contribution, present only when a model answered. */
7182
+ interface RootCauseAnalysis {
7183
+ model: string;
7184
+ summary: string;
7185
+ suspects: RootCauseSuspect[];
7186
+ caveats: string[];
7187
+ needsMoreData: string[];
7188
+ }
7189
+ /** The deterministic verdict, always present. */
7190
+ interface RootCauseSummary {
7191
+ totals: {
7192
+ info: number;
7193
+ warn: number;
7194
+ critical: number;
7195
+ /**
7196
+ * How many observations are measurement gaps rather than findings. A run
7197
+ * over a sparse capture is mostly gaps, and a reader has to be able to tell
7198
+ * "nothing was wrong" from "nothing could be measured".
7199
+ */
7200
+ gaps: number;
7201
+ };
7202
+ /** One sentence, from the highest-severity observation. */
7203
+ verdict: string;
7204
+ }
7205
+ /** The complete, versioned document. */
7206
+ interface RootCauseDocument {
7207
+ schemaVersion: typeof ROOT_CAUSE_SCHEMA_VERSION;
7208
+ generator: RootCauseGenerator;
7209
+ scene: RootCauseScene;
7210
+ summary: RootCauseSummary;
7211
+ /** Ranked by severity then id: a total order, so two runs agree. */
7212
+ observations: RootCauseObservation[];
7213
+ analysis?: RootCauseAnalysis;
7214
+ }
7215
+ /** Everything {@link buildRootCauseDocument} needs; all values are measured. */
7216
+ interface RootCauseInput {
7217
+ app: string;
7218
+ device: string;
7219
+ window: TimeRange;
7220
+ generator: RootCauseGenerator;
7221
+ evidence: readonly Evidence[];
7222
+ }
7223
+ /**
7224
+ * Rank evidence for a reader: most urgent first, ties broken by id.
7225
+ *
7226
+ * The tie-break is not cosmetic. Without it the order depends on the input
7227
+ * array, and two runs over the same capture would produce documents that diff
7228
+ * against each other for no reason — the same defect the rest of this package
7229
+ * spends its determinism tests preventing.
7230
+ */
7231
+ declare function rankObservations(evidence: readonly Evidence[]): RootCauseObservation[];
7232
+ /**
7233
+ * Build the deterministic document.
7234
+ *
7235
+ * The `analysis` field is absent: only {@link askRootCause} adds it, and only
7236
+ * when a model answered. A caller that renders the document without one gets a
7237
+ * usable report, which is the property HapRay's `--skip-llm` lacks.
7238
+ */
7239
+ declare function buildRootCauseDocument(input: RootCauseInput): RootCauseDocument;
7240
+
7241
+ /**
7242
+ * The model turn for the root-cause report (HapRay parity row 36).
7243
+ *
7244
+ * One `decide()` call, not a loop: the document is already the question, and
7245
+ * the answer is prose attached to it. Two things differ from HapRay's version,
7246
+ * and both are about making the answer checkable:
7247
+ *
7248
+ * 1. **The model cites evidence ids.** HapRay hands over its report JSON and
7249
+ * asks for a root cause; nothing ties the answer to a measured item, so an
7250
+ * invented finding reads like a real one. Here the prompt carries the ranked
7251
+ * observations *with their ids*, and an id the run did not produce is moved
7252
+ * to {@link RootCauseSuspect.ungrounded}.
7253
+ * 2. **The names are looked up.** A suspect that mentions `aboutToAppear`,
7254
+ * `libfoo.so` or a thread name is checked against what the evidence actually
7255
+ * carried. HapRay has no such check, and its `with_source` mode needs a
7256
+ * source tree and a symbol index to get anywhere close.
7257
+ *
7258
+ * Neither check is semantic: they answer one question — "did the model name
7259
+ * something this run measured?" — and leave interpretation to the reader.
7260
+ */
7261
+ /** The most evidence items a prompt carries, most urgent first. */
7262
+ declare const PROMPT_EVIDENCE_LIMIT = 40;
7263
+ /**
7264
+ * The prompt for one root-cause turn.
7265
+ *
7266
+ * A plain string, like `agentPrompt`: whatever client a caller brings turns it
7267
+ * into its own request shape. The observations are rendered rather than
7268
+ * `JSON.stringify`-ed so the ids are impossible to miss — a model that cannot
7269
+ * see them cannot cite them.
7270
+ */
7271
+ declare function rootCausePrompt(document: RootCauseDocument): string;
7272
+ /**
7273
+ * How an HTTP client must render and read this turn.
7274
+ *
7275
+ * The default `GUI_TURN` is the wrong shape twice over: it would tell the model
7276
+ * to answer with a gesture and an `expect` block, and it would then reject the
7277
+ * answer it asked for, because `parseDecision` insists on an `action` or
7278
+ * `done`. The answer here is JSON prose with citations, so the parser accepts
7279
+ * any JSON object and leaves validation to {@link parseRootCauseAnswer}, which
7280
+ * knows the evidence ids.
7281
+ */
7282
+ declare const ROOT_CAUSE_TURN: AgentTurnShape;
7283
+ /**
7284
+ * Read a model's answer.
7285
+ *
7286
+ * The answer is data from outside this package, so every field is checked: a
7287
+ * non-object, a non-JSON string, or a suspect that is not an object is a
7288
+ * refusal naming what was wrong. An id the run did not produce is not a
7289
+ * refusal — it is recorded in `ungrounded`, because the reader needs to see
7290
+ * what the model claimed as much as what it got right.
7291
+ */
7292
+ declare function parseRootCauseAnswer(content: string, document: RootCauseDocument, model: string): RootCauseAnalysis;
7293
+ /**
7294
+ * Every string the evidence actually carried.
7295
+ *
7296
+ * Process, thread, any string signal value, and every identifier-shaped token
7297
+ * in the analyzer's own `explain` sentence and in the item's `kind`. The last
7298
+ * two matter because the analyzers name the inputs they were missing —
7299
+ * `ui.json`, `trace.thread_state`, `coverageReport.json` — and a model quoting
7300
+ * those back is repeating what this run reported, not inventing a symbol. A set
7301
+ * rather than a list because the check is membership, and the vocabulary of one
7302
+ * run is small.
7303
+ */
7304
+ declare function groundingVocabulary(document: RootCauseDocument): Set<string>;
7305
+ /**
7306
+ * Names a suspect mentions that the run never measured.
7307
+ *
7308
+ * Only *identifier-shaped* tokens are candidates: a token with a dot, an
7309
+ * underscore, a hyphen, an embedded capital, or a file extension. Ordinary
7310
+ * prose is not checked, because "the main thread was busy" is an interpretation
7311
+ * and not a claim about a measured entity — flagging its words would make the
7312
+ * check noise and train a reader to ignore it.
7313
+ *
7314
+ * A citation id is not a name: it is checked separately by
7315
+ * {@link parseRootCauseAnswer}, and a suspect whose only "unknown" is an id it
7316
+ * already had rejected would report the same problem twice.
7317
+ */
7318
+ declare function ungroundedNames(suspect: RootCauseSuspect, vocabulary: Set<string>): string[];
7319
+ /**
7320
+ * Ask the model once, and attach its answer to the document.
7321
+ *
7322
+ * The deterministic half is copied unchanged: the model adds a section, it does
7323
+ * not replace the ranking. A suspect naming something unmeasured keeps its
7324
+ * citation check and gains the names in `ungrounded`, so one field answers
7325
+ * "which ids were real" and the other "which names were real".
7326
+ */
7327
+ declare function askRootCause(model: AgentModel, document: RootCauseDocument, options: {
7328
+ model: string;
7329
+ }): Promise<RootCauseDocument>;
7330
+
7331
+ /**
7332
+ * Render the document as Markdown.
7333
+ *
7334
+ * Deterministic: the same document renders to the same bytes, because every
7335
+ * list it walks is already in a total order and every map is sorted on the way
7336
+ * out.
7337
+ */
7338
+ declare function renderRootCauseMarkdown(document: RootCauseDocument): string;
7339
+
7340
+ export { ANIMATION_BANDS, type ActionContext, type ActionDevice, type ActionOutcome, type ActiveAlloc, type AddressRef, type AgentConfig, type AgentDecision, type AgentDevice, type AgentFetch, type AgentHistoryEntry, type AgentModel, type AgentOptions, type AgentResult, type AgentStatus, type AgentStep, type AgentStepStatus, type AgentTranscript, type AgentTurn, type AgentTurnShape, type AnalyzeContext, type AnalyzeResult, type Analyzer, type AnalyzerRun, type AnalyzerSection, type AnimationAnalysis, type AnimationLabel, type AnimationSeverity, type AppIdentity, BUNDLE_RENDERED_FILES, type BaselineComparison, type BelowThresholdPattern, type BinaryFacts, type BinaryInput, type BinaryReport, type BinderAnalysis, BinderAnalyzer, type BinderEndpoint, type BinderEvent, type BinderInterfaceStat, type BinderProcessStat, BinderQuery, type BinderThreadStat, type BinderTransaction, type BundleRerenderInput, CATEGORY_EXTENSIONS, CATEGORY_MAX_BYTES, COLLECTOR_NAMES, type CallchainSample, type CallstackEvent, type CallstackEventWithArgs, CallstackQuery, type CapabilityId, type CapabilityInputs, CapabilityMatrix, type CapabilityState, type CaseLoad, type CategoryTotal, type CollectOptions, type CollectSession, type Collector, type CollectorName, type CompiledRule, type ComponentReuse, ComponentReuseAnalyzer, type ConnectOptions, type ContentPattern, CoverageAnalyzer, type CoverageCounts, type CoverageFile, type CoverageRatio, type CoverageReport, type CreateEmulatorRequest, DEFAULT_HILOG_RULES, DEFAULT_QUERY_LIMIT, DEVICE_PERF_PATH, DEVICE_SCREENSHOT_PATH, DEVICE_UI_PATH, type DeltaStatus, type DepGraph, type DepGraphEdge, type DepGraphFile, Device, type DeviceDeps, type DeviceIdentity, DeviceNotFoundError, type DiscoveredCase, type DrillDownHandle, type DuplicateGroup, EM_AARCH64, EXCLUDE_PATTERNS, type ElfFile, type ElfSection, type ElfSymbol, EmptyFrameAnalyzer, type EmptyFrameFilter, type EmulatorBackend, EmulatorClient, type EmulatorClientOptions, EmulatorCommandError, type EmulatorImage, EmulatorImageMissingError, type EmulatorInstance, EmulatorLifecycle, type EmulatorLifecycleOptions, EmulatorNotFoundError, type EmulatorStartResult, type EmulatorStopResult, type Env, type Evidence, type EvidenceKind, type ExpectPresent, type ExpectationOutcome, type ExplorationAction, type ExplorationClock, type ExplorationDevice, type ExplorationDeviceOptions, type ExplorationHost, type ExplorationOptions, type ExplorationOutcome, type ExplorationResult, type ExplorationState, type ExplorationStep, type ExplorationStrategy, type ExplorationTargetDevice, FLAMEGRAPH_FILES, FPS_COMMAND, FTRACE_CATEGORIES, FaultTreeAnalyzer, type FaultTreeSignals, type Fidelity, type FileCategory, type FileRule, FlamegraphAnalyzer, type FlamegraphPageInput, type FoldedStack, type FpsBucket, type FpsWindow, type Frame, FrameAnalyzer, type FrameFlag, FrameLoadAnalyzer, FrameLoadIndex, type FrameLoadIndexInput, type FrameLoadThread, FrameQuery, type FrameStats, type FrameType, type FtraceOptions, type FunctionRange, GEOMETRY_TOLERANCE_PX, GUI_TURN, GcAnalyzer, type GcSignals, type Gesture, GestureDriver, type GestureResult, HILOG_COMMAND, HIPROFILER_PLUGIN_NAMES, HITCH_COMMAND, HITRACE_DEFAULT_CATEGORIES, type HapAnalysis, type HapPackage, type HarEdge, Hdc, HdcNotFoundError, type HdcOptions, type HdcResult, type HdcSlice, type HdcTarget, type HidumperCapture, HidumperCollector, type HidumperSnapshot, HilogAnalyzer, HilogCollector, type HilogLevel, type HilogLine, type HilogMatch, type HilogParseOptions, type HilogRule, type HiperfCapture, type HiperfCollectOptions, HiperfCollector, type HiprofilerCollectOptions, type HiprofilerCollectRequest, HiprofilerCollector, type HiprofilerConfigOptions, type HiprofilerPlugin, type HiprofilerPluginName, HitraceCollector, type HttpAgentModelOptions, IGNORED_ATTRIBUTES, IRREVERSIBLE_PATTERNS, type ImageComparison, IngestError, InstantQuery, type InstructionClass, type InstructionCounts, type InventoryFile, type IrreversiblePattern, type JsheapCapture, JsheapCollector, MAX_QUERY_LIMIT, METRIC_DIRECTIONS, MIN_BUFFER_PAGES, MIN_HASH_PIXELS, MemMeasureQuery, MemoryAnalyzer, MemoryMeasureAnalyzer, type MemoryPluginOptions, type MetadataPattern, type Metric, type MetricDelta, type MetricDirection, type MetricUnit, type ModuleDecl, type NamedQueryDefinition, type NamedQueryInfo, type NamedQueryResult, type NamingAnswer, type NamingCase, type NamingQuestion, type NamingReport, type NativeCategory, type NativeEventKind, type NativeHookEvent, type NativeHookFrame, NativeHookQuery, type NativeHookStatistic, NativeMemoryAnalyzer, type NativeMemoryResult, type NativeNames, type NativeTimelineBucket, type NativehookOptions, OhosPerfError, type OptimizationAnalysis, type OptimizationBasis, type OptimizationLevel, type OptimizationPotential, type OptimizationVerdict, type OversizedFile, PARITY_ROWS, PLANE_A_PLUGINS, PROMPT_EVIDENCE_LIMIT, type ParityRow, type ParityStatus, type PerfCallchain, type PerfFileAttribution, type PerfFunction, type PerfLeafAttribution, PerfQuery, type PerfSampleRow, type PerfThread, type PixelOnlyChange, type ProbeResult, type ProbeRunner, type ProbeSnapshot, type ProcessInfo, type ProcessMeasure, type ProcessMeasureFilter, ProcessQuery, ProcfsCollector, type ProcfsSample, type ProcfsStatus, type Provenance, type QueryArgument, type QueryContext, type QueryHandle, REPORT_SCHEMA_VERSION, ROOT_CAUSE_SCHEMA_VERSION, ROOT_CAUSE_TURN, type RecoveredSymbol, type RecoveryResult, type Rect, type RedundancyLevel, type RedundancyType, RedundantFileAnalyzer, type RedundantFileEntry, type RedundantFileReport, type RedundantThreadPattern, type RedundantThreadsSummary, type RegionPixelChange, RenderAnalyzer, type ReplayResult, type ReportGenerator, type ReportInput, type ReportModel, type ReportScenario, type ReportSection, type ReportSummary, type ReportTotals, type RgbaImage, type RootCauseAnalysis, type RootCauseDocument, type RootCauseGenerator, type RootCauseInput, type RootCauseObservation, type RootCauseScene, type RootCauseSummary, type RootCauseSuspect, RsSkipAnalyzer, type RsSkipFrame, type RsSkipResult, type RsSkipTraceMethod, type RuleMatch, type RuleMatchKind, type RunOptions, type RunResult, type RunStepResult, type RunnerCollectOptions, type RunnerDevice, SECTION_TITLES, type Scenario, type ScenarioAction, ScenarioRunner, type ScenarioStep, Scene, type SceneLayout, type SceneMetadata, type SceneStep, type SceneStepRef, type ScenesComparison, SchedQuery, type SchedSlice, type ScreenshotCapture, ScreenshotCollector, type Selector, type SelectorRect, type SmapsRollup, StartupAnalyzer, StartupQuery, type StartupRecord, type StepCapture, type StepComparison, type StepExpectation, type StepStatus, Streamer, StreamerNotFoundError, type StreamerOptions, type SymbolStat, SymbolsAnalyzer, TECH_RULES, type TechRule, type ThreadAnalysis, type ThreadAnalysisSummary, ThreadAnalyzer, type ThreadInfo, ThreadQuery, type ThreadState, ThreadStateQuery, type ThreadWakeupResult, type ThreadWakeupThread, type TimeRange, type TimingCycle, type TraceCollectOptions, type Trend, type TrendOrder, type TrendPoint, type TrendRun, type TrendSeries, UI_DIFF_FILES, UiAnalyzer, type UiCompareOptions, type UiDiff, type UiDiffSide, type UiNode, type UiTreeDiff, type UiTreeDifference, UitestCollector, type UnmeasuredRegion, type UnreleasedRow, type UnresolvedAddress, type VsyncAnalysis, VsyncAnalyzer, type VsyncPeriod, type VsyncPeriodKind, type VsyncSeverity, type WakeupEvent, type WindowHitches, type ZipArchive, type ZipEntry, addressOfOffset, agentPrompt, aggregateUnreleased, analyseAnimations, analyzeBinaries, analyzeHap, analyzeThreadWakeup, animationSeverity, askRootCause, buildDepGraph, buildHiprofilerConfig, buildInventory, buildMatrix, buildNativeTimeline, buildReport, buildRootCauseDocument, buildTrend, categorize, classifyInstruction, classifyNativePath, classifyOptimization, compareImages, compareRegion, compareResults, compareSceneDirs, compareScenes, compileRules, computeBinderAnalysis, computeComponentReuse, computeFaultTree, computeFpsWindows, computeGc, computeRsSkip, computeThreadAnalysis, computeVsyncAnomalies, connect, countInstructions, createSceneLayout, cropRegion, decodePng, defaultAnalyzers, describeDecision, deviceExplorationHost, dhash, diffTrees, discoverCases, encodePng, escapeHtml, evaluateExpectation, evidence, executeAction, explorationDevice, explore, extractBinaries, filterEmptyFrames, flattenUiTree, ftracePlugin, functionAt, gpuPlugin, groundingVocabulary, hapSection, hashTree, hiperfRecordCommand, httpAgentModel, ingestScene, inspectBinary, irreversibleReason, isUnresolvedSymbol, isZip, loadCases, lookupQuery, markRegions, matchHapRules, matchRules, matchSelector, measureNaming, memoryPlugin, metric, nativeEventKind, nativehookPlugin, nodeIdentity, normaliseName, openDb, openZip, optimizationSection, pairNativeMemory, paritySummary, parseBounds, parseCoverageReport, parseDecision, parseFpsCounts, parseHilogLine, parseHilogText, parseHiperfSummary, parseHitches, parseProcfsStatus, parseRedundantFile, parseRootCauseAnswer, parseScenario, parseSelector, parseSmapsRollup, planNextAction, queryDefinitions, rankObservations, readAgentConfig, readElf, readHidumperCapture, readHilogText, readJsheapSnapshot, readProcfsSamples, readSceneMetadata, readUiTree, recoverSymbols, renderBundle, renderEvidenceCsv, renderFlamegraphHtml, renderFlamegraphSvg, renderMetricsCsv, renderReportHtml, renderReportJson, renderReportXlsx, renderRootCauseMarkdown, renderScenesComparison, renderSummaryJson, renderTree, renderTrendHtml, renderTrendJson, renderUiDiffHtml, replayAgent, resolveAppIdentity, resolveAppIpids, resolveQueryLimit, resolveSelector, rootCausePrompt, round2HalfEven, runAgent, runAnalyzerSections, runAnalyzers, runDrillDown, runNamedQuery, runProbe, sortSteps, summarizeReport, symbolIndex, tableRowCounts, trendRunFromReport, ungroundedNames, unknownQueryError, validateRules, writeProcfsSamples, writeRunFiles, writeSceneMetadata, xpowerPlugin };