humanish 0.112.0 → 0.114.0

package/dist/study/preflight.js

@@ -1,11 +1,15 @@
+import { personaBackgroundWarnings } from "./warnings.js";
+import { resolveCommittedPersonasForCwd, studyPersonaIds } from "./persona-resolve.js";
 import path from "node:path";
 import { isLoopbackUrl } from "./parse/subject.js";
 import {} from "./types.js";
 import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./preflight-probes.js";
-import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
+import { digest, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
 import { routeOf } from "./plan.js";
 import { resolveStudyManifest } from "./discover.js";
 import { participantList } from "./study-fields.js";
+import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
+import { cli } from "../cli/invocation.js";
 const DEFAULT_PREFLIGHT_TIMEOUT_MS = 30_000;
 export async function runStudyPreflight(options) {
     const cwd = path.resolve(options.cwd);
@@ -33,6 +37,9 @@ export async function runStudyPreflight(options) {
             error: resolved.error,
         };
     }
+    const personas = resolved.config.route === "computer-use" || resolved.config.route === "shared-world"
+        ? (await resolveCommittedPersonasForCwd(cwd, studyPersonaIds(resolved.config))).personas
+        : new Map();
     const route = routeOf(resolved.config);
     const ctx = {
         cwd,
@@ -52,31 +59,64 @@ export async function runStudyPreflight(options) {
         ],
         targets: collectTargets(resolved.config),
         sandbox: { created: false },
-        warnings: resolved.warnings,
+        warnings: [...resolved.warnings, ...personaBackgroundWarnings(resolved.config, personas)],
     };
-    switch (reachability) {
-        case "metadata":
-            return finalize(ctx, {
-                check: {
+    const machine = machineCheck(ctx.config);
+    // A local study's app and desktops run on this machine, so the hosted probes do not apply.
+    if (reachability !== "metadata" && isLocalBrowserStudy(ctx.config))
+        return finalize(ctx, {
+            checks: [
+                {
                     name: "reachability",
                     ok: true,
-                    message: "metadata-only; no network, sandbox, or model calls. Credentials, local login, dependencies and target reachability were not checked; use humanish doctor --study <study> for setup checks.",
+                    checked: false,
+                    message: `${reachability} reachability does not apply to a local study: its app runs on this machine and its participant desktops in the local runtime, not in a hosted sandbox.`,
                 },
+                machine,
+            ],
+        });
+    switch (reachability) {
+        case "metadata":
+            return finalize(ctx, {
+                checks: [
+                    {
+                        name: "reachability",
+                        ok: true,
+                        message: "metadata-only; no network, sandbox, or model calls. Target reachability was not checked.",
+                    },
+                    machine,
+                ],
             });
         case "public-preview":
             return await runPublicPreviewPreflight(ctx);
         case "sandbox-loopback":
             return await runSandboxLoopbackPreflight(ctx);
         case "prepared-host":
-            return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE", "prepared-host preflight requires a library adapter hook; the plain CLI can validate metadata only for this mode.", [
-                {
-                    name: "prepared-host",
-                    ok: false,
-                    message: "no generic CLI hook exists for adopter-prepared hosts yet",
-                },
-            ]);
+            return finalize(ctx, {
+                checks: [
+                    {
+                        name: "reachability",
+                        ok: true,
+                        checked: false,
+                        message: "prepared-host reachability has no CLI check: it needs a library adapter hook for a host you prepare yourself. The study file was checked.",
+                    },
+                    machine,
+                ],
+            });
     }
 }
+/** What study check leaves to doctor: this machine's setup for the study, and the command. */
+function machineCheck(config) {
+    const command = cli(`doctor --study ${config.id}`);
+    return {
+        name: "this machine",
+        ok: true,
+        checked: false,
+        message: isLocalBrowserStudy(config)
+            ? `The local runtime, the participant sign-in and whether this study's desktops fit were not checked. Run ${command} to check them.`
+            : `Credentials, local login and dependencies were not checked. Run ${command} to check them.`,
+    };
+}
 function collectTargets(config) {
     const targets = [];
     if (config.subject.appUrl) {

package/dist/study/summary.js

@@ -15,7 +15,7 @@ import { requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
 import { inspectStudyManifest } from "./discover.js";
-import { isComputerUseComposition } from "./routing.js";
+import { computerUseParticipantCount, isComputerUseComposition } from "./routing.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { participantList, declaredParticipantCount } from "./study-fields.js";
@@ -127,7 +127,7 @@ export async function readStudySummary(cwd, study, options = {}) {
             missingKeys = missing;
     }
     // Computed once: a test-then-use pair reads as though the two calls could differ.
-    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route);
+    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
     const subject = subjectOf(config);
     const participants = participantsOf(inspected.config);
     const runtime = options.checkKeys === true && isLocalBrowserStudy(inspected.config)

package/dist/study/warnings.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedPersona } from "./persona.js";
 import type { StudyConfig } from "./types.js";
 /**
  * The fields a config sets that its route does not read, each as `field` or `field (reason)`.
@@ -19,3 +20,7 @@ export declare function inertFieldPaths(config: StudyConfig): string[];
  */
 export declare function egressAllowIgnoredWarning(config: StudyConfig): string | undefined;
 export declare function forwardDeclaredWarnings(config: StudyConfig): string[];
+/** Authored participant text is checked before runtime instructions or researcher criteria join it. */
+export declare function scriptedMissionWarnings(config: StudyConfig): string[];
+/** Backgrounds give participants a reason to act beyond the assigned task. */
+export declare function personaBackgroundWarnings(config: StudyConfig, personas: ReadonlyMap<string, ResolvedPersona>): string[];

package/dist/study/warnings.js

@@ -1,7 +1,7 @@
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
-import { participantList, declaredParticipantCount } from "./study-fields.js";
+import { participantList, participantInstruction, declaredParticipantCount, } from "./study-fields.js";
 // The computer-use and terminal routes consume mission/persona/model (they compose the agent prompt
 // and bundle provenance).
 const promptRoute = (routes) => routes.cua || routes.terminal;
@@ -311,5 +311,82 @@ export function forwardDeclaredWarnings(config) {
             warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants. These get no inbox and are never told one exists: ${uncovered.join(", ")}. Add a recipient with an address for each one whose flow needs email.`);
         }
     }
-    return warnings;
+    return [...warnings, ...scriptedMissionWarnings(config)];
+}
+const UI_ACTION = /\b(?:click|tap|press|type\b[^.!?\n]*?\binto|select\b[^.!?\n]*?\bfrom)\b/gi;
+function normalizedUrl(value) {
+    try {
+        return new URL(value).href;
+    }
+    catch {
+        return value;
+    }
+}
+function scriptedLine(line, entry) {
+    const urls = line.match(/https?:\/\/[^\s<>"'`)]+/gi) ?? [];
+    if (urls.some((url) => normalizedUrl(url.replace(/[.,;!?]+$/, "")) !== (entry ? normalizedUrl(entry) : undefined)))
+        return true;
+    if (/^\s*(?:\d+[.)]|[-*+])\s+/.test(line))
+        return true;
+    if (/\b(?:click|tap|press|open|select|choose)\s+(?:on\s+)?(?:the\s+)?[`"'“‘][^`"'”’]+[`"'”’]/i.test(line) ||
+        /[`"'“‘][^`"'”’]+[`"'”’]\s+(?:button|link|tab|menu|control|field)\b/i.test(line))
+        return true;
+    if (/(?:^|[\s`"'])(?:button|input|textarea|select|form|div|span|main|a)?(?:[#.][a-zA-Z_][\w-]*|\[[\w-]+(?:[~|^$*]?=|\]))|\b[a-z][\w-]*\s*>\s*[a-z#.[]/i.test(line))
+        return true;
+    return actionChain(line);
+}
+function actionChain(text) {
+    const actions = [...text.matchAll(UI_ACTION)];
+    return (actions.length > 1 ||
+        (actions.length === 1 &&
+            /\bthen\b/i.test(text.slice((actions[0]?.index ?? 0) + (actions[0]?.[0].length ?? 0)))));
+}
+/** Authored participant text is checked before runtime instructions or researcher criteria join it. */
+export function scriptedMissionWarnings(config) {
+    if (config.route !== "computer-use" && config.route !== "shared-world")
+        return [];
+    const fields = [
+        ["actor.mission", config.actor?.mission],
+        ["participants.instruction", participantInstruction(config)],
+        ...(participantList(config) ?? []).map((participant, index) => [
+            `participants[${index}].instruction`,
+            participant.instruction,
+        ]),
+        ...(config.actor?.tasks ?? []).map((task, index) => [
+            `actor.tasks[${index}].goal`,
+            task.goal,
+        ]),
+    ];
+    return fields.flatMap(([field, text]) => {
+        const chain = actionChain(text ?? "");
+        const matches = text
+            ?.split(/\r?\n/)
+            .filter((line) => scriptedLine(line, config.subject.appUrl ?? config.subject.serve?.url) ||
+            (chain && (line.match(UI_ACTION) !== null || /\bthen\b/i.test(line)))) ?? [];
+        if (matches.length === 0)
+            return [];
+        return [
+            `${field} reads like a script, which can hide where a participant would get lost. Matched lines:\n${matches
+                .slice(0, 3)
+                .map((line) => `> ${line}`)
+                .join("\n")}\nDescribe a situation and desired outcome instead. For example: "Saturday's event needs two setup volunteers and one cleanup volunteer. See whether this app helps you organize the event and keep people informed." Keep researcher criteria in tasks[].success.`,
+        ];
+    });
+}
+/** Backgrounds give participants a reason to act beyond the assigned task. */
+export function personaBackgroundWarnings(config, personas) {
+    if (config.route !== "computer-use" && config.route !== "shared-world")
+        return [];
+    const roster = participantList(config);
+    return declaredParticipantIds(config).flatMap((id, index) => {
+        const personaId = roster?.[index]?.persona ?? config.actor?.persona;
+        if (personaId && personas.get(personaId)?.background)
+            return [];
+        const reason = personaId
+            ? `persona ${personaId} has no readable background`
+            : "no persona is assigned";
+        return [
+            `Participant ${id} has no persona background because ${reason}. Add a short, fictional background describing their experience and situation. Run humanish study show ${config.id} --json to see what the participant receives.`,
+        ];
+    });
 }

package/dist/substrates/local/capacity.d.ts

@@ -0,0 +1,75 @@
+/**
+ * What one participant desktop container may use: Docker's `--memory` and `--memory-swap` limit
+ * and its `--cpus` quota. The Firecracker guest inside it has 2 GiB and 2 vCPUs; the rest is room
+ * for Firecracker and its jailer.
+ */
+export declare const DESKTOP_RESERVATION: {
+    readonly memoryGiB: 3;
+    readonly cpus: 2;
+};
+/** A machine's or a VM's total memory and CPU count. */
+export interface MachineSize {
+    readonly memoryBytes: number;
+    readonly cpus: number;
+}
+/** A Lima VM size as `limactl` takes it: whole GiB and CPUs. */
+export interface VmSize {
+    readonly memoryGiB: number;
+    readonly cpus: number;
+}
+/** How many participant desktops the local runtime holds at once, and why. */
+export interface LocalCapacity {
+    /** The humanish Lima VM on a Mac, or this Linux machine, which runs desktops directly. */
+    readonly host: "lima-vm" | "linux-host";
+    /** The VM's or the machine's memory, rounded down to a tenth of a GiB, and CPUs. */
+    readonly memoryGiB: number;
+    readonly cpus: number;
+    readonly reservedMemoryGiB: number;
+    readonly perDesktop: {
+        readonly memoryGiB: number;
+        readonly cpus: number;
+    };
+    readonly desktops: number;
+    /**
+     * More desktops fit by memory than by CPUs at 2 each, so busy desktops share CPU time and run
+     * slower. A CPU quota throttles; it does not kill, so CPUs never lower `desktops`.
+     */
+    readonly sharesCpus?: true;
+    /** No humanish Lima VM exists yet: the size is the one setup would create. */
+    readonly planned?: true;
+    /** The Mac's own memory and CPUs, which a Lima VM cannot exceed. */
+    readonly machine?: {
+        readonly memoryGiB: number;
+        readonly cpus: number;
+    };
+}
+/**
+ * Desktops that fit in a host of this size, after the host's own memory. Memory decides: a desktop
+ * past it is killed, while one past the CPUs only runs slower.
+ */
+export declare function localCapacity(host: LocalCapacity["host"], size: MachineSize, more?: {
+    planned?: boolean;
+    machine?: MachineSize;
+}): LocalCapacity;
+/** This machine's memory and CPUs, or the size a test passes in. */
+export declare function machineSize(machine?: MachineSize): MachineSize;
+/** A new VM's size: room for four desktops, capped at half the Mac's memory and CPUs. */
+export declare function defaultVmSize(mac: MachineSize): VmSize;
+/**
+ * Why a VM size the user asked for cannot work, or undefined: it must hold at least one desktop
+ * and fit within the Mac.
+ */
+export declare function vmSizeProblem(size: VmSize, mac: MachineSize): string | undefined;
+/** The capacity in a sentence or two: the host's size, what each desktop takes and how many fit. */
+export declare function describeCapacity(capacity: LocalCapacity): string;
+/**
+ * What a local study that runs `needed` desktops at once is told: a refusal on a Mac, whose Lima
+ * VM has a fixed size, or a warning on Linux, where free memory varies. Undefined when they fit.
+ */
+export declare function capacityShortfall(capacity: LocalCapacity, needed: number): {
+    refusal: string;
+} | {
+    warning: string;
+} | undefined;
+/** What a participant whose desktop Docker killed for memory is told, with what to change. */
+export declare function outOfMemoryMessage(host: LocalCapacity["host"]): string;

package/dist/substrates/local/capacity.js

@@ -0,0 +1,143 @@
+import { availableParallelism, totalmem } from "node:os";
+import { cli } from "../../cli/invocation.js";
+import { plural } from "../../run/text.js";
+const GiB = 1024 ** 3;
+/**
+ * What one participant desktop container may use: Docker's `--memory` and `--memory-swap` limit
+ * and its `--cpus` quota. The Firecracker guest inside it has 2 GiB and 2 vCPUs; the rest is room
+ * for Firecracker and its jailer.
+ */
+export const DESKTOP_RESERVATION = { memoryGiB: 3, cpus: 2 };
+/** Memory the runtime host keeps for its own Linux, Docker daemon and SSH before any desktop. */
+const HOST_RESERVED_MEMORY_GIB = 1;
+/** The VM setup creates holds this many desktops, unless half the Mac is smaller. */
+const DEFAULT_VM_DESKTOPS = 4;
+/**
+ * Desktops that fit in a host of this size, after the host's own memory. Memory decides: a desktop
+ * past it is killed, while one past the CPUs only runs slower.
+ */
+export function localCapacity(host, size, more = {}) {
+    const memoryGiB = size.memoryBytes / GiB;
+    const byMemory = Math.floor((memoryGiB - HOST_RESERVED_MEMORY_GIB) / DESKTOP_RESERVATION.memoryGiB);
+    const byCpus = Math.floor(size.cpus / DESKTOP_RESERVATION.cpus);
+    return {
+        host,
+        memoryGiB: Math.floor(memoryGiB * 10) / 10,
+        cpus: size.cpus,
+        reservedMemoryGiB: HOST_RESERVED_MEMORY_GIB,
+        perDesktop: { ...DESKTOP_RESERVATION },
+        desktops: Math.max(0, byMemory),
+        ...(byMemory > byCpus ? { sharesCpus: true } : {}),
+        ...(more.planned ? { planned: true } : {}),
+        ...(more.machine === undefined
+            ? {}
+            : {
+                machine: {
+                    memoryGiB: Math.floor(more.machine.memoryBytes / GiB),
+                    cpus: more.machine.cpus,
+                },
+            }),
+    };
+}
+/** The memory and CPUs a VM needs to hold `desktops` desktops. */
+function vmSizeFor(desktops) {
+    return {
+        memoryGiB: HOST_RESERVED_MEMORY_GIB + desktops * DESKTOP_RESERVATION.memoryGiB,
+        cpus: desktops * DESKTOP_RESERVATION.cpus,
+    };
+}
+/** This machine's memory and CPUs, or the size a test passes in. */
+export function machineSize(machine) {
+    return machine ?? { memoryBytes: totalmem(), cpus: availableParallelism() };
+}
+/** A new VM's size: room for four desktops, capped at half the Mac's memory and CPUs. */
+export function defaultVmSize(mac) {
+    const wanted = vmSizeFor(DEFAULT_VM_DESKTOPS);
+    return {
+        memoryGiB: Math.min(wanted.memoryGiB, Math.floor(mac.memoryBytes / GiB / 2)),
+        cpus: Math.min(wanted.cpus, Math.floor(mac.cpus / 2)),
+    };
+}
+/**
+ * Why a VM size the user asked for cannot work, or undefined: it must hold at least one desktop
+ * and fit within the Mac.
+ */
+export function vmSizeProblem(size, mac) {
+    const one = vmSizeFor(1);
+    const macGiB = Math.floor(mac.memoryBytes / GiB);
+    if (size.memoryGiB < one.memoryGiB || size.cpus < one.cpus)
+        return `One participant desktop needs a VM with at least ${one.memoryGiB} GiB and ${one.cpus} CPUs: ${DESKTOP_RESERVATION.memoryGiB} GiB and ${DESKTOP_RESERVATION.cpus} CPUs for the desktop and ${HOST_RESERVED_MEMORY_GIB} GiB for the VM itself.`;
+    if (size.memoryGiB > macGiB)
+        return `--memory ${size.memoryGiB} is more than the ${macGiB} GiB this Mac has. Choose ${macGiB} or less; about half leaves room for macOS and your app.`;
+    if (size.cpus > mac.cpus)
+        return `--cpus ${size.cpus} is more than the ${mac.cpus} CPUs this Mac has. Choose ${mac.cpus} or fewer.`;
+    return undefined;
+}
+/** "2 desktops fit", "1 desktop fits". */
+function desktopsFit(count, future = false) {
+    return `${plural(count, "desktop")} ${future ? "will fit" : count === 1 ? "fits" : "fit"}`;
+}
+/** The capacity in a sentence or two: the host's size, what each desktop takes and how many fit. */
+export function describeCapacity(capacity) {
+    const each = `each participant desktop reserves ${capacity.perDesktop.memoryGiB} GiB`;
+    const cpus = capacity.sharesCpus
+        ? ` The desktops share ${capacity.cpus} CPUs, so they run slower when all of them are busy.`
+        : "";
+    const size = `${capacity.memoryGiB} GiB and ${capacity.cpus} CPUs`;
+    if (capacity.host === "linux-host")
+        return `This machine has ${size}. After ${capacity.reservedMemoryGiB} GiB for the system, ${each}, so ${desktopsFit(capacity.desktops)} at once.${cpus}`;
+    const vm = capacity.planned
+        ? `Setup will create the humanish Lima VM with ${size}.`
+        : `The humanish Lima VM has ${size}.`;
+    return `${vm} It keeps ${capacity.reservedMemoryGiB} GiB for itself and ${each}, so ${desktopsFit(capacity.desktops, capacity.planned)} at once.${cpus} To change its size, run ${cli("runtime setup --memory <GiB> --cpus <n>")}.`;
+}
+/**
+ * What a local study that runs `needed` desktops at once is told: a refusal on a Mac, whose Lima
+ * VM has a fixed size, or a warning on Linux, where free memory varies. Undefined when they fit.
+ */
+export function capacityShortfall(capacity, needed) {
+    const fits = capacity.desktops;
+    if (needed <= fits)
+        return undefined;
+    const host = capacity.host === "linux-host"
+        ? "this machine"
+        : capacity.planned
+            ? "the humanish Lima VM that setup creates"
+            : "the humanish Lima VM";
+    const holds = `${host} holds ${fits}: it has ${capacity.memoryGiB} GiB, keeps ${capacity.reservedMemoryGiB} GiB for ${capacity.host === "lima-vm" ? "itself" : "the system"}, and each desktop reserves ${capacity.perDesktop.memoryGiB} GiB.`;
+    const runs = `This study runs ${plural(needed, "participant desktop")} at once, and ${holds}`;
+    const cloud = [
+        "Run it on cloud desktops, which have no local memory limit. In the study file, set these two fields, add `subject.serve` with the command that starts your app, and provide E2B_API_KEY:",
+        "     subject.source: local-tree",
+        "     execution.target: e2b-desktop",
+    ];
+    const fewer = fits === 0
+        ? []
+        : [
+            `Run fewer at once: set \`execution.concurrency: ${fits}\` to run them ${fits} at a time, or lower \`participants\` to ${fits}.`,
+        ];
+    if (capacity.host === "linux-host")
+        return {
+            warning: `${runs} The run starts anyway because free memory on Linux varies, but a desktop that runs out of memory is killed and its participant fails. To avoid that, run it on cloud desktops (\`subject.source: local-tree\` and \`execution.target: e2b-desktop\`, with a \`subject.serve\` command)${fits === 0 ? "" : `, or set \`execution.concurrency: ${fits}\``}.`,
+        };
+    const memoryGiB = Math.max(vmSizeFor(needed).memoryGiB, Math.ceil(capacity.memoryGiB));
+    const machine = capacity.machine;
+    const bigger = machine !== undefined && memoryGiB > machine.memoryGiB
+        ? `This Mac has ${machine.memoryGiB} GiB, too little for a VM that holds ${needed} desktops.`
+        : `Give the VM room for ${needed} desktops: ${cli(`runtime setup --memory ${memoryGiB}`)}`;
+    const steps = [cloud.join("\n"), bigger, ...fewer];
+    return {
+        refusal: [
+            `${runs} More desktops than that run the VM out of memory and their browsers crash, so nothing was started.`,
+            "To run this study, do one of these:",
+            ...steps.map((step, index) => `${index + 1}. ${step}`),
+        ].join("\n"),
+    };
+}
+/** What a participant whose desktop Docker killed for memory is told, with what to change. */
+export function outOfMemoryMessage(host) {
+    const shared = host === "lima-vm"
+        ? `all desktops share the humanish Lima VM's memory. Run fewer participants at once with \`execution.concurrency\`, give the VM more memory with ${cli("runtime setup --memory <GiB>")}, or run on cloud desktops (\`subject.source: local-tree\` with \`execution.target: e2b-desktop\`).`
+        : `all desktops share this machine's memory. Run fewer participants at once with \`execution.concurrency\`, close other memory-heavy programs, or run on cloud desktops (\`subject.source: local-tree\` with \`execution.target: e2b-desktop\`).`;
+    return `The participant's desktop ran out of memory: Docker killed its container (OOMKilled), so its browser closed mid-session. Each desktop may use ${DESKTOP_RESERVATION.memoryGiB} GiB, and ${shared}`;
+}

package/dist/substrates/local/firecracker-desktop.d.ts

@@ -10,7 +10,15 @@ export interface LocalFirecrackerAssets {
 }
 export interface LocalFirecrackerDesktop extends DesktopSession {
     finishRecording(destination: Writable): Promise<DesktopRecordingMetadata>;
+    /** Whether Docker killed this desktop's container for memory; undefined when it cannot tell. */
+    killedForMemory?(): Promise<boolean | undefined>;
 }
+/**
+ * Whether Docker recorded an `oom` event for the container since `since` (epoch ms). The
+ * container is created with --rm, so its OOMKilled state is gone once it exits; the daemon's
+ * recent events still hold the kill.
+ */
+export declare function desktopKilledForMemory(container: string, since: number): Promise<boolean | undefined>;
 interface LocalFirecrackerOptions {
     assets: LocalFirecrackerAssets;
     appUrl: string;

package/dist/substrates/local/firecracker-desktop.js

@@ -10,11 +10,40 @@ import { runtimeDocker, runtimeExec, usesLima } from "./runtime-host.js";
 import { openLimaTunnel } from "./runtime-ssh.js";
 import { guestMediaConfigSchema } from "../../guest/media-config.js";
 import { cli } from "../../cli/invocation.js";
+import { DESKTOP_RESERVATION } from "./capacity.js";
 const docker = async (args) => (await runtimeDocker(args, {}, 60_000)).stdout.trim();
 const readLogs = async (id) => {
     const result = await runtimeDocker(["logs", "--tail", "100", id], {}, 10_000);
     return result.stdout + result.stderr;
 };
+/**
+ * Whether Docker recorded an `oom` event for the container since `since` (epoch ms). The
+ * container is created with --rm, so its OOMKilled state is gone once it exits; the daemon's
+ * recent events still hold the kill.
+ */
+export async function desktopKilledForMemory(container, since) {
+    // Relative times use the clock of the machine Docker runs on, which is the Lima VM on a Mac.
+    const seconds = Math.ceil((Date.now() - since) / 1000) + 60;
+    try {
+        const events = await docker([
+            "events",
+            "--since",
+            `${seconds}s`,
+            "--until",
+            "0s",
+            "--filter",
+            `container=${container}`,
+            "--filter",
+            "event=oom",
+            "--format",
+            "{{.Action}}",
+        ]);
+        return events.split("\n").some((line) => line.trim() === "oom");
+    }
+    catch {
+        return undefined;
+    }
+}
 function checkDesktopOptions(options) {
     if (options.media !== undefined) {
         guestMediaConfigSchema.parse(options.media);
@@ -164,11 +193,11 @@ function dockerCreateArgs(options) {
         "--sysctl",
         "net.ipv4.ip_forward=1",
         "--memory",
-        "3g",
+        `${DESKTOP_RESERVATION.memoryGiB}g`,
         "--memory-swap",
-        "3g",
+        `${DESKTOP_RESERVATION.memoryGiB}g`,
         "--cpus",
-        "2",
+        String(DESKTOP_RESERVATION.cpus),
         "--pids-limit",
         "128",
         "--tmpfs",
@@ -276,6 +305,7 @@ export async function createLocalFirecrackerDesktop(options) {
     const aborted = () => {
         void close();
     };
+    const createdAt = Date.now();
     try {
         const { uid, gid } = await prepareVmHost(host, url, inbox, signal);
         const container = await startContainer(host, dockerCreateArgs({
@@ -305,6 +335,7 @@ export async function createLocalFirecrackerDesktop(options) {
         return {
             ...session,
             finishRecording: (destination) => client.finishRecording(destination),
+            killedForMemory: () => desktopKilledForMemory(container, createdAt),
         };
     }
     catch (error) {

package/dist/substrates/local/runtime-host.d.ts

@@ -1,9 +1,12 @@
+import { type MachineSize, type VmSize } from "./capacity.js";
 export declare const LIMA_INSTANCE = "humanish-runtime";
 export interface RuntimeHostOptions {
     env?: NodeJS.ProcessEnv;
     signal?: AbortSignal;
     platform?: NodeJS.Platform;
     arch?: string;
+    /** This machine's memory and CPUs; tests pass a fixed size. */
+    machine?: MachineSize;
 }
 export declare const usesLima: (options?: RuntimeHostOptions) => boolean;
 export declare function runtimeArchitecture(options?: RuntimeHostOptions): "amd64" | "arm64" | undefined;
@@ -22,11 +25,21 @@ export declare function runtimeDocker(args: string[], options?: RuntimeHostOptio
     stdout: string;
     stderr: string;
 }>;
-export declare function limaStatus(options?: RuntimeHostOptions): Promise<{
+/** The humanish Lima VM's state, and its memory and CPUs when it exists. */
+export interface LimaStatus {
     ready: boolean;
     exists: boolean;
     message: string;
-}>;
-export declare function prepareLima(options?: RuntimeHostOptions, progress?: (message: string) => void): Promise<void>;
+    size?: MachineSize;
+}
+export declare function limaStatus(options?: RuntimeHostOptions): Promise<LimaStatus>;
+/**
+ * Start the humanish Lima VM, creating it at `size` (or the default size) when it does not exist.
+ * An existing VM keeps its size unless `size` differs, in which case it is stopped, resized and
+ * started again.
+ */
+export declare function prepareLima(options?: RuntimeHostOptions & {
+    size?: Partial<VmSize>;
+}, progress?: (message: string) => void): Promise<void>;
 /** Copy across the OS boundary explicitly; shared folders cannot carry sockets. */
 export declare function loadRuntimeArchive(archive: string, options: RuntimeHostOptions): Promise<void>;