@bivy/bivy 0.20.7-staging.2 → 0.20.7-staging.3

package/dist/apps/scenarios.js

@@ -0,0 +1,307 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+/** Scenarios: named starting points for a live app, one JSON file each in the
+ * project. Opening one puts the preview in that state and Reset puts it back.
+ * A web page's scenario is per viewer: a page, steps taken in it, responses
+ * the gateway simulates. A desktop app's is the app's: it restarts with the
+ * scenario's arguments and environment (its API pointed at a simulating proxy)
+ * and the steps are clicks, keys and menu items in its window. Neither needs
+ * anything from the app's framework. See docs/apps.md#scenarios. */
+export const SCENARIO_DIR = path.join(".bivy", "scenarios");
+const MAX_FILES = 100;
+const MAX_BYTES = 64 * 1024;
+const MAX_STEPS = 50;
+const MAX_RULES = 20;
+const MAX_CHAIN = 5;
+const MAX_DELAY_MS = 30_000;
+const MAX_WAIT_MS = 10_000;
+const ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+const text = (value, label, max) => {
+    if (typeof value !== "string" || !value.trim() || value.length > max)
+        throw new Error(`${label} must be text of 1–${max} characters.`);
+    return value.trim();
+};
+const page = (value, label) => {
+    const at = text(value, label, 2048);
+    if (!at.startsWith("/") || at.startsWith("//"))
+        throw new Error(`${label} must be a path that starts with /.`);
+    return at;
+};
+/** Each step kind, as a row: the key that names it, how its value is read,
+ *  and which preview it belongs to when only one can take it (a CSS selector
+ *  means a page; pixels or a menu path mean a desktop window). Adding a kind of
+ *  step means adding a row here and a case in the runner that takes it. */
+const STEPS = [
+    { key: "click", read: (raw) => {
+            if (Array.isArray(raw.click)) {
+                if (raw.click.length !== 2 || !raw.click.every((n) => Number.isInteger(n) && n >= 0 && n < 65536))
+                    throw new Error("click in a desktop app takes [x, y]: whole pixels in its screenshot.");
+                return { step: { click: [raw.click[0], raw.click[1]] }, kind: "desktop" };
+            }
+            return { step: { click: text(raw.click, "click", 300) }, kind: "web" };
+        } },
+    { key: "fill", read: (raw) => {
+            if (typeof raw.with !== "string" || raw.with.length > 2000)
+                throw new Error("fill needs \"with\": the text to put in the field (up to 2,000 characters).");
+            return { step: { fill: text(raw.fill, "fill", 300), with: raw.with }, kind: "web" };
+        } },
+    { key: "type", read: (raw) => {
+            if (typeof raw.type !== "string" || !raw.type || raw.type.length > 2000)
+                throw new Error("type takes the text to type, up to 2,000 characters.");
+            return { step: { type: raw.type }, kind: "desktop" };
+        } },
+    { key: "press", read: (raw) => ({ step: { press: text(raw.press, "press", 40) } }) },
+    { key: "menu", read: (raw) => ({ step: { menu: text(raw.menu, "menu", 300) }, kind: "desktop" }) },
+    { key: "wait", read: (raw) => {
+            if (typeof raw.wait === "number") {
+                if (!Number.isFinite(raw.wait) || raw.wait < 0 || raw.wait > MAX_WAIT_MS)
+                    throw new Error(`wait takes a selector, or milliseconds up to ${MAX_WAIT_MS}.`);
+                return { step: { wait: Math.round(raw.wait) } };
+            }
+            return { step: { wait: text(raw.wait, "wait", 300) }, kind: "web" };
+        } },
+];
+/** Fields that only one kind of preview has. */
+const FIELD_KINDS = { open: "web", fresh: "web", args: "desktop", env: "desktop", api: "desktop" };
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+function readStep(raw, index) {
+    const step = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+    const kind = STEPS.find((row) => row.key in step);
+    if (!kind)
+        throw new Error(`Step ${index + 1} must be one of: ${STEPS.map((row) => row.key).join(", ")}.`);
+    try {
+        return kind.read(step);
+    }
+    catch (error) {
+        throw new Error(`Step ${index + 1}: ${error.message}`);
+    }
+}
+function readArgs(raw) {
+    if (!Array.isArray(raw) || raw.length > 30 || !raw.every((arg) => typeof arg === "string" && arg.length <= 1000))
+        throw new Error("args must be a list of up to 30 arguments.");
+    return [...raw];
+}
+function readEnv(raw) {
+    const entries = raw && typeof raw === "object" && !Array.isArray(raw) ? Object.entries(raw) : undefined;
+    if (!entries || entries.length > 30 || !entries.every(([name, value]) => ENV_NAME.test(name) && typeof value === "string" && value.length <= 4000))
+        throw new Error("env maps up to 30 variable names to text values.");
+    return Object.fromEntries(entries);
+}
+function readApi(raw) {
+    const api = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+    if (typeof api.env !== "string" || !ENV_NAME.test(api.env))
+        throw new Error("api.env is the environment variable the app reads its API address from, like API_URL.");
+    let target;
+    try {
+        target = new URL(String(api.target));
+    }
+    catch {
+        throw new Error("api.target is the API's real address, like http://127.0.0.1:4000.");
+    }
+    if (!["http:", "https:"].includes(target.protocol) || target.username || target.password || target.search || target.hash)
+        throw new Error("api.target must be an http(s) address without credentials, query or fragment.");
+    return { env: api.env, target: target.href.replace(/\/$/, "") };
+}
+/** "POST /api/payments*" or "/api/orders": an optional method, then a path where * matches anything. */
+function readRule(raw, index) {
+    const label = `Network rule ${index + 1}`;
+    const rule = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : undefined;
+    if (!rule)
+        throw new Error(`${label} must be an object.`);
+    const [first, second, ...extra] = text(rule.match, `${label} "match"`, 300).split(/\s+/);
+    const method = second ? first.toUpperCase() : undefined;
+    if (extra.length || (method && !METHODS.includes(method)))
+        throw new Error(`${label}: "match" is an optional method and a path, like "POST /api/payments*".`);
+    const result = { ...(method ? { method } : {}), path: page(second ?? first, `${label} path`) };
+    if (rule.status !== undefined) {
+        if (!Number.isInteger(rule.status) || rule.status < 200 || rule.status > 599)
+            throw new Error(`${label}: status must be an HTTP status from 200 to 599.`);
+        result.status = rule.status;
+    }
+    if (rule.json !== undefined)
+        result.json = rule.json;
+    if (rule.body !== undefined) {
+        if (typeof rule.body !== "string" || rule.body.length > 32_000)
+            throw new Error(`${label}: body must be text up to 32,000 characters.`);
+        result.body = rule.body;
+    }
+    if (result.json !== undefined && result.body !== undefined)
+        throw new Error(`${label}: use json or body, not both.`);
+    if (rule.delayMs !== undefined) {
+        if (typeof rule.delayMs !== "number" || !Number.isFinite(rule.delayMs) || rule.delayMs < 0 || rule.delayMs > MAX_DELAY_MS)
+            throw new Error(`${label}: delayMs must be 0–${MAX_DELAY_MS}.`);
+        result.delayMs = Math.round(rule.delayMs);
+    }
+    if (rule.offline !== undefined && rule.offline !== true)
+        throw new Error(`${label}: offline can only be true.`);
+    if (rule.offline) {
+        if (result.status !== undefined || result.json !== undefined || result.body !== undefined)
+            throw new Error(`${label}: an offline rule sends no response, so it has no status, json or body.`);
+        result.offline = true;
+    }
+    if (!result.offline && result.status === undefined && result.json === undefined && result.body === undefined && !result.delayMs)
+        throw new Error(`${label} does nothing: give it a status, json, body, delayMs or offline.`);
+    return result;
+}
+/** One scenario file's contents. Throws a message meant for whoever wrote it. */
+export function readScenario(id, raw, changedAt = 0) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("A scenario is a JSON object with at least a \"name\".");
+    const input = raw;
+    const known = new Set(["$schema", "name", "description", "view", "from", "steps", "network", ...Object.keys(FIELD_KINDS)]);
+    const unknown = Object.keys(input).filter((key) => !known.has(key));
+    if (unknown.length)
+        throw new Error(`Unknown field${unknown.length === 1 ? "" : "s"} ${unknown.map((key) => `"${key}"`).join(", ")}. A scenario has: ${[...known].filter((key) => key !== "$schema").join(", ")}.`);
+    if (input.steps !== undefined && (!Array.isArray(input.steps) || input.steps.length > MAX_STEPS))
+        throw new Error(`steps must be a list of up to ${MAX_STEPS} steps.`);
+    if (input.network !== undefined && (!Array.isArray(input.network) || input.network.length > MAX_RULES))
+        throw new Error(`network must be a list of up to ${MAX_RULES} rules.`);
+    if (input.fresh !== undefined && typeof input.fresh !== "boolean")
+        throw new Error("fresh must be true or false.");
+    const from = input.from === undefined ? undefined : text(input.from, "from", 64);
+    if (from !== undefined && !ID.test(from))
+        throw new Error("from names another scenario by its file name, without .json.");
+    if (from === id)
+        throw new Error("A scenario can't start from itself.");
+    const steps = (input.steps ?? []).map(readStep);
+    // What the fields and steps say it's for: a page, a desktop window, or either.
+    const says = [
+        ...Object.entries(FIELD_KINDS).filter(([key]) => input[key] !== undefined).map(([key, kind]) => ({ kind, what: `"${key}"` })),
+        ...steps.flatMap((step, index) => step.kind ? [{ kind: step.kind, what: `step ${index + 1}` }] : []),
+    ];
+    const kind = says[0]?.kind;
+    const other = says.find((item) => item.kind !== kind);
+    if (other)
+        throw new Error(`${says.find((item) => item.kind === "web").what} is for web pages and ${says.find((item) => item.kind === "desktop").what} for desktop apps: a scenario is for one or the other.`);
+    return {
+        id, name: text(input.name, "name", 80), changedAt, ...(kind ? { kind } : {}),
+        ...(input.description === undefined ? {} : { description: text(input.description, "description", 200) }),
+        ...(input.view === undefined ? {} : { view: text(input.view, "view", 100) }),
+        ...(from ? { from } : {}),
+        ...(input.open === undefined ? {} : { open: page(input.open, "open") }),
+        ...(input.fresh ? { fresh: true } : {}),
+        steps: steps.map((item) => item.step),
+        network: (input.network ?? []).map(readRule),
+        ...(input.args === undefined ? {} : { args: readArgs(input.args) }),
+        ...(input.env === undefined ? {} : { env: readEnv(input.env) }),
+        ...(input.api === undefined ? {} : { api: readApi(input.api) }),
+    };
+}
+/** Every scenario file in a workspace. Files are read fresh each time (there
+ * are few, and an agent may have just written one). A file that can't be read
+ * is a problem to report, never a reason to hide the others. */
+export function loadScenarios(workspace) {
+    const scenarios = [];
+    const problems = [];
+    const dir = path.join(workspace, SCENARIO_DIR);
+    let names;
+    try {
+        if (!fs.lstatSync(dir).isDirectory())
+            return { scenarios, problems };
+        names = fs.readdirSync(dir).filter((name) => name.endsWith(".json")).sort().slice(0, MAX_FILES);
+    }
+    catch {
+        return { scenarios, problems };
+    }
+    for (const name of names) {
+        const id = name.slice(0, -".json".length);
+        const file = path.join(SCENARIO_DIR, name);
+        try {
+            if (!ID.test(id))
+                throw new Error("Name the file with lowercase letters, digits and dashes, like checkout-api-down.json.");
+            const stat = fs.lstatSync(path.join(dir, name));
+            if (!stat.isFile())
+                throw new Error("Not a regular file.");
+            if (stat.size > MAX_BYTES)
+                throw new Error("Larger than 64 KiB.");
+            let raw;
+            try {
+                raw = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+            }
+            catch (error) {
+                throw new Error(`Not valid JSON: ${error.message}`);
+            }
+            scenarios.push(readScenario(id, raw, stat.mtimeMs));
+        }
+        catch (error) {
+            problems.push({ id, file, error: error.message });
+        }
+    }
+    return { scenarios, problems };
+}
+/** The scenarios that belong to one view: those naming it (or its app), or
+ *  naming none, that fit its kind of preview. */
+export function scenariosFor(list, app, view, kind) {
+    const names = [app.toLowerCase(), view.toLowerCase()];
+    return list.filter((scenario) => (!scenario.view || names.includes(scenario.view.toLowerCase())) && (!scenario.kind || scenario.kind === kind));
+}
+/** In words, for the pill: "POST /api/payments* → 503". */
+export function describeRule(rule) {
+    const outcome = rule.offline ? "offline" : rule.status ?? (rule.json !== undefined || rule.body !== undefined ? 200 : `+${rule.delayMs}ms`);
+    return `${rule.method ? `${rule.method} ` : ""}${rule.path} → ${outcome}`;
+}
+function simulated(rules) {
+    if (!rules.length)
+        return undefined;
+    return describeRule(rules[0]) + (rules.length > 1 ? ` (+${rules.length - 1} more)` : "");
+}
+/** Resolves a scenario through its `from` chain: the base's page and steps
+ * first, then each one built on it; network rules nearest first, so a scenario
+ * overrides what it builds on. */
+export function planScenario(list, id, kind = "web") {
+    const chain = [];
+    for (let at = id; at;) {
+        const scenario = list.find((item) => item.id === at);
+        if (!scenario)
+            throw new Error(at === id ? `No scenario called "${id}".` : `"${chain.at(-1).id}" starts from "${at}", which doesn't exist or can't be read.`);
+        if (chain.some((item) => item.id === at))
+            throw new Error(`"${id}" starts from itself through ${chain.map((item) => item.id).join(" → ")}.`);
+        chain.push(scenario);
+        if (chain.length > MAX_CHAIN)
+            throw new Error(`"${id}" builds on more than ${MAX_CHAIN} scenarios.`);
+        at = scenario.from;
+    }
+    const mismatch = chain.find((scenario) => scenario.kind && scenario.kind !== kind);
+    if (mismatch)
+        throw new Error(`"${mismatch.id}" is for ${mismatch.kind === "web" ? "web pages" : "desktop apps"}, and this is ${kind === "web" ? "a web page" : "a desktop app"}.`);
+    const order = [...chain].reverse();
+    const network = chain.flatMap((scenario) => scenario.network);
+    const api = chain.find((scenario) => scenario.api)?.api;
+    if (kind === "desktop" && network.length && !api)
+        throw new Error(`"${id}" simulates responses, but a desktop app calls its API directly: add "api": {"env": "API_URL", "target": "http://127.0.0.1:4000"} so Bivy can put a proxy in between.`);
+    return {
+        id, name: chain[0].name, kind, fresh: order.some((scenario) => scenario.fresh === true),
+        stages: order.map((scenario, index) => ({ ...(scenario.open ? { open: scenario.open } : index === 0 && kind === "web" ? { open: "/" } : {}), steps: scenario.steps })),
+        network, ...(simulated(network) ? { simulated: simulated(network) } : {}),
+        args: order.flatMap((scenario) => scenario.args ?? []), env: Object.assign({}, ...order.map((scenario) => scenario.env ?? {})), ...(api ? { api } : {}),
+    };
+}
+/** What a list or tile shows. `since`: the app's creation; files changed after it are new. */
+export function summarize(list, problems, since, kind = "web") {
+    const rows = list.map((scenario) => {
+        try {
+            const plan = planScenario(list, scenario.id, kind);
+            const open = [...plan.stages].reverse().find((stage) => stage.open)?.open;
+            return {
+                id: scenario.id, name: scenario.name, ...(scenario.description ? { description: scenario.description } : {}),
+                ...(open ? { open } : {}),
+                steps: plan.stages.reduce((sum, stage) => sum + stage.steps.length, 0),
+                ...(plan.simulated ? { simulated: plan.simulated } : {}), ...(plan.fresh ? { fresh: true } : {}),
+                ...(scenario.changedAt > since ? { isNew: true } : {}),
+            };
+        }
+        catch (error) {
+            return { id: scenario.id, name: scenario.name, steps: 0, error: error.message };
+        }
+    });
+    return [...rows, ...problems.map((problem) => ({ id: problem.id, name: problem.id, steps: 0, error: problem.error }))];
+}
+/** The rule a request meets, if any: the first whose method and path match. */
+export function matchRule(rules, method, url) {
+    const [pathname] = url.split("?");
+    return rules.find((rule) => (!rule.method || rule.method === (method ?? "GET").toUpperCase())
+        && new RegExp(`^${rule.path.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`).test(rule.path.includes("?") ? url : pathname));
+}

package/dist/apps/service.js

@@ -13,6 +13,11 @@ import { captureFrame, encodePng, sendInput } from "./rfb.js";
 import { inputEvents, readAction } from "./input.js";
 import { pressMenu, readMenuPath, readMenus } from "./menu.js";
 import { pngSize } from "./review.js";
+import { SCENARIO_DIR, loadScenarios, planScenario, scenariosFor, summarize } from "./scenarios.js";
+import { startScenarioProxy } from "./scenario-proxy.js";
+const scenarioKind = (entry) => entry.target.kind === "display" ? "desktop" : "web";
+/** A desktop step in words, for the message when one fails. */
+const stepWords = (step) => "click" in step ? `click ${Array.isArray(step.click) ? step.click.join(",") : step.click}` : "type" in step ? `type "${step.type.slice(0, 40)}"` : "press" in step ? `press ${step.press}` : "menu" in step ? `menu ${step.menu}` : "wait" in step ? `wait ${step.wait}` : "step";
 const NO_REVIEWS = { publish: (review) => review, expire: () => { } };
 const NO_PINS = { publish: (pin) => pin };
 /** A pin's region is in the page CSS pixels of the viewport it was marked in.
@@ -62,6 +67,8 @@ export class AppService {
     latest = new Map();
     /** Per view: the newest reviewer note a run-end card has already counted. */
     handedOver = new Map();
+    /** Per desktop app in a scenario with an API: the proxy in front of it and the variable pointing there. */
+    proxies = new Map();
     /** Screenshots in progress, so a card, Compare and a baseline share one browser run. */
     inflight = new Map();
     constructor(registry, gateway, terminals, options = {}) {
@@ -76,6 +83,7 @@ export class AppService {
         this.reviews = options.reviews ?? NO_REVIEWS;
         this.pinSink = options.pins ?? NO_PINS;
         this.settleMs = options.settleMs ?? COMPARE_SETTLE_MS;
+        registry.desktopScenario = (viewId, scenario) => this.desktopScenario(viewId, scenario);
     }
     /** A session's apps, or every app on this machine when no session is given. */
     list(sessionId) {
@@ -117,6 +125,11 @@ export class AppService {
             const server = this.servers.get(id);
             if (entry?.target.kind !== "display" || !server?.termId)
                 continue;
+            // In a scenario, the new code starts in it again, steps and all.
+            if (entry.scenario) {
+                void this.desktopScenario(id, entry.scenario.id).catch(() => { });
+                continue;
+            }
             this.terminals.close(server.termId);
             server.termId = undefined;
             void this.ensureServer(entry).catch(() => { });
@@ -225,7 +238,7 @@ export class AppService {
             const presented = current && run.reviews.get(entry.app.id) === current.id;
             if (!shouldReview({ trigger: "run", mode, muted: run.muted, revisionChanged: true, change }) && !(presented && after))
                 continue;
-            latest = this.review(entry, run, { trigger: presented ? current.trigger : "run", note: presented ? current.note : undefined, path: entry.lastPath ?? "/", shot: after, before });
+            latest = this.review(entry, run, { trigger: presented ? current.trigger : "run", note: presented ? current.note : undefined, try: presented ? current.try : undefined, path: entry.lastPath ?? "/", shot: after, before });
         }
         // Reviewer notes that arrived since the last hand-over ride on the view's
         // card for this run, or get a card of their own. A count only: the notes
@@ -264,6 +277,7 @@ export class AppService {
             throw new Error("Path must start with /.");
         const note = typeof input.note === "string" ? input.note.trim().slice(0, 500) : undefined;
         const entry = this.pickView(sessionId, input.target);
+        const tries = input.try?.length ? this.tryScenarios(entry, input.try) : undefined;
         const mode = this.registry.reviewMode(entry.app.id);
         const active = this.runs.get(sessionId);
         const run = active && !active.ended ? active : undefined;
@@ -279,9 +293,90 @@ export class AppService {
         const shot = enabled ? await this.shotOf(entry, path) : undefined;
         const baseline = run?.baseline.get(entry.view.id);
         const before = baseline && shot && !baseline.equals(shot) && path === (entry.lastPath ?? "/") ? baseline : undefined;
-        const review = this.review(entry, run, { trigger, note, path, shot, before, screenshotsOff: !enabled });
+        const review = this.review(entry, run, { trigger, note, path, shot, before, screenshotsOff: !enabled, ...(tries ? { try: tries } : {}) });
         return { review, message: enabled ? (shot ? "The user sees it in the chat." : "The user sees a card in the chat, but the screenshot failed.") : "The user sees a card in the chat. Screenshots are off on this machine, so it has no picture." };
     }
+    /** `bivy app scenarios`: a view's scenarios as the preview shows them, and
+     *  files that can't be opened, with what's wrong (picked like `present`). */
+    scenarios(sessionId, target) {
+        const entry = this.pickView(sessionId, target);
+        const { scenarios, problems } = loadScenarios(entry.workspace);
+        const kind = scenarioKind(entry);
+        return { app: entry.app.name, view: entry.view.name, dir: SCENARIO_DIR, scenarios: summarize(scenariosFor(scenarios, entry.app.name, entry.view.name, kind), problems, entry.app.createdAt, kind) };
+    }
+    /** Scenarios a review card offers to try, by ID, each one that can be opened. */
+    tryScenarios(entry, ids) {
+        const { scenarios, problems } = loadScenarios(entry.workspace);
+        const kind = scenarioKind(entry);
+        const known = summarize(scenariosFor(scenarios, entry.app.name, entry.view.name, kind), problems, entry.app.createdAt, kind);
+        const wanted = [...new Set(ids.map((id) => id.trim().toLowerCase().replace(/\.json$/, "")).filter(Boolean))].slice(0, 6);
+        return wanted.map((id) => {
+            const found = known.find((item) => item.id === id);
+            if (!found)
+                throw new Error(`No scenario "${id}" for ${entry.view.name}. ${known.length ? `Its scenarios: ${known.map((item) => item.id).join(", ")}.` : `Write one in ${SCENARIO_DIR}/${id}.json.`}`);
+            if (found.error)
+                throw new Error(`Scenario "${id}" can't be opened: ${found.error}`);
+            return { id: found.id, name: found.name };
+        });
+    }
+    /** Puts a desktop app in a scenario ("" for none). It is one program for
+     *  everyone watching, so the scenario is the app's: it restarts with the
+     *  scenario's arguments and environment, its API (if the scenario has one)
+     *  behind a proxy that applies the network rules, and then the steps run in
+     *  its window the way an agent's input does. A step that fails leaves the app
+     *  where it got to and says which step, rather than throwing. */
+    async desktopScenario(viewId, id) {
+        const entry = this.registry.getView(viewId);
+        if (entry?.target.kind !== "display")
+            throw new Error("Desktop scenarios are for desktop apps.");
+        const plan = id ? planScenario(scenariosFor(loadScenarios(entry.workspace).scenarios, entry.app.name, entry.view.name, "desktop"), id, "desktop") : null;
+        this.proxies.get(viewId)?.close();
+        this.proxies.delete(viewId);
+        if (plan?.api) {
+            const proxy = await startScenarioProxy(plan.api.target, plan.network);
+            this.proxies.set(viewId, { close: proxy.close, env: { [plan.api.env]: proxy.url } });
+        }
+        entry.scenario = plan ?? undefined;
+        const server = this.servers.get(viewId);
+        if (server?.termId) {
+            this.terminals.close(server.termId);
+            server.termId = undefined;
+        }
+        await this.windowShown(entry);
+        if (!plan)
+            return { plan: null };
+        const steps = plan.stages.flatMap((stage) => stage.steps);
+        for (const [index, step] of steps.entries()) {
+            try {
+                await this.desktopStep(entry, step);
+            }
+            catch (error) {
+                return { plan, error: `Step ${index + 1} (${stepWords(step)}): ${error.message}` };
+            }
+            await new Promise((r) => setTimeout(r, AFTER_INPUT_MS));
+        }
+        return { plan };
+    }
+    async desktopStep(entry, step) {
+        if ("wait" in step) {
+            if (typeof step.wait === "number")
+                await new Promise((r) => setTimeout(r, step.wait));
+            return;
+        }
+        if ("menu" in step) {
+            if (!entry.displayControl)
+                throw new Error("This machine's desktop apps don't expose their menus (macOS only). Use a key combo instead.");
+            await pressMenu(entry.displayControl, readMenuPath(step.menu));
+            return;
+        }
+        if (!entry.display)
+            throw new Error("The app isn't running. Check its Logs in the Apps sheet.");
+        const action = "click" in step && Array.isArray(step.click) ? { kind: "click", x: step.click[0], y: step.click[1] }
+            : "type" in step ? { kind: "type", text: step.type } : "press" in step ? { kind: "key", keys: step.press } : undefined;
+        if (!action)
+            throw new Error("That step is for web pages.");
+        await sendInput(entry.display, inputEvents(readAction(action)));
+    }
     /** No more cards for the rest of the session's current run. */
     mute(sessionId) {
         const run = this.runs.get(sessionId);
@@ -348,7 +443,8 @@ export class AppService {
      * returning to a view's stable address. */
     /** `scale`: the opening device's pixel density, used if this starts a display. */
     /** `page`: start on this page instead of the app's root (a review card's page). */
-    async open(sessionId, appId, viewId, returnTo, direct = false, scale, page) {
+    /** `scenario`: open it in that scenario (the shell enters it once the app has loaded). */
+    async open(sessionId, appId, viewId, returnTo, direct = false, scale, page, scenario) {
         const entry = this.registry.requireView(sessionId, appId, viewId);
         if (entry.target.kind === "display" && !entry.display)
             entry.displayScale = scale === 2 ? 2 : 1;
@@ -358,8 +454,12 @@ export class AppService {
             if (direct && !this.gateway.openDirect)
                 throw new Error("This machine can't open previews directly.");
             let url = direct ? this.gateway.openDirect(viewId) : this.gateway.open(viewId, returnTo);
-            if (page && page.startsWith("/") && !page.startsWith("//") && page.length <= 2048)
-                url += `~${encodeURIComponent(page).replace(/~/g, "%7E")}`;
+            const start = page && page.startsWith("/") && !page.startsWith("//") && page.length <= 2048 ? page : undefined;
+            const inScenario = !direct && scenario && /^[a-z0-9][a-z0-9-]{0,63}$/.test(scenario) ? scenario : undefined;
+            if (start || inScenario)
+                url += `~${start ? encodeURIComponent(start).replace(/~/g, "%7E") : ""}`;
+            if (inScenario)
+                url += `~${inScenario}`;
             // Don't wait for a managed server to boot: the preview shows it starting
             // and reloads itself once it answers.
             if (this.servers.get(viewId))
@@ -646,8 +746,10 @@ export class AppService {
         return this.displays.ensure(entry.view.id, entry.app.name, entry.displayScale).then((display) => {
             entry.display = display.socket;
             entry.displayControl = display.control;
-            const [command, ...args] = [...display.launch ?? [], target.command, ...target.args];
-            return { command: command, args, workspace: target.workspace, env: display.env, name: `${entry.app.name} · ${entry.view.name}` };
+            // A scenario adds its arguments and environment; the display's own variables always win.
+            const [command, ...args] = [...display.launch ?? [], target.command, ...target.args, ...entry.scenario?.args ?? []];
+            const env = { ...entry.scenario?.env, ...this.proxies.get(entry.view.id)?.env, ...display.env };
+            return { command: command, args, workspace: target.workspace, env, name: `${entry.app.name} · ${entry.view.name}` };
         });
     }
     /** Services start synchronously; a desktop app waits for its display. */
@@ -699,6 +801,8 @@ export class AppService {
     }
     stopServer(id) {
         this.displays.stop(id);
+        this.proxies.get(id)?.close();
+        this.proxies.delete(id);
         const entry = this.registry.getView(id);
         if (entry) {
             entry.display = undefined;

package/dist/apps/styles.css

@@ -3243,6 +3243,10 @@ p.setup-note .btn.link { min-height: 44px; margin-block: calc((1lh - 44px) / 2);
 .review-side .seg-btn { min-block-size: 44px; min-inline-size: 72px; }
 .review-banner { margin: 0 var(--space-3); }
 .review-note { margin: var(--space-3) var(--space-3) 0; padding-inline-start: var(--space-3); border-inline-start: 2px solid var(--line-strong); color: var(--ink); font-size: var(--text-sm); white-space: pre-wrap; }
+/* "Try it": scenarios the agent offered, each opening the live preview in that state. */
+.review-try { display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-1); margin: var(--space-3) var(--space-3) 0; }
+.review-try-label { margin-inline-end: var(--space-1); color: var(--muted); font-size: var(--text-sm); }
+.review-try .btn { min-block-size: var(--space-7); }
 .review-status { margin: var(--space-2) var(--space-3) 0; color: var(--muted); font-size: var(--text-sm); }
 .review-actions { display: flex; flex-wrap: wrap; gap: var(--space-1); padding: var(--space-3); }
 .review-actions .btn { min-block-size: var(--space-7); }

package/dist/apps/types.js

@@ -15,7 +15,8 @@ export function isAppReview(value) {
         && (review.trigger === "present" || review.trigger === "run" || review.trigger === "asked" || review.trigger === "notes") && typeof review.at === "number"
         && (review.shot === undefined || isShot(review.shot)) && (review.before === undefined || isShot(review.before))
         && (review.note === undefined || typeof review.note === "string")
-        && (review.notes === undefined || (Number.isInteger(review.notes) && review.notes >= 0));
+        && (review.notes === undefined || (Number.isInteger(review.notes) && review.notes >= 0))
+        && (review.try === undefined || (Array.isArray(review.try) && review.try.length <= 6 && review.try.every((item) => !!item && typeof item.id === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(item.id) && typeof item.name === "string" && item.name.length <= 80)));
 }
 export const APP_PIN_STATES = ["open", "changed", "gone", "done"];
 export const APP_PIN_BLOCK = "bivy_app_pin";

package/dist/controllers/app-commands.js

@@ -25,11 +25,12 @@ export function createAppCommands(service, workspaceFor, published = () => { },
             published(app);
             return { app };
         },
-        "apps.open": (msg) => service.open(String(msg.sessionId), String(msg.appId), String(msg.viewId), typeof msg.returnTo === "string" ? msg.returnTo : undefined, msg.direct === true, typeof msg.scale === "number" ? msg.scale : undefined, typeof msg.path === "string" ? msg.path : undefined),
+        "apps.open": (msg) => service.open(String(msg.sessionId), String(msg.appId), String(msg.viewId), typeof msg.returnTo === "string" ? msg.returnTo : undefined, msg.direct === true, typeof msg.scale === "number" ? msg.scale : undefined, typeof msg.path === "string" ? msg.path : undefined, typeof msg.scenario === "string" ? msg.scenario : undefined),
         "apps.shot": (msg) => service.shot(String(msg.sessionId), typeof msg.appId === "string" ? msg.appId : undefined, { widths: msg.widths, themes: msg.themes, path: typeof msg.path === "string" ? msg.path : undefined }),
         "apps.input": (msg) => service.act(String(msg.sessionId), typeof msg.target === "string" ? msg.target : undefined, msg.action),
         "apps.menu": (msg) => service.menu(String(msg.sessionId), typeof msg.target === "string" ? msg.target : undefined, msg.path),
-        "apps.present": (msg) => service.present(String(msg.sessionId), { target: typeof msg.target === "string" ? msg.target : undefined, path: typeof msg.path === "string" ? msg.path : undefined, note: typeof msg.note === "string" ? msg.note : undefined }),
+        "apps.present": (msg) => service.present(String(msg.sessionId), { target: typeof msg.target === "string" ? msg.target : undefined, path: typeof msg.path === "string" ? msg.path : undefined, note: typeof msg.note === "string" ? msg.note : undefined, try: Array.isArray(msg.try) ? msg.try.filter((id) => typeof id === "string") : undefined }),
+        "apps.scenarios": (msg) => service.scenarios(String(msg.sessionId), typeof msg.target === "string" ? msg.target : undefined),
         "apps.showMe": (msg) => service.present(String(msg.sessionId), { target: typeof msg.appId === "string" ? msg.appId : undefined, trigger: "asked" }),
         "apps.mute": (msg) => service.mute(String(msg.sessionId)),
         "apps.reviewMode": (msg) => service.setReviewMode(String(msg.sessionId), String(msg.appId), msg.mode),

package/dist/exec.js

@@ -174,7 +174,10 @@ async function main() {
             const model = created.model;
             if (args.model && model?.id) {
                 const qualified = !model.provider || model.id.startsWith(`${model.provider}/`) ? model.id : `${model.provider}/${model.id}`;
-                if (![model.id, qualified].some((id) => id === args.model || id.endsWith(`/${args.model}`))) {
+                // Compare model names: the same model can sit under another provider
+                // spelling in this agent (openai-codex/gpt-5.6-sol is OpenCode's openai/gpt-5.6-sol).
+                const name = (id) => id.slice(id.lastIndexOf("/") + 1);
+                if (![model.id, qualified].some((id) => id === args.model || name(id) === name(args.model))) {
                     err(`Model "${args.model}" is not available for this agent; using ${qualified}.\n`);
                 }
             }

package/dist/node-env.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Imported first by server.ts, so the node's environment is clean before any
+// module reads it or launches an agent (see runtime/inherited-session-env.ts).
+import { scrubInheritedSessionEnv } from "./runtime/inherited-session-env.js";
+scrubInheritedSessionEnv();

package/dist/protocol/client-command-routes.js

@@ -3,7 +3,7 @@
 /** Direct-mode adapters for operations whose canonical implementation is the
  * client command registry. Relay and HTTP now differ only in framing. */
 export const CLIENT_COMMAND_ROUTES = [
-    ...["list", "publish", "offers", "adopt", "open", "logs", "shot", "input", "menu", "present", "showMe", "mute", "reviewMode", "annotate", "clearNotes", "agentNotes", "notes", "share", "unshare", "revoke", "remove"].map((action) => ({ method: "post", path: `/api/apps/${action}`, kind: `apps.${action}` })),
+    ...["list", "publish", "offers", "adopt", "open", "logs", "shot", "input", "menu", "present", "scenarios", "showMe", "mute", "reviewMode", "annotate", "clearNotes", "agentNotes", "notes", "share", "unshare", "revoke", "remove"].map((action) => ({ method: "post", path: `/api/apps/${action}`, kind: `apps.${action}` })),
     { method: "post", path: "/api/artifacts/list", kind: "artifacts.list" },
     { method: "post", path: "/api/access/get", kind: "access.get" },
     { method: "post", path: "/api/tailnet/machines", kind: "tailnet.machines" },

package/dist/protocol/client-command-schemas.js

@@ -17,11 +17,12 @@ export const CLIENT_COMMAND_SCHEMAS = {
     "apps.publish": Type.Object({ ...request, ...session, manifest: Type.Unknown() }),
     "apps.offers": Type.Object({ ...request, ...optionalSession }),
     "apps.adopt": Type.Object({ ...request, ...session, port: Type.Integer({ minimum: 1024, maximum: 65535 }) }),
-    "apps.open": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String(), returnTo: Type.Optional(Type.String({ maxLength: 2048 })), direct: Type.Optional(Type.Boolean()), scale: Type.Optional(Type.Integer({ minimum: 1, maximum: 2 })), path: Type.Optional(Type.String({ maxLength: 2048 })) }),
+    "apps.open": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String(), returnTo: Type.Optional(Type.String({ maxLength: 2048 })), direct: Type.Optional(Type.Boolean()), scale: Type.Optional(Type.Integer({ minimum: 1, maximum: 2 })), path: Type.Optional(Type.String({ maxLength: 2048 })), scenario: Type.Optional(Type.String({ maxLength: 64 })) }),
     "apps.shot": Type.Object({ ...request, ...session, appId: Type.Optional(Type.String()), widths: Type.Optional(Type.Array(Type.Integer(), { maxItems: 4 })), themes: Type.Optional(Type.Array(Type.Union([Type.Literal("light"), Type.Literal("dark")]), { maxItems: 2 })), path: Type.Optional(Type.String({ maxLength: 2048 })) }),
     "apps.input": Type.Object({ ...request, ...session, target: Type.Optional(Type.String({ maxLength: 200 })), action: Type.Object({ kind: Type.String({ maxLength: 20 }) }) }),
     "apps.menu": Type.Object({ ...request, ...session, target: Type.Optional(Type.String({ maxLength: 200 })), path: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 200 }), { minItems: 1, maxItems: 8 })) }),
-    "apps.present": Type.Object({ ...request, ...session, target: Type.Optional(Type.String({ maxLength: 200 })), path: Type.Optional(Type.String({ maxLength: 2048 })), note: Type.Optional(Type.String({ maxLength: 2000 })) }),
+    "apps.present": Type.Object({ ...request, ...session, target: Type.Optional(Type.String({ maxLength: 200 })), path: Type.Optional(Type.String({ maxLength: 2048 })), note: Type.Optional(Type.String({ maxLength: 2000 })), try: Type.Optional(Type.Array(Type.String({ maxLength: 64 }), { maxItems: 6 })) }),
+    "apps.scenarios": Type.Object({ ...request, ...session, target: Type.Optional(Type.String({ maxLength: 200 })) }),
     "apps.showMe": Type.Object({ ...request, ...session, appId: Type.Optional(Type.String()) }),
     "apps.mute": Type.Object({ ...request, ...session }),
     "apps.reviewMode": Type.Object({ ...request, ...session, appId: Type.String(), mode: Type.Union([Type.Literal("ready"), Type.Literal("every"), Type.Literal("off")]) }),