@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/mcp/src/tools.js

@@ -0,0 +1,382 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { z } from "zod";
+import { DESCRIBE_SECTIONS, describeView } from "./describe-sections.js";
+import { bounded, DEFAULT_MAX_OUTPUT_CHARS } from "./output.js";
+import { errorText, MAX_WAIT_MS, ToolError } from "./session.js";
+export const TOOL_GROUPS = {
+    discover: ["lab_describe", "check", "env_show"],
+    environment: ["lab_open", "lab_close", "env_start", "env_status", "env_stop", "env_reset", "root_calls_allow", "identities_list", "identities_create"],
+    run: ["run_scenario", "run_action", "step", "pause", "continue", "run_negative_controls"],
+    debug: ["run_report", "step_evidence", "transaction_landed", "read_chain", "chain_console", "read_ui", "tail_logs", "explain_failure"],
+    host: ["host_verify"],
+    versions: ["versions", "versions_verify", "versions_update", "versions_pin"],
+    recordings: ["recordings", "recording_show"],
+};
+export const TOOL_NAMES = Object.values(TOOL_GROUPS).flat();
+const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const LOCAL_WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+const READ_REMOTE = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
+const LOCK_WRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
+const where = z
+    .enum(["lab", "headless"])
+    .optional()
+    .describe('lab: in the open lab window, shown live there (the default while one is open). headless: a lab of its own, on the lab\'s worker ports with a clean chain, nothing shown (the only way while no window is open). When the person\'s words do not say which ("run it in CI mode", "run all features"), ask them: "in the open lab or headless?"');
+const lockConfirm = z
+    .string()
+    .max(200)
+    .optional()
+    .describe('Exactly the versions tool\'s confirmations.updateLock ("update-lock <server session>"); without it the call is refused and nothing is written');
+const waitMs = z
+    .number()
+    .int()
+    .min(0)
+    .max(MAX_WAIT_MS)
+    .optional()
+    .describe(`Block up to this many milliseconds for progress (max ${MAX_WAIT_MS}); 0 returns at once. Poll run_report / env_status for longer work.`);
+const runId = z.string().optional().describe("Run id from run_scenario/run_action/run_negative_controls/host_verify; default: the latest run");
+const inputs = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional().describe("Inputs, validated against the scenario's or action's input schema (lab_describe / env_status list it)");
+export function registerTools(server, session, options = {}) {
+    const limit = options.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+    const result = (value) => ({ content: [{ type: "text", text: bounded(session.redactor.value(value), limit) }] });
+    const failure = (error) => ({
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: bounded(session.redactor.value({ error: errorText(error), ...(error instanceof ToolError ? error.details : {}) }), limit),
+            },
+        ],
+    });
+    const progressOf = (extra) => {
+        const token = extra._meta?.progressToken;
+        if (token === undefined)
+            return undefined;
+        let logged = false;
+        const failed = (error) => {
+            if (logged)
+                return;
+            logged = true;
+            session.log.append(`${new Date().toISOString()} warn progress notifications failed: ${session.redactor.text(errorText(error))}\n`);
+        };
+        return (progress, total, message) => { extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress, total, message } }).catch(failed); };
+    };
+    const tool = (name, config, run) => 
+    server.registerTool(name, { ...config, inputSchema: z.object(config.inputSchema).meta({ additionalProperties: false }) }, async (args, extra) => {
+        try {
+            await session.sync();
+            return result(await run(args, progressOf(extra)));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    tool("lab_describe", {
+        title: "Describe the lab",
+        description: "Read-only; starts nothing. The lab from lab.config.ts: environments (offer, topology, whether each can start and why not), apps with availability and reasons, integrations (services, actions with input schemas, assertions, step groups), registered sentences, feature files and their scenarios, secret names (never values), registered scenarios once an environment runs, and resolvedConfig: every value the lab runs with, where it came from (yours: written in lab.config.ts; default: the lab's rule, with why; detected: read from the product; advanced: given under advanced; machine: read from this machine's variables, the variable named in why and how to set it in change) and the line in lab.config.ts that changes it. A large lab does not fit in one result: then ask for one section (and match) at a time.",
+        inputSchema: {
+            environment: z.string().optional().describe("Environment whose availability and registry to show; default: the running one, else the lab's default"),
+            section: z.enum(DESCRIBE_SECTIONS).optional().describe("Only this part of the description, in full; default: everything (cut when it is larger than one result)"),
+            match: z.string().optional().describe("With section: only entries whose id, app, name, path, pattern, owner, key or label contains this text (case-insensitive)"),
+        },
+        annotations: READ,
+    }, async (args) => {
+        const view = describeView(await session.describe(args.environment), args, limit);
+        const notices = { ...(options.aiKit ? { aiKit: options.aiKit } : {}), ...(options.release ? { release: options.release } : {}) };
+        return Object.keys(notices).length && view && typeof view === "object" ? { ...notices, ...view } : view;
+    });
+    tool("check", {
+        title: "Check the lab configuration",
+        description: "Read-only; starts nothing. Like `product-lab check`: validates lab.config.ts and reports per environment what cannot start, topology losses, which apps are available and exactly which chain, service, capability or secret is missing, and unusable secrets (names only).",
+        inputSchema: { environment: z.string().optional().describe("Only this environment; default: all") },
+        annotations: READ,
+    }, (args) => session.check(args.environment));
+    tool("recordings", {
+        title: "List recorded runs",
+        description: "Read-only; starts nothing, runs nothing, needs no running environment. Like `product-lab recordings`: the lab's recorded runs, newest first (title, status, identities, steps, how many frames were captured, unavailable or failed), where they are kept, the recording mode and retention, and recordings that could not be read.",
+        inputSchema: {},
+        annotations: READ,
+    }, () => session.recordings());
+    tool("recording_show", {
+        title: "Show one recorded run",
+        description: "Read-only playback; never runs an action, submits a transaction or rewinds a chain, and works after the environment stopped. Like `product-lab recordings <id>`: the recorded steps across identities, per step and identity the frame before and after (with a note on its timing, or why it is unavailable or failed), chain observations the lab had made, and transactions. `images` is where the frame files are. `healthSummary` comes first: the steps (1-based) the machine held back, those the lab's own loop did, and those with any health finding; `health` gives each step's machine and chain numbers and findings, and with `step` only that step's.",
+        inputSchema: {
+            id: z.string().min(1).max(200).describe("A recording id from the recordings tool"),
+            step: z.number().int().min(1).optional().describe("Only this step's frames and health (1-based)"),
+        },
+        annotations: READ,
+    }, (args) => session.recording(args.id, args.step));
+    tool("versions", {
+        title: "Show the lab's versions",
+        description: "Read-only; never writes lab.lock.json. Like `product-lab versions`: each component's selector (defineLab({ versions: { policy } })), the locked version and source, and its status. With available, also what each selector (latest-release for a locked one) gives now; that fetches from GitHub or the lab's declared networks. confirmations.updateLock is the token versions_update and versions_pin require.",
+        inputSchema: { available: z.boolean().optional().describe("Also resolve what each selector gives now (fetches)") },
+        annotations: READ_REMOTE,
+    }, (args) => session.versions(!!args.available));
+    tool("versions_verify", {
+        title: "Verify lab.lock.json",
+        description: "Read-only. Like `product-lab versions verify`: fetches every locked component again and compares digests. ok: verified; failed: a mismatch or a locked selection with no entry; neither: something could not be fetched.",
+        inputSchema: {},
+        annotations: READ_REMOTE,
+    }, () => session.verifyVersions());
+    tool("versions_update", {
+        title: "Update lab.lock.json",
+        description: "Side effects: WRITES lab.lock.json (every later locked run uses it); fetches from GitHub or the lab's declared networks; recorded in the audit log. Like `product-lab versions update`: resolves the components (default all the lab selects) with their selector, or with `to` (never `locked`), and writes the lock only when it changes. Requires confirm: the versions tool's confirmations.updateLock for this server session; without it nothing is fetched or written. Returns the lock's location, digests before and after, whether it was written and the changes.",
+        inputSchema: {
+            components: z.array(z.string().max(100)).max(50).optional().describe("Component ids (for example host:truapi-cli); default: every component the lab selects"),
+            to: z.string().max(200).optional().describe("Resolve with this selector instead of the lab's (for example latest-release); never locked"),
+            confirm: lockConfirm,
+        },
+        annotations: LOCK_WRITE,
+    }, (args) => session.updateLock(args));
+    tool("versions_pin", {
+        title: "Pin a component in lab.lock.json",
+        description: "Side effects: WRITES lab.lock.json for one component; fetches that version from GitHub or the lab's declared networks; recorded in the audit log. Like `product-lab versions pin <component> <version>`: locks an explicit version, `release:owner/repo@tag` or a git ref (`git:<repo>@<ref>`). Requires confirm: the versions tool's confirmations.updateLock for this server session; without it nothing is fetched or written. Returns the lock's location, digests before and after, whether it was written and the change.",
+        inputSchema: {
+            component: z.string().max(100).describe("Component id, for example host:truapi-cli"),
+            version: z.string().max(200).describe("An explicit version, release:owner/repo@tag or git:<repo>@<ref>"),
+            confirm: lockConfirm,
+        },
+        annotations: LOCK_WRITE,
+    }, (args) => session.pinVersion(args));
+    tool("env_show", {
+        title: "Show an environment topology",
+        description: "Read-only; starts nothing. Like `product-lab env show <id>`: the resolved topology (chains, ports, runtimes, binaries, capabilities with reasons, customizations, issues), whether it can start, and the run manifest it would record.",
+        inputSchema: { environment: z.string().optional().describe("Environment id; default: the lab's default") },
+        annotations: READ,
+    }, (args) => session.envShow(args.environment));
+    tool("env_start", {
+        title: "Start an environment",
+        description: "Side effects: starts local processes (chain nodes, hosts, app servers) on the ports lab.config.ts declares and creates the lab's initial identities; recorded in the audit log. Only local environments unless the server was started with --allow-public. Returns within waitMs (default 45000) with state starting or running; poll env_status while starting. One environment at a time. Refused while the lab window of this lab (`bun run lab`) runs in another process: this server runs a lab of its own, and the refusal names that window. rpc (chain to URL) is this start's own RPC for chains the environment takes one for (env_status shows the RPC each chain uses and where it came from); a URL off this machine needs --allow-public and, for an endpoint RPC, rpcReason; a URL with credentials is refused (it belongs in lab.config.ts as a secret).",
+        inputSchema: {
+            environment: z.string().optional().describe("Environment id; default: the lab's default"),
+            option: z.string().optional().describe("One of the environment's options (lab_describe lists them, with the one a start picks now and why); remembered as the person's choice for its next start. Default: that pick"),
+            waitMs,
+            rpc: z.record(z.string(), z.string()).optional().describe("This start's RPC per chain, chain id to ws(s) or http(s) URL, for example { people: \"ws://127.0.0.1:9944\" }"),
+            rpcReason: z.string().optional().describe("Why the lab may use an RPC off this machine (needed for an endpoint RPC there, unless the environment is a public target)"),
+            keep: z.boolean().optional().describe("Keep the chain and people as the last kept start left them (true), or start clean (false, the default for agents). What each environment keeps: env_status's keepBetweenStarts"),
+        },
+        annotations: LOCAL_WRITE,
+    }, (args) => session.envStart(args));
+    tool("env_status", {
+        title: "Environment status",
+        description: "Read-only. State (stopped/starting/running/failed), endpoints, actors, registered scenarios with input schemas, workspace, the current run, best/finalized blocks per chain, notices, the run manifest path and the log files tail_logs can read.",
+        inputSchema: {},
+        annotations: READ,
+    }, () => session.envStatus());
+    tool("env_stop", {
+        title: "Stop the environment",
+        description: "Side effects: stops every process this server started for the environment (hosts, app servers, chain nodes) and ends its sessions. A persistent workspace keeps its data; an ephemeral topology's chain state is discarded. Refuses while a run is active unless cancelRun is true (submitted transactions are never rolled back). Only stops what this server started.",
+        inputSchema: { cancelRun: z.boolean().optional().describe("Stop even if a run is active") },
+        annotations: DESTRUCTIVE,
+    }, (args) => session.envStop(args));
+    tool("lab_open", {
+        title: "Open the lab window",
+        description: "Side effects: starts this lab's window as a person's `bun run lab` would (its default environment's chains and people, on the ports lab.config.ts declares), detached: it keeps running after this server stops, its log under .product-lab/lab-window/. Asks first: without confirm the call is refused with the token to confirm with. Returns once the window answers (state open, its address) or after waitMs (state starting: ask again). This server then drives the window's lab: runs you start show there live. A window already open is reported, nothing started.",
+        inputSchema: {
+            confirm: z.string().max(200).optional().describe("Exactly the token a first lab_open call returned (\"lab-open …\"); without it nothing starts"),
+            headless: z.boolean().optional().describe("The window without showing it (CI, a machine without a screen); default: shown, for the person beside the agent"),
+            waitMs,
+        },
+        annotations: LOCAL_WRITE,
+    }, (args) => session.labOpen(args));
+    tool("lab_close", {
+        title: "Close the lab window lab_open opened",
+        description: "DESTRUCTIVE: stops the lab window lab_open opened (its environment, people and browser, as Ctrl-C in its terminal would). A window a person started in a terminal is never stopped here: the call is refused and says so.",
+        inputSchema: {},
+        annotations: DESTRUCTIVE,
+    }, () => session.labClose());
+    tool("env_reset", {
+        title: "Reset the environment",
+        description: 'DESTRUCTIVE: rebuilds the owned environment\'s chain and backend state (a new generation) and recreates identities; earlier evidence no longer matches the chain. Requires confirm: the reset token of the current environment session (env_status reports it under confirmations.reset; the same rule as the panel). An environment that does not support reset (an attached one, for example) is refused by name and left unchanged.',
+        inputSchema: { confirm: z.string().describe("Exactly env_status's confirmations.reset (for example \"reset 1b4e28ba-…\")") },
+        annotations: DESTRUCTIVE,
+    }, (args) => session.envReset(args));
+    tool("root_calls_allow", {
+        title: "Allow root calls in this session",
+        description: "Side effects: none until an action makes one; then on chain, as Root. Allows this environment session's root calls: calls an action dispatches with the chain's Root origin through its own Sudo pallet, for an environment the lab declares them for (defineLab({ rootCalls })). Requires confirm: env_status's confirmations.rootCalls (it changes with every start and reset). Each call is still decided and checked: never on a mainnet, on a chain the lab started or a public testnet it knows by genesis, only calls on the lab's allow-list, only with a key that is the chain's Sudo.Key; each is recorded as evidence. An environment without rootCalls is refused by name.",
+        inputSchema: { confirm: z.string().describe("Exactly env_status's confirmations.rootCalls (for example \"root-calls 1b4e28ba-…\")") },
+        annotations: DESTRUCTIVE,
+    }, (args) => session.allowRootCalls(args));
+    tool("identities_list", {
+        title: "List identities",
+        description: "Read-only. The running environment's actors (test identities): id, name, username, product account, app URL, status and host (with the host's options on for it); kind preOnboarded marks an existing account. Also the hosts an identity can be created on, each with the options its adapter declares (name, label, why, type, value, perIdentity), the lab's pre-onboarded identities (by name and secret name) and, on a public network, its public target. Never keys or mnemonics.",
+        inputSchema: {},
+        annotations: READ,
+    }, () => session.identities());
+    tool("identities_create", {
+        title: "Create an identity",
+        description: "Side effects: creates a new actor in the running local environment (a fresh host identity, its host and app processes, and whatever funding or onboarding the lab's integration performs on the local chain). host and hostOptions choose where: one of the hosts identities_list lists, and its per-identity options by name (an option the host's adapter does not declare per identity is refused by name). With preOnboarded, opens that existing identity instead (declared in lab.config actors; its wallet from a secret): nothing is created or funded. A public environment creates no identity. Keys stay server-side.",
+        inputSchema: {
+            waitMs,
+            host: z.string().min(1).optional().describe("A host id identities_list lists (or its plain name, \"truAPI CLI\"); default: the lab's default host"),
+            hostOptions: z.record(z.string(), z.union([z.boolean(), z.string()])).optional().describe("The host's per-identity options, name to value, as identities_list's hosts declare them (each option's name; true or false, or one of its choices)"),
+            preOnboarded: z.string().min(1).optional().describe("The name of a pre-onboarded identity (identities_list lists them) to open instead of creating one"),
+        },
+        annotations: LOCAL_WRITE,
+    }, (args) => session.createIdentity(args));
+    tool("run_scenario", {
+        title: "Run a scenario",
+        description: "Side effects: runs real work against local environments (UI actions in the real app, signed transactions on the local chain). Two ways. scenario: a registered scenario (env_status lists them) on the running environment, through the same runner as the lab panel; supports step/pause/continue. feature/tags/name (or mode: one of the lab's modes, its tags, environment, host and device): the lab's own Cucumber configuration, or without one the bundled run (steps generated from registered sentences plus the lab's step() files), in a child process this server owns (its hooks start their own environment); with inProcess, in this server against the running environment, stopping at the lab's saved breakpoints (product-lab breakpoints, or the panel) and, with checkpointMode, after every step, so step/pause/continue work and run_report shows what the paused run waits with. Returns a run id at once (or after waitMs); poll run_report. where chooses the lab: the open lab window (default while one is open; a feature run there runs in its process, shown live) or headless.",
+        inputSchema: {
+            scenario: z.string().optional().describe("Registered scenario id on the running environment"),
+            actor: z.string().optional().describe("Actor id or name (scenario mode); default: the first running actor. Not for scenarios that declare actors"),
+            actors: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Scenarios that declare actors (env_status lists them): scenario actor → identity id or name to reuse, or "new" (default "new"). Two actors never share an identity; bindings are fixed for the run'),
+            binding: z.enum(["manual", "fresh"]).optional().describe("manual (default: the identities chosen in actors) or fresh (CI: every actor gets a new identity)"),
+            inputs,
+            checkpointMode: z.boolean().optional().describe("Pause after every step (scenario mode, or feature mode with inProcess)"),
+            inProcess: z
+                .boolean()
+                .optional()
+                .describe("Feature mode: run in this server against the running environment (env_start first) with the bundled steps, pausing before each saved breakpoint; run_report then shows the paused step, its values, the identities' balances and nonces, their apps and recent events"),
+            feature: z.union([z.string(), z.array(z.string())]).optional().describe("Feature file(s) relative to lab.config.ts (feature mode; lab_describe lists them)"),
+            tags: z.string().optional().describe("Cucumber tag expression, e.g. '@smoke and not @slow' (feature mode)"),
+            name: z.string().optional().describe("Scenario name regular expression (feature mode)"),
+            environment: z.string().optional().describe("Scenario mode: must be the running environment. Feature mode: exported as PRODUCT_LAB_ENVIRONMENT to the Cucumber hooks (default: the environment of the fixtures the selected scenarios name, when they name one)"),
+            mode: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Feature mode: one of the lab's modes (defineLab({ modes }), product-lab config lists them): its tags (narrowed by tags), environment, host and device. A mode with several rows needs row; one that moves versions runs with product-lab test --mode"),
+            row: z.string().min(1).optional().describe("With mode: the row to run, by id (an error lists them)"),
+            rebuildFixtures: z
+                .boolean()
+                .optional()
+                .describe("Feature mode: a scenario tagged @fixture:<name> starts from that saved fixture (restored before it); a missing or stale one refuses the scenario with its reasons unless this is true, then its setup runs and is saved first"),
+            where,
+            waitMs,
+        },
+        annotations: LOCAL_WRITE,
+    }, (args, progress) => session.runScenario(args, progress));
+    tool("run_action", {
+        title: "Run one action",
+        description: "Side effects: performs one registered integration action (one unit of real work: a UI action, a signed chain call, a root call on a local chain, or a backend call, as its `via` says) for one actor on the running environment. Inputs are validated against the action's schema before anything runs. Returns a run id; poll run_report.",
+        inputSchema: {
+            action: z.string().describe("Action id, integration.action (lab_describe lists them with input schemas)"),
+            actor: z.string().optional().describe("Actor id or name; default: the first running actor"),
+            inputs,
+            where,
+            waitMs,
+        },
+        annotations: LOCAL_WRITE,
+    }, (args, progress) => session.runAction(args, progress));
+    tool("step", {
+        title: "Step a paused run",
+        description: "Side effects: continues the current paused run (a scenario run, or an inProcess feature run) by exactly one step (which may submit transactions), then pauses again.",
+        inputSchema: { runId, waitMs },
+        annotations: LOCAL_WRITE,
+    }, (args, progress) => session.step(args, progress));
+    tool("pause", {
+        title: "Pause the current run",
+        description: "Side effects: asks the current run (a scenario run, or an inProcess feature run) to pause after its current step (an in-flight transaction is not paused); a feature run already paused reports what it waits with. No chain effect.",
+        inputSchema: { runId },
+        annotations: { ...LOCAL_WRITE, idempotentHint: true },
+    }, async (args) => session.pause(args.runId));
+    tool("continue", {
+        title: "Continue a paused run",
+        description: "Side effects: resumes the current paused run to its end (leaving checkpoint mode); an inProcess feature run stops again at its next breakpoint. Remaining steps may submit transactions.",
+        inputSchema: { runId, waitMs },
+        annotations: LOCAL_WRITE,
+    }, (args, progress) => session.continueRun(args, progress));
+    tool("run_negative_controls", {
+        title: "Run negative controls",
+        description: "Side effects: runs negative controls through the lab's Cucumber configuration (or the bundled run) in child processes this server owns, one after another; their hooks start local environments. By default every control the feature files tag: a feature tagged @negative-control runs whole, a scenario tagged alone runs alone (@runs-with:rebuild-fixtures rebuilds its fixtures). Each is judged by its tags: valid only if it fails at exactly one scenario step, its scenario's last (@fails-at-step-N: that one), from that step's own check and never for an infrastructure reason (@fails-with:<reason>: that reason only). Each control reports the failure it judged: step, position, reason id and message. Returns a batch id; poll run_report, then explain_failure.",
+        inputSchema: {
+            feature: z.union([z.string(), z.array(z.string())]).optional().describe("Control feature file(s), each run whole; default: every control the tags declare"),
+            tags: z.string().optional().describe("Tag expression selecting the feature files to run as controls, each whole (default: every tagged control)"),
+            expectations: z.unknown().optional().describe("Gone and refused: a control's tags judge it (@fails-at-step-N, @fails-with:<reason>)"),
+            waitMs,
+        },
+        annotations: LOCAL_WRITE,
+    }, (args) => session.runNegativeControls(args));
+    tool("run_report", {
+        title: "Run report",
+        description: "Read-only. Status, steps (status, duration, transaction count), error, recent messages and transactions of a run; for feature runs the Cucumber scenarios and steps; for control batches each control's verdict. waitMs long-polls until the run finishes or pauses.",
+        inputSchema: { runId, waitMs },
+        annotations: READ,
+    }, (args, progress) => session.runReport(args, progress));
+    tool("step_evidence", {
+        title: "Step evidence",
+        description: "Read-only. What one step recorded: its transactions (hash, block, status), extrinsic hashes for evidence that names { blockHash, extrinsicIndex } (read from the running environment), every block number in its evidence, the evidence it returned (finalized reads, UI observations), and screenshot/snapshot paths when the step produced any. health: the step's machine and chain health with its findings, from the samples so far while the run is recorded (live: true), else from its recording (recording names it; recording_show has every step's).",
+        inputSchema: { runId, step: z.number().int().min(0).describe("Step index from run_report") },
+        annotations: READ,
+    }, (args) => session.stepEvidence(args));
+    tool("transaction_landed", {
+        title: "Did this transaction land",
+        description: "Read-only (finalized chain reads). Whether a run's transactions landed, decided from finalized state: succeeded, failed (dispatch error), not-included (provably never: its mortality ended or its nonce was used) or unknown (may still land; never a guess). Checks every transaction the run recorded and every txHash or { blockHash, extrinsicIndex } its evidence names (runId, optional step), or one transaction you describe (txHash, with signer, after = a finalized block number before it was signed, and nonce to prove absence; or blockHash + index). A landed transaction that stored content (a Bulletin store) adds stores: its content id and whether the store returns it (present, missing or unread); so do a failed step's Statement Store statements and the writes it declared, asked of the store again. waitMs keeps asking while unknown.",
+        inputSchema: {
+            runId,
+            step: z.number().int().min(0).optional().describe("One step of the run (default: every step)"),
+            chain: z.string().optional().describe("Chain id (env_status endpoints); default: the environment's only chain"),
+            txHash: z.string().optional().describe("0x blake2-256 hash of the signed extrinsic (describes one transaction instead of a run)"),
+            signer: z.string().optional().describe("Its signer: SS58 address or 0x public key"),
+            after: z.number().int().min(0).optional().describe("A finalized block number known before it was signed (it cannot be at or before it)"),
+            nonce: z.number().int().min(0).optional().describe("The signer's nonce it used"),
+            blockHash: z.string().optional().describe("A receipt's block hash (with index)"),
+            index: z.number().int().min(0).optional().describe("The receipt's extrinsic index"),
+            waitMs,
+        },
+        annotations: READ,
+    }, (args) => session.transactionLanded(args));
+    tool("read_chain", {
+        title: "Read chain storage",
+        description: "Read-only. A storage query at a chosen block through the running environment's own endpoint for that chain (never an arbitrary URL; loopback only unless --allow-public): pallet + item (+ keys), all entries under partial keys, or a raw storage key. Default block: finalized.",
+        inputSchema: {
+            chain: z.string().default("people").describe("Chain id as the environment reports it (env_status endpoints)"),
+            pallet: z.string().optional().describe("e.g. System"),
+            item: z.string().optional().describe("e.g. Account, Events"),
+            keys: z.array(z.unknown()).optional().describe('Storage keys as JSON (SS58 addresses as strings; big integers as "123n")'),
+            at: z.union([z.string(), z.number()]).optional().describe('"finalized" (default), "best", a block number, or a 0x block hash'),
+            entries: z.boolean().optional().describe("Return entries under the (partial) keys"),
+            limit: z.number().int().min(1).max(200).optional().describe("Entries to return (default 20)"),
+            raw: z.string().optional().describe("Raw 0x storage key instead of pallet/item"),
+            where: z.string().optional().describe("Keep only array elements / entries whose JSON contains this text (e.g. Remarked)"),
+        },
+        annotations: READ,
+    }, (args) => session.readChain(args));
+    tool("chain_console", {
+        title: "Chain console",
+        description: "Read-only. The running environment's blocks and their events (backlog 24), read now from the block after the last one read up to each chain's best head (at most 50 new blocks per chain per call; older ones skipped and named): by default only events that mention a running identity's account, named; `all` for every extrinsic event. Each entry says whether it is final; a best block replaced at its height says `replaced` with the hash it replaced (its events never happened). Pass the returned `cursor` as `since` to get only what changed.",
+        inputSchema: {
+            chain: z.string().optional().describe("Only this chain (env_status endpoints name them)"),
+            since: z.number().int().min(0).optional().describe("A previous call's cursor: only entries new or changed after it"),
+            all: z.boolean().optional().describe("Every extrinsic event, not only the running identities' (default false)"),
+        },
+        annotations: READ,
+    }, (args) => session.chainConsole(args));
+    tool("read_ui", {
+        title: "Read the UI",
+        description: "Read-only. What the lab's registered observer reads for an actor's app now (sessions().observe): the independent UI/app observation the lab defines, bounded.",
+        inputSchema: { actor: z.string().optional().describe("Actor id or name; default: the first actor"), app: z.string().optional().describe("App id (must be available)") },
+        annotations: READ,
+    }, (args) => session.readUi(args));
+    tool("tail_logs", {
+        title: "Tail logs",
+        description: "Read-only. The last lines (max 500) of a log this server owns: `server` (in-process lab and provider output), `run:<id>` (a feature run's Cucumber output) or `file:<name>` (log files the running environment reports). Without source, lists the sources. Secret values are scrubbed.",
+        inputSchema: {
+            source: z.string().optional().describe("server | run:<runId> | file:<name>; omit to list sources"),
+            lines: z.number().int().min(1).max(500).optional().describe("Default 100"),
+            filter: z.string().optional().describe("Substring, or /regex/flags"),
+        },
+        annotations: READ,
+    }, (args) => session.tailLogs(args));
+    tool("explain_failure", {
+        title: "Explain a failure",
+        description: "Read-only. Structured JSON for the failed step of a run (default: the latest failed run, or the last environment start failure): step, layer (chain | ui | host | environment | test), verdict (failed, failed-as-intended, wrong-reason, control-passed, invalid-control), expected vs actual, blocks mentioned and recorded, the matched rule and its confidence, a hint, and the next tool calls to confirm it. For a control batch, one explanation per control.",
+        inputSchema: { runId },
+        annotations: READ,
+    }, (args) => session.explain(args));
+    tool("host_verify", {
+        title: "Verify a host",
+        description: "Side effects: runs the host conformance kit for one host: its targets module's setup starts what the host needs (local chains, a browser, throwaway identities) on the ports it declares, then closes it. Contracts for undeclared capabilities are reported unsupported, never passed; one whose positive control did not hold (the host never reached the chain) is inconclusive, never failed or passed. Returns a run id; poll run_report.",
+        inputSchema: {
+            host: z.string().describe("Host id defined in the targets module"),
+            targets: z.string().optional().describe("Module (relative to lab.config.ts) whose default export is defineHostVerifications([...]); default: the server's --host-targets"),
+            waitMs,
+        },
+        annotations: LOCAL_WRITE,
+    }, (args) => session.hostVerify(args));
+}