agent-scenario-loop 0.1.0

package/dist/core/schema-validator.js

@@ -0,0 +1,407 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaValidationError = exports.SCHEMAS = void 0;
+exports.assertValidJson = assertValidJson;
+exports.formatValidationErrorMessage = formatValidationErrorMessage;
+exports.validateJson = validateJson;
+const fs = require('node:fs');
+const path = require('node:path');
+/**
+ * Error thrown when a manifest or generated artifact does not satisfy its schema.
+ */
+class SchemaValidationError extends Error {
+    label;
+    errors;
+    /**
+     * @param {string} label
+     * @param {{code: string, path: string, message: string}[]} errors
+     */
+    constructor(label, errors) {
+        super(formatValidationErrorMessage(label, errors));
+        this.name = 'SchemaValidationError';
+        this.label = label;
+        this.errors = errors;
+    }
+}
+exports.SchemaValidationError = SchemaValidationError;
+/**
+ * Reads and parses a JSON file.
+ *
+ * @param {string} filePath
+ * @returns {unknown}
+ */
+function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+/**
+ * Loads a schema from the repo-local `schemas` directory.
+ *
+ * @param {string} relativePath
+ * @returns {Record<string, unknown>}
+ */
+function loadSchema(relativePath) {
+    const sourcePath = path.join(__dirname, '..', 'schemas', relativePath);
+    const compiledPath = path.join(__dirname, '..', '..', 'schemas', relativePath);
+    const schemaPath = fs.existsSync(sourcePath) ? sourcePath : compiledPath;
+    return readJson(schemaPath);
+}
+const SCHEMAS = {
+    budgetVerdict: loadSchema('budget-verdict.schema.json'),
+    causalRun: loadSchema('causal-run.schema.json'),
+    comparison: loadSchema('comparison.schema.json'),
+    health: loadSchema('health.schema.json'),
+    liveProof: loadSchema('live-proof.schema.json'),
+    liveProofSet: loadSchema('live-proof-set.schema.json'),
+    manifest: loadSchema('manifest.schema.json'),
+    metrics: loadSchema('metrics.schema.json'),
+    projectValidation: loadSchema('project-validation.schema.json'),
+    scenario: loadSchema('scenario.schema.json'),
+    runnerCapabilities: loadSchema('runner-capabilities.schema.json'),
+    verdict: loadSchema('verdict.schema.json'),
+};
+exports.SCHEMAS = SCHEMAS;
+/**
+ * Formats a validation path as a JSONPath-like string.
+ *
+ * @param {(string | number)[]} pathSegments
+ * @returns {string}
+ */
+function formatPath(pathSegments) {
+    if (pathSegments.length === 0) {
+        return '$';
+    }
+    return pathSegments.reduce((result, segment) => {
+        if (typeof segment === 'number') {
+            return `${result}[${segment}]`;
+        }
+        if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(segment)) {
+            return `${result}.${segment}`;
+        }
+        return `${result}[${JSON.stringify(segment)}]`;
+    }, '$');
+}
+/**
+ * Stringifies object values with stable key ordering for `uniqueItems` checks.
+ *
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function stableStringify(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return JSON.stringify(value);
+    }
+    return JSON.stringify(Object.keys(value)
+        .sort()
+        .reduce((result, key) => {
+        const source = value;
+        result[key] = source[key];
+        return result;
+    }, {}));
+}
+/**
+ * Formats enum values for validation error messages.
+ *
+ * @param {unknown[]} values
+ * @returns {string}
+ */
+function describeAllowedValues(values) {
+    return values.map((value) => JSON.stringify(value)).join(', ');
+}
+/**
+ * Resolves local JSON Schema references such as `#/$defs/capability`.
+ *
+ * @param {Record<string, unknown>} rootSchema
+ * @param {string} ref
+ * @returns {Record<string, unknown>}
+ */
+function resolveLocalRef(rootSchema, ref) {
+    if (!ref.startsWith('#/')) {
+        throw new Error(`Only local schema refs are supported: ${ref}`);
+    }
+    return ref
+        .slice(2)
+        .split('/')
+        .reduce((current, token) => {
+        const key = token.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (!current || typeof current !== 'object' || !(key in current)) {
+            throw new Error(`Schema ref could not be resolved: ${ref}`);
+        }
+        return current[key];
+    }, rootSchema);
+}
+/**
+ * Returns true when a value satisfies a schema without recording validation errors.
+ *
+ * @param {unknown} value
+ * @param {Record<string, unknown>} schema
+ * @param {Record<string, unknown>} rootSchema
+ * @returns {boolean}
+ */
+function matchesSchema(value, schema, rootSchema) {
+    return validateSchema(value, schema, rootSchema, [], []).length === 0;
+}
+/**
+ * Checks a JavaScript value against one JSON Schema primitive type.
+ *
+ * @param {unknown} value
+ * @param {string} type
+ * @returns {boolean}
+ */
+function isType(value, type) {
+    if (type === 'null') {
+        return value === null;
+    }
+    if (type === 'array') {
+        return Array.isArray(value);
+    }
+    if (type === 'object') {
+        return !!value && typeof value === 'object' && !Array.isArray(value);
+    }
+    if (type === 'integer') {
+        return Number.isInteger(value);
+    }
+    if (type === 'number') {
+        return typeof value === 'number' && Number.isFinite(value);
+    }
+    return typeof value === type;
+}
+/**
+ * Validates the `type` keyword and records one error on mismatch.
+ *
+ * @param {{value: unknown, expectedType: string | string[], pathSegments: (string | number)[], errors: {code: string, path: string, message: string}[]}} options
+ * @returns {boolean}
+ */
+function validateType({ value, expectedType, pathSegments, errors, }) {
+    const expectedTypes = Array.isArray(expectedType) ? expectedType : [expectedType];
+    if (!expectedTypes.some((type) => isType(value, type))) {
+        errors.push({
+            code: 'invalid_type',
+            path: formatPath(pathSegments),
+            message: `Expected ${expectedTypes.join(' or ')}.`,
+        });
+        return false;
+    }
+    return true;
+}
+/**
+ * Validates the JSON Schema subset used by this package's public contracts.
+ *
+ * @param {unknown} value
+ * @param {Record<string, unknown>} schema
+ * @param {Record<string, unknown>} rootSchema
+ * @param {(string | number)[]} [pathSegments]
+ * @param {{code: string, path: string, message: string}[]} [errors]
+ * @returns {{code: string, path: string, message: string}[]}
+ */
+function validateSchema(value, schema, rootSchema, pathSegments = [], errors = []) {
+    if (!schema || typeof schema !== 'object') {
+        return errors;
+    }
+    if (schema.$ref) {
+        validateSchema(value, resolveLocalRef(rootSchema, schema.$ref), rootSchema, pathSegments, errors);
+    }
+    for (const childSchema of schema.allOf ?? []) {
+        validateSchema(value, childSchema, rootSchema, pathSegments, errors);
+    }
+    if ('const' in schema && !Object.is(schema.const, value)) {
+        errors.push({
+            code: 'invalid_const',
+            path: formatPath(pathSegments),
+            message: `Expected ${JSON.stringify(schema.const)}.`,
+        });
+    }
+    if (schema.if && matchesSchema(value, schema.if, rootSchema)) {
+        if (schema.then) {
+            validateSchema(value, schema.then, rootSchema, pathSegments, errors);
+        }
+    }
+    else if (schema.if && schema.else) {
+        validateSchema(value, schema.else, rootSchema, pathSegments, errors);
+    }
+    if (schema.not && matchesSchema(value, schema.not, rootSchema)) {
+        errors.push({
+            code: 'schema_not',
+            path: formatPath(pathSegments),
+            message: schema.not.description ?? 'Value must not match the disallowed schema.',
+        });
+    }
+    if (schema.type && !validateType({ value, expectedType: schema.type, pathSegments, errors })) {
+        return errors;
+    }
+    if (schema.enum && !schema.enum.some((allowed) => Object.is(allowed, value))) {
+        errors.push({
+            code: 'invalid_enum',
+            path: formatPath(pathSegments),
+            message: `Expected one of ${describeAllowedValues(schema.enum)}.`,
+        });
+    }
+    if (typeof schema.pattern === 'string' && typeof value === 'string') {
+        const regex = new RegExp(schema.pattern, 'u');
+        if (!regex.test(value)) {
+            errors.push({
+                code: 'invalid_pattern',
+                path: formatPath(pathSegments),
+                message: `Expected value to match ${schema.pattern}.`,
+            });
+        }
+    }
+    if (typeof schema.minLength === 'number' && typeof value === 'string' && value.length < schema.minLength) {
+        errors.push({
+            code: 'too_short',
+            path: formatPath(pathSegments),
+            message: `Expected at least ${schema.minLength} character(s).`,
+        });
+    }
+    if (typeof schema.minimum === 'number' && typeof value === 'number' && value < schema.minimum) {
+        errors.push({
+            code: 'below_minimum',
+            path: formatPath(pathSegments),
+            message: `Expected value to be >= ${schema.minimum}.`,
+        });
+    }
+    if (Array.isArray(value)) {
+        validateArray(value, schema, rootSchema, pathSegments, errors);
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        validateObject(value, schema, rootSchema, pathSegments, errors);
+    }
+    return errors;
+}
+/**
+ * Validates array-specific schema keywords.
+ *
+ * @param {unknown[]} value
+ * @param {Record<string, unknown>} schema
+ * @param {Record<string, unknown>} rootSchema
+ * @param {(string | number)[]} pathSegments
+ * @param {{code: string, path: string, message: string}[]} errors
+ * @returns {void}
+ */
+function validateArray(value, schema, rootSchema, pathSegments, errors) {
+    if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+        errors.push({
+            code: 'too_few_items',
+            path: formatPath(pathSegments),
+            message: `Expected at least ${schema.minItems} item(s).`,
+        });
+    }
+    if (schema.uniqueItems === true) {
+        const seen = new Set();
+        for (const item of value) {
+            const key = stableStringify(item);
+            if (seen.has(key)) {
+                errors.push({
+                    code: 'duplicate_item',
+                    path: formatPath(pathSegments),
+                    message: 'Expected array items to be unique.',
+                });
+                break;
+            }
+            seen.add(key);
+        }
+    }
+    if (schema.items) {
+        const itemSchema = schema.items;
+        value.forEach((item, index) => validateSchema(item, itemSchema, rootSchema, [...pathSegments, index], errors));
+    }
+}
+/**
+ * Validates object-specific schema keywords.
+ *
+ * @param {Record<string, unknown>} value
+ * @param {Record<string, unknown>} schema
+ * @param {Record<string, unknown>} rootSchema
+ * @param {(string | number)[]} pathSegments
+ * @param {{code: string, path: string, message: string}[]} errors
+ * @returns {void}
+ */
+function validateObject(value, schema, rootSchema, pathSegments, errors) {
+    if (typeof schema.minProperties === 'number' && Object.keys(value).length < schema.minProperties) {
+        errors.push({
+            code: 'too_few_properties',
+            path: formatPath(pathSegments),
+            message: `Expected at least ${schema.minProperties} properties.`,
+        });
+    }
+    for (const requiredKey of schema.required ?? []) {
+        if (!(requiredKey in value)) {
+            errors.push({
+                code: 'missing_required_property',
+                path: formatPath([...pathSegments, requiredKey]),
+                message: `Missing required property \`${requiredKey}\`.`,
+            });
+        }
+    }
+    const definedProperties = schema.properties ?? {};
+    for (const [key, propertySchema] of Object.entries(definedProperties)) {
+        if (key in value) {
+            validateSchema(value[key], propertySchema, rootSchema, [...pathSegments, key], errors);
+        }
+    }
+    for (const key of Object.keys(value)) {
+        if (key in definedProperties) {
+            continue;
+        }
+        if (schema.additionalProperties === false) {
+            errors.push({
+                code: 'additional_property',
+                path: formatPath([...pathSegments, key]),
+                message: `Unexpected property \`${key}\`.`,
+            });
+        }
+        else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+            validateSchema(value[key], schema.additionalProperties, rootSchema, [...pathSegments, key], errors);
+        }
+    }
+}
+/**
+ * Validates a value against a schema and returns structured errors instead of throwing.
+ *
+ * @param {unknown} value
+ * @param {Record<string, unknown>} schema
+ * @param {string} [label]
+ * @returns {{valid: boolean, errors: {code: string, path: string, message: string}[], message: string}}
+ */
+function validateJson(value, schema, label = 'JSON document') {
+    const errors = validateSchema(value, schema, schema);
+    if (errors.length > 0) {
+        return {
+            valid: false,
+            errors,
+            message: formatValidationErrorMessage(label, errors),
+        };
+    }
+    return {
+        valid: true,
+        errors: [],
+        message: '',
+    };
+}
+/**
+ * Validates a value against a schema, throwing `SchemaValidationError` on failure.
+ *
+ * @param {unknown} value
+ * @param {Record<string, unknown>} schema
+ * @param {string} label
+ * @returns {unknown}
+ */
+function assertValidJson(value, schema, label) {
+    const result = validateJson(value, schema, label);
+    if (!result.valid) {
+        throw new SchemaValidationError(label, result.errors);
+    }
+    return value;
+}
+/**
+ * Formats schema errors as a CLI-readable message.
+ *
+ * @param {string} label
+ * @param {{path: string, message: string}[]} errors
+ * @returns {string}
+ */
+function formatValidationErrorMessage(label, errors) {
+    return [
+        `${label} failed schema validation:`,
+        ...errors.map((error) => `- ${error.path}: ${error.message}`),
+    ].join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './core/agent-summary';
+export * from './core/artifact-contract';
+export * from './core/artifact-layout';
+export * from './core/artifact-writer';
+export * from './core/comparison';
+export * from './core/evidence-interpreter';
+export * from './core/execution-plan';
+export * from './core/planner';
+export * from './core/ports';
+export * from './core/run-index';
+export * from './core/schema-validator';

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./core/agent-summary"), exports);
+__exportStar(require("./core/artifact-contract"), exports);
+__exportStar(require("./core/artifact-layout"), exports);
+__exportStar(require("./core/artifact-writer"), exports);
+__exportStar(require("./core/comparison"), exports);
+__exportStar(require("./core/evidence-interpreter"), exports);
+__exportStar(require("./core/execution-plan"), exports);
+__exportStar(require("./core/planner"), exports);
+__exportStar(require("./core/ports"), exports);
+__exportStar(require("./core/run-index"), exports);
+__exportStar(require("./core/schema-validator"), exports);

package/dist/runner/agent-device-driver.d.ts

@@ -0,0 +1,126 @@
+type AgentDevicePlatform = 'android' | 'apple' | 'ios' | 'linux' | 'macos';
+type AgentDeviceCommandResult = {
+    action: string;
+    args: string[];
+    capturePath?: string;
+    command: string;
+    exitCode: number;
+    rawFileName: string;
+    stderr: string;
+    stdout: string;
+};
+type AgentDeviceCommandExecutor = (command: string, args: string[]) => Promise<{
+    args: string[];
+    command: string;
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+}>;
+type AgentDeviceDriverOptions = {
+    agentDevicePath: string;
+    device?: string;
+    executor: AgentDeviceCommandExecutor;
+    extraArgs?: string[];
+    json?: boolean;
+    platform: AgentDevicePlatform;
+    serial?: string;
+    session?: string;
+    target?: 'desktop' | 'mobile' | 'tv';
+    udid?: string;
+};
+type AgentDeviceSelector = {
+    kind: string;
+    match?: string;
+    value: string;
+};
+type AgentDeviceAlertAction = 'accept' | 'dismiss' | 'get' | 'wait';
+type AgentDeviceAlertOptions = {
+    action?: AgentDeviceAlertAction;
+    rawFileName?: string;
+    timeoutMs?: number;
+};
+type AgentDeviceAssertVisibleOptions = {
+    rawFileName?: string;
+    selector: AgentDeviceSelector;
+};
+type AgentDeviceInspectTreeOptions = {
+    interactive?: boolean;
+    rawFileName?: string;
+};
+type AgentDeviceOpenOptions = {
+    appOrUrl: string;
+    rawFileName?: string;
+    url?: string;
+};
+type AgentDeviceReadLogsOptions = {
+    rawFileName?: string;
+};
+type AgentDeviceScreenshotOptions = {
+    outputPath: string;
+    rawFileName?: string;
+};
+type AgentDeviceScrollOptions = {
+    amount?: string;
+    direction?: string;
+    durationMs?: number;
+    endX?: number;
+    endY?: number;
+    pixels?: number;
+    rawFileName?: string;
+    startX?: number;
+    startY?: number;
+};
+type AgentDeviceTapOptions = {
+    rawFileName?: string;
+    ref?: string;
+    selector?: AgentDeviceSelector;
+    x?: number;
+    y?: number;
+};
+type AgentDeviceDriver = {
+    alert: (options?: AgentDeviceAlertOptions) => Promise<AgentDeviceCommandResult>;
+    assertVisible: (options: AgentDeviceAssertVisibleOptions) => Promise<AgentDeviceCommandResult>;
+    close: (app: string) => Promise<AgentDeviceCommandResult>;
+    inspectTree: (options?: AgentDeviceInspectTreeOptions) => Promise<AgentDeviceCommandResult>;
+    open: (options: AgentDeviceOpenOptions) => Promise<AgentDeviceCommandResult>;
+    readLogs: (options?: AgentDeviceReadLogsOptions) => Promise<AgentDeviceCommandResult>;
+    screenshot: (options: AgentDeviceScreenshotOptions) => Promise<AgentDeviceCommandResult>;
+    scroll: (options?: AgentDeviceScrollOptions) => Promise<AgentDeviceCommandResult>;
+    tap: (options: AgentDeviceTapOptions) => Promise<AgentDeviceCommandResult>;
+};
+/**
+ * Builds global CLI flags shared by all agent-device driver actions.
+ *
+ * @param {AgentDeviceDriverOptions} options
+ * @returns {string[]}
+ */
+declare function buildAgentDeviceGlobalArgs(options: AgentDeviceDriverOptions): string[];
+/**
+ * Formats one portable selector as an agent-device selector expression.
+ *
+ * @param {AgentDeviceSelector} selector
+ * @returns {string}
+ */
+declare function formatAgentDeviceSelector(selector: AgentDeviceSelector): string;
+/**
+ * Combines stdout and stderr into the raw evidence text written by callers.
+ *
+ * @param {{stdout: string, stderr: string}} result
+ * @returns {string}
+ */
+declare function formatAgentDeviceRawOutput(result: {
+    stdout: string;
+    stderr: string;
+}): string;
+/**
+ * Creates an agent-device-backed driver for portable mobile actions.
+ *
+ * The adapter shells out through an injected executor so consumers can choose
+ * local, remote, or test doubles without making agent-device a package dependency.
+ *
+ * @param {AgentDeviceDriverOptions} options
+ * @returns {AgentDeviceDriver}
+ */
+declare function createAgentDeviceDriver(options: AgentDeviceDriverOptions): AgentDeviceDriver;
+export { buildAgentDeviceGlobalArgs, createAgentDeviceDriver, formatAgentDeviceRawOutput, formatAgentDeviceSelector, };
+export type { AgentDeviceAlertAction, AgentDeviceAlertOptions, AgentDeviceAssertVisibleOptions, AgentDeviceCommandExecutor, AgentDeviceCommandResult, AgentDeviceDriver, AgentDeviceDriverOptions, AgentDeviceInspectTreeOptions, AgentDeviceOpenOptions, AgentDevicePlatform, AgentDeviceReadLogsOptions, AgentDeviceScreenshotOptions, AgentDeviceScrollOptions, AgentDeviceSelector, AgentDeviceTapOptions, };