agent-scenario-loop 0.1.0

package/dist/core/evidence-interpreter.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interpretEvidence = interpretEvidence;
+exports.isTimingEvidenceTrusted = isTimingEvidenceTrusted;
+/**
+ * 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 : [];
+}
+/**
+ * Returns whether timing evidence can be used for interpretation.
+ *
+ * @param {Record<string, unknown>} health
+ * @returns {boolean}
+ */
+function isTimingEvidenceTrusted(health) {
+    return health?.healthStatus === 'passed';
+}
+/**
+ * Builds evidence-backed interpretation hints without overriding scenario health.
+ *
+ * Timing-based hints are only emitted after scenario health passed.
+ *
+ * @param {{health: Record<string, unknown>, verdict?: Record<string, unknown> | null, comparison?: Record<string, unknown> | null}} options
+ * @returns {{timingTrusted: boolean, recommendations: string[], blockedReasons: string[]}}
+ */
+function interpretEvidence({ health, verdict = null, comparison = null, }) {
+    const timingTrusted = isTimingEvidenceTrusted(health);
+    const blockedReasons = [];
+    const recommendations = [];
+    if (!timingTrusted) {
+        blockedReasons.push('scenario health did not pass');
+        recommendations.push('harden scenario health before interpreting timing evidence');
+    }
+    const failedChecks = asArray(health?.checks).filter((check) => {
+        const record = check;
+        return !!record && typeof record === 'object' && record.status !== 'passed';
+    });
+    for (const check of failedChecks) {
+        const record = check;
+        const name = typeof record.name === 'string' ? record.name : record.code;
+        recommendations.push(`resolve health check ${name ?? 'unknown_check'}`);
+    }
+    if (timingTrusted) {
+        const failedBudgets = asArray(verdict?.budgetChecks).filter((check) => {
+            const record = check;
+            return !!record && typeof record === 'object' && record.pass === false;
+        });
+        for (const check of failedBudgets) {
+            const record = check;
+            recommendations.push(`investigate failed budget ${record.name ?? 'unknown budget'}`);
+        }
+        if (comparison?.comparisonStatus === 'worse') {
+            recommendations.push('investigate regression against baseline comparison');
+        }
+        if (comparison?.comparisonStatus === 'mixed') {
+            recommendations.push('inspect mixed baseline comparison signals before claiming improvement');
+        }
+    }
+    return {
+        timingTrusted,
+        recommendations,
+        blockedReasons,
+    };
+}

package/dist/core/execution-plan.d.ts

@@ -0,0 +1,44 @@
+type ScenarioManifest = import('./planner').ScenarioManifest;
+type ScenarioStepKind = 'launch' | 'command' | 'waitForMilestone' | 'captureEvidence' | 'gesture' | 'assertUi';
+type RunnerPortMethod = 'launch' | 'executeStep' | 'waitForTruthEvent' | 'captureEvidence';
+type ScenarioExecutionStep = {
+    id: string;
+    index: number;
+    kind: ScenarioStepKind;
+    portMethod: RunnerPortMethod;
+    required: boolean;
+    adapterOptions?: Record<string, unknown>;
+    artifact?: string;
+    command?: string;
+    driverAction?: string;
+    milestone?: string;
+    selector?: Record<string, unknown>;
+    timeoutMs?: number;
+};
+type ScenarioExecutionPlan = {
+    scenarioId: string;
+    flowId?: string;
+    steps: ScenarioExecutionStep[];
+    driverActions: {
+        optional: string[];
+        required: string[];
+    };
+};
+declare const STEP_KIND_TO_PORT_METHOD: Record<ScenarioStepKind, RunnerPortMethod>;
+/**
+ * Normalizes one scenario step into an adapter-facing execution step.
+ *
+ * @param {Record<string, unknown>} step
+ * @param {number} index
+ * @returns {ScenarioExecutionStep}
+ */
+declare function normalizeScenarioStep(step: Record<string, unknown>, index: number): ScenarioExecutionStep;
+/**
+ * Builds the adapter-facing execution plan for a scenario manifest.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {ScenarioExecutionPlan}
+ */
+declare function buildScenarioExecutionPlan(scenario: ScenarioManifest): ScenarioExecutionPlan;
+export { STEP_KIND_TO_PORT_METHOD, buildScenarioExecutionPlan, normalizeScenarioStep, };
+export type { RunnerPortMethod, ScenarioExecutionPlan, ScenarioExecutionStep, ScenarioStepKind, };

package/dist/core/execution-plan.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STEP_KIND_TO_PORT_METHOD = void 0;
+exports.buildScenarioExecutionPlan = buildScenarioExecutionPlan;
+exports.normalizeScenarioStep = normalizeScenarioStep;
+const { collectScenarioDriverActions } = require('./planner');
+const STEP_KIND_TO_PORT_METHOD = {
+    assertUi: 'executeStep',
+    captureEvidence: 'captureEvidence',
+    command: 'executeStep',
+    gesture: 'executeStep',
+    launch: 'launch',
+    waitForMilestone: 'waitForTruthEvent',
+};
+exports.STEP_KIND_TO_PORT_METHOD = STEP_KIND_TO_PORT_METHOD;
+/**
+ * Resolves the scenario identifier for execution-plan artifacts and logs.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {string}
+ */
+function getScenarioId(scenario) {
+    return scenario.id ?? scenario.name ?? 'unknown-scenario';
+}
+/**
+ * Returns true for scenario step kinds supported by the execution-plan contract.
+ *
+ * @param {unknown} kind
+ * @returns {kind is ScenarioStepKind}
+ */
+function isScenarioStepKind(kind) {
+    return typeof kind === 'string' && kind in STEP_KIND_TO_PORT_METHOD;
+}
+/**
+ * Builds a deterministic id for an unnamed scenario step.
+ *
+ * @param {number} index
+ * @param {ScenarioStepKind} kind
+ * @returns {string}
+ */
+function buildDefaultStepId(index, kind) {
+    return `${String(index + 1).padStart(2, '0')}-${kind}`;
+}
+/**
+ * Normalizes one scenario step into an adapter-facing execution step.
+ *
+ * @param {Record<string, unknown>} step
+ * @param {number} index
+ * @returns {ScenarioExecutionStep}
+ */
+function normalizeScenarioStep(step, index) {
+    if (!isScenarioStepKind(step.kind)) {
+        throw new Error(`Scenario step ${index + 1} has unsupported kind.`);
+    }
+    return {
+        id: typeof step.id === 'string' && step.id.length > 0 ? step.id : buildDefaultStepId(index, step.kind),
+        index,
+        kind: step.kind,
+        portMethod: STEP_KIND_TO_PORT_METHOD[step.kind],
+        required: step.required !== false,
+        ...(step.adapterOptions && typeof step.adapterOptions === 'object' && !Array.isArray(step.adapterOptions)
+            ? { adapterOptions: step.adapterOptions }
+            : {}),
+        ...(typeof step.artifact === 'string' ? { artifact: step.artifact } : {}),
+        ...(typeof step.command === 'string' ? { command: step.command } : {}),
+        ...(typeof step.driverAction === 'string' ? { driverAction: step.driverAction } : {}),
+        ...(typeof step.milestone === 'string' ? { milestone: step.milestone } : {}),
+        ...(step.selector && typeof step.selector === 'object' && !Array.isArray(step.selector)
+            ? { selector: step.selector }
+            : {}),
+        ...(typeof step.timeoutMs === 'number' && Number.isFinite(step.timeoutMs) ? { timeoutMs: step.timeoutMs } : {}),
+    };
+}
+/**
+ * Builds the adapter-facing execution plan for a scenario manifest.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {ScenarioExecutionPlan}
+ */
+function buildScenarioExecutionPlan(scenario) {
+    const steps = Array.isArray(scenario.steps)
+        ? scenario.steps.map((step, index) => {
+            if (!step || typeof step !== 'object' || Array.isArray(step)) {
+                throw new Error(`Scenario step ${index + 1} must be an object.`);
+            }
+            return normalizeScenarioStep(step, index);
+        })
+        : [];
+    return {
+        scenarioId: getScenarioId(scenario),
+        ...(typeof scenario.flowId === 'string' ? { flowId: scenario.flowId } : {}),
+        steps,
+        driverActions: collectScenarioDriverActions(scenario),
+    };
+}

package/dist/core/planner.d.ts

@@ -0,0 +1,132 @@
+type ManifestRecord = Record<string, unknown>;
+type PlannerIssue = {
+    code: string;
+    message: string;
+    [key: string]: unknown;
+};
+type CompatibilityResult = {
+    compatible: boolean;
+    errors: PlannerIssue[];
+    warnings: PlannerIssue[];
+    matched: {
+        platforms: string[];
+        capabilities: string[];
+        driverActions: string[];
+        artifacts: string[];
+        evidenceProviders: string[];
+    };
+};
+type ScenarioStep = ManifestRecord & {
+    adapterOptions?: unknown;
+    driverAction?: unknown;
+    id?: unknown;
+    required?: unknown;
+    selector?: unknown;
+};
+type ScenarioManifest = ManifestRecord & {
+    adapterOptions?: unknown;
+    id?: string;
+    name?: string;
+    flowId?: string;
+    platforms?: unknown[];
+    requiredCapabilities?: unknown[];
+    optionalCapabilities?: unknown[];
+    steps?: ScenarioStep[];
+    artifacts?: {
+        required?: unknown[];
+        optional?: unknown[];
+    };
+};
+type RunnerManifest = ManifestRecord & {
+    runnerId?: string;
+    name?: string;
+    kind?: string;
+    platforms?: unknown[];
+    capabilities?: unknown[];
+    driverActions?: unknown[];
+    artifactOutputs?: unknown[];
+};
+/**
+ * Returns non-empty string values with duplicates removed and deterministic ordering.
+ *
+ * @param {unknown[]} values
+ * @returns {string[]}
+ */
+declare function uniqueSorted(values: unknown[]): string[];
+/**
+ * Finds the unique string values shared by two arrays.
+ *
+ * @param {unknown[]} left
+ * @param {unknown[]} right
+ * @returns {string[]}
+ */
+declare function intersection(left: unknown[], right: unknown[]): string[];
+/**
+ * Collects driver operations available from the primary runner and active providers.
+ *
+ * @param {{runner: Record<string, unknown>, evidenceProviders: Record<string, unknown>[], effectivePlatforms: string[]}} options
+ * @returns {string[]}
+ */
+declare function collectProvidedDriverActions({ runner, evidenceProviders, effectivePlatforms, }: {
+    runner: RunnerManifest;
+    evidenceProviders: RunnerManifest[];
+    effectivePlatforms: string[];
+}): string[];
+/**
+ * Collects driver operations required by scenario steps.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {{required: string[], optional: string[]}}
+ */
+declare function collectScenarioDriverActions(scenario: ScenarioManifest): {
+    required: string[];
+    optional: string[];
+};
+/**
+ * Validates adapter-specific scenario metadata for the selected platform set.
+ *
+ * @param {{scenario: ScenarioManifest, effectivePlatforms: string[], errors: PlannerIssue[], runner?: RunnerManifest}} options
+ * @returns {void}
+ */
+declare function validateScenarioAdapterOptions({ effectivePlatforms, errors, runner, scenario, }: {
+    effectivePlatforms: string[];
+    errors: PlannerIssue[];
+    runner?: RunnerManifest;
+    scenario: ScenarioManifest;
+}): void;
+/**
+ * Evaluates whether a scenario can be served by a primary runner plus evidence providers.
+ *
+ * @param {{scenario?: Record<string, unknown>, runner?: Record<string, unknown>, evidenceProviders?: Record<string, unknown>[], platform?: string | null}} [options]
+ * @returns {{compatible: boolean, errors: Record<string, unknown>[], warnings: Record<string, unknown>[], matched: {platforms: string[], capabilities: string[], driverActions: string[], artifacts: string[], evidenceProviders: string[]}}}
+ */
+declare function evaluateRunnerCompatibility({ scenario, runner, evidenceProviders, platform, }?: {
+    scenario?: ScenarioManifest;
+    runner?: RunnerManifest;
+    evidenceProviders?: RunnerManifest[];
+    platform?: string | null;
+}): CompatibilityResult;
+/**
+ * Builds the initial `health.json` artifact from planner compatibility results.
+ *
+ * @param {{scenario: Record<string, unknown>, runId?: string, compatibility: Record<string, unknown>}} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildCompatibilityHealth({ scenario, runId, compatibility, }: {
+    scenario: ScenarioManifest;
+    runId?: string;
+    compatibility: CompatibilityResult;
+}): ManifestRecord;
+/**
+ * Builds a pre-budget `verdict.json` artifact from scenario health.
+ *
+ * @param {{scenario: Record<string, unknown>, runId?: string, health: Record<string, unknown>}} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildUnevaluatedVerdict({ scenario, runId, health, }: {
+    scenario: ScenarioManifest;
+    runId?: string;
+    health: ManifestRecord;
+}): ManifestRecord;
+export { buildCompatibilityHealth, buildUnevaluatedVerdict, collectProvidedDriverActions, collectScenarioDriverActions, evaluateRunnerCompatibility, intersection, uniqueSorted, validateScenarioAdapterOptions, };
+export type { CompatibilityResult, ManifestRecord, PlannerIssue, RunnerManifest, ScenarioManifest, };