firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/drivers/action-trace.js

@@ -0,0 +1,210 @@
+/**
+ * Sanitized browser action trace for the playwright.v1 driver (Plan20 FIR-493;
+ * root `firedrill.native-trace-segment.v1`, profile `sanitized-actions-v1`,
+ * agreed with root 2026-11-10).
+ *
+ * On only when the approved plan sets `trace: "sanitized-actions"`. The flow
+ * then gets its page through a recording view. Every call still runs on the
+ * real Playwright object with the same arguments and the same result, so the
+ * flow behaves as before. Each traced call records only which kind of
+ * operation it was, how it ended and when it ended. Nothing else is read or
+ * kept: never selectors, addresses, typed values, page text, arguments, return
+ * values or errors.
+ *
+ * Recorded: calls on the page and on the frames, locators, element handles,
+ * keyboard, mouse and touchscreen reached from it (including pages that its
+ * methods return), when the method is one of the operations below. Not
+ * recorded: other calls (hover, evaluate, drag, route and the like), objects
+ * handed to event handlers, and anything reached through the browser context.
+ * Assertions from a test library run inside Playwright, so `assert` is never
+ * recorded. This is not a Playwright trace, HAR or video.
+ *
+ * Each browser session is one capture (`capture_id`) whose events are numbered
+ * from 1 without gaps. A segment is cut when a step ends, after login or a
+ * reset, and at 256 events. The session's last segment carries the terminal
+ * coverage: `complete`, or `partial` with the reason.
+ */
+import { randomUUID } from 'node:crypto';
+import { TRACE_SEGMENT_MAX_EVENTS } from '../contracts.js';
+/** Operations recorded per browser session at most; past this the capture is partial (`limit_reached`). */
+export const TRACE_MAX_EVENTS_PER_SESSION = 4_096;
+/** Playwright methods and the operation each one is. `setChecked` is `check` or `uncheck` by its first argument. */
+const OPERATIONS = new Map(Object.entries({
+    goto: 'navigate', reload: 'navigate', goBack: 'navigate', goForward: 'navigate', setContent: 'navigate',
+    click: 'click', dblclick: 'click', tap: 'click',
+    fill: 'fill', type: 'fill', pressSequentially: 'fill', insertText: 'fill', clear: 'fill', setInputFiles: 'fill',
+    press: 'press',
+    selectOption: 'select', selectText: 'select',
+    check: 'check', uncheck: 'uncheck',
+    waitFor: 'wait', waitForSelector: 'wait', waitForLoadState: 'wait', waitForURL: 'wait', waitForNavigation: 'wait',
+    waitForTimeout: 'wait', waitForFunction: 'wait', waitForResponse: 'wait', waitForRequest: 'wait', waitForEvent: 'wait',
+    waitForElementState: 'wait',
+    textContent: 'observe', innerText: 'observe', innerHTML: 'observe', inputValue: 'observe', getAttribute: 'observe',
+    isVisible: 'observe', isHidden: 'observe', isEnabled: 'observe', isDisabled: 'observe', isChecked: 'observe',
+    isEditable: 'observe', count: 'observe', allTextContents: 'observe', allInnerTexts: 'observe', content: 'observe',
+    title: 'observe', boundingBox: 'observe', ariaSnapshot: 'observe',
+}));
+/** Members that mark a page, frame, locator, element handle or input device: objects the view records through. */
+const MARKERS = ['click', 'locator', 'press', 'tap'];
+function thenable(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        && typeof value.then === 'function';
+}
+export class ActionTrace {
+    captureId = randomUUID();
+    #clock;
+    /** Latest time read: the trace's times never go back, so its events and segments stay in order. */
+    #latest;
+    #defaultSink;
+    #sink;
+    /** Set while a step runs: a call that fails after it aborted ended `cancelled`, not `failed`. */
+    #stop = null;
+    #events = [];
+    #sequence = 0;
+    #segmentIndex = 0;
+    #segmentStart;
+    #partial = null;
+    #ended = false;
+    #views = new WeakMap();
+    #targets = new WeakMap();
+    /** `now` is the observation clock; `sink` receives segments cut outside a step. */
+    constructor(now, sink) {
+        this.#clock = now;
+        this.#latest = now();
+        this.#defaultSink = sink;
+        this.#sink = sink;
+        this.#segmentStart = this.#latest;
+    }
+    /** The flow's view of a Playwright object: the same behavior, recorded. */
+    view(target) {
+        return this.#wrap(target);
+    }
+    /** Segments cut from now on go to `sink` (the running step's records); `stop` is the step's abort signal. */
+    attach(sink, stop) {
+        this.#sink = sink;
+        this.#stop = stop;
+    }
+    detach() {
+        this.#sink = this.#defaultSink;
+        this.#stop = null;
+    }
+    /** Cut a segment of the operations recorded since the last one (nothing when there are none). */
+    cut() {
+        if (!this.#ended && this.#events.length)
+            this.#emit(null);
+    }
+    /**
+     * End the capture with its last segment and terminal coverage: complete, or
+     * partial for the first reason that applied (a limit, a lost segment, or `reason`).
+     */
+    end(reason = null) {
+        if (this.#ended)
+            return;
+        const partial = this.#partial ?? reason;
+        this.#ended = true;
+        this.#emit(partial ? { coverage: 'partial', reason: partial } : { coverage: 'complete', reason: null });
+    }
+    #record(operation, outcome) {
+        if (this.#ended)
+            return;
+        if (this.#sequence >= TRACE_MAX_EVENTS_PER_SESSION) {
+            this.#partial ??= 'limit_reached';
+            return;
+        }
+        this.#events.push({ sequence: ++this.#sequence, at_ms: this.#now(), operation, outcome });
+        if (this.#events.length >= TRACE_SEGMENT_MAX_EVENTS)
+            this.#emit(null);
+    }
+    #emit(terminal) {
+        const end = this.#now();
+        const segment = {
+            capture_id: this.captureId, segment_index: this.#segmentIndex++, start_at_ms: this.#segmentStart, end_at_ms: end,
+            events: this.#events, terminal,
+        };
+        this.#events = [];
+        this.#segmentStart = end;
+        let kept = false;
+        try {
+            kept = this.#sink(segment);
+        }
+        catch {
+            kept = false;
+        }
+        if (!kept)
+            this.#partial ??= 'capture_failed';
+    }
+    #now() {
+        const time = this.#clock();
+        if (typeof time === 'number' && Number.isFinite(time) && time > this.#latest)
+            this.#latest = time;
+        return this.#latest;
+    }
+    #failure() {
+        return this.#stop?.aborted ? 'cancelled' : 'failed';
+    }
+    #wrap(target) {
+        const known = this.#views.get(target);
+        if (known)
+            return known;
+        const methods = new Map();
+        const view = new Proxy(target, {
+            get: (object, property) => {
+                const value = Reflect.get(object, property, object);
+                const own = Object.getOwnPropertyDescriptor(object, property);
+                // Proxy invariant: a fixed data property reads as itself.
+                if (property === 'constructor' || (own && !own.configurable && own.writable === false))
+                    return value;
+                // Symbols and underscored members are Playwright's own plumbing: run on the real object, never recorded.
+                const internal = typeof property !== 'string' || property.startsWith('_');
+                if (typeof value === 'function') {
+                    const cached = methods.get(property);
+                    if (cached?.source === value)
+                        return cached.method;
+                    const method = internal ? value.bind(object) : this.#method(object, property, value);
+                    methods.set(property, { source: value, method });
+                    return method;
+                }
+                return internal ? value : this.#result(value);
+            },
+        });
+        this.#views.set(target, view);
+        this.#targets.set(view, target);
+        return view;
+    }
+    #method(object, name, method) {
+        return (...args) => {
+            // The real objects go to Playwright; only the method's name (and setChecked's flag) picks the operation.
+            const real = args.map((arg) => (arg !== null && typeof arg === 'object' ? this.#targets.get(arg) ?? arg : arg));
+            const operation = name === 'setChecked' ? (real[0] ? 'check' : 'uncheck') : OPERATIONS.get(name);
+            let result;
+            try {
+                result = Reflect.apply(method, object, real);
+            }
+            catch (error) {
+                if (operation)
+                    this.#record(operation, this.#failure());
+                throw error;
+            }
+            if (!thenable(result)) {
+                if (operation)
+                    this.#record(operation, 'completed');
+                return this.#result(result);
+            }
+            return Promise.resolve(result).then((value) => { if (operation)
+                this.#record(operation, 'completed'); return this.#result(value); }, (error) => { if (operation)
+                this.#record(operation, this.#failure()); throw error; });
+        };
+    }
+    /** A returned page, frame, locator, element handle or input device (or a list of them) comes back recorded too. */
+    #result(value) {
+        if (Array.isArray(value))
+            return value.some((item) => this.#recordable(item)) ? value.map((item) => this.#result(item)) : value;
+        return this.#recordable(value) ? this.#wrap(value) : value;
+    }
+    #recordable(value) {
+        if (value === null || typeof value !== 'object' || this.#targets.has(value))
+            return false;
+        const record = value;
+        return MARKERS.some((name) => typeof record[name] === 'function');
+    }
+}

package/dist/cli/src/native/drivers/function-wrapper.js

@@ -0,0 +1,152 @@
+/**
+ * function-wrapper.v1 driver (Plan20 spec 3.3).
+ *
+ * The coding agent writes a small wrapper file inside an approved root that
+ * imports the customer's function and speaks the jsonl-process.v1 protocol on
+ * stdin/stdout. The user approves it; its sha256 is pinned as the descriptor's
+ * `adapter_sha256` (ctx.adapterSha256).
+ *
+ * Launch: argv = [...runtime.args, <absolute wrapper path>] with
+ * `runtime.executable`, shell:false, cwd = the wrapper's root, env = ctx.env.
+ * Before EVERY launch (first launch and each bounded relaunch after the wrapper
+ * process exits) the wrapper file is re-read and re-hashed; a mismatch is
+ * `native_plan_changed` and nothing is run.
+ *
+ * Residual: the runtime re-reads the wrapper after the hash check (time-of-check
+ * to time-of-use). Copying it elsewhere would break its relative imports, so the
+ * file is run in place; native mode is trusted local execution, not a sandbox.
+ *
+ * A step in flight when the wrapper exits is never replayed (unknown outcome for
+ * non-idempotent steps); only the next step triggers a relaunch.
+ *
+ * Import handshake: after importing the customer's function, and before reading
+ * any request, the wrapper prints one stdout line containing WRAPPER_READY. Only
+ * then is it started; readiness additionally requires it still running.
+ */
+import { CliError } from '../../http.js';
+import { nativeError } from '../contracts.js';
+import { insideRoot } from '../roots.js';
+import { JsonLinesProcess, JsonLinesSession } from './jsonl-process.js';
+import { DRIVER_ERRORS, OwnDigest, driverBounds, driverPlanFor, emit, planError, readPinned, rootPath, unattested } from './types.js';
+/** The line a wrapper prints once the customer's function imported (bounded by the driver's setup time). */
+export const WRAPPER_READY = 'firedrill-wrapper-ready';
+export class FunctionWrapperDriver {
+    profile = 'function-wrapper.v1';
+    prepared = null;
+    process = null;
+    launching = null;
+    relaunches = 0;
+    disposed = false;
+    sessions = new Set();
+    launches = [];
+    /** SHA-256 of the wrapper module verified against the approved adapter digest before its runtime loaded it. */
+    importSha256 = null;
+    async describe() {
+        return { available: true, reason: null };
+    }
+    async prepare(ctx) {
+        const plan = driverPlanFor(ctx, 'function-wrapper.v1');
+        if (this.prepared)
+            throw planError('The function wrapper driver is already prepared; nothing else was started.');
+        if (!plan.runtime || typeof plan.runtime.executable !== 'string' || !plan.runtime.executable || !Array.isArray(plan.runtime.args))
+            throw planError('The approved wrapper runtime has no executable, so the wrapper was not started.');
+        const root = rootPath(ctx, plan.root_alias);
+        const wrapper = await insideRoot(root, plan.wrapper);
+        if (this.disposed)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The function wrapper driver was stopped, so the wrapper was not started.');
+        this.prepared = { ctx, root, wrapper, executable: plan.runtime.executable, args: [...plan.runtime.args] };
+        this.launching = this.launch();
+        try {
+            this.process = await this.launching;
+        }
+        finally {
+            this.launching = null;
+        }
+    }
+    /** Re-hash the wrapper, then start it. */
+    async launch() {
+        const prepared = this.prepared;
+        if (!prepared || this.disposed)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The function wrapper driver is not prepared, so the wrapper was not started.');
+        const { ctx } = prepared;
+        const pinned = await readPinned(prepared.wrapper, ctx.adapterSha256);
+        if (this.disposed || ctx.signal.aborted)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The function wrapper was stopped before launch, so it was not started.');
+        this.importSha256 = pinned.sha256;
+        emit(ctx, 'state.observed', { type: 'adapter.verified', profile: this.profile, adapter_sha256: new OwnDigest(pinned.sha256) });
+        // The wrapper prints WRAPPER_READY once the user's function imported: a wrapper that
+        // fails to import exits or stays silent and is never reported ready.
+        return await JsonLinesProcess.start(ctx, {
+            label: 'function wrapper',
+            executable: prepared.executable, args: [...prepared.args, prepared.wrapper], cwd: prepared.root, env: ctx.env,
+            readiness: { kind: 'stdout', pattern: WRAPPER_READY }, readinessTimeoutMs: driverBounds(ctx).flowSetupMs,
+            stopTimeoutMs: driverBounds(ctx).stopTimeoutMs,
+            onSpawned: (channel) => { this.launches.push(channel); },
+        });
+    }
+    /** Current wrapper process; relaunches (re-hashed, bounded) only between steps. */
+    async channel() {
+        if (this.process && !this.process.exited)
+            return this.process;
+        if (this.launching)
+            return await this.launching;
+        const prepared = this.prepared;
+        if (!prepared)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The function wrapper driver is not prepared, so the step was not sent.');
+        if (this.relaunches >= driverBounds(prepared.ctx).maxWrapperRelaunches)
+            throw nativeError('process_exited', 'The function wrapper exited too many times, so it was not started again and the step was not sent.');
+        this.relaunches += 1;
+        // Release the dead wrapper's pipes before replacing it (its group was swept on exit).
+        if (this.process) {
+            await this.process.stop().catch(() => undefined);
+            this.process = null;
+        }
+        emit(prepared.ctx, 'action.observed', { type: 'adapter.relaunch', profile: this.profile, relaunch: this.relaunches });
+        this.launching = this.launch();
+        try {
+            this.process = await this.launching;
+            return this.process;
+        }
+        finally {
+            this.launching = null;
+        }
+    }
+    async openSession(ctx, sessionKey) {
+        if (!this.prepared)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The function wrapper driver was not prepared, so no session was opened.');
+        if (!sessionKey)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The session key is empty, so no session was opened.');
+        const session = new JsonLinesSession(ctx, sessionKey, () => this.channel(), () => this.sessions.delete(session));
+        this.sessions.add(session);
+        emit(ctx, 'action.observed', { type: 'session.opened', profile: this.profile, session_key: sessionKey });
+        return session;
+    }
+    /** The digest of the wrapper module the runtime imported, verified against the approved adapter digest. */
+    async readinessProbe(_ctx) {
+        // Started (its import-ready line seen) and still running: hashing alone is not readiness.
+        if (!this.process || this.process.exited || !this.importSha256) {
+            throw unattested('The function wrapper is not running after importing the function, so its import cannot be attested. Nothing was claimed.');
+        }
+        return { kind: 'function_import', response_sha256: this.importSha256 };
+    }
+    async dispose() {
+        this.disposed = true;
+        for (const session of [...this.sessions])
+            await session.close();
+        const launching = this.launching;
+        if (launching)
+            await launching.then((proc) => proc.stop(), () => undefined);
+        const current = this.process;
+        this.process = null;
+        this.prepared = null;
+        await current?.stop();
+        // Includes failed readiness and earlier relaunches, not only the last
+        // successfully prepared process. Keep receipts after disposal.
+        for (const channel of this.launches)
+            await channel.stop();
+    }
+    ownedProcesses() {
+        // Driver-only identity, not an assertion that this is a declared service.
+        return this.launches.map((channel) => ({ alias: '@function-wrapper', launch_id: channel.launchId, exit: channel.exit }));
+    }
+}