@farmslot/recipe-runner 0.23.0

package/dist/runtime/operation.js

@@ -0,0 +1,184 @@
+// Invocation records keep concurrent command observations independent of locks.
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { validateOperationRecord } from '@farmslot/protocol';
+export function processIdentity(pid) {
+    try {
+        const value = execFileSync('ps', ['-p', String(pid), '-o', 'lstart='], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+        return value || undefined;
+    }
+    catch (error) {
+        if (error.status === 1)
+            return undefined;
+        throw error;
+    }
+}
+export class OperationRecord {
+    constructor(directory, command, target, options = {}) {
+        this.lastFlush = 0;
+        this.disabled = false;
+        const id = randomUUID();
+        const now = new Date().toISOString();
+        this.notification = options.mirrorDirectory
+            ? path.join(path.dirname(options.mirrorDirectory), 'operations-updated.json')
+            : undefined;
+        this.file = path.join(directory, `${id}.json`);
+        this.files = [
+            this.file,
+            ...(options.mirrorDirectory ? [path.join(options.mirrorDirectory, `${id}.json`)] : []),
+        ];
+        const logPath = path.join(options.mirrorDirectory ?? directory, `${id}.log`);
+        ensureRuntimeDirectory(path.dirname(logPath));
+        fs.writeFileSync(logPath, '', { flag: 'wx', mode: 0o600 });
+        fs.chmodSync(logPath, 0o600);
+        const identity = processIdentity(process.pid);
+        if (!identity)
+            throw new Error('Cannot identify the operation owner process');
+        this.value = {
+            schemaVersion: 1,
+            id,
+            ...(options.parentId ? { parentId: options.parentId } : {}),
+            command,
+            target,
+            pid: process.pid,
+            processStartedAt: identity,
+            startedAt: now,
+            updatedAt: now,
+            status: 'running',
+            logPath,
+        };
+        for (const file of this.files)
+            ensureRuntimeDirectory(path.dirname(file));
+        this.flush();
+        this.timer = setInterval(() => this.observe(() => this.flush()), 5000);
+        this.timer.unref();
+    }
+    stage(stage) {
+        if (stage === this.value.stage)
+            return;
+        this.value.stage = stage;
+        this.value.stageStartedAt = new Date().toISOString();
+        this.observe(() => this.flush());
+    }
+    output(chunk) {
+        if (chunk.length === 0)
+            return;
+        this.observe(() => {
+            fs.appendFileSync(this.value.logPath, chunk);
+            this.value.lastOutputAt = new Date().toISOString();
+            if (Date.now() - this.lastFlush >= 1000)
+                this.flush();
+        });
+    }
+    finish(exitCode) {
+        clearInterval(this.timer);
+        this.value.exitCode = exitCode;
+        this.value.status = exitCode === 0 ? 'pass' : 'fail';
+        this.value.finishedAt = new Date().toISOString();
+        this.observe(() => this.flush());
+    }
+    observe(write) {
+        if (this.disabled)
+            return;
+        try {
+            write();
+        }
+        catch (error) {
+            // Observation is optional. Stop it explicitly without terminating the
+            // command or its children from an event callback. Old records go stale.
+            this.disabled = true;
+            clearInterval(this.timer);
+            process.stderr.write(`Operation observation disabled for ${this.value.id}: ${error.message}\n`);
+        }
+    }
+    flush() {
+        this.lastFlush = Date.now();
+        this.value.updatedAt = new Date(this.lastFlush).toISOString();
+        for (const file of this.files) {
+            const temporary = `${file}.${process.pid}.tmp`;
+            fs.writeFileSync(temporary, `${JSON.stringify(this.value)}\n`, { mode: 0o600 });
+            fs.chmodSync(temporary, 0o600);
+            fs.renameSync(temporary, file);
+        }
+        if (this.notification) {
+            const temporary = `${this.notification}.${this.value.id}.tmp`;
+            fs.writeFileSync(temporary, JSON.stringify({ updatedAt: this.value.updatedAt }), {
+                mode: 0o600,
+            });
+            fs.chmodSync(temporary, 0o600);
+            fs.renameSync(temporary, this.notification);
+        }
+    }
+}
+// New observation directories must remain traversable even under a restrictive umask.
+export function ensureRuntimeDirectory(directory) {
+    if (fs.existsSync(directory))
+        return;
+    ensureRuntimeDirectory(path.dirname(directory));
+    try {
+        fs.mkdirSync(directory, { mode: 0o700 });
+    }
+    catch (error) {
+        // Another invocation can create the shared directory first.
+        if (error.code === 'EEXIST')
+            return;
+        throw error;
+    }
+    fs.chmodSync(directory, 0o700);
+}
+export function readOperations(directory, onInvalid) {
+    if (!fs.existsSync(directory))
+        return [];
+    return fs
+        .readdirSync(directory)
+        .filter((name) => /^[a-f0-9-]{36}\.json$/.test(name))
+        .flatMap((name) => {
+        try {
+            const value = JSON.parse(fs.readFileSync(path.join(directory, name), 'utf8'));
+            validateOperationRecord(value, name.slice(0, -5));
+            return [value];
+        }
+        catch (error) {
+            // Another invocation may prune a completed record between list and read.
+            if (error.code === 'ENOENT')
+                return [];
+            if (!onInvalid)
+                throw error;
+            onInvalid(error);
+            return [];
+        }
+    })
+        .sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+}
+/** Keep captured text bounded without copying the whole tail for every chunk. */
+export class OperationOutputTail {
+    constructor(limit = 64 * 1024 * 1024) {
+        this.limit = limit;
+        this.chunks = [];
+        this.length = 0;
+    }
+    append(chunk) {
+        if (!chunk)
+            return;
+        this.chunks.push(chunk);
+        this.length += chunk.length;
+        while (this.length > this.limit) {
+            const first = this.chunks[0];
+            const remove = Math.min(first.length, this.length - this.limit);
+            if (remove === first.length)
+                this.chunks.shift();
+            else
+                this.chunks[0] = first.slice(remove);
+            this.length -= remove;
+        }
+    }
+    toString() {
+        return this.chunks.join('');
+    }
+}
+//# sourceMappingURL=operation.js.map

package/dist/runtime/operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../../src/runtime/operation.ts"],"names":[],"mappings":"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"}

package/dist/runtime/orchestrate-up.d.ts

@@ -0,0 +1,22 @@
+import type { RuntimeDecisionReport, RuntimeReadinessDecision } from './decision-types.js';
+export interface OrchestrateRuntimeUpOptions<T extends RuntimeDecisionReport = RuntimeDecisionReport> {
+    decide: () => Promise<T>;
+    onInstall: (report: T) => Promise<void>;
+    onLaunch: (report: T) => Promise<void>;
+    onReady: (report: T) => Promise<void>;
+    onBlocked?: (report: T) => Promise<void>;
+    /** Shared flag — set true after first install attempt to prevent loops. */
+    installAttempted?: {
+        value: boolean;
+    };
+}
+export interface OrchestrateRuntimeUpResult<T extends RuntimeDecisionReport = RuntimeDecisionReport> {
+    report: T;
+    exitDecision: RuntimeReadinessDecision;
+}
+/**
+ * Generic install → relaunch decision loop for product runners.
+ * Hosts supply shell/platform actions via onInstall/onLaunch/onReady callbacks.
+ */
+export declare function orchestrateRuntimeUp<T extends RuntimeDecisionReport>(options: OrchestrateRuntimeUpOptions<T>): Promise<OrchestrateRuntimeUpResult<T>>;
+//# sourceMappingURL=orchestrate-up.d.ts.map

package/dist/runtime/orchestrate-up.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate-up.d.ts","sourceRoot":"","sources":["../../src/runtime/orchestrate-up.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE3F,MAAM,WAAW,2BAA2B,CAC1C,CAAC,SAAS,qBAAqB,GAAG,qBAAqB;IAEvD,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,SAAS,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;CACvC;AAED,MAAM,WAAW,0BAA0B,CACzC,CAAC,SAAS,qBAAqB,GAAG,qBAAqB;IAEvD,MAAM,EAAE,CAAC,CAAC;IACV,YAAY,EAAE,wBAAwB,CAAC;CACxC;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,SAAS,qBAAqB,EACxE,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CA4BxC"}

package/dist/runtime/orchestrate-up.js

@@ -0,0 +1,35 @@
+/**
+ * Generic install → relaunch decision loop for product runners.
+ * Hosts supply shell/platform actions via onInstall/onLaunch/onReady callbacks.
+ */
+export async function orchestrateRuntimeUp(options) {
+    const installFlag = options.installAttempted ?? { value: false };
+    const report = await options.decide();
+    switch (report.decision) {
+        case 'install': {
+            if (installFlag.value) {
+                throw new Error(`install did not resolve runtime (${report.reasonCode})`);
+            }
+            installFlag.value = true;
+            await options.onInstall(report);
+            return orchestrateRuntimeUp({ ...options, installAttempted: installFlag });
+        }
+        case 'launch':
+        case 'relaunch':
+        case 'build':
+            await options.onLaunch(report);
+            return { report, exitDecision: report.decision };
+        case 'ready':
+            await options.onReady(report);
+            return { report, exitDecision: 'ready' };
+        case 'blocked':
+            if (options.onBlocked)
+                await options.onBlocked(report);
+            return { report, exitDecision: 'blocked' };
+        default:
+            if (options.onBlocked)
+                await options.onBlocked(report);
+            return { report, exitDecision: report.decision };
+    }
+}
+//# sourceMappingURL=orchestrate-up.js.map

package/dist/runtime/orchestrate-up.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate-up.js","sourceRoot":"","sources":["../../src/runtime/orchestrate-up.ts"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAuC;IAEvC,MAAM,WAAW,GAAG,OAAO,CAAC,gBAAgB,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACjE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;IAEtC,QAAQ,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,oCAAoC,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC;YAC5E,CAAC;YACD,WAAW,CAAC,KAAK,GAAG,IAAI,CAAC;YACzB,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAChC,OAAO,oBAAoB,CAAC,EAAE,GAAG,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,CAAC,CAAC;QAC7E,CAAC;QACD,KAAK,QAAQ,CAAC;QACd,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO;YACV,MAAM,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC/B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;QACnD,KAAK,OAAO;YACV,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC9B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;QAC3C,KAAK,SAAS;YACZ,IAAI,OAAO,CAAC,SAAS;gBAAE,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACvD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;QAC7C;YACE,IAAI,OAAO,CAAC,SAAS;gBAAE,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACvD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IACrD,CAAC;AACH,CAAC"}

package/dist/runtime/react-native-bridge.d.ts

@@ -0,0 +1,17 @@
+import type { UiActionTransport } from '../adapters/ui.js';
+import type { ActionExecutionContext } from '../core/types.js';
+export type ReactNativeBridgeCommandName = 'navigate' | 'press' | 'keyPress' | 'setInput' | 'scroll' | 'waitFor' | 'screenshot' | 'status' | 'lifecycle' | 'hud' | 'trace' | 'observeUi';
+export interface ReactNativeBridgeCommand {
+    command: ReactNativeBridgeCommandName;
+    nodeId: string;
+    payload: Record<string, unknown>;
+}
+export interface ReactNativeBridge {
+    send(command: ReactNativeBridgeCommand, context: ActionExecutionContext): Promise<unknown>;
+}
+export interface CreateReactNativeBridgeUiTransportOptions {
+    bridge: ReactNativeBridge;
+}
+export declare function createReactNativeBridgeUiTransport(options: CreateReactNativeBridgeUiTransportOptions): UiActionTransport;
+export declare const createReactNativeCdpBridgeUiTransport: typeof createReactNativeBridgeUiTransport;
+//# sourceMappingURL=react-native-bridge.d.ts.map

package/dist/runtime/react-native-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-native-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/react-native-bridge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAoB,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAA2B,MAAM,kBAAkB,CAAC;AAExF,MAAM,MAAM,4BAA4B,GACpC,UAAU,GACV,OAAO,GACP,UAAU,GACV,UAAU,GACV,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,KAAK,GACL,OAAO,GACP,WAAW,CAAC;AAEhB,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,4BAA4B,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,OAAO,EAAE,wBAAwB,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5F;AAED,MAAM,WAAW,yCAAyC;IACxD,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAgBD,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,yCAAyC,GACjD,iBAAiB,CAwBnB;AAED,eAAO,MAAM,qCAAqC,2CAAqC,CAAC"}

package/dist/runtime/react-native-bridge.js

@@ -0,0 +1,57 @@
+const RN_COMMANDS = {
+    'ui.navigate': 'navigate',
+    'ui.press': 'press',
+    'ui.key_press': 'keyPress',
+    'ui.set_input': 'setInput',
+    'ui.scroll': 'scroll',
+    'ui.wait_for': 'waitFor',
+    'ui.screenshot': 'screenshot',
+    'app.status': 'status',
+    'app.lifecycle': 'lifecycle',
+    'app.hud': 'hud',
+    'app.trace': 'trace',
+};
+export function createReactNativeBridgeUiTransport(options) {
+    return {
+        async execute(action, node, context) {
+            const { action: _action, ...payload } = node;
+            const command = RN_COMMANDS[action];
+            if (!command) {
+                throw new Error(`${action} is not supported by the React Native bridge. Next: use the native Agent Device adapter for ${action}.`);
+            }
+            return options.bridge.send({ command, nodeId: context.nodeId, payload }, context);
+        },
+        async observe(refs, node, context) {
+            const result = await options.bridge.send({
+                command: 'observeUi',
+                nodeId: context.nodeId,
+                payload: { refs, node },
+            }, context);
+            return normalizeBridgeObservationResult(result, refs);
+        },
+    };
+}
+export const createReactNativeCdpBridgeUiTransport = createReactNativeBridgeUiTransport;
+function normalizeBridgeObservationResult(result, refs) {
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        return {
+            warnings: refs.map((ref) => ({ ref, message: 'Bridge observeUi returned no object.' })),
+        };
+    }
+    const record = result;
+    if (record.ok === false) {
+        const message = typeof record.error === 'string' ? record.error : 'Bridge observeUi failed.';
+        return { warnings: refs.map((ref) => ({ ref, message })) };
+    }
+    const observations = record.observations;
+    const warnings = record.warnings;
+    return {
+        ...(observations && typeof observations === 'object' && !Array.isArray(observations)
+            ? { observations: observations }
+            : {}),
+        ...(Array.isArray(warnings)
+            ? { warnings: warnings }
+            : {}),
+    };
+}
+//# sourceMappingURL=react-native-bridge.js.map

package/dist/runtime/react-native-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-native-bridge.js","sourceRoot":"","sources":["../../src/runtime/react-native-bridge.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const RECIPE_RUNNER_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,qBAAqB,QAAsB,CAAC"}

package/dist/version.js

@@ -0,0 +1,8 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+if (typeof packageJson.version !== 'string' || !packageJson.version) {
+    throw new Error('@farmslot/recipe-runner package version is missing.');
+}
+export const RECIPE_RUNNER_VERSION = packageJson.version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAA0B,CAAC;AAExE,IAAI,OAAO,WAAW,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;IACpE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,163 @@
+{
+  "name": "@farmslot/recipe-runner",
+  "version": "0.23.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "farmslot-visual-review": "./bin/farmslot-visual-review.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js",
+      "default": "./dist/cli/index.js"
+    },
+    "./cli/support": {
+      "types": "./dist/cli/support.d.ts",
+      "import": "./dist/cli/support.js",
+      "default": "./dist/cli/support.js"
+    },
+    "./runner": {
+      "types": "./dist/core/runner.d.ts",
+      "import": "./dist/core/runner.js",
+      "default": "./dist/core/runner.js"
+    },
+    "./types": {
+      "types": "./dist/core/types.d.ts",
+      "import": "./dist/core/types.js",
+      "default": "./dist/core/types.js"
+    },
+    "./writers": {
+      "types": "./dist/node/writers.d.ts",
+      "import": "./dist/node/writers.js",
+      "default": "./dist/node/writers.js"
+    },
+    "./adapters/core": {
+      "types": "./dist/adapters/core.d.ts",
+      "import": "./dist/adapters/core.js",
+      "default": "./dist/adapters/core.js"
+    },
+    "./adapters/app-lifecycle": {
+      "types": "./dist/adapters/app-lifecycle.d.ts",
+      "import": "./dist/adapters/app-lifecycle.js",
+      "default": "./dist/adapters/app-lifecycle.js"
+    },
+    "./adapters/ui": {
+      "types": "./dist/adapters/ui.d.ts",
+      "import": "./dist/adapters/ui.js",
+      "default": "./dist/adapters/ui.js"
+    },
+    "./runtime/browser-extension": {
+      "types": "./dist/runtime/browser-extension.d.ts",
+      "import": "./dist/runtime/browser-extension.js",
+      "default": "./dist/runtime/browser-extension.js"
+    },
+    "./runtime/cdp": {
+      "types": "./dist/runtime/cdp.d.ts",
+      "import": "./dist/runtime/cdp.js",
+      "default": "./dist/runtime/cdp.js"
+    },
+    "./runtime/react-native-bridge": {
+      "types": "./dist/runtime/react-native-bridge.d.ts",
+      "import": "./dist/runtime/react-native-bridge.js",
+      "default": "./dist/runtime/react-native-bridge.js"
+    },
+    "./runtime/deps-readiness": {
+      "types": "./dist/runtime/deps-readiness.d.ts",
+      "import": "./dist/runtime/deps-readiness.js",
+      "default": "./dist/runtime/deps-readiness.js"
+    },
+    "./runtime/log-analysis": {
+      "types": "./dist/runtime/log-analysis.d.ts",
+      "import": "./dist/runtime/log-analysis.js",
+      "default": "./dist/runtime/log-analysis.js"
+    },
+    "./runtime/metro-probe": {
+      "types": "./dist/runtime/metro-probe.d.ts",
+      "import": "./dist/runtime/metro-probe.js",
+      "default": "./dist/runtime/metro-probe.js"
+    },
+    "./runtime/decision-types": {
+      "types": "./dist/runtime/decision-types.d.ts",
+      "import": "./dist/runtime/decision-types.js",
+      "default": "./dist/runtime/decision-types.js"
+    },
+    "./runtime/orchestrate-up": {
+      "types": "./dist/runtime/orchestrate-up.d.ts",
+      "import": "./dist/runtime/orchestrate-up.js",
+      "default": "./dist/runtime/orchestrate-up.js"
+    },
+    "./visual-review": {
+      "types": "./visual-review/index.d.mts",
+      "import": "./visual-review/index.mjs",
+      "default": "./visual-review/index.mjs"
+    },
+    "./runtime/operation": {
+      "types": "./dist/runtime/operation.d.ts",
+      "import": "./dist/runtime/operation.js",
+      "default": "./dist/runtime/operation.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "test": "node ../../scripts/quality/run-tsx-tests.mjs --cwd . --tsconfig tsconfig.json test src/core/observations.test.ts && node --test test/visual-review-tool.test.mjs",
+    "format": "prettier --write --ignore-path ../../.prettierignore .",
+    "format:check": "prettier --check --ignore-path ../../.prettierignore .",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" \"test/**/*.ts\" --fix",
+    "quality": "prettier --check --ignore-path ../../.prettierignore . && eslint \"src/**/*.ts\" \"test/**/*.ts\" && tsc --noEmit --project tsconfig.json && yarn build && yarn test",
+    "build": "yarn workspace @farmslot/protocol build && rm -rf dist && tsc --project tsconfig.build.json",
+    "prepack": "cd ../.. && node scripts/quality/check-farmslot-package-readiness.mjs --require-changelog --packages @farmslot/recipe-runner && yarn workspace @farmslot/recipe-runner build",
+    "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/recipe-runner"
+  },
+  "dependencies": {
+    "@farmslot/protocol": "0.34.0",
+    "commander": "^12.0.0",
+    "semver": "^7.7.3",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.12",
+    "eslint": "^10.3.0",
+    "prettier": "^3.8.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deeeed/farmslot.git",
+    "directory": "packages/recipe-runner"
+  },
+  "bugs": {
+    "url": "https://github.com/deeeed/farmslot/issues"
+  },
+  "license": "MIT",
+  "homepage": "https://farmslot.io/docs/architecture/recipe-runner",
+  "keywords": [
+    "farmslot",
+    "recipe-runner",
+    "validation",
+    "agentic-engineering"
+  ],
+  "files": [
+    "README.md",
+    "LICENSE",
+    "bin/**/*.mjs",
+    "visual-review/**/*.mjs",
+    "visual-review/**/*.d.mts",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/*.js.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/test/fixtures/scroll-to-visible/README.md

@@ -0,0 +1,39 @@
+# scroll-to-visible conformance
+
+Two layers exercise the `ui.scroll_to` contract.
+
+## Provider-neutral suite
+
+`test/scroll-to-visible.test.ts` runs recipes through `createRecipeRunner` and
+`createStandardUiAdapters` against a fake native-style provider: one scroll surface in
+window coordinates, one device lock, and a retained session:
+
+| Case                                         | Expectation                                                               |
+| -------------------------------------------- | ------------------------------------------------------------------------- |
+| Target already in the safe viewport          | `alreadyVisible: true`, no `scrollTo` call, settlement `skipped`          |
+| Far target                                   | one absolute `scrollTo`, `before`/`after` bounds, settled, `finalVisible` |
+| Flattened Text target + measurable anchor    | passes via `visibility_anchor_test_id`; target still asserted present     |
+| Anchor present, target missing               | `SCROLL_TARGET_MISSING`; the anchor never stands in for the target        |
+| Row under the HUD                            | `safeViewport` excludes the HUD; the row ends above it                    |
+| Layout that never stops changing             | `SCROLL_SETTLEMENT_TIMEOUT` with the last geometry                        |
+| Layout that shifts once, then settles        | passes with the settled bounds                                            |
+| Three nodes on one retained session          | same `sessionId`, one connection, no self-lock                            |
+| Provider that keeps its lock                 | next node fails `SCROLL_SESSION_CONFLICT`                                 |
+| Surface missing / box-less target, no anchor | `SCROLL_SURFACE_MISSING` / `SCROLL_TARGET_NOT_MEASURABLE`                 |
+| Content too short to reach the target        | `SCROLL_TARGET_NOT_VISIBLE`; `verify_visible: false` records it instead   |
+
+Every failure is `cause_class: harness` with `error_code` and the observed geometry in
+`error_details`. Absolute versus relative `ui.scroll` movement is covered in
+`test/recipe-runner.test.ts`.
+
+## Real browser page
+
+`page.html` is the same scenario set on a real DOM: a `scroll-surface` container, a far
+`history-proof` row, a `display: contents` `flat-text` span inside the measurable
+`flat-anchor` row, and a `jitter-target` below a block that grows on every animation
+frame when the URL has `?jitter=1`. Serve it from the Command Center Vite origin so the
+CDP runner can attach to it:
+
+```
+<ui_url>/@fs<repo>/packages/recipe-runner/test/fixtures/scroll-to-visible/page.html
+```