agent-scenario-loop 0.1.0

package/core/config-template.json

@@ -0,0 +1,41 @@
+{
+  "projectName": "replace-me",
+  "app": {
+    "displayName": "Example App",
+    "scheme": "example-app",
+    "profileSessionScheme": "example-app",
+    "iosBundleId": "com.example.app",
+    "iosConflictingBundleIds": [],
+    "androidPackage": "com.example.app",
+    "ios": {
+      "xcodeScheme": "Example App",
+      "launchConfiguration": "Debug",
+      "profileConfiguration": "Release"
+    }
+  },
+  "paths": {
+    "artifactRoot": "artifacts/asl",
+    "iosArtifactsRoot": "artifacts/asl/ios",
+    "androidArtifactsRoot": "artifacts/asl/android",
+    "scenarioRoot": "examples/scenarios/mobile",
+    "iosScenarioRoot": "examples/scenarios/ios",
+    "androidScenarioRoot": "examples/scenarios/mobile"
+  },
+  "drivers": {
+    "default": "fixture-log-ingest",
+    "supported": ["fixture-log-ingest", "adb", "ios-simctl", "agent-device", "argent", "xcodebuildmcp"]
+  },
+  "versionControl": {
+    "commit": [
+      "core/**",
+      "runner/**",
+      "app/**",
+      "examples/scenarios/**",
+      "docs/**"
+    ],
+    "ignore": [
+      "artifacts/asl/**",
+      "raw simulator recordings, screenshots, and ephemeral profiler exports"
+    ]
+  }
+}

package/dist/core/agent-summary.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Builds the minimum agent-facing markdown summary for a run.
+ *
+ * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null}} options
+ * @returns {string}
+ */
+declare function buildAgentSummaryMarkdown({ health, verdict, comparison }: AgentSummaryInput): string;
+export { buildAgentSummaryMarkdown, };
+export type { AgentSummaryInput, SummaryRecord, };
+type SummaryRecord = Record<string, unknown>;
+type AgentSummaryInput = {
+    health: SummaryRecord;
+    verdict: SummaryRecord;
+    comparison?: SummaryRecord | null;
+};

package/dist/core/agent-summary.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAgentSummaryMarkdown = buildAgentSummaryMarkdown;
+/**
+ * Returns an array when the value is already an array; otherwise returns an empty array.
+ *
+ * @param {unknown} value
+ * @returns {unknown[]}
+ */
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/**
+ * Wraps a scalar value in markdown code ticks.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function code(value) {
+    return `\`${String(value ?? 'unknown')}\``;
+}
+/**
+ * Reads the first non-empty string from candidate values.
+ *
+ * @param {unknown[]} values
+ * @param {string} fallback
+ * @returns {string}
+ */
+function firstString(values, fallback) {
+    const found = values.find((value) => typeof value === 'string' && value.length > 0);
+    return typeof found === 'string' ? found : fallback;
+}
+/**
+ * Formats an optional next-action hint stored on a health check.
+ *
+ * @param {SummaryRecord} record
+ * @returns {string}
+ */
+function formatNextAction(record) {
+    const metadata = record.metadata;
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+        return '';
+    }
+    const metadataRecord = metadata;
+    const nextAction = firstString([metadataRecord.nextAction], '');
+    if (!nextAction) {
+        return '';
+    }
+    const nextActionCode = firstString([metadataRecord.nextActionCode], '');
+    return nextActionCode
+        ? ` Next action ${code(nextActionCode)}: ${nextAction}`
+        : ` Next action: ${nextAction}`;
+}
+/**
+ * Formats health or warning checks as markdown list items.
+ *
+ * @param {unknown[]} checks
+ * @returns {string[]}
+ */
+function formatChecks(checks) {
+    return asArray(checks).map((check) => {
+        if (!check || typeof check !== 'object') {
+            return '- unknown check';
+        }
+        const record = check;
+        const name = firstString([record.name, record.code], 'unknown_check');
+        const status = firstString([record.status], 'unknown');
+        const message = firstString([record.message], 'no message');
+        return `- ${code(name)}: ${status} - ${message}${formatNextAction(record)}`;
+    });
+}
+/**
+ * Formats failed budget checks as markdown list items.
+ *
+ * @param {unknown[]} budgetChecks
+ * @returns {string[]}
+ */
+function formatFailedBudgets(budgetChecks) {
+    return asArray(budgetChecks)
+        .filter((check) => {
+        const record = check;
+        return !!record && typeof record === 'object' && record.pass === false;
+    })
+        .map((check) => {
+        const record = check;
+        const name = firstString([record.name], 'unknown budget');
+        const metric = firstString([record.metric], 'unknown metric');
+        return `- ${name}: ${metric} expected ${record.expected ?? 'n/a'}, actual ${record.actual ?? 'n/a'}`;
+    });
+}
+/**
+ * Formats comparison provenance for agent-readable summaries.
+ *
+ * @param {SummaryRecord} comparison
+ * @returns {string[]}
+ */
+function formatComparisonBasis(comparison) {
+    const basis = comparison.comparisonBasis;
+    if (!basis || typeof basis !== 'object' || Array.isArray(basis)) {
+        return [];
+    }
+    const basisRecord = basis;
+    const baseline = basisRecord.baseline;
+    const current = basisRecord.current;
+    if (!baseline || typeof baseline !== 'object' || !current || typeof current !== 'object') {
+        return [];
+    }
+    const baselineRecord = baseline;
+    const currentRecord = current;
+    const lines = [
+        '',
+        '## comparison basis',
+        '',
+        `- Strategy: ${code(firstString([basisRecord.strategy], 'unknown'))}`,
+        `- Baseline: ${code(firstString([baselineRecord.runId], 'unknown-baseline'))} at ${code(firstString([baselineRecord.runDir], 'unknown-dir'))}`,
+        `- Current: ${code(firstString([currentRecord.runId], 'unknown-current'))} at ${code(firstString([currentRecord.runDir], 'unknown-dir'))}`,
+    ];
+    const selection = basisRecord.selection;
+    if (selection && typeof selection === 'object' && !Array.isArray(selection)) {
+        const selectionRecord = selection;
+        lines.push(`- Selection: inspected ${selectionRecord.candidatesInspected ?? 'unknown'}, trusted ${selectionRecord.trustedCandidates ?? 'unknown'}, trusted prior ${selectionRecord.trustedPriorCandidates ?? 'unknown'}, skipped current ${selectionRecord.skippedCurrentRun ?? 'unknown'}`);
+    }
+    return lines;
+}
+/**
+ * Builds the minimum agent-facing markdown summary for a run.
+ *
+ * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null}} options
+ * @returns {string}
+ */
+function buildAgentSummaryMarkdown({ health, verdict, comparison = null }) {
+    const scenarioId = firstString([health?.scenarioId, verdict?.scenarioId], 'unknown-scenario');
+    const runId = firstString([health?.runId, verdict?.runId], 'unknown-run');
+    const healthStatus = firstString([health?.healthStatus], 'failed');
+    const verdictStatus = firstString([verdict?.verdictStatus], 'inconclusive');
+    const comparisonStatus = comparison
+        ? firstString([comparison.comparisonStatus], 'inconclusive')
+        : 'not_available';
+    const lines = [
+        '# agent summary',
+        '',
+        `- Scenario: ${code(scenarioId)}`,
+        `- Run ID: ${code(runId)}`,
+        `- Health: ${healthStatus}`,
+        `- Verdict: ${verdictStatus}`,
+        `- Comparison: ${comparisonStatus}`,
+        '',
+        '## gate',
+        '',
+    ];
+    if (healthStatus === 'passed') {
+        lines.push('Scenario health passed. Optimization claims still require verdict or comparison evidence.');
+    }
+    else {
+        lines.push('Do not optimize from this run. Scenario health did not pass.');
+    }
+    const failedChecks = asArray(health?.checks).filter((check) => {
+        const record = check;
+        return !!record && typeof record === 'object' && record.status !== 'passed';
+    });
+    if (failedChecks.length > 0) {
+        lines.push('', '## failed checks', '', ...formatChecks(failedChecks));
+    }
+    const warnings = asArray(health?.warnings);
+    if (warnings.length > 0) {
+        lines.push('', '## warnings', '', ...formatChecks(warnings));
+    }
+    const failedBudgets = formatFailedBudgets(asArray(verdict?.budgetChecks));
+    if (failedBudgets.length > 0) {
+        lines.push('', '## failed budgets', '', ...failedBudgets);
+    }
+    if (comparison) {
+        lines.push('', '## comparison', '', firstString([comparison.summary], 'No comparison summary provided.'));
+        lines.push(...formatComparisonBasis(comparison));
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/core/artifact-contract.d.ts

@@ -0,0 +1,151 @@
+declare const PROFILE_EVENT_PREFIX = "[profile-event]";
+type ArtifactRecord = Record<string, any>;
+type ProfileEvent = ArtifactRecord & {
+    event?: string;
+    scenario?: string;
+    runId?: string;
+    iteration?: number;
+    atMs?: number;
+    timestamp?: number | string;
+};
+type BudgetCheck = {
+    name: string;
+    actual: unknown;
+    limit: number;
+    pass: boolean;
+    unit: string;
+};
+/**
+ * Returns a nearest-rank percentile for numeric measurements.
+ *
+ * @param {number[]} values
+ * @param {number} percentileValue
+ * @returns {number | null}
+ */
+declare function percentile(values: number[], percentileValue: number): number | null;
+/**
+ * Extracts structured profile events from device logs.
+ *
+ * Supports both JSON payloads and the older key/value payload format.
+ *
+ * @param {string} logText
+ * @param {{runId?: string, scenario?: string}} [filters]
+ * @returns {Record<string, unknown>[]}
+ */
+declare function extractProfileEvents(logText: string, filters?: {
+    runId?: string;
+    scenario?: string;
+}): ProfileEvent[];
+/**
+ * Builds timing metrics from app-emitted profile events.
+ *
+ * @param {{scenario: string, runId: string, events: Record<string, unknown>[], expectedIterations: number, timeoutCount?: number, artifacts?: Record<string, unknown>, cycleEventNames?: Record<string, string> | null, budgets?: Record<string, unknown> | null}} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildMetricsFromProfileEvents({ scenario, runId, events, expectedIterations, timeoutCount, artifacts, cycleEventNames, budgets, }: {
+    scenario: string;
+    runId: string;
+    events: ProfileEvent[];
+    expectedIterations: number;
+    timeoutCount?: number;
+    artifacts?: ArtifactRecord;
+    cycleEventNames?: ArtifactRecord | null;
+    budgets?: ArtifactRecord | null;
+}): ArtifactRecord;
+/**
+ * Evaluates configured profile budgets against generated metrics.
+ *
+ * @param {{metrics: Record<string, unknown>, budgets?: Record<string, unknown> | null}} options
+ * @returns {Record<string, unknown> | null}
+ */
+declare function evaluateProfileBudgets({ metrics, budgets }: {
+    metrics: ArtifactRecord;
+    budgets?: ArtifactRecord | null;
+}): ArtifactRecord | null;
+/**
+ * Recursively sorts object keys and array values for stable JSON artifacts.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+declare function sortValue(value: any): any;
+/**
+ * Builds a causal timeline from app-owned profile events.
+ *
+ * @param {{events: Record<string, unknown>[], startedAt?: string, phaseMap?: Record<string, string> | null, owner?: string | null}} options
+ * @returns {Record<string, unknown>[]}
+ */
+declare function buildCausalTimeline({ events, startedAt, phaseMap, owner, }: {
+    events: ProfileEvent[];
+    startedAt?: string;
+    phaseMap?: ArtifactRecord | null;
+    owner?: string | null;
+}): ArtifactRecord[];
+/**
+ * Builds the `budget-verdict.json` profile artifact from budget evaluation.
+ *
+ * @param {{flowId: string, runId: string, budgetEvaluation?: Record<string, unknown> | null, visualOutcome?: Record<string, unknown> | null, baselineRunId?: string | null}} options
+ * @returns {Record<string, unknown> | null}
+ */
+declare function buildBudgetVerdict({ flowId, runId, budgetEvaluation, visualOutcome, baselineRunId, }: {
+    flowId: string;
+    runId: string;
+    budgetEvaluation?: ArtifactRecord | null;
+    visualOutcome?: ArtifactRecord | null;
+    baselineRunId?: string | null;
+}): ArtifactRecord | null;
+/**
+ * Builds the `causal-run.json` profile artifact.
+ *
+ * @param {Record<string, unknown>} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildCausalRun({ scenario, flowId, runId, platform, buildFlavor, interactionDriver, trigger, budgets, timeline, artifacts, manifest, metrics, }: ArtifactRecord): ArtifactRecord;
+/**
+ * Builds the run manifest artifact.
+ *
+ * @param {Record<string, unknown>} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildManifest({ scenario, scenarioHash, runId, platform, status, startedAt, endedAt, interactionDriver, comparisonLane, simulator, bundleId, gitSha, toolVersions, artifacts, failureReason, }: ArtifactRecord): ArtifactRecord;
+/**
+ * Builds the human-readable profile summary.
+ *
+ * @param {{manifest: Record<string, unknown>, metrics: Record<string, unknown>}} options
+ * @returns {string}
+ */
+declare function buildSummaryMarkdown({ manifest, metrics }: {
+    manifest: ArtifactRecord;
+    metrics: ArtifactRecord;
+}): string;
+/**
+ * Extracts possible accessibility or test identifiers from a UI tree dump.
+ *
+ * @param {string} rawDescription
+ * @returns {string[]}
+ */
+declare function extractCandidateIdentifiers(rawDescription: string): string[];
+/**
+ * Finds the first UI identifier matching a required pattern.
+ *
+ * @param {string} rawDescription
+ * @param {string} pattern
+ * @returns {string | null}
+ */
+declare function findMatchingIdentifier(rawDescription: string, pattern: string): string | null;
+/**
+ * Evaluates a UI contract from required identifier patterns.
+ *
+ * @param {{rawDescription: string, requiredIdentifierPatterns?: string[]}} options
+ * @returns {{pass: boolean, checks: Record<string, unknown>[], missingPatterns: string[]}}
+ */
+declare function evaluateUiContract({ rawDescription, requiredIdentifierPatterns, }: {
+    rawDescription: string;
+    requiredIdentifierPatterns?: string[];
+}): {
+    pass: boolean;
+    checks: ArtifactRecord[];
+    missingPatterns: string[];
+};
+export { PROFILE_EVENT_PREFIX, buildBudgetVerdict, buildCausalRun, buildCausalTimeline, buildManifest, buildMetricsFromProfileEvents, buildSummaryMarkdown, evaluateUiContract, evaluateProfileBudgets, extractCandidateIdentifiers, extractProfileEvents, findMatchingIdentifier, percentile, sortValue, };
+export type { ArtifactRecord, BudgetCheck, ProfileEvent, };