@parcha/agentrun-pi 0.1.0-beta.14 → 0.1.0-beta.15

package/dist/signin/resolve.js

@@ -0,0 +1,163 @@
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
+import { USAGE_LIMIT_CODE, UsageLimitError } from "./limit.js";
+import { CHATGPT_PROVIDER, chatgptModels, consoleInteraction, signIn } from "./signin.js";
+import { agentrunHome, fileCredentialStore } from "./store.js";
+/** What Sign in with ChatGPT covers: streaming Responses calls with `store: false`, without these. */
+export const CHATGPT_UNSUPPORTED = Object.freeze(["temperature", "max_output_tokens", "previous_response_id", "hosted tools", "audio input", "video input"]);
+export class ResolveError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ResolveError";
+    }
+}
+const meets = (model, need) => need === "images" ? model.input.includes("image") : need !== "video";
+function resolved(model, apiKey, getApiKey, source, extra = {}) {
+    const responsesOnly = source === "chatgpt" || extra.responsesOnly === true;
+    const result = { model, source, responsesOnly, unsupported: responsesOnly ? CHATGPT_UNSUPPORTED : [], ...extra };
+    Object.defineProperty(result, "apiKey", { value: apiKey, enumerable: false });
+    Object.defineProperty(result, "getApiKey", { value: getApiKey, enumerable: false });
+    Object.defineProperty(result, "toJSON", {
+        enumerable: false,
+        value: () => {
+            const { model: _model, ...rest } = result;
+            return { provider: model.provider, model: model.id, ...rest, ...(rest.eyes ? { eyes: rest.eyes.toJSON() } : {}) };
+        },
+    });
+    return result;
+}
+/** The env key of `provider` set in `env`, and the names it was looked up under. Anthropic takes an API key only. */
+async function providerKey(provider, env, signal) {
+    if (provider.id === "anthropic")
+        return { key: env.ANTHROPIC_API_KEY || undefined, names: ["ANTHROPIC_API_KEY"] };
+    const names = [];
+    const result = await provider.auth.apiKey?.resolve({
+        ctx: { env: async (name) => { names.push(name); return env[name] || undefined; }, fileExists: async () => false },
+        signal,
+    });
+    return { key: result?.auth.apiKey, names };
+}
+/** The account's models (GET /v1/models), those it lists as visible. */
+async function accountModels(baseUrl, apiKey, signal) {
+    const response = await fetch(`${baseUrl}/models`, { headers: { authorization: `Bearer ${apiKey}` }, signal });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        if (body.includes(USAGE_LIMIT_CODE))
+            throw new UsageLimitError();
+        throw new ResolveError("MODEL_LIST", `GET ${baseUrl}/models answered ${response.status}`);
+    }
+    const data = (await response.json()).data ?? [];
+    return data
+        .filter((entry) => typeof entry?.id === "string" && (entry.visibility === undefined || entry.visibility === "list"))
+        .map((entry) => ({ id: entry.id, created: typeof entry.created === "number" ? entry.created : 0 }));
+}
+/** The preferred id when it is listed and capable, else the newest listed model pi-ai knows that meets `needs`. */
+function choose(provider, listed, needs, preferred) {
+    const known = new Map(provider.getModels().map((model) => [model.id, model]));
+    const capable = listed
+        .flatMap((entry) => { const model = known.get(entry.id); return model && needs.every((need) => meets(model, need)) ? [{ model, created: entry.created }] : []; })
+        .sort((a, b) => b.created - a.created || a.model.id.localeCompare(b.model.id));
+    const pick = capable.find((entry) => entry.model.id === preferred) ?? capable[0];
+    if (!pick)
+        throw new ResolveError("NO_MODEL", `The account lists ${listed.length} models, and none is a ${provider.name} model pi-ai knows that takes ${needs.join(", ")}.`);
+    return pick.model;
+}
+async function flagModel(providerId, modelId, needs, preferred, env, signal, flag) {
+    const provider = builtinProviders().find((entry) => entry.id === providerId);
+    if (!provider)
+        throw new ResolveError("UNKNOWN_PROVIDER", `${flag} ${providerId}: pi-ai has no provider with that id`);
+    const { key, names } = await providerKey(provider, env, signal);
+    if (!key)
+        throw new ResolveError("MISSING_KEY", `${flag} ${providerId} needs ${names.join(" or ") || "its key"} set`);
+    // Video cannot be read from pi-ai's catalog: an explicit model is trusted to read it.
+    const checked = needs.filter((need) => need !== "video");
+    let model;
+    if (modelId) {
+        model = provider.getModels().find((entry) => entry.id === modelId);
+        if (!model)
+            throw new ResolveError("UNKNOWN_MODEL", `${provider.name} has no model ${modelId} in pi-ai's catalog`);
+        const gap = checked.filter((need) => !meets(model, need));
+        if (gap.length)
+            throw new ResolveError("NEEDS", `${provider.name} ${modelId} does not take ${gap.join(" or ")} input, which this run needs`);
+    }
+    else if (providerId === CHATGPT_PROVIDER && provider.baseUrl) {
+        model = choose(provider, await accountModels(provider.baseUrl, key, signal), checked, preferred);
+    }
+    else {
+        const fallback = preferred ? provider.getModels().find((entry) => entry.id === preferred) : undefined;
+        if (!fallback || !checked.every((need) => meets(fallback, need)))
+            throw new ResolveError("FLAGS", `${flag} ${providerId} needs a model id too`);
+        model = fallback;
+    }
+    return { model, key };
+}
+/**
+ * The model this run uses and the key to send, in the order above. The eyes model, when the spec has one, resolves the
+ * same way: an explicit eyes model with its provider's key, else the lead's model when it meets the eyes' needs, else
+ * a `ResolveError` ("EYES") naming the gap. The ChatGPT plan takes no video input.
+ */
+export async function resolveModel(spec, options = {}) {
+    const env = options.env ?? process.env;
+    const signal = options.signal ?? new AbortController().signal;
+    const needs = spec.models.lead.needs;
+    let lead;
+    if (options.provider || options.model) {
+        if (!options.provider)
+            throw new ResolveError("FLAGS", "--model needs --provider");
+        const { model, key } = await flagModel(options.provider, options.model, needs, spec.models.lead.default, env, signal, "--provider");
+        lead = resolved(model, key, async () => key, "flag");
+    }
+    else {
+        const home = agentrunHome(options.home, env);
+        const store = fileCredentialStore(home);
+        if ((await store.read(CHATGPT_PROVIDER, { signal }))?.type !== "oauth") {
+            // The run's signal reaches the sign-in through its interaction, so a cancel ends the login and frees its port.
+            const interaction = options.interaction ?? consoleInteraction();
+            // Its calls are forwarded, not spread: an interaction's notify and prompt may be methods of its class.
+            const cancelled = options.signal ? {
+                signal: interaction.signal ? AbortSignal.any([interaction.signal, options.signal]) : options.signal,
+                notify: (event) => interaction.notify(event),
+                prompt: (prompt) => interaction.prompt(prompt),
+            } : interaction;
+            try {
+                await signIn({ ...options, home, env, interaction: cancelled });
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason;
+                throw error;
+            }
+        }
+        const models = chatgptModels(store);
+        const getApiKey = async () => {
+            const key = (await models.getAuth(CHATGPT_PROVIDER, { signal }))?.auth.apiKey;
+            if (!key)
+                throw new ResolveError("SIGNED_OUT", "The ChatGPT sign-in is gone from auth.json; sign in again");
+            return key;
+        };
+        const key = await getApiKey();
+        const provider = models.getProvider(CHATGPT_PROVIDER);
+        const model = choose(provider, await accountModels(provider.baseUrl, key, signal), needs, spec.models.lead.default);
+        lead = resolved(model, key, getApiKey, "chatgpt", {
+            limit: `Model calls count toward your ChatGPT plan's usage limit (five hours on Plus, shared with your other apps); this run expects about ${spec.expectedCalls}.`,
+        });
+    }
+    const eyes = spec.models.eyes;
+    if (!eyes)
+        return lead;
+    if (options.eyes) {
+        const { model, key } = await flagModel(options.eyes.provider, options.eyes.model ?? eyes.default, eyes.needs, eyes.default, env, signal, "--eyes-model");
+        lead.eyes = resolved(model, key, async () => key, "flag");
+        return lead;
+    }
+    const gap = eyes.needs.filter((need) => !meets(lead.model, need));
+    if (gap.length) {
+        const reasons = gap.map((need) => need === "images" ? `the lead model ${lead.model.id} takes no image input`
+            : lead.source === "chatgpt" ? "the ChatGPT plan takes no video input"
+                : `pi-ai's catalog lists no video input for ${lead.model.provider} ${lead.model.id}`);
+        throw new ResolveError("EYES", `The run's eyes need ${gap.join(" and ")} input: ${reasons.join("; ")}. Name a model that reads it with --eyes-model and set its provider's key${gap.includes("video") ? ", or list images and let frames be extracted locally" : ""}.`);
+    }
+    lead.eyes = resolved(lead.model, lead.apiKey, lead.getApiKey, "lead", { responsesOnly: lead.responsesOnly });
+    return lead;
+}

package/dist/signin/signin.d.ts

@@ -0,0 +1,44 @@
+import type { AuthInteraction, MutableModels } from "@earendil-works/pi-ai";
+import { type FileCredentialStore } from "./store.js";
+export declare const AGENT_NAME = "AgentRun";
+/** pi-ai's provider id for OpenAI, whose OAuth method is Sign in with ChatGPT. */
+export declare const CHATGPT_PROVIDER = "openai";
+export type SignInOptions = {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    /** The app name OpenAI shows on the consent screen. Default "AgentRun". */
+    agentName?: string;
+    /** How the sign-in talks to the user. Default: the terminal (`consoleInteraction`). */
+    interaction?: AuthInteraction;
+};
+export type SignedIn = {
+    home: string;
+    provider: typeof CHATGPT_PROVIDER;
+    hostId: string;
+    expires: number;
+};
+export declare class SignInError extends Error {
+    readonly code: "PORT_IN_USE" | "APP_NAME_IGNORED";
+    constructor(code: "PORT_IN_USE" | "APP_NAME_IGNORED", message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A pi-ai collection with only OpenAI, whose credentials live in `store`. */
+export declare function chatgptModels(store: FileCredentialStore): MutableModels;
+/**
+ * Sign in once per install; the token refreshes on its own afterwards. The sign-in page must name this app: pi-ai
+ * before 1.1 ignores `agentName` and names pi, so a page that names anything else is never shown, and the sign-in fails
+ * with `SignInError` ("APP_NAME_IGNORED") before the browser opens.
+ */
+export declare function signIn(options?: SignInOptions): Promise<SignedIn>;
+export type ConsoleIo = {
+    input?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    output?: NodeJS.WritableStream;
+    /** Opens the sign-in page; default the platform's opener, skipped when AGENTRUN_NO_BROWSER is set. */
+    open?: (url: string) => void;
+};
+/** The terminal: prints the sign-in page's address and opens it, then waits for the browser's callback or, on a
+ *  terminal, a pasted redirect address. The page address carries no token. */
+export declare function consoleInteraction(io?: ConsoleIo): AuthInteraction;

package/dist/signin/signin.js

@@ -0,0 +1,126 @@
+// Sign in with ChatGPT through pi-ai's own flow (`openaiChatGPTOAuth.login`), unchanged. We pass the two options it
+// takes: `agentName`, this app's name rather than pi's, and `getDeviceId`, the host id kept in auth.json. The credential
+// it returns goes straight into the file store through pi-ai's `Models.login`; nothing here sees or prints a token.
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { createModels } from "@earendil-works/pi-ai/models";
+import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
+import { agentrunHome, fileCredentialStore } from "./store.js";
+export const AGENT_NAME = "AgentRun";
+/** pi-ai's provider id for OpenAI, whose OAuth method is Sign in with ChatGPT. */
+export const CHATGPT_PROVIDER = "openai";
+export class SignInError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "SignInError";
+    }
+}
+/** A pi-ai collection with only OpenAI, whose credentials live in `store`. */
+export function chatgptModels(store) {
+    const models = createModels({ credentials: store });
+    models.setProvider(openaiProvider());
+    return models;
+}
+/**
+ * Sign in once per install; the token refreshes on its own afterwards. The sign-in page must name this app: pi-ai
+ * before 1.1 ignores `agentName` and names pi, so a page that names anything else is never shown, and the sign-in fails
+ * with `SignInError` ("APP_NAME_IGNORED") before the browser opens.
+ */
+export async function signIn(options = {}) {
+    const home = agentrunHome(options.home, options.env);
+    const agentName = options.agentName ?? AGENT_NAME;
+    const store = fileCredentialStore(home);
+    const hostId = await store.hostId();
+    const inner = options.interaction ?? consoleInteraction();
+    const stop = new AbortController();
+    let named;
+    const interaction = {
+        signal: inner.signal ? AbortSignal.any([inner.signal, stop.signal]) : stop.signal,
+        notify(event) {
+            if (event.type === "auth_url" && (named = new URL(event.url).searchParams.get("agent_name_hint")) !== agentName)
+                return stop.abort();
+            inner.notify(event);
+        },
+        // pi-ai's login ends only when the browser's callback comes or this prompt rejects, and its callback server holds
+        // port 1455 until then: a cancel rejects the prompt even when the interaction's own prompt does not watch it.
+        prompt: (prompt) => {
+            if (stop.signal.aborted)
+                return Promise.reject(stop.signal.reason);
+            const cancel = prompt.signal;
+            if (!cancel)
+                return inner.prompt(prompt);
+            if (cancel.aborted)
+                return Promise.reject(cancel.reason);
+            return new Promise((resolve, reject) => {
+                const onAbort = () => reject(cancel.reason);
+                cancel.addEventListener("abort", onAbort, { once: true });
+                inner.prompt(prompt).then(resolve, reject).finally(() => cancel.removeEventListener("abort", onAbort));
+            });
+        },
+    };
+    // A variable, not a literal: pi-ai before 1.1 has no `agentName` in its `LoginOptions` type, and the page check above
+    // refuses those versions at run time.
+    const loginOptions = { agentName, getDeviceId: () => hostId };
+    let credential;
+    try {
+        credential = await chatgptModels(store).login(CHATGPT_PROVIDER, "oauth", interaction, loginOptions);
+    }
+    catch (error) {
+        if (stop.signal.aborted) {
+            throw new SignInError("APP_NAME_IGNORED", `The installed pi-ai names ${named ? `"${named}"` : "no app"} on the sign-in page instead of "${agentName}": it ignores the app name. Sign in with ChatGPT needs a pi-ai that passes it on (1.1.0 or later).`, { cause: error });
+        }
+        // pi-ai's callback port is fixed at 1455, and its message for a taken port names the likely holder.
+        if (error instanceof Error && /\bPort 1455 is in use\b/.test(error.message)) {
+            throw new SignInError("PORT_IN_USE", `${error.message}\nFinish or cancel the other login, then run again.`, { cause: error });
+        }
+        throw error;
+    }
+    return { home, provider: CHATGPT_PROVIDER, hostId, expires: credential.type === "oauth" ? credential.expires : 0 };
+}
+/** The terminal: prints the sign-in page's address and opens it, then waits for the browser's callback or, on a
+ *  terminal, a pasted redirect address. The page address carries no token. */
+export function consoleInteraction(io = {}) {
+    const input = io.input ?? process.stdin;
+    const output = io.output ?? process.stderr;
+    const open = io.open ?? (process.env.AGENTRUN_NO_BROWSER ? undefined : openBrowser);
+    return {
+        notify(event) {
+            if (event.type === "auth_url") {
+                output.write(`Continue with ChatGPT: sign in at\n  ${event.url}\n${event.instructions ? `${event.instructions}\n` : ""}`);
+                open?.(event.url);
+            }
+            else if (event.type === "progress" || event.type === "info") {
+                output.write(`${event.message}\n`);
+            }
+        },
+        prompt(prompt) {
+            return new Promise((done, fail) => {
+                const signal = prompt.signal;
+                if (signal?.aborted)
+                    return fail(signal.reason);
+                // Off a terminal only the browser's callback can finish the sign-in; the prompt waits to be cancelled.
+                const lines = input.isTTY ? createInterface({ input, output }) : undefined;
+                const onAbort = () => { lines?.close(); fail(signal?.reason); };
+                signal?.addEventListener("abort", onAbort, { once: true });
+                lines?.question(`${prompt.message} `, (answer) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    lines.close();
+                    done(answer);
+                });
+            });
+        },
+    };
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]]
+        : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch { /* no opener: the address is printed */ }
+}

package/dist/signin/spec.d.ts

@@ -0,0 +1,116 @@
+/** A run mode an item is needed for: `live` (paid calls) or `kill` (the kill on a real box). Without `for`, every run. */
+export type RunMode = "live" | "kill";
+export type Platform = "linux" | "darwin" | "win32";
+export type Key = {
+    env: string;
+    why: string;
+    where: string;
+    required: boolean;
+    for?: RunMode;
+};
+/** `min` is an x.y.z version, compared with the first x.y.z that `<cmd> --version` prints. */
+export type Program = {
+    cmd: string;
+    why: string;
+    required: boolean;
+    platforms?: Platform[];
+    min?: string;
+    for?: RunMode;
+};
+/** An npm package the demo loads only when used, installed with `--no-save` so it is never a dependency. */
+export type Package = {
+    name: string;
+    version: string;
+    why: string;
+    required: boolean;
+    for?: RunMode;
+};
+/** One of its members; an array member means all of its items (a key pair, or a key with its package). */
+export type Choice = {
+    oneOf: Array<Key | Program | Package | Array<Key | Program | Package>>;
+    why: string;
+    for?: RunMode;
+};
+export type ModelNeed = "text" | "tools" | "images";
+export type EyesNeed = "images" | "video";
+export type DemoSpec = {
+    name: string;
+    models: {
+        lead: {
+            needs: ModelNeed[];
+            default?: string;
+        };
+        /** A second model the run calls itself. */
+        eyes?: {
+            needs: EyesNeed[];
+            default?: string;
+        };
+        judge?: {
+            jev: true;
+        };
+    };
+    keys: Array<Key | Choice>;
+    programs: Array<Program | Choice>;
+    packages?: Array<Package | Choice>;
+    expectedCalls: number;
+    /** USD for one `--live` run. */
+    expectedCost: number;
+};
+/** Jev in a stranger's run: its own key, or Jev through OpenRouter. Nothing is substituted silently. */
+export declare const JEV_KEYS: Choice;
+export type CheckOptions = {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    /** The demo's directory, where its packages resolve from. Default: the current directory. */
+    dir?: string;
+    live?: boolean;
+    kill?: boolean;
+    /** An explicit eyes model (`--eyes-model`); its key is checked when the model is resolved. */
+    eyes?: {
+        provider: string;
+        model: string;
+    };
+};
+/** One requirement of this run and whether this machine meets it. `fix` says what to do, never a value. */
+export type ReportItem = {
+    kind: "key" | "program" | "package" | "choice" | "model";
+    name: string;
+    why: string;
+    required: boolean;
+    met: boolean;
+    fix?: string;
+};
+export type KeyReport = {
+    ok: boolean;
+    /** 2 when a required item is missing: nothing may start. */
+    exitCode: 0 | 2;
+    items: ReportItem[];
+    missing: ReportItem[];
+    expectedCalls: number;
+    expectedCost: number;
+    /** The report as printed: every requirement, what is missing and how to fix it. */
+    text: string;
+};
+/**
+ * What this demo needs for this run, and what is missing. Items whose `for` is not this run's mode are left out, choice
+ * members included; `kill` implies `live`. A choice is met by any member, an array member only when all of its items
+ * are. A relative `dir` is taken from the current directory. A required program
+ * outside its platforms is missing, before anything starts, and so is one below its `min` or whose version cannot be
+ * read. It sends no request and prompts for nothing, so a run that checks first sends nothing while a required item is
+ * missing (`exitCode` 2).
+ */
+export declare function checkKeys(spec: DemoSpec, options?: CheckOptions): KeyReport;
+export type SetupPromptReport = {
+    ok: boolean;
+    /** Spec names the prompt never mentions: key env names, program commands and package names, choice members included. */
+    missing: string[];
+    /** Credential env names the prompt mentions that the spec does not list. */
+    extra: string[];
+};
+/**
+ * Whether a demo's SETUP-PROMPT.md matches its spec. Every key env name, program command and package name in the spec,
+ * choice members included, appears in the prompt. "Nothing more" covers credential env names only: an UPPER_SNAKE name
+ * that reads as a credential and is not in the spec fails. A prompt's own command words (sudo, an install step) are
+ * never read as programs.
+ */
+export declare function checkSetupPrompt(spec: DemoSpec, text: string): SetupPromptReport;

package/dist/signin/spec.js

@@ -0,0 +1,181 @@
+// What a demo needs, and the key check that runs before anything else. Neither check sends a request or prompts. They
+// read only the environment they are given, the PATH in it and the demo's own node_modules, and the key check runs one
+// process: `<cmd> --version`, for a program with a minimum version. A key's value is never read past "is it set", and
+// never printed.
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, join, resolve } from "node:path";
+/** Jev in a stranger's run: its own key, or Jev through OpenRouter. Nothing is substituted silently. */
+export const JEV_KEYS = {
+    oneOf: [
+        { env: "TYPESAFE_API_KEY", why: "Jev's typed judgments", where: "https://console.typesafe.ai/keys", required: true },
+        { env: "OPENROUTER_API_KEY", why: "Jev through OpenRouter", where: "https://openrouter.ai/keys", required: true },
+    ],
+    why: "the judge is Jev",
+    for: "live",
+};
+const isChoice = (item) => "oneOf" in item;
+const isKey = (item) => "env" in item;
+const isProgram = (item) => "cmd" in item;
+const nameOf = (item) => isKey(item) ? item.env : isProgram(item) ? item.cmd : `${item.name}@${item.version}`;
+/** Every requirement of `spec`, the implied ones included: Jev's keys when the judge is Jev. */
+function requirements(spec) {
+    return [...spec.keys, ...(spec.models.judge?.jev ? [JEV_KEYS] : []), ...spec.programs, ...(spec.packages ?? [])];
+}
+/** The file `cmd` runs from `env`'s PATH, or undefined when it is not there. */
+function onPath(cmd, ctx) {
+    const exts = ctx.platform === "win32" ? ["", ...(ctx.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+    for (const dir of (ctx.env.PATH ?? ctx.env.Path ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const file = join(dir, cmd + ext);
+            try {
+                if (!statSync(file).isFile())
+                    continue;
+                accessSync(file, constants.X_OK);
+                return file;
+            }
+            catch { /* not this one */ }
+        }
+    }
+    return undefined;
+}
+const XYZ = /(\d+)\.(\d+)\.(\d+)/;
+const versionParts = (version) => XYZ.exec(version)?.slice(1, 4).map(Number);
+/** The first x.y.z that `file --version` prints, stdout before stderr; undefined when it prints none, fails or hangs. */
+function programVersion(file, ctx) {
+    const shell = ctx.platform === "win32" && /\.(cmd|bat)$/i.test(file);
+    const run = spawnSync(file, ["--version"], { env: ctx.env, encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"], shell });
+    return run.status === 0 ? XYZ.exec(`${run.stdout}\n${run.stderr}`)?.[0] : undefined;
+}
+/** Whether x.y.z `found` is at least `min`. */
+function atLeast(found, min) {
+    const [a, b] = [versionParts(found), versionParts(min)];
+    for (let i = 0; i < 3; i += 1)
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    return true;
+}
+/** The version of `name` that Node would load from `dir`, or undefined when it resolves nowhere. */
+function installedVersion(name, dir) {
+    for (const base of createRequire(join(dir, "noop.js")).resolve.paths(name) ?? []) {
+        const manifest = join(base, name, "package.json");
+        if (!existsSync(manifest))
+            continue;
+        try {
+            return String(JSON.parse(readFileSync(manifest, "utf8")).version);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/** Whether `item` is met here, and the fix when it is not. */
+function checkMember(item, ctx) {
+    if (isKey(item))
+        return ctx.env[item.env] ? { met: true } : { met: false, fix: `set ${item.env} (create it: ${item.where})` };
+    if (isProgram(item)) {
+        if (item.platforms && !item.platforms.includes(ctx.platform)) {
+            return { met: false, fix: `${item.cmd} runs on ${item.platforms.join(" or ")} only; this machine is ${ctx.platform}` };
+        }
+        const file = onPath(item.cmd, ctx);
+        if (!file)
+            return { met: false, fix: `install ${item.cmd}${item.min ? ` ${item.min} or later` : ""}; it is not on PATH` };
+        if (!item.min)
+            return { met: true };
+        if (!versionParts(item.min))
+            return { met: false, fix: `the spec's minimum for ${item.cmd} (${item.min}) is not an x.y.z version` };
+        const found = programVersion(file, ctx);
+        if (!found)
+            return { met: false, fix: `${item.cmd} --version printed no x.y.z version, so ${item.min} or later cannot be confirmed` };
+        return atLeast(found, item.min) ? { met: true } : { met: false, fix: `${item.cmd} is ${found}; this run needs ${item.min} or later` };
+    }
+    const found = installedVersion(item.name, ctx.dir);
+    if (found === item.version)
+        return { met: true };
+    const install = `npm install --no-save ${item.name}@${item.version}`;
+    return { met: false, fix: found === undefined ? install : `${install} (found ${found})` };
+}
+const applies = (item, options) => !item.for || (item.for === "live" ? options.live || options.kill : options.kill) === true;
+/**
+ * What this demo needs for this run, and what is missing. Items whose `for` is not this run's mode are left out, choice
+ * members included; `kill` implies `live`. A choice is met by any member, an array member only when all of its items
+ * are. A relative `dir` is taken from the current directory. A required program
+ * outside its platforms is missing, before anything starts, and so is one below its `min` or whose version cannot be
+ * read. It sends no request and prompts for nothing, so a run that checks first sends nothing while a required item is
+ * missing (`exitCode` 2).
+ */
+export function checkKeys(spec, options = {}) {
+    const ctx = { env: options.env ?? process.env, platform: options.platform ?? process.platform, dir: resolve(options.dir ?? ".") };
+    const items = [];
+    for (const item of requirements(spec)) {
+        if (!applies(item, options))
+            continue;
+        if (!isChoice(item)) {
+            const kind = isKey(item) ? "key" : isProgram(item) ? "program" : "package";
+            items.push({ kind, name: nameOf(item), why: item.why, required: item.required, ...checkMember(item, ctx) });
+            continue;
+        }
+        // A member's own `for` applies too: an item this mode does not need drops out of its member, and a member left with
+        // nothing drops out of the choice, which this mode then does not need at all.
+        const members = item.oneOf.map((member) => (Array.isArray(member) ? member : [member]).filter((one) => applies(one, options))).filter((all) => all.length);
+        if (!members.length)
+            continue;
+        const options_ = members.map((all) => {
+            const checked = all.map((one) => ({ one, ...checkMember(one, ctx) }));
+            return { name: all.map(nameOf).join(" + "), met: checked.every((one) => one.met), fixes: checked.filter((one) => !one.met).map((one) => one.fix) };
+        });
+        const met = options_.some((option) => option.met);
+        items.push({
+            kind: "choice", name: options_.map((option) => option.name).join(" or "), why: item.why, required: true, met,
+            ...(met ? {} : { fix: `one of: ${options_.map((option) => option.fixes.join(", ")).join("; or ")}` }),
+        });
+    }
+    const eyes = spec.models.eyes;
+    if (eyes && (options.live || options.kill) && eyes.needs.includes("video") && !options.eyes) {
+        items.push({
+            kind: "model", name: "eyes", why: "the run's eyes read video", required: true, met: false,
+            fix: "the ChatGPT plan takes no video input, and the lead model's catalog lists none; name a model that reads video natively with --eyes-model and set its provider's key, or list images and let frames be extracted locally",
+        });
+    }
+    const missing = items.filter((item) => item.required && !item.met);
+    const mode = options.kill ? "--live --kill" : options.live ? "--live" : "on fakes";
+    const lines = [`${spec.name} (${mode}) needs:`];
+    for (const item of items) {
+        const state = item.met ? "ok      " : item.required ? "MISSING " : "optional";
+        lines.push(`  ${state} ${item.kind} ${item.name}: ${item.why}`);
+        if (!item.met)
+            lines.push(`           ${item.fix}`);
+    }
+    if (options.live || options.kill) {
+        lines.push("  model: Sign in with ChatGPT (your plan pays), or --provider and --model with that provider's key");
+        lines.push(`Expected: about ${spec.expectedCalls} model calls, about $${spec.expectedCost.toFixed(2)} at list prices.`);
+    }
+    lines.push(missing.length
+        ? `${missing.length} required ${missing.length === 1 ? "item is" : "items are"} missing, so nothing started. SETUP-PROMPT.md beside this demo walks through each one.`
+        : "Everything this run needs is here.");
+    return { ok: missing.length === 0, exitCode: missing.length ? 2 : 0, items, missing, expectedCalls: spec.expectedCalls, expectedCost: spec.expectedCost, text: lines.join("\n") };
+}
+/** An UPPER_SNAKE name that reads as a credential: `*_API_KEY`, `*_KEY`, `*_TOKEN*`, `*_SECRET*`, `*_PROJECT_ID`. */
+const CREDENTIAL = /_(API_)?KEY$|_TOKEN|_SECRET|_PROJECT_ID$/;
+const ENV_NAME = /(?<![A-Za-z0-9_])[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+(?![A-Za-z0-9_])/g;
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** `name` as a whole word: not part of a longer name, a path, or a hyphenated command. */
+const mentions = (text, name) => new RegExp(`(?<![A-Za-z0-9_@/.-])${escape(name)}(?![A-Za-z0-9_/-])`).test(text);
+/**
+ * Whether a demo's SETUP-PROMPT.md matches its spec. Every key env name, program command and package name in the spec,
+ * choice members included, appears in the prompt. "Nothing more" covers credential env names only: an UPPER_SNAKE name
+ * that reads as a credential and is not in the spec fails. A prompt's own command words (sudo, an install step) are
+ * never read as programs.
+ */
+export function checkSetupPrompt(spec, text) {
+    const members = requirements(spec).flatMap((item) => isChoice(item) ? item.oneOf.flat() : [item]);
+    const names = members.map((item) => isKey(item) ? item.env : isProgram(item) ? item.cmd : item.name);
+    const envs = new Set(members.filter(isKey).map((item) => item.env));
+    const missing = [...new Set(names)].filter((name) => !mentions(text, name));
+    const extra = [...new Set(text.match(ENV_NAME) ?? [])].filter((name) => CREDENTIAL.test(name) && !envs.has(name));
+    return { ok: missing.length === 0 && extra.length === 0, missing, extra };
+}