@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/mcp/src/session-run.js

@@ -0,0 +1,417 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { setTimeout as delay } from "node:timers/promises";
+import { join, relative, resolve } from "node:path";
+import { DEVICE_VARIABLE } from "@parity/product-lab/domain/checks";
+import { matchesTags } from "@parity/product-lab/domain/features";
+import { CONTROL_TAGS, ScenarioInputError, taggedControls } from "@parity/product-lab/domain/runs";
+import { EnvironmentSession } from "./session-environment.js";
+import { ToolError, MAX_WAIT_MS, answered, clampWait, errorText, isFinished, noRunYet, toolError, waitFor } from "./session-shared.js";
+export class RunSession extends EnvironmentSession {
+    async runScenario(request, progress) {
+        if (request.row !== undefined && request.mode === undefined)
+            throw new ToolError("row picks a row of a mode; give mode too");
+        if (request.mode !== undefined && request.environment !== undefined)
+            throw new ToolError(`Mode ${request.mode} decides the environment; drop environment`);
+        const featureMode = request.feature !== undefined || request.tags !== undefined || request.name !== undefined || request.mode !== undefined;
+        if (featureMode && request.scenario)
+            throw new ToolError("Give either scenario (a registered scenario on the running environment) or feature/tags/name (a Cucumber run), not both");
+        if (!featureMode && !request.scenario)
+            throw new ToolError("Give scenario (see env_status scenarios) or feature/tags/name");
+        if (!featureMode && request.inProcess)
+            throw new ToolError("inProcess is for feature mode (feature/tags/name)");
+        const runtime = await this._runtimeFor(request.where);
+        if (featureMode)
+            return this._startFeatureRun(request, runtime);
+        return this._startScenario(request.scenario, request, false, progress, runtime);
+    }
+    async _runtimeFor(where) {
+        const window = this.runtime.attached;
+        if (where === "lab" && !window)
+            throw new ToolError('No lab window is open for this lab: lab_open opens it (it asks first), or run with where: "headless"');
+        if (where !== "headless" || !window)
+            return this.runtime;
+        if (!this.options.headlessLab)
+            throw new ToolError("A headless lab beside the open window needs this server started by product-lab (`product-lab mcp`); run in the lab instead");
+        try {
+            return await this.options.headlessLab.runtime();
+        }
+        catch (error) {
+            throw new ToolError(errorText(error));
+        }
+    }
+    _runtimeOf(runId) {
+        const run = runId ? this._runs.get(runId) : undefined;
+        return (run && (run.kind === "scenario" || run.kind === "feature") && run.runtime) || this.runtime;
+    }
+    async runAction(request, progress) {
+        const lab = await this.declarative();
+        const actions = lab.catalog.actions();
+        if (!actions.includes(request.action))
+            throw new ToolError(`Unknown action ${request.action}`, { actions });
+        return this._startScenario(request.action, request, true, progress, await this._runtimeFor(request.where));
+    }
+    async _startScenario(scenarioId, request, action, progress, runtime = this.runtime) {
+        const running = this._requireRunning(runtime);
+        if (request.environment && request.environment !== running.environment)
+            throw new ToolError(`The running environment is ${running.environment}, not ${request.environment}`);
+        const snapshot = runtime.snapshot();
+        const scenario = snapshot.scenarios.find((item) => item.id === scenarioId);
+        if (!scenario)
+            throw new ToolError(action
+                ? `Action ${scenarioId} is not available in ${running.environment} (its integration or requirements are unavailable)`
+                : `Unknown scenario ${scenarioId} in ${running.environment}`, { scenarios: snapshot.scenarios.map((item) => item.id) });
+        const identities = snapshot.actors.map((item) => ({ id: item.id, name: item.name, status: item.status }));
+        const bound = scenario.actors?.length ? this._bindingChoices(scenario.actors, request.actors ?? {}, snapshot.actors) : undefined;
+        if (!bound && request.actors && Object.keys(request.actors).length)
+            throw new ToolError(`Scenario ${scenarioId} declares no actors to bind; give actor instead`);
+        const actor = bound
+            ? undefined
+            : request.actor
+                ? snapshot.actors.find((item) => item.id === request.actor || item.name === request.actor)
+                : snapshot.actors.find((item) => !item.status || item.status === "running");
+        if (!bound && !actor)
+            throw new ToolError(request.actor ? `Unknown actor ${request.actor}` : "No running actor; identities_create adds one", { actors: identities });
+        let handle;
+        try {
+            const started = {
+                scenario: scenarioId,
+                ...(actor ? { actor: actor.id } : {}),
+                ...(bound ? { actors: bound, ...(request.binding ? { binding: request.binding } : {}) } : {}),
+                inputs: request.inputs ?? {},
+                checkpointMode: !!request.checkpointMode,
+            };
+            handle = runtime.startScenario ? await runtime.startScenario(started) : runtime.runScenario(started);
+        }
+        catch (error) {
+            if (error instanceof ScenarioInputError)
+                throw new ToolError(`Invalid inputs: ${errorText(error)}`, { schema: scenario.inputs });
+            throw error;
+        }
+        const run = {
+            id: handle.id,
+            kind: "scenario",
+            environmentId: running.environment,
+            scenarioId,
+            action,
+            actorId: actor?.id ?? "",
+            inputs: request.inputs ?? {},
+            handle,
+            directory: join(this.runsDirectory, "runs", handle.id),
+            startedAt: Date.now(),
+            ...(runtime !== this.runtime ? { runtime } : {}),
+        };
+        this._remember(run);
+        this.audit(action ? "run_action" : "run_scenario", { runId: run.id, environment: running.environment, scenario: scenarioId, ...(actor ? { actor: actor.id } : { actors: bound }) });
+        void handle.completion.then(() => {
+            run.finished = true;
+            this._persist(run);
+        });
+        await this._wait(run, request.waitMs ?? 0, progress);
+        return this.report(run.id);
+    }
+    _bindingChoices(actors, requested, identities) {
+        const choices = {};
+        for (const [name, value] of Object.entries(requested)) {
+            if (value === "new") {
+                choices[name] = "new";
+                continue;
+            }
+            const identity = identities.find((item) => item.id === value || item.name === value);
+            if (!identity)
+                throw new ToolError(`Unknown identity ${value} for ${name}`, { actors, identities: identities.map((item) => ({ id: item.id, name: item.name, status: item.status })) });
+            choices[name] = { existing: identity.id };
+        }
+        return choices;
+    }
+    async transactionLanded(request) {
+        this._requireRunning();
+        const waitMs = Math.min(request.waitMs ?? 0, MAX_WAIT_MS);
+        if (request.txHash !== undefined || request.blockHash !== undefined) {
+            const transaction = {
+                ...(request.txHash !== undefined ? { txHash: request.txHash } : {}),
+                ...(request.signer !== undefined ? { signer: request.signer } : {}),
+                ...(request.after !== undefined ? { after: request.after } : {}),
+                ...(request.nonce !== undefined ? { nonce: request.nonce } : {}),
+                ...(request.blockHash !== undefined ? { receipt: { blockHash: request.blockHash, index: request.index ?? -1 } } : {}),
+            };
+            try {
+                return await this.runtime.checkTransaction({ ...(request.chain !== undefined ? { chain: request.chain } : {}), transaction, waitMs });
+            }
+            catch (error) {
+                throw new ToolError(errorText(error));
+            }
+        }
+        const run = this._run(request.runId);
+        if (run.kind !== "scenario")
+            throw new ToolError(`Run ${run.id} is a ${run.kind} run; transaction_landed checks scenario and action runs of the running environment`);
+        try {
+            return await this.runtime.checkTransactions({ runId: run.id, ...(request.step !== undefined ? { step: request.step } : {}), waitMs });
+        }
+        catch (error) {
+            throw new ToolError(errorText(error));
+        }
+    }
+    _activeInProcessFeature(runId) {
+        const runtime = this._runtimeOf(runId);
+        const current = runtime.environmentState().state === "running" ? runtime.snapshot().featureRun : undefined;
+        if (!current || current.mode !== "in-process" || current.finishedAt !== undefined)
+            return undefined;
+        const run = this._runs.get(current.id);
+        if (!run || run.kind !== "feature")
+            return undefined;
+        if (runId && runId !== run.id)
+            throw new ToolError(`Run ${runId} is not the current run (${run.id}); step, pause and continue act on the current run only`);
+        return run;
+    }
+    async _nextCheckpoint(run, before, waitMs) {
+        const deadline = Date.now() + clampWait(waitMs);
+        const key = () => JSON.stringify(run.handle.record().checkpoint ?? null);
+        while (Date.now() < deadline && !this._finished(run) && (key() === before || key() === "null"))
+            await delay(100);
+    }
+    _currentScenarioRun(runId) {
+        const runtime = this._runtimeOf(runId);
+        this._requireRunning(runtime);
+        const job = runtime.snapshot().job;
+        if (!job)
+            throw new ToolError("No scenario run on the running environment");
+        if (runId && runId !== job.id)
+            throw new ToolError(`Run ${runId} is not the current run (${job.id}); step, pause and continue act on the current run only`);
+        const run = this._runs.get(job.id);
+        if (!run || run.kind !== "scenario")
+            throw new ToolError(`Run ${job.id} was not started by this server`);
+        return run;
+    }
+    async pause(runId) {
+        const feature = this._activeInProcessFeature(runId);
+        if (feature) {
+            if (feature.handle.record().checkpoint)
+                return this.runReport({ runId: feature.id });
+            await answered((feature.runtime ?? this.runtime).pause());
+            return { runId: feature.id, pauseRequested: true, note: "The in-process feature run pauses after its current step." };
+        }
+        const run = this._currentScenarioRun(runId);
+        await answered((run.runtime ?? this.runtime).pause());
+        return { runId: run.id, pauseRequested: true, note: "The run pauses after its current step completes (an in-flight transaction is not paused)." };
+    }
+    async continueRun(request, progress) {
+        const feature = this._activeInProcessFeature(request.runId);
+        if (feature) {
+            const before = JSON.stringify(feature.handle.record().checkpoint ?? null);
+            if (before === "null")
+                throw new ToolError(`Run ${feature.id} is not paused`);
+            await answered((feature.runtime ?? this.runtime).continue({ checkpointMode: false }));
+            await this._nextCheckpoint(feature, before, request.waitMs ?? 0);
+            return this.runReport({ runId: feature.id });
+        }
+        const run = this._currentScenarioRun(request.runId);
+        await answered((run.runtime ?? this.runtime).continue({ checkpointMode: false }));
+        await this._wait(run, request.waitMs ?? 0, progress);
+        return this.report(run.id);
+    }
+    async step(request, progress) {
+        const feature = this._activeInProcessFeature(request.runId);
+        if (feature) {
+            const before = JSON.stringify(feature.handle.record().checkpoint ?? null);
+            if (before === "null")
+                throw new ToolError(`Run ${feature.id} is not paused; step continues a paused run by exactly one step`);
+            await answered((feature.runtime ?? this.runtime).continue({ checkpointMode: true }));
+            await this._nextCheckpoint(feature, before, request.waitMs ?? MAX_WAIT_MS);
+            return this.runReport({ runId: feature.id });
+        }
+        const run = this._currentScenarioRun(request.runId);
+        const job = run.handle.execution;
+        if (job.status !== "paused")
+            throw new ToolError(`Run ${run.id} is ${job.status}; step continues a paused run by exactly one step`);
+        const done = job.steps.filter((item) => item.status === "complete").length;
+        await answered((run.runtime ?? this.runtime).continue({ checkpointMode: true }));
+        await waitFor(run.handle.settled(), request.waitMs ?? MAX_WAIT_MS);
+        const now = run.handle.execution;
+        progress?.(now.steps.filter((item) => item.status === "complete").length, now.steps.length, `step ${done}`);
+        return this.report(run.id);
+    }
+    async _modeRow(runtime, mode, rowId) {
+        let plan;
+        try {
+            plan = await runtime.planSuite({ suite: mode, mode: true, base: "main" });
+        }
+        catch (error) {
+            throw toolError(error);
+        }
+        if (plan.empty)
+            throw new ToolError(plan.empty);
+        const rows = rowId ? plan.rows.filter((row) => row.id === rowId) : plan.rows;
+        if (!rows.length)
+            throw new ToolError(`Mode ${mode} has no row ${rowId}`, { rows: plan.rows.map((row) => row.id) });
+        if (rows.length > 1)
+            throw new ToolError(`Mode ${mode} has ${rows.length} rows; give row (product-lab test --mode ${mode} runs them all)`, { rows: rows.map((row) => row.id) });
+        const row = rows[0];
+        if (row.skip)
+            throw new ToolError(`Mode ${mode} row ${row.id} is ${row.skip.status}: ${row.skip.reason}`);
+        if (Object.keys(row.candidates).length)
+            throw new ToolError(`Mode ${mode} row ${row.id} moves versions (${Object.entries(row.candidates).map(([id, selector]) => `${id}@${selector}`).join(", ")}); run it with product-lab test --mode ${mode} --row ${row.id}, which resolves them`);
+        return row;
+    }
+    async _startFeatureRun(request, runtime = this.runtime) {
+        await this.declarative();
+        const row = request.mode !== undefined ? await this._modeRow(runtime, request.mode, request.row) : undefined;
+        if (row) {
+            if ((request.inProcess || runtime.attached) && (row.host || row.device))
+                throw new ToolError(`Mode ${request.mode} row ${row.id} runs on ${[row.host && `host ${row.host}`, row.device && `device ${row.device}`].filter(Boolean).join(" and ")}, which a run in this lab's process cannot switch to; run with where: "headless"`);
+            if ((request.inProcess || runtime.attached) && this._requireRunning(runtime).environment !== row.environment)
+                throw new ToolError(`Mode ${request.mode} row ${row.id} runs on ${row.environment}, but ${this._requireRunning(runtime).environment} is running`);
+            request = { ...request, tags: request.tags ? `(${row.tags}) and (${request.tags})` : row.tags, ...(row.paths?.length && request.feature === undefined ? { feature: [...row.paths] } : {}) };
+        }
+        const modeEnv = row && (row.host || row.device) ? { ...(row.host ? { PRODUCT_LAB_HOST: row.host } : {}), ...(row.device ? { [DEVICE_VARIABLE]: row.device } : {}) } : undefined;
+        const requested = request.feature === undefined ? [] : Array.isArray(request.feature) ? request.feature : [request.feature];
+        if (request.inProcess || runtime.attached) {
+            this._requireRunning(runtime);
+            const run = await this._featureRun({
+                paths: requested,
+                ...(request.tags ? { tags: request.tags } : {}),
+                ...(request.name ? { name: request.name } : {}),
+                ...(request.rebuildFixtures ? { fixtures: "rebuild" } : {}),
+            }, undefined, { breakpoints: true, pauseAfterStep: !!request.checkpointMode }, runtime);
+            await this._wait(run, request.waitMs ?? 0);
+            return this.runReport({ runId: run.id });
+        }
+        const run = await this._featureRun({
+            paths: requested,
+            ...(request.tags ? { tags: request.tags } : {}),
+            ...(request.name ? { name: request.name } : {}),
+            ...(row ? { environment: row.environment } : request.environment ? { environment: request.environment } : {}),
+            ...(request.rebuildFixtures ? { fixtures: "rebuild" } : {}),
+            ...(modeEnv ? { env: modeEnv } : {}),
+        });
+        await this._wait(run, request.waitMs ?? 0);
+        return this.report(run.id);
+    }
+    async _featureRun(selection, control, inProcess, runtime = this.runtime) {
+        let handle;
+        try {
+            handle = await runtime.runFeatures({
+                ...selection,
+                ...(this.options.cucumberConfig && !inProcess ? { configuration: this.options.cucumberConfig } : {}),
+                ...(inProcess ? { inProcess, label: "mcp" } : {}),
+                runsDirectory: join(this.runsDirectory, "runs"),
+                ...(control ? { control: {} } : {}),
+            });
+        }
+        catch (error) {
+            throw toolError(error);
+        }
+        const record = handle.record();
+        const run = { id: handle.id, kind: "feature", handle, directory: record.directory, ...(control ? { control: { batch: control.batch } } : {}), ...(runtime !== this.runtime ? { runtime } : {}) };
+        this._remember(run);
+        this.audit("run_feature", { runId: run.id, ...record.selection, ...(control ? { control: control.batch } : {}) });
+        void handle.completion.then(() => this._persist(run));
+        return run;
+    }
+    async runNegativeControls(request) {
+        if (request.expectations !== undefined)
+            throw new ToolError(`expectations is gone: a control's tags say where and why it must fail (${CONTROL_TAGS.control}, ${CONTROL_TAGS.failsAtStep}N, ${CONTROL_TAGS.failsWith}<reason>) and judge it`);
+        await this.declarative();
+        const listing = await this.features(true);
+        const tags = request.tags ?? CONTROL_TAGS.control;
+        const features = listing.features;
+        const requested = request.feature === undefined ? undefined : (Array.isArray(request.feature) ? request.feature : [request.feature]).map((path) => relative(this.root, resolve(this.root, path)));
+        const selected = requested || request.tags
+            ? features.filter((feature) => (requested ? requested.includes(feature.path) : feature.scenarios.some((scenario) => matchesTags(tags, scenario.tags)))).map((feature) => ({ path: feature.path, runsWith: [] }))
+            : taggedControls(features);
+        if (!selected.length)
+            throw new ToolError(`No feature matches ${requested ? requested.join(", ") : tags}`, { features: features.map((feature) => ({ path: feature.path, tags: [...new Set(feature.scenarios.flatMap((scenario) => scenario.tags))] })) });
+        const id = `controls-${randomUUID().slice(0, 8)}`;
+        const batch = {
+            id,
+            kind: "control",
+            tags,
+            controls: selected.map((control) => ({ feature: control.path })),
+            startedAt: Date.now(),
+            directory: join(this.runsDirectory, "runs", id),
+        };
+        const rebuild = new Set(selected.filter((control) => control.runsWith.includes("rebuild-fixtures")).map((control) => control.path));
+        this._remember(batch);
+        const completions = [];
+        for (const control of batch.controls) {
+            const run = await this._featureRun({ paths: [control.feature], ...(rebuild.has(control.feature) ? { fixtures: "rebuild" } : {}) }, { batch: id });
+            control.runId = run.id;
+            completions.push(run.handle.completion);
+        }
+        void Promise.all(completions).then(() => {
+            batch.finishedAt = Date.now();
+            this._persist(batch);
+        });
+        await this._wait(batch, request.waitMs ?? 0);
+        return this.report(id);
+    }
+    async _wait(run, waitMs, progress) {
+        if (run.kind === "scenario") {
+            let last = -1;
+            const report = () => {
+                if (!progress)
+                    return;
+                const job = run.handle.execution;
+                const done = job.steps.filter((item) => item.status === "complete").length;
+                if (done === last)
+                    return;
+                last = done;
+                const current = job.steps.find((item) => item.status === "running");
+                progress(done, job.steps.length, current ? `running: ${current.title}` : job.status);
+            };
+            report();
+            const off = run.handle.onEvent(report);
+            try {
+                await waitFor(run.handle.settled(), waitMs);
+            }
+            finally {
+                off();
+            }
+            return;
+        }
+        const deadline = Date.now() + clampWait(waitMs);
+        const paused = () => run.kind === "feature" && run.handle.record().checkpoint !== undefined;
+        while (Date.now() < deadline && !this._finished(run) && !paused())
+            await delay(100);
+    }
+    _finished(run) {
+        if (run.kind === "scenario")
+            return isFinished(run.handle.execution);
+        if (run.kind === "feature")
+            return run.handle.record().finishedAt !== undefined;
+        if (run.kind === "host")
+            return run.finishedAt !== undefined;
+        return run.controls.every((control) => {
+            const child = control.runId ? this._runs.get(control.runId) : undefined;
+            return !child || (child.kind === "feature" && child.handle.record().finishedAt !== undefined);
+        });
+    }
+    _remember(run) {
+        this._runs.set(run.id, run);
+        this._runOrder.push(run.id);
+        if (this._runOrder.length > 200) {
+            const dropped = this._runOrder.shift();
+            this._runs.delete(dropped);
+        }
+    }
+    _persist(run) {
+        try {
+            mkdirSync(run.directory, { recursive: true, mode: 0o700 });
+            writeFileSync(join(run.directory, "report.json"), JSON.stringify(this.redactor.value(this.report(run.id)), null, 2) + "\n", { mode: 0o600 });
+        }
+        catch (error) {
+            this.log.append(`could not write the report of ${run.id}: ${errorText(error)}\n`);
+        }
+    }
+    _run(runId) {
+        const id = runId ?? this._runOrder[this._runOrder.length - 1];
+        if (!id)
+            throw noRunYet();
+        const run = this._runs.get(id);
+        if (!run)
+            throw new ToolError(`Unknown run ${id}`, { runs: this._runOrder.slice(-20) });
+        return run;
+    }
+}

package/entrypoints/mcp/src/session-shared.d.ts

@@ -0,0 +1,181 @@
+import type { Execution, FeatureRunHandle, LabRuntime, RunHandle, TransactionActivity, VerifiedHostReport } from "@parity/product-lab/ports";
+import type { ChainClientFactory, CodecSource } from "./chain.js";
+import type { LogBuffer } from "./logs.js";
+/** Longest a single tool call blocks (waitMs); keeps every call well inside client tool timeouts. */
+export declare const MAX_WAIT_MS = 45000;
+export interface LabSessionOptions {
+    /** The lab.config.ts the runtime loads (reported; runs, features and targets resolve against its directory). */
+    configPath: string;
+    /** Allow environments whose offer is not local (and non-loopback chain endpoints). Set by whoever configures the server, never by a tool call; the runtime is built with the same policy. */
+    allowPublic?: boolean;
+    /** Where runs, reports and the audit log are written. Default `<config dir>/.product-lab/mcp`. */
+    runsDirectory?: string;
+    /** Cucumber configuration for feature runs. Default: cucumber.{ts,mjs,js,cjs} next to lab.config.ts. */
+    cucumberConfig?: string;
+    /** Default module for host_verify (default export defineHostVerifications([...])). */
+    hostTargets?: string;
+    chainClientFactory?: ChainClientFactory;
+    /** Storage codecs per block (tests); default: decoded from the block's own metadata. */
+    chainCodecs?: CodecSource;
+    /** The server's own log (console capture on stdio). */
+    log?: LogBuffer;
+    /**
+     * B1: a lab of its own for headless runs while this lab's window is open (its worker ports, a clean chain), started
+     * on the first such run and stopped with the server; absent when the server was not started by product-lab.
+     */
+    headlessLab?: {
+        runtime(): Promise<LabRuntime>;
+        close(): Promise<void>;
+    };
+    /** B1: opens and closes this lab's window (lab_open, lab_close); absent when the server was not started by product-lab. */
+    labWindows?: LabWindowControl;
+}
+/** B1: what lab_open and lab_close need (composition's labWindowLauncher). */
+export interface LabWindowControl {
+    open(request?: {
+        headless?: boolean;
+        waitMs?: number;
+    }): Promise<{
+        state: "open";
+        window: {
+            window: string;
+            lab: string;
+            startedAt: string;
+        };
+        log: string;
+        openedHere: boolean;
+    } | {
+        state: "starting";
+        log: string;
+        elapsedMs: number;
+    }>;
+    close(): Promise<void>;
+}
+export interface ScenarioRun {
+    id: string;
+    kind: "scenario";
+    environmentId: string;
+    scenarioId: string;
+    action: boolean;
+    actorId: string;
+    inputs: Record<string, unknown>;
+    handle: RunHandle;
+    directory: string;
+    startedAt: number;
+    finished?: boolean;
+    /** B1: the lab it runs in when that is not this server's runtime (a headless lab beside the open window). */
+    runtime?: LabRuntime;
+}
+export interface FeatureRun {
+    id: string;
+    kind: "feature";
+    /** The runtime's run (RunFeatures): its record, logs and completion. */
+    handle: FeatureRunHandle;
+    directory: string;
+    /** Set when the run belongs to a negative-control batch. */
+    control?: {
+        batch: string;
+    };
+    /** B1: the lab it runs in when that is not this server's runtime (a headless lab beside the open window). */
+    runtime?: LabRuntime;
+}
+export interface ControlBatch {
+    id: string;
+    kind: "control";
+    tags: string;
+    /** Each control: a feature file or one scenario (`path:line`), judged by its tags. */
+    controls: {
+        feature: string;
+        runId?: string;
+    }[];
+    startedAt: number;
+    finishedAt?: number;
+    directory: string;
+}
+export interface HostRun {
+    id: string;
+    kind: "host";
+    host: string;
+    targets: string;
+    startedAt: number;
+    finishedAt?: number;
+    report?: VerifiedHostReport;
+    conforms?: boolean;
+    error?: string;
+    directory: string;
+    abort: AbortController;
+}
+export type Run = ScenarioRun | FeatureRun | ControlBatch | HostRun;
+export declare class ToolError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * B2: a run tool asked before this server ran anything. The server runs a lab of its own, apart from the lab window's
+ * (B1 will attach it): the window's runs are not here, but each one is kept as a recording.
+ */
+export declare function noRunYet(): ToolError;
+/**
+ * A call that returns nothing on a lab of its own (pause, continue, allowRootCalls) returns the window's answer when
+ * this server is attached to the lab window (B1): awaited, so a refusal there is this call's.
+ */
+export declare function answered(value: void | Promise<unknown>): Promise<void>;
+export declare const clampWait: (value: number | undefined) => number;
+export type ProgressSink = (progress: number, total: number, message: string) => void;
+/** Wait for `promise` at most `waitMs` (clamped to MAX_WAIT_MS); undefined when the wait ran out. The timer never outlives the wait. */
+export declare function waitFor<T>(promise: Promise<T>, waitMs: number): Promise<T | undefined>;
+export declare function isFinished(job: Execution): boolean;
+/**
+ * One run in a line per step. A run the setup principal owns (29 September 2026: a feature step whose calls include
+ * setup work) says `owner: "Setup"` instead of an actor, and each setup step ends in "(Setup)": setup work is credited
+ * to no identity.
+ */
+export declare function jobSummary(job: Execution): {
+    error?: string | undefined;
+    status: "failed" | "complete" | "running" | "cancelled" | "paused" | "cancelling";
+    steps: string[];
+    owner: string;
+    id: string;
+    scenario: string;
+} | {
+    error?: string | undefined;
+    status: "failed" | "complete" | "running" | "cancelled" | "paused" | "cancelling";
+    steps: string[];
+    actor: string;
+    id: string;
+    scenario: string;
+};
+export declare function transactionView(item: TransactionActivity): {
+    ms?: number | undefined;
+    detail?: string | undefined;
+    step?: number | undefined;
+    block?: import("@parity/product-lab").BlockReference | undefined;
+    hash?: string | undefined;
+    label: string;
+    chain: string;
+    status: import("@parity/product-lab").TransactionStatus;
+};
+/** Block numbers a step's evidence refers to (the domain's `Evidence.blocks()`). */
+export declare function evidenceBlocks(value: unknown): {
+    path: string;
+    block: number;
+}[];
+/** Objects in evidence that name an extrinsic by block hash and index (the domain's `Evidence.receipts()`). */
+export declare function extrinsicRefs(value: unknown): {
+    path: string;
+    block?: number;
+    blockHash: string;
+    index: number;
+}[];
+/** UI artefacts a step reported (CollectEvidence's `artifacts`): screenshot, snapshot, video or trace paths. */
+export declare function uiArtifacts(paths: readonly string[]): {
+    paths: string[];
+    note: string | undefined;
+};
+/** The runtime refused a request before anything started (EnvironmentRequestError, from the domain). */
+export declare function isRefusal(error: unknown): boolean;
+/** A refusal the runtime explains with details (a feature run's known features, a host module's hosts) as a tool error. */
+export declare function toolError(error: unknown): ToolError;
+export declare function errorText(error: unknown): string;
+export declare function firstLines(text: string, count: number): string;
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;