A desktop coding agent with free access to frontier models.
TypeScript
/**
* The desktop's Linux sandbox ("box", ported from the CLI: see launch.ts):
* one per server, for every local workspace whose box is on. It keeps
*
* - the per-workspace choice in the workspace's OmniRush settings
* (`localBox: { mode: "on" | "off", offered }`; no mode: the server's
* default from /collect/capabilities -> local_box.default);
* - the engine bits (the shell, named bash, and the box plugin) that go
* into the one engine config when any workspace may use a box;
* - <box home>/desktop-projects.json, the projects the plugin routes to
* their box (everything else runs natively through the same shell);
* - each project's run: the per-turn checkpoints and the label its chats'
* uploads carry;
* - the machine's backend setting (`auto`, one backend id, or `native`) in
* <state>/box.json, and the server's allowlist of backends
* (local_box.backends, remembered in <state>/box-server.json).
*
* Nothing here blocks opening a project: probes are bounded, a missing image
* downloads in the background, a box that cannot start leaves its project
* on this machine.
*
* Not to be confused with the OpenWork worker sandbox (`sandboxBackend`).
*/
import { existsSync, readFileSync } from "node:fs";
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { boxHome, boxKey, boxSnapshotsDir, containerName, installShell, listBoxes, mountReplaced, readRecord, resetBox, savedTurns, type BoxLabel, type BoxLog } from "./box.js";
import { LABELS, OPT_IN, REQUIRED_FIRST, backendsFor, driverFor } from "./backends/index.js";
import { limaHome } from "./backends/lima.js";
import type { BoxExec } from "./backends/types.js";
import type { BoxEndpoint } from "./client.js";
import { hostBuilds, hostBuildsNotice, hostBuildThings, hostRules } from "./host-builds.js";
import { detectStack, imageFor, type BoxImage } from "./images.js";
import { portLine } from "./ports.js";
import { writeFileAtomic } from "../atomic-write.js";
import { askedBackend, boxRun, planBox, pullActivityAt, pullLog, pullMarker, pulling, pullInBackground, setupWait, resolveMode, saveBackend, serverBackends, serverDefault, serverLocalBox, serverRequired, shimsDir, type BoxRun, type ProjectBoxMode, type ServerBoxDefault } from "./launch.js";
import { desktopText, hostOnlyProject, requiredLaunch, shadowsApply, shadowsNotice, type RequiredFallback } from "./required.js";
import { cachedWindowsChecks, classifySetup, linuxAllow, resumeWinSetup, saveSetupState, setupState, windowsInstall, windowsRestart, windowsUpdate, type BoxSetup } from "./setup.js";
import type { BoxInstallLogPaths } from "./install-log.js";
import { DESKTOP_PROJECTS_FILE } from "./plugin-lib.js";
import { farmRun } from "../stock-mode/stock-mode.mjs";
import { BUILDATHON_OFFER_NOTICE, buildathonBoxFor, buildathonProjectsFile, LESS_REPRO_NOTICE } from "../buildathon-repro.js";
import { layerSizes, pullProgress, type PullProgress } from "./pull-progress.js";
import { detectRuntime, type BackendAlternative, type DetectOptions, type RuntimeInfo, type RuntimeResult } from "./runtime.js";
/** What the capture side needs of a chat's box (plain data: it crosses to the capture worker). */
/** A box chat after its project's box was turned off. */
export const PINNED_BOX_NOTE = "This chat keeps running in the sandbox. New chats follow the new setting.";
/** A chat's pin from its first prompt: where it runs, the local_box revision, the capture policy its uploads keep. */
export type ChatPin = { box: boolean; revision: string | null; capturePolicy?: string; verified?: boolean; lateReason?: string };
export type BoxCaptureInfo = {
key: string;
root: string;
croot: string;
container: string;
runtimeBin: string;
/** Arguments before the runtime's own (`-e docker` for a WSL engine). */
runtimeArgs: string[];
/** The backend id (backends/index.ts). */
backend: string;
/** How files-used reads the box when it is not `docker exec` (bubblewrap, Apple container, the WSL distro). */
exec: BoxExec | null;
/** environment.sandbox of the chat's uploads. */
label: BoxLabel;
};
export type BoxWorkspace = { id: string; path: string; directory?: string; workspaceType: string };
export type BoxStatus = {
/** The server's start for a new chat on each model (local_box.model_start); null from an older server. */
modelStart: Record<string, { start: "native" | "box"; switchable: boolean }> | null;
/** The local_box policy revision new chats pin. */
revision: string | null;
/** This chat's pin (asked for one chat): where it runs and the revision it started under; null before its first prompt. */
chatPin: ChatPin | null;
/** The project's own choice (null: the server's default). */
mode: ProjectBoxMode;
serverDefault: ServerBoxDefault;
/** Whether the project's chats should run in its box. */
on: boolean;
/**
* "host-builds": the server's default would put it in the box, but its folder has this computer's builds (macOS, Windows).
* "required": the server requires the sandbox for new chats. "host-only": required, but the project only builds on this OS.
*/
source: "env" | "project" | "server" | "default" | "host-builds" | "buildathon" | "required" | "host-only";
/** The server offers the box and this project was not offered it yet. */
offer: boolean;
state: "off" | "unavailable" | "downloading" | "starting" | "ready" | "failed";
runtime: { ok: boolean; name: string | null; flavor: string | null; version: string | null; reason: string | null } | null;
/** What runs the box on this machine: the chosen backend, why, and the others (each with why not). */
backend: BoxBackendView | null;
/** The machine's backend setting and the values it takes here. */
backendSetting: { value: string; source: "env" | "setting" | "auto"; choices: Array<{ id: string; label: string }> };
image: { ref: string; stack: string; present: boolean | null; downloading: boolean } | null;
/** How far the image download is (while it downloads, when the runtime's output says). */
progress: PullProgress | null;
container: { name: string; exists: boolean; running: boolean } | null;
/** The server's OS (the card's next step when no backend works). */
platform: NodeJS.Platform;
/** One line for the user (why it is off, that it is downloading). */
notice: string | null;
error: string | null;
/**
* macOS / Windows: the folder has this computer's builds (host-builds.ts). `native`: its chats
* stay on this computer (only the server's default had it on); else it is on by the user's
* choice and `notice` warns that rebuilding them in the box replaces them. Null otherwise.
*/
hostBuilds: { native: boolean; things: string; notice: string } | null;
/** macOS / Windows, while the project's chats run in the box: the one line that says so (null elsewhere). */
boxNotice: string | null;
/**
* The server requires the sandbox for new chats (local_box.required): the switch and "Off (this
* computer)" are disabled with `requiredText.optOut`. False with an older server.
*/
required: boolean;
requiredText: { line: string; optOut: string; keptOldChat: string } | null;
/** Required, but the project only builds on this OS (an Xcode project, a WPF app): its chats run here. */
hostOnly: { things: string[]; notice: string } | null;
/** Required and not ready: what the sandbox needs on this computer (the setup screen). Null otherwise. */
setup: (BoxSetup & { line: string | null }) | null;
/** Asked for one chat (`?session=`): it ran on this computer before the sandbox was required and stays here. */
chatKept: boolean;
/** Servers in the box open at the same port on this computer's 127.0.0.1 (Docker/Podman boxes; ports.ts). */
ports: Array<{ port: number; url: string; line: string }>;
};
/** The setup screen's steps (POST /workspace/:id/box/setup). */
export const BOX_SETUP_ACTIONS = ["linux_allow", "win_install", "win_restart", "win_update", "decline", "check"] as const;
export type BoxSetupAction = (typeof BOX_SETUP_ACTIONS)[number];
export function isBoxSetupAction(value: unknown): value is BoxSetupAction {
return BOX_SETUP_ACTIONS.some((action) => action === value);
}
/** PUT mode "off" (or the backend "native") while the sandbox is required: refused (409 box_required). */
export class BoxRequiredError extends Error {
readonly code = "box_required";
constructor() {
super(desktopText("opt_out_refused"));
}
}
export type BoxBackendView = {
/** The chosen backend's id (null when none works here). */
id: string | null;
label: string | null;
version: string | null;
flavor: string | null;
/** Why this one (the ranked order, the setting, the server's allowlist), or why none. */
why: string | null;
/** Every backend tried here: id, whether it works, one line why not. Empty until the first full check. */
alternatives: Array<{ id: string; label: string; ok: boolean; reason: string | null }>;
/** The server limits the backends (local_box.backends). */
allowed: string[] | null;
};
/** The backend choices of a platform: auto, the ranked ids there, the opt-in ones, native. */
export function backendChoices(platform: NodeJS.Platform = process.platform): Array<{ id: string; label: string }> {
const optIn = (OPT_IN[platform] ?? []).map((id) => ({ id, label: `${LABELS[id] ?? id} (opt-in)` }));
// macOS' own VM: first under the required sandbox, else chosen by name only.
const first = (REQUIRED_FIRST[platform] ?? []).map((id) => ({ id, label: LABELS[id] ?? id }));
return [{ id: "auto", label: "Automatic" }, ...first, ...backendsFor(platform).map((id) => ({ id, label: LABELS[id] ?? id })), ...optIn, { id: "native", label: "Off (this computer)" }];
}
export type BoxServiceOptions = {
/** The capture state dir: the server default is remembered here, snapshots go under sandbox/snapshots. */
stateDir: string;
readSettings: (workspaceId: string) => Promise<{ mode: ProjectBoxMode; offered: boolean }>;
writeSettings: (workspaceId: string, update: { mode?: ProjectBoxMode; offered?: boolean }) => Promise<void>;
workspaces: () => BoxWorkspace[];
/** The engine plugin file (opencode-plugins/omnirush-box). */
pluginPath: () => string;
log?: BoxLog;
env?: NodeJS.ProcessEnv;
/** Whether a running box's project folder was deleted and made again (box.ts mountReplaced; tests replace it). */
folderReplaced?: (box: { endpoint: BoxEndpoint; croot: string }) => Promise<boolean>;
/** The OS whose builds count as this computer's (host-builds.ts; tests set it). */
platform?: NodeJS.Platform;
};
/** `waitingImage`: planned while its image was downloading (planned again as soon as the image is here). */
type Project = { run: BoxRun | null; notice: string | null; planning: Promise<BoxRun | null> | null; nextPlanAt: number; waitingImage: boolean; why?: PlanWhy | null; pull?: { runtime: RuntimeInfo; image: BoxImage } | null; lastRuntime?: RuntimeResult | null };
/** Why the project's last plan has no box (the `box.plan` reason), with the runtime's failure in safe words. */
type PlanWhy = { reason: "no_runtime" | "helpers_missing" | "downloading"; runtime?: { name: string | null; code: string | null } };
/**
* A chat's `box.plan` trace event (once per chat and app run): where its
* prompts run and why, as the CLI's `client.launch` `box`. `reason`: box,
* box_failed, off, offer, host_builds, kept_old_chat, no_runtime,
* helpers_missing, downloading, planning; `source`: what turned the box on or
* off (project, server, default, flag, host-builds, chat).
*/
export type BoxPlanOutcome = { native: boolean; source: string | null; reason: string; runtime?: { name: string | null; code: string | null }; required?: true; capable?: boolean; fallback?: RequiredFallback };
/** The backend tried and its failure code (bubblewrap's apparmor, no_bwrap, ...; `timeout`), never its text or a path. */
export function runtimeWhy(runtime: { name?: unknown; code?: unknown; reason?: unknown } | null | undefined): { name: string | null; code: string | null } {
const code = typeof runtime?.code === "string" && /^[a-z_]{1,32}$/.test(runtime.code) ? runtime.code
: /did not answer in time/.test(String(runtime?.reason ?? "")) ? "timeout" : null;
const name = typeof runtime?.name === "string" && /^[a-z-]{1,16}$/.test(runtime.name) ? runtime.name : null;
return { name, code };
}
/** A project whose image is downloading is planned again at most this often. */
const REPLAN_MS = 15_000;
/** A prompt waits at most this long for its turn's checkpoint. */
const FREEZE_WAIT_MS = 90_000;
/** The full backend check (every backend, for the status card's "others") is reused this long. */
const ALTERNATIVES_MS = 60_000;
/**
* Required: a prompt waits for its project's box while the first setup makes progress (the
* download's log moves: the VM's setup lines, the image's bytes) and stops waiting after this
* long with none (the CLI: a run's no-progress stop counts the setup too).
*/
const REQUIRED_WAIT_MS = 15 * 60_000;
/** ...and at most this long in all, however slow the network (a first macOS VM setup is ~0.7 GB). */
const REQUIRED_SETUP_MAX_MS = 60 * 60_000;
/** How often a waiting prompt looks again. */
const REQUIRED_POLL_MS = 1_000;
export function boxRoot(workspace: BoxWorkspace): string {
return workspace.directory?.trim() || workspace.path;
}
export class BoxService {
private readonly projects = new Map<string, Project>();
private readonly turns = new Map<string, number>();
/** Each chat's turn number as of its last prompt here (its turns before this run, then one per prompt). */
private readonly chatTurns = new Map<string, number>();
/** Per chat, its counts before the prompt beforePrompt last saw (promptCancelled puts them back). */
private readonly uncommitted = new Map<string, { chatTurns: number | undefined; boxed: boolean; turns: number | undefined }>();
/** Chats (and their project's key) that ran on this machine before the server's default turned the box on: they stay here. */
private readonly nativeChats = new Map<string, string>();
/** Of nativeChats, the ones on a model that runs only on this computer (launch reason native_model). */
private readonly nativeModelChats = new Set<string>();
/** Chats sent to their project's box in this run (a failed checkpoint included). */
private readonly boxedChats = new Set<string>();
/**
* Each chat's pin, from its first prompt: whether it runs in the box and the
* local_box policy revision it started under (model_start). A started chat
* never moves: a box chat whose project's box is turned off is refused
* (pinnedBoxGone), a chat that ran here stays here. Kept in chat-pins.json.
*/
private pins: Map<string, ChatPin> | null = null;
/** Chats whose box.plan event went out in this run. */
private readonly outcomeSent = new Set<string>();
private readonly home: string;
private readonly env: NodeJS.ProcessEnv;
private readonly platform: NodeJS.Platform;
private log: BoxLog;
private projectsWrite: Promise<void> = Promise.resolve();
private installLog: BoxInstallLogPaths | null = null;
private alternatives: { at: number; key: string; list: BackendAlternative[] } | null = null;
private readonly folderReplaced: NonNullable<BoxServiceOptions["folderReplaced"]>;
constructor(private readonly options: BoxServiceOptions) {
this.folderReplaced = options.folderReplaced ?? (({ endpoint, croot }) => mountReplaced({ endpoint }, { croot, readyMs: 1_000 }));
this.env = options.env ?? process.env;
this.platform = options.platform ?? process.platform;
this.home = boxHome(this.env);
this.log = options.log ?? (() => {});
}
/**
* The install log of box chats (install-log.ts): new boxes mount its
* folder and put its wrappers on PATH; the plugin points their calls at its
* raw folder. Set at server start, before any box is planned.
*/
useInstallLog(paths: BoxInstallLogPaths | null): void {
this.installLog = paths;
}
/** Logs go here from now on (the server's logger, once it exists). */
useLog(log: BoxLog): void {
this.log = log;
}
get snapshotsDir(): string {
return boxSnapshotsDir(this.options.stateDir);
}
serverDefault(): ServerBoxDefault {
return serverDefault(this.options.stateDir);
}
/** The server's `required` for this device (box-server.json), its fallback and prefetch. */
required(): ReturnType<typeof serverRequired> {
return serverRequired(this.options.stateDir);
}
/**
* The backend detection's inputs: the setting (or OMNIRUSH_BOX_BACKEND) and the server's allowlist.
* While the sandbox is required, a saved "native" reads as automatic (OMNIRUSH_BOX_BACKEND=native still counts).
*/
private detectOptions(): Pick<DetectOptions, "asked" | "allow" | "preferShadows" | "required"> {
const asked = askedBackend({ env: this.env, stateDir: this.options.stateDir });
const required = this.required().required;
const backend = asked.source === "setting" && asked.backend === "native" && required ? "auto" : asked.backend;
// Under required on macOS / Windows the backends that give the box its own build folders (shadows) come first.
return { asked: backend, allow: serverBackends(this.options.stateDir), ...(required && shadowsApply(this.platform, this.env) ? { preferShadows: true } : {}), ...(required ? { required: true } : {}) };
}
private detect(extra: DetectOptions = {}): Promise<RuntimeResult> {
return detectRuntime({ boxHome: this.home, env: this.env, ...this.detectOptions(), ...extra });
}
/** The Claude provider's box bits (opencode-plugins/claude-provider): the box home and the box shell; null without the shell helper. */
claudeBits(): { home: string; shell: string } | null {
try {
return { home: this.home, shell: installShell(this.home, { env: this.env }) };
} catch {
return null;
}
}
/**
* Save the machine's backend ("auto", one backend id, "native"). Projects
* are planned again with it (a running box keeps going until its project
* is planned again). Throws for an unknown value.
*/
async setBackend(value: unknown): Promise<string> {
if (value === "native" && this.required().required) throw new BoxRequiredError();
const saved = saveBackend(this.options.stateDir, value);
this.alternatives = null;
const now = await this.detect({ fresh: true });
const chosen = now.ok ? now.backend ?? now.name : null;
for (const project of this.projects.values()) {
if (project.run && project.run.backend === chosen) continue;
this.dropRun(project);
project.notice = null;
project.nextPlanAt = 0;
}
await this.writeProjects();
void this.ensureAll();
return saved;
}
/**
* The server's backends allowlist changed (box-server.json): a project whose box runs on a
* backend it no longer allows is planned again (its chats go on natively until then).
*/
async serverBackendsChanged(): Promise<void> {
const allow = serverBackends(this.options.stateDir);
this.alternatives = null;
// A plan in flight (started with the old allowlist) settles first.
await Promise.allSettled([...this.projects.values()].map((project) => project.planning));
for (const project of this.projects.values()) {
if (!project.run || !allow || allow.includes(project.run.backend)) continue;
this.dropRun(project);
project.notice = null;
project.nextPlanAt = 0;
}
await this.writeProjects();
}
private async mode(workspace: BoxWorkspace) {
const settings = await this.options.readSettings(workspace.id).catch(() => ({ mode: null, offered: false }));
const server = this.serverDefault();
const { required } = this.required();
// A buildathon project (the app lists them): the event's `repro.box` comes before the server's default.
const buildathon = workspace.workspaceType === "local" ? this.buildathonBox(boxRoot(workspace)) : null;
const resolved = resolveMode({ env: this.env, project: settings.mode, server, offered: settings.offered, buildathon, required });
// Required: the folder's builds no longer keep it here (the box keeps its own copies); a project that
// only builds on this OS (an Xcode project, a WPF app) does.
if (resolved.source === "required") {
const hostOnly = workspace.workspaceType === "local" ? this.hostOnly(boxRoot(workspace)) : null;
if (hostOnly) return { settings, server, ...resolved, on: false, source: "host-only" as const, hostBuilds: null, hostOnly };
return { settings, server, ...resolved, hostBuilds: null, hostOnly: null };
}
const gate = workspace.workspaceType === "local" ? this.hostGate(boxRoot(workspace), resolved) : null;
// A box already running for the project keeps its chats (builds made since do not move them out).
const running = this.projects.get(boxKey(boxRoot(workspace)))?.run;
if (gate?.native && !(running && !running.native)) return { settings, server, ...resolved, on: false, source: "host-builds" as const, offer: false, hostBuilds: gate, hostOnly: null };
return { settings, server, ...resolved, hostBuilds: gate, hostOnly: null };
}
private hostOnly(root: string): { things: string[]; notice: string } | null {
try {
return hostOnlyProject(root, { platform: this.platform });
} catch {
return null;
}
}
/**
* macOS / Windows: a project folder with this computer's builds (node_modules,
* a venv, Mach-O / PE programs; host-builds.ts). Only the server's default
* putting it in the box: its chats stay here (`native`); the user's own
* choice (the project's switch, OMNIRUSH_BOX=1): in the box, with a warning.
* Null on Linux, with the box off, or when the folder has none.
* OMNIRUSH_BOX_KEEP_NATIVE=off or OMNIRUSH_BOX_HOST_BUILDS=off skips it.
*/
private buildathonBox(root: string): "on" | "offer" | "off" | null {
try {
return buildathonBoxFor(root, buildathonProjectsFile(this.home));
} catch {
return null;
}
}
private hostGate(root: string, mode: { on: boolean; source: string }): { native: boolean; things: string; notice: string } | null {
if (!mode.on || !hostRules(this.platform)) return null;
if (String(this.env.OMNIRUSH_BOX_KEEP_NATIVE ?? "").trim().toLowerCase() === "off") return null;
let found;
try {
found = hostBuilds(root, { platform: this.platform, stateDir: this.options.stateDir, env: this.env });
} catch (error) {
this.log("warn", "host builds check failed", { error: error instanceof Error ? error.message : String(error) });
return null;
}
if (!found.found) return null;
// Only a default (the server's, or the buildathon's) keeps the folder here; the user's own choice does not.
const native = mode.source === "server" || mode.source === "buildathon";
return { native, things: hostBuildThings(found), notice: hostBuildsNotice(native ? "native" : "explicit", { platform: this.platform, result: found }) };
}
/**
* The engine config additions (`shell` and the plugin), or null: only when
* some local workspace has its box on or the server's default is on or
* offer, and the helpers for this machine are installed.
*/
async engineBits(): Promise<{ shell: string; plugin: string } | null> {
let wanted = this.serverDefault() !== "off" || this.required().required || ["1", "on", "true"].includes(String(this.env.OMNIRUSH_BOX ?? "").trim().toLowerCase());
// A chat that started in the box keeps it after its project's box was turned off.
wanted ||= [...this.loadPins().values()].some((pin) => pin.box);
for (const workspace of this.options.workspaces()) {
if (wanted) break;
if (workspace.workspaceType !== "local") continue;
wanted = (await this.mode(workspace)).on;
}
if (!wanted) return null;
try {
return { shell: installShell(this.home, { env: this.env }), plugin: this.options.pluginPath() };
} catch (error) {
this.log("info", "box engine bits unavailable", { error: error instanceof Error ? error.message : String(error) });
return null;
}
}
/**
* The project's run when its box is on and can start (planned once, in
* the background; a downloading image is looked at again later), else null.
*/
ensure(workspace: BoxWorkspace, { keep = false }: { keep?: boolean } = {}): Promise<BoxRun | null> {
if (workspace.workspaceType !== "local") return Promise.resolve(null);
const root = boxRoot(workspace);
const key = boxKey(root);
const project = this.projects.get(key) ?? { run: null, notice: null, planning: null, nextPlanAt: 0, waitingImage: false };
this.projects.set(key, project);
if (project.planning) return project.planning;
project.planning = (async () => {
const { on, hostBuilds: gate } = await this.mode(workspace);
// `keep`: a chat that started in the box stays there after its project's box was turned off.
if (!on && !keep) {
if (gate?.native && project.notice !== gate.notice) this.log("info", "box: the server's default not applied, the folder has this computer's builds", { key, things: gate.things });
this.dropRun(project);
project.notice = gate?.native ? gate.notice : null;
await this.writeProjects();
return null;
}
if (project.run && !project.run.native) {
const box = project.run.box;
// The folder was deleted and made again (a new clone) while its box ran: the box still has the deleted
// one, where every command fails. Planned again, the box restarts on the new folder (openBox).
if (!box?.ready || !box.endpoint || !(await this.folderReplaced({ endpoint: box.endpoint, croot: box.croot }).catch(() => false))) return project.run;
this.log("info", "box folder replaced while it ran: starting it again", { key });
this.dropRun(project);
project.nextPlanAt = 0;
}
if (Date.now() < project.nextPlanAt) return null;
const plan = await planBox({ env: this.env, home: this.home, root, log: this.log, shims: shimsDir(this.env), platform: this.platform, stateDir: this.options.stateDir, ...this.detectOptions(), required: this.required().required });
project.waitingImage = !plan.box && plan.downloading === true;
project.lastRuntime = plan.box ? null : plan.runtime;
project.pull = !plan.box && plan.downloading === true && plan.image && plan.runtime?.ok ? { runtime: plan.runtime, image: plan.image } : null;
project.why = plan.box ? null
: plan.downloading === true ? { reason: "downloading" }
: plan.runtime && !plan.runtime.ok ? { reason: "no_runtime", runtime: runtimeWhy(plan.runtime) }
: { reason: "helpers_missing" };
if (!plan.box) {
this.dropRun(project);
project.notice = plan.notice;
project.nextPlanAt = Date.now() + REPLAN_MS;
await this.writeProjects();
return null;
}
project.notice = null;
project.run?.close();
project.run = boxRun(plan, {
log: this.log,
// Box ports on this computer's 127.0.0.1: only under the required sandbox.
required: this.required().required,
pkglog: this.installLog ? { root: this.installLog.root, bin: this.installLog.bin, py: this.installLog.py } : null,
tmpRoot: join(this.home, "pending"),
// boxd stopped while the app ran: started again (installs kept), or once why not and what to do.
onRevive: (event) => {
if (event.ok) {
this.log("info", "box started again after it stopped", { key, why: event.why });
if (project.notice?.startsWith("Sandbox stopped:")) project.notice = null;
} else {
project.notice = `Sandbox stopped: ${event.error}.`;
}
},
// A server in the box (its own network) at the same port on this computer's 127.0.0.1: one log line (ports.ts).
onPort: (event) => { if (event.open) this.log("info", event.line ?? `box port ${event.port} open`, { key, port: event.port }); },
onNative: (reason) => {
project.notice = `Sandbox off for now: ${reason}.`;
project.nextPlanAt = Date.now() + REPLAN_MS;
void this.writeProjects();
},
});
await this.writeProjects();
return project.run;
})().finally(() => {
project.planning = null;
});
return project.planning;
}
/** Plans every local workspace whose box is on (server start, a changed default); never throws. */
async ensureAll(): Promise<void> {
await Promise.allSettled(this.options.workspaces().map((workspace) => this.ensure(workspace)));
}
/**
* A workspace was opened, made active or added: its box is planned now, in
* the background (a missing image starts downloading, the box starts), so
* it is ready before the first prompt. Never throws.
*/
opened(workspace: BoxWorkspace): void {
if (workspace.workspaceType !== "local") return;
const project = this.projects.get(boxKey(boxRoot(workspace)));
if (project && !project.run) project.nextPlanAt = 0;
// The box starts as soon as its run exists (boxRun); a missing image starts downloading.
void this.ensure(workspace).then((run) => {
this.log("info", "box planned for an opened project", { key: boxKey(boxRoot(workspace)), box: Boolean(run && !run.native) });
}).catch(() => null);
}
/**
* The server asks for images to be fetched ahead (local_box.setup.prefetch):
* the base image, in the background, next to the stacks the open projects'
* plans download (ensureAll). Skipped on a metered connection (OMNIRUSH_BOX_METERED=1)
* and when no backend works. Whether a download started.
*/
async prefetch(): Promise<boolean> {
if (!this.required().prefetch || this.env.OMNIRUSH_BOX_METERED === "1") return false;
const runtime = await this.detect().catch(() => null);
if (!runtime?.ok) return false;
const image = imageFor("base", { env: this.env });
if (pulling(this.home, runtime, image.pull)) return false;
if (await driverFor(runtime).imagePresent(runtime, image, { home: this.home, env: this.env }).catch(() => null)) return false;
this.log("info", "box prefetch", { image: image.pull, backend: runtime.backend ?? runtime.name });
pullInBackground(runtime, image, this.home, { env: this.env, log: this.log });
return true;
}
/** The projects the plugin routes to their box: on, planned, not gone native. */
private writeProjects(): Promise<void> {
const keys = [...this.projects.entries()].filter(([, project]) => project.run && !project.run.native).map(([key]) => key).sort();
const file = join(this.home, DESKTOP_PROJECTS_FILE);
const write = async () => {
const content = `${JSON.stringify({ keys, ...(this.installLog ? { pkglog_dir: this.installLog.raw } : {}), ...(this.nativeChats.size ? { native_chats: [...this.nativeChats.keys()].sort() } : {}), updated: Date.now() })}\n`;
await mkdir(this.home, { recursive: true });
const tmp = `${file}.${process.pid}.tmp`;
await writeFile(tmp, content, { mode: 0o600 });
await rename(tmp, file);
};
this.projectsWrite = this.projectsWrite.then(write, write).catch((error) => {
this.log("warn", "box projects file not written", { error: error instanceof Error ? error.message : String(error) });
});
return this.projectsWrite;
}
/** The keys the plugin reads now (tests). */
async listedProjects(): Promise<string[]> {
await this.projectsWrite;
try {
const value = JSON.parse(await readFile(join(this.home, DESKTOP_PROJECTS_FILE), "utf8"));
return Array.isArray(value?.keys) ? value.keys : [];
} catch {
return [];
}
}
async setMode(workspace: BoxWorkspace, mode: ProjectBoxMode): Promise<BoxStatus> {
if (mode === "off" && this.required().required) throw new BoxRequiredError();
await this.options.writeSettings(workspace.id, { mode, offered: true });
const key = boxKey(boxRoot(workspace));
// Turned on by the user: the project's chats that stayed on this machine move to the box too.
if (mode === "on" && [...this.nativeChats.values()].includes(key)) {
for (const [sessionId, chatKey] of this.nativeChats) if (chatKey === key) this.nativeChats.delete(sessionId);
await this.writeProjects();
}
const project = this.projects.get(key);
if (project) project.nextPlanAt = 0;
// Planned in the background: a missing image starts downloading now.
void this.ensure(workspace).catch(() => null);
return this.status(workspace);
}
/** Whether the project's work runs in its box (the same decision as status().on, without probing the runtime). */
async sandboxOn(workspace: BoxWorkspace): Promise<boolean> {
if (workspace.workspaceType !== "local") return false;
return (await this.mode(workspace)).on;
}
async status(workspace: BoxWorkspace, { fresh = false, sessionId = null }: { fresh?: boolean; sessionId?: string | null } = {}): Promise<BoxStatus> {
const { settings, server, on, source, offer, hostBuilds: gate, lessRepro, hostOnly, required } = await this.mode(workspace);
// The server's "offer": shown once per folder (CLI: the tip, once per folder).
if (offer && workspace.workspaceType === "local") await this.options.writeSettings(workspace.id, { offered: true }).catch(() => undefined);
const root = boxRoot(workspace);
const key = boxKey(root);
const project = this.projects.get(key);
const needed = required === true;
const requiredText = needed ? { line: desktopText("required_line"), optOut: desktopText("opt_out_refused"), keptOldChat: desktopText("kept_old_chat") } : null;
const chatKept = Boolean(sessionId && this.nativeChats.has(sessionId));
// How a new chat on each model starts (the server's model_start, with its revision), and this chat's pin.
const localBox = serverLocalBox(this.options.stateDir);
const modelStart = localBox?.model_start && typeof localBox.model_start === "object" ? (localBox.model_start as BoxStatus["modelStart"]) : null;
const revision = typeof localBox?.revision === "string" ? localBox.revision : null;
const chatPin = sessionId ? this.chatPin(sessionId) : null;
const base = { mode: settings.mode, serverDefault: server, on, source, offer, error: null, hostBuilds: gate, boxNotice: null, required: needed, requiredText, hostOnly, setup: null, chatKept: chatKept || chatPin?.box === false, ports: [] as BoxStatus["ports"], modelStart, revision, chatPin };
const backendSetting = { ...askedBackend({ env: this.env, stateDir: this.options.stateDir }), choices: backendChoices() };
const setting = { value: backendSetting.backend, source: backendSetting.source, choices: backendSetting.choices };
if (workspace.workspaceType !== "local") return { ...base, on: false, offer: false, state: "off", runtime: null, backend: null, backendSetting: setting, image: null, progress: null, container: null, platform: this.platform, notice: "The sandbox is for folders on this computer." };
// The full check (every backend) on a fresh look or once a minute; the cached choice otherwise.
const { asked, allow } = this.detectOptions();
const altKey = JSON.stringify([asked, allow]);
const full = fresh || !this.alternatives || this.alternatives.key !== altKey || Date.now() - this.alternatives.at > ALTERNATIVES_MS;
const timeout = full ? 10_000 : 4_000;
const runtime = await Promise.race([
this.detect(full ? { all: true } : {}),
new Promise<RuntimeResult>((resolve) => setTimeout(() => resolve({ ok: false, reason: "the sandbox backend did not answer in time" }), timeout)),
]);
if (full && runtime.alternatives) this.alternatives = { at: Date.now(), key: altKey, list: runtime.alternatives };
const alternatives = (runtime.alternatives ?? this.alternatives?.list ?? []).map((alt) => ({ id: alt.backend, label: LABELS[alt.backend] ?? alt.backend, ok: alt.ok, reason: alt.reason ? alt.reason.split("\n")[0]!.slice(0, 300) : null }));
const runtimeView = runtime.ok
? { ok: true, name: runtime.name, flavor: runtime.flavor, version: runtime.version, reason: null }
: { ok: false, name: null, flavor: null, version: null, reason: runtime.reason };
const backendId = runtime.ok ? runtime.backend ?? runtime.name : null;
const backend: BoxBackendView = {
id: backendId,
label: backendId ? LABELS[backendId] ?? backendId : null,
version: runtime.ok ? runtime.version || null : null,
flavor: runtime.ok ? runtime.flavor || null : null,
why: runtime.ok ? runtime.why ?? null : runtime.reason,
alternatives,
allowed: allow ?? null,
};
const image = imageFor(detectStack(root), { env: this.env });
const name = containerName(key, this.env);
let present: boolean | null = null;
let container: BoxStatus["container"] = null;
if (runtime.ok) {
present = Boolean(await driverFor(runtime).imagePresent(runtime, image, { home: this.home, env: this.env }).catch(() => null));
const mine = (await listBoxes(runtime, { env: this.env, home: this.home }).catch(() => [])).find((box) => box.key === key);
container = { name, exists: Boolean(mine), running: Boolean(mine?.running) };
}
const downloading = runtime.ok && pulling(this.home, runtime, image.pull);
// The download finished: plan the project now (not at its next chat), so the card goes on to starting and ready.
if (on && runtime.ok && project?.waitingImage && !downloading && (present || container?.exists)) {
project.waitingImage = false;
project.notice = null;
project.nextPlanAt = 0;
void this.ensure(workspace).catch(() => null);
}
const marker = runtime.ok ? pullMarker(this.home, runtime, image.pull) : null;
const progress = downloading && marker && runtime.ok ? pullProgress(pullLog(marker), marker, layerSizes(runtime, image)) : null;
const record = readRecord(this.home, key);
const run = project?.run ?? null;
const state: BoxStatus["state"] = !on ? "off"
: !runtime.ok ? "unavailable"
: run && !run.native ? (run.box?.ready ? "ready" : run.box?.state === "failed" ? "failed" : "starting")
: downloading || (!present && !container?.exists) ? "downloading"
: project?.notice ? "unavailable" : "starting";
const setup = needed && on && state !== "ready" ? await this.setupFor(runtime, { fresh }) : null;
return {
...base,
state,
runtime: runtimeView,
backend,
backendSetting: setting,
image: { ref: image.pull, stack: image.stack, present, downloading },
progress,
container,
platform: this.platform,
notice: on ? project?.notice ?? (runtime.ok ? null : `Sandbox off for now: ${runtime.reason}.`)
: chatPin?.box ? PINNED_BOX_NOTE
: gate?.native ? gate.notice
: hostOnly ? hostOnly.notice
: lessRepro ? LESS_REPRO_NOTICE
: offer && source === "buildathon" ? BUILDATHON_OFFER_NOTICE
: null,
error: run?.box?.error ?? (record?.state === "off" || record?.state === "failed" ? record.error || null : null),
// The box's own build folders in use (required.json texts.desktop.shadows), else the plain macOS/Windows line.
boxNotice: on && run && !run.native && run.box?.shadows ? shadowsNotice(run.box.currentShadows(), this.platform) ?? hostBuildsNotice("box", { platform: this.platform })
: on && hostRules(this.platform) ? hostBuildsNotice("box", { platform: this.platform }) : null,
setup,
ports: run && !run.native ? (run.forwardedPorts?.() ?? []).map((port) => ({ port, url: `http://127.0.0.1:${port}`, line: portLine(port) })) : [],
};
}
/** What the sandbox needs here before it can run (the setup screen); this PC's checks are read (and cached) for it on Windows. */
async setupFor(runtime: RuntimeResult | null, { fresh = false }: { fresh?: boolean } = {}): Promise<BoxSetup & { line: string | null }> {
const checks = this.platform === "win32" && runtime && !runtime.ok ? await cachedWindowsChecks({ fresh }).catch(() => null) : null;
// macOS: the OmniRush VM picked and not made yet (it sets itself up; the panel shows its progress).
const macVm = this.platform === "darwin" && Boolean(runtime?.ok && runtime.backend === "lima" && !runtime.installed && !this.limaMade(runtime));
const setup = classifySetup({ runtime, platform: this.platform, checks, state: setupState(this.home), fallback: this.required().fallback, macVm });
// The one line (required.json texts.desktop.cannot_run) when the box cannot run here.
const why = setup.whyText ?? (runtime && !runtime.ok ? runtime.reason.split("\n")[0]!.replace(/\.$/, "") : null);
return { ...setup, line: setup.need === "cannot_run" && why ? desktopText("cannot_run", { why }) : null };
}
/** Whether the OmniRush VM was made since the (cached) probe said it was not: its LIMA_HOME has the instance. */
private limaMade(runtime: RuntimeResult): boolean {
if (!runtime.ok || runtime.backend !== "lima") return false;
try { return existsSync(join(limaHome(this.home, this.env, undefined, runtime.instance), runtime.instance ?? "omnirush-box", "lima.yaml")); } catch { return false; }
}
/**
* App start on Windows after "Set up (one restart)" (the resume marker):
* `wsl --update` when WSL asks for it, then every project is planned (the
* distro import and the image download follow). Never throws.
*/
async resumeSetup(): Promise<boolean> {
if (this.platform !== "win32" || setupState(this.home).win?.state !== "restart") return false;
// A slow `wsl --update` goes on in the background (setup.ts RESUME_UPDATE_WAIT_MS) and finishes the same way.
const ready = async (): Promise<void> => {
this.alternatives = null;
await this.detect({ fresh: true }).catch(() => null);
void this.ensureAll();
void this.prefetch().catch(() => false);
};
const resumed = await resumeWinSetup({ home: this.home, env: this.env, log: (level, message) => this.log(level, message), onReady: () => { this.log("info", "sandbox setup resume", { state: "ready" }); void ready(); } }).catch(() => null);
this.log("info", "sandbox setup resume", { state: resumed?.state ?? "failed" });
if (!resumed?.ok) return false;
await ready();
return true;
}
/**
* Try again now (the card's retry): a box that failed to start, or a
* project that went on without it, is planned again; its container and
* installs stay. The status after a fresh check.
*/
async retry(workspace: BoxWorkspace): Promise<BoxStatus> {
const project = this.projects.get(boxKey(boxRoot(workspace)));
if (project && (project.run?.native || project.run?.box?.state === "failed")) this.dropRun(project);
if (project) {
project.notice = null;
project.nextPlanAt = 0;
}
this.alternatives = null;
// A runtime started or installed meanwhile: the cached answer (a failure is kept 2 minutes) is asked again.
await Promise.race([this.detect({ fresh: true }), new Promise((resolve) => setTimeout(resolve, 10_000).unref?.())]);
await this.writeProjects();
void this.ensure(workspace).catch(() => null);
return this.status(workspace, { fresh: true });
}
/**
* One setup step (box/setup.ts), then a fresh look: a step that worked has
* the project planned again (and the images fetched ahead), so the box
* starts. Only the steps of this OS run; the others are a fresh look.
*/
async setup(workspace: BoxWorkspace, action: BoxSetupAction): Promise<BoxStatus> {
const home = this.home;
const which = this.platform === "win32" ? "win" : this.platform === "linux" ? "linux" : null;
// The admin steps (pkexec, UAC, a restart) run only where the server requires the sandbox.
if (!this.required().required && action !== "check") return this.status(workspace, { fresh: true });
if (action === "linux_allow" && this.platform === "linux") await linuxAllow({ home, env: this.env });
else if (action === "win_install" && this.platform === "win32") await windowsInstall({ home, env: this.env });
else if (action === "win_update" && this.platform === "win32") await windowsUpdate({ env: this.env });
else if (action === "win_restart" && this.platform === "win32") await windowsRestart();
else if (action === "decline" && which) saveSetupState(home, which, { state: "declined", message: "Set up later; chats run on this computer meanwhile." });
if (action === "check" && this.platform === "win32") await cachedWindowsChecks({ fresh: true }).catch(() => null);
if (action === "win_restart") return this.status(workspace);
const status = await this.retry(workspace);
if (status.setup?.need === "none") void this.prefetch().catch(() => false);
return status;
}
/** Remove the project's container (installs gone); the next chat starts a fresh one. */
async reset(workspace: BoxWorkspace): Promise<{ removed: boolean }> {
const root = boxRoot(workspace);
const key = boxKey(root);
const runtime = await this.detect();
const project = this.projects.get(key);
if (project) {
this.dropRun(project);
project.nextPlanAt = 0;
}
await this.writeProjects();
if (!runtime.ok) return { removed: false };
const result = await resetBox(runtime, root, { env: this.env, home: this.home });
void this.ensure(workspace).catch(() => null);
return { removed: result.removed };
}
/** Download the project's image now (the toggle turned on with no image here). */
async pull(workspace: BoxWorkspace): Promise<boolean> {
const runtime = await this.detect();
if (!runtime.ok) return false;
const image = imageFor(detectStack(boxRoot(workspace)), { env: this.env });
if (await driverFor(runtime).imagePresent(runtime, image, { home: this.home, env: this.env })) return false;
pullInBackground(runtime, image, this.home, { env: this.env, log: this.log });
return true;
}
private snapshotDir(sessionId: string): string {
return join(this.snapshotsDir, sessionId);
}
/**
* A prompt of `sessionId` is about to reach the engine: the turn's
* checkpoint (what the box changed since the chat's previous one) is
* taken and saved where the project archive reads it, and the chat's box
* label returned for its uploads. Null when the chat runs natively. Never
* throws; waits at most FREEZE_WAIT_MS.
*/
/**
* A prompt beforePrompt saw was not dispatched (stopped, refused before the
* engine): the chat's turn count, its in-the-box mark and turn number go back
* to what they were, so the next prompt is classified as this one was.
*/
promptCancelled(sessionId: string): void {
const before = this.uncommitted.get(sessionId);
if (!before) return;
this.uncommitted.delete(sessionId);
if (before.chatTurns === undefined) this.chatTurns.delete(sessionId);
else this.chatTurns.set(sessionId, before.chatTurns);
if (!before.boxed) this.boxedChats.delete(sessionId);
if (before.turns === undefined) this.turns.delete(sessionId);
else this.turns.set(sessionId, before.turns);
}
async beforePrompt(sessionId: string, workspace: BoxWorkspace, { capture = true, turnsBefore = 0, nativeModel = false, signal }: { capture?: boolean; turnsBefore?: number; nativeModel?: boolean; signal?: AbortSignal } = {}): Promise<BoxCaptureInfo | null> {
if (!/^[A-Za-z0-9._:-]{8,128}$/.test(sessionId)) return null;
// A chat on a model that runs only on this computer (model-modes/: Kimi) runs here, exempt from
// the required sandbox, unless it already ran in the box (a chat's model never changes).
if (nativeModel && !this.nativeChats.has(sessionId) && !this.boxedChats.has(sessionId) && !this.turns.has(sessionId) && savedTurns(this.snapshotDir(sessionId)) === 0) {
this.nativeChats.set(sessionId, boxKey(boxRoot(workspace)));
this.nativeModelChats.add(sessionId);
await this.writeProjects();
this.log("info", "box: a chat on a model that runs only on this computer stays here", { sessionId });
}
// The chat's own turn number, counted with the box on or off: a chat that ran natively
// (reopened, or its box turned on mid-chat) has its first checkpoint (turn-1) before a later
// turn; the checkpoint names it as session_turn (CLI: the same).
const turnsSoFar = this.chatTurns.get(sessionId) ?? turnsBefore;
const chatTurn = capture ? turnsSoFar + 1 : 0;
// What this prompt counts as "the chat has run": undone if it never reaches the engine (promptCancelled).
this.uncommitted.set(sessionId, { chatTurns: this.chatTurns.get(sessionId), boxed: this.boxedChats.has(sessionId), turns: this.turns.get(sessionId) });
if (capture) this.chatTurns.set(sessionId, chatTurn);
// Required: a new chat waits for its project's box (the download, the start) instead of starting here;
// a chat that already ran on this machine stays here, without waiting.
const required = workspace.workspaceType === "local" && (await this.mode(workspace).catch(() => null))?.source === "required";
const oldChat = capture && turnsSoFar > 0 && !this.boxedChats.has(sessionId) && !this.turns.has(sessionId) && savedTurns(this.snapshotDir(sessionId)) === 0;
if (required && oldChat && !this.nativeChats.has(sessionId)) {
this.nativeChats.set(sessionId, boxKey(boxRoot(workspace)));
await this.writeProjects();
this.log("info", "box: a chat that ran on this machine stays there", { sessionId, turnsBefore, required: true });
}
// One pin per chat: a chat that started in the box keeps it, whatever the project's setting says now.
const keep = this.chatPin(sessionId)?.box === true;
const run = required && !this.nativeChats.has(sessionId) ? await this.waitForBox(workspace, signal) : await this.ensure(workspace, { keep }).catch(() => null);
// The send was stopped while it waited: no checkpoint and no pin, the caller does not dispatch it, and the
// chat counts as not having run this turn (a retry waits for the box again).
if (signal?.aborted) {
this.promptCancelled(sessionId);
return null;
}
if (!run || run.native) {
await this.pin(sessionId, false);
return null;
}
// A chat with turns but no checkpoint ran on this machine (reopened, or started in this run before the
// server's default reached the app, or while the image downloaded): when only the server's default
// turned the box on, it goes on here (new chats get the box); a project turned on by its user moves it.
// One pin per chat (2026-10-24): it stays here whoever turned the box on since.
if (capture && turnsSoFar > 0 && !this.nativeChats.has(sessionId) && !this.boxedChats.has(sessionId) && !this.turns.has(sessionId) && savedTurns(this.snapshotDir(sessionId)) === 0 && !this.chatPin(sessionId)?.box) {
this.nativeChats.set(sessionId, run.key);
await this.writeProjects();
this.log("info", "box: a chat that ran on this machine stays there", { sessionId, turnsBefore });
}
if (this.nativeChats.has(sessionId) || !capture) {
await this.pin(sessionId, false);
return null;
}
this.boxedChats.add(sessionId);
await this.pin(sessionId, true);
const turn = (this.turns.get(sessionId) ?? savedTurns(this.snapshotDir(sessionId))) + 1;
const started = Date.now();
try {
const frozen = await Promise.race([
run.freeze(`turn-${turn}`, { sessionId, turn, sessionTurn: chatTurn, chain: this.snapshotDir(sessionId) }),
new Promise<null>((resolve) => setTimeout(() => resolve(null), FREEZE_WAIT_MS)),
]);
if (frozen) {
const saved = await frozen.save(this.snapshotDir(sessionId));
this.turns.set(sessionId, turn);
run.setTurn(turn);
this.log("info", "box checkpoint saved", { sessionId, turn, sessionTurn: chatTurn, changed: saved.changed, bytes: saved.bytes, ms: Date.now() - started });
}
} catch (error) {
this.log("warn", "box checkpoint failed", { sessionId, turn, error: error instanceof Error ? error.message : String(error) });
}
const label = run.label(sessionId);
const box = run.box;
if (!label || !box) return null;
return { key: run.key, root: run.root, croot: box.croot, container: box.container, runtimeBin: run.runtimeBin, runtimeArgs: run.runtimeArgs, backend: run.backend, exec: run.exec, label };
}
/**
* Required: the project's box, waited for while its image downloads (at
* most REQUIRED_WAIT_MS; planned again as soon as the download ends). Null
* when it cannot run here (no backend: the setup screen says why; the
* chat goes on per the server's required_fallback).
*/
private async waitForBox(workspace: BoxWorkspace, signal?: AbortSignal): Promise<BoxRun | null> {
const key = boxKey(boxRoot(workspace));
const startedAt = Date.now();
let lastProgressAt = startedAt;
let said = false;
for (;;) {
// A stopped send stops waiting at once (its request was given up).
if (signal?.aborted) return null;
const run = await this.ensure(workspace).catch(() => null);
if (run) return run;
const project = this.projects.get(key);
if (project?.why?.reason !== "downloading") return null;
const pull = project.pull;
const moved = pull ? pullActivityAt(this.home, pull.runtime, pull.image.pull) : null;
if (moved !== null && moved > lastProgressAt) lastProgressAt = moved;
const wait = setupWait({ startedAt, lastProgressAt, now: Date.now(), idleMs: REQUIRED_WAIT_MS, maxMs: REQUIRED_SETUP_MAX_MS });
if (wait.over) {
this.log("warn", "required sandbox wait over", { reason: wait.over, waitedMs: Date.now() - startedAt });
return null;
}
if (!said && Date.now() - startedAt >= 60_000) {
said = true;
this.log("info", "required sandbox: the prompt waits for the first setup", { maxMin: Math.round(REQUIRED_SETUP_MAX_MS / 60_000) });
}
await new Promise<void>((resolve) => {
const timer = setTimeout(done, REQUIRED_POLL_MS);
function done() {
clearTimeout(timer);
signal?.removeEventListener("abort", done);
resolve();
}
signal?.addEventListener("abort", done, { once: true });
});
if (signal?.aborted) return null;
if (pull && !pulling(this.home, pull.runtime, pull.image.pull)) project.nextPlanAt = 0;
}
}
/** The chat's box.plan outcome, once per chat and app run (null after that, or for a folder not on this computer). */
private pinFile(): string {
return join(this.options.stateDir, "chat-pins.json");
}
private loadPins(): Map<string, ChatPin> {
if (this.pins) return this.pins;
this.pins = new Map();
try {
const value: unknown = JSON.parse(readFileSync(this.pinFile(), "utf8"));
if (value && typeof value === "object") {
for (const [id, pin] of Object.entries(value)) {
if (pin && typeof pin === "object" && typeof (pin as { box?: unknown }).box === "boolean") {
const { revision, capturePolicy, verified, lateReason } = pin as { revision?: unknown; capturePolicy?: unknown; verified?: unknown; lateReason?: unknown };
this.pins.set(id, {
box: (pin as { box: boolean }).box,
revision: typeof revision === "string" ? revision : null,
...(typeof capturePolicy === "string" && capturePolicy ? { capturePolicy } : {}),
...(typeof verified === "boolean" ? { verified } : {}),
...(typeof lateReason === "string" && lateReason ? { lateReason } : {}),
});
}
}
}
} catch { /* none yet */ }
return this.pins;
}
/** A chat's pin ({ box, revision, capturePolicy? }), or null before its first prompt. Never evicted. */
chatPin(sessionId: string): ChatPin | null {
return this.loadPins().get(sessionId) ?? null;
}
/** The capture policy a chat's uploads keep: set once at its first prompt, or to the one the server's binding stored. */
async setCapturePolicy(sessionId: string, policy: string): Promise<void> {
await this.updatePin(sessionId, { capturePolicy: policy });
}
/** What the server's binding says of a chat: whether it is verified, and why it was bound late (never verified then). */
async updatePin(sessionId: string, patch: Partial<Pick<ChatPin, "capturePolicy" | "verified" | "lateReason">>): Promise<void> {
const pins = this.loadPins();
const pin = pins.get(sessionId);
if (!pin || Object.entries(patch).every(([key, value]) => pin[key as keyof ChatPin] === value)) return;
pins.set(sessionId, { ...pin, ...patch });
await writeFileAtomic(this.pinFile(), `${JSON.stringify(Object.fromEntries(pins))}\n`).catch(() => undefined);
}
private async pin(sessionId: string, box: boolean): Promise<void> {
const pins = this.loadPins();
if (pins.has(sessionId)) return;
const revision = serverLocalBox(this.options.stateDir)?.revision;
pins.set(sessionId, { box, revision: typeof revision === "string" ? revision : null });
await writeFileAtomic(this.pinFile(), `${JSON.stringify(Object.fromEntries(pins))}\n`).catch(() => undefined);
}
/**
* Why a chat pinned to the box cannot run in it now (no backend, an image
* that cannot be had), or null: it keeps the box even when its project's
* box was turned off since, and is refused only when the box truly cannot run.
*/
/**
* Farm runs (stock mode asked for at launch, stock-mode.mjs farmRun) run only in the box, which keeps them
* offline (boxd egress.go): a prompt of a workspace that cannot use it is refused, before any model call or
* upload, with the line and, while the image is still downloading, when to try again (`retryAfter`, seconds).
* Null: not a farm run, or the box is there. CLI: src/box/launch.js farmRefusal / farmGate.
*/
async farmRefusal(workspace: BoxWorkspace): Promise<FarmRefusal | null> {
const line = await this.farmRefusalLine(workspace);
if (!line) return null;
const project = this.projects.get(boxKey(boxRoot(workspace)));
if (project?.why?.reason !== "downloading") return { line };
return { line, retryAfter: Math.max(1, Math.ceil(((project.nextPlanAt || 0) - Date.now()) / 1000)) || Math.ceil(REPLAN_MS / 1000) };
}
private async farmRefusalLine(workspace: BoxWorkspace): Promise<string | null> {
if (!farmRun(this.env)) return null;
if (workspace.workspaceType !== "local") return farmLine("not a local project");
const mode = await this.mode(workspace).catch(() => null);
if (mode && !mode.on) {
if (["0", "off", "false"].includes(String(this.env.OMNIRUSH_BOX ?? "").trim().toLowerCase())) return farmLine("box off: OMNIRUSH_BOX=0");
return farmLine(mode.source === "host-only" ? "host-only project" : `box off: ${mode.source}`);
}
const run = await this.ensure(workspace).catch(() => null);
if (run && !run.native) return null;
const project = this.projects.get(boxKey(boxRoot(workspace)));
const why = project?.why;
const reason = project?.lastRuntime && !project.lastRuntime.ok ? project.lastRuntime.reason : null;
if (why?.reason === "no_runtime") return farmLine(`no backend that keeps it offline${reason ? `: ${String(reason).slice(0, 200)}` : ""}`);
if (why?.reason === "downloading") return farmLine("the sandbox image is still downloading; try again when it is done");
return farmLine(project?.notice ? String(project.notice).slice(0, 200) : "the sandbox cannot start on this computer right now");
}
async pinnedBoxUnavailable(sessionId: string, workspace: BoxWorkspace): Promise<string | null> {
if (workspace.workspaceType !== "local" || !this.chatPin(sessionId)?.box) return null;
const run = await this.ensure(workspace, { keep: true }).catch(() => null);
if (run && !run.native) return null;
const project = this.projects.get(boxKey(boxRoot(workspace)));
return project?.waitingImage ? null : project?.notice ?? "the sandbox cannot start on this computer right now";
}
async planOutcome(sessionId: string, workspace: BoxWorkspace): Promise<BoxPlanOutcome | null> {
if (workspace.workspaceType !== "local" || this.outcomeSent.has(sessionId)) return null;
this.outcomeSent.add(sessionId);
const mode = await this.mode(workspace).catch(() => null);
if (!mode) return { native: true, source: null, reason: "plan_failed" };
const { fallback } = this.required();
// Required (required.ts requiredLaunch, as the CLI's launch event): whether this machine can run the box and,
// on this machine, the fallback in force: `native` where it can't (counted in full), the server's
// required_fallback where the box was turned off (OMNIRUSH_BOX=0) or the setup declined.
const native = (reason: string, extra: Partial<BoxPlanOutcome> = {}): BoxPlanOutcome => ({ native: true, source: mode.source, reason, ...(mode.required ? requiredLaunch(reason, { native: true, serverFallback: fallback }) : {}), ...extra });
if (this.nativeChats.has(sessionId)) return this.nativeModelChats.has(sessionId) ? native("native_model", { source: "model" }) : native("kept_old_chat", { source: "chat" });
if (this.boxedChats.has(sessionId)) return { native: false, source: mode.source, reason: "box", ...(mode.required ? requiredLaunch("box", { native: false }) : {}) };
if (!mode.on) {
if (mode.required && mode.source === "env") return native("env_off");
if (mode.source === "host-only") return native("host_only");
return native(mode.source === "host-builds" ? "host_builds" : mode.offer ? "offer" : "off");
}
const project = this.projects.get(boxKey(boxRoot(workspace)));
if (project?.run?.native) return native("box_failed");
if (project?.why) {
const runtime = project.why.runtime ? { runtime: project.why.runtime } : {};
if (mode.required && project.why.reason !== "downloading") {
const setup = await this.setupFor(project.lastRuntime ?? null).catch(() => null);
// As the CLI: only a step this app can run here (Allow, the WSL setup, the VM) is setup; else it cannot run.
const fixable = setup && ["linux_allow", "win_install", "win_restart", "win_update", "mac_vm"].includes(setup.need);
const reason = !fixable || project.why.reason === "helpers_missing" ? "cannot_run" : setup.declined ? "setup_declined" : "setup_needed";
return native(reason, runtime);
}
return native(project.why.reason, runtime);
}
// Not planned yet (a plan still running, or waiting for its next try).
return native("planning");
}
/** Whether chats ran in a box during this run (they get a `final` checkpoint at quit). */
hasChats(): boolean {
return this.turns.size > 0;
}
/** At quit: every chat with checkpoints gets its `final` leaf (bounded); the sessions that got one. */
/** Let a project's box run go (no more restart requests answered for it). */
private dropRun(project: Project): void {
project.run?.close();
project.run = null;
}
/** The app quits: stop watching every project's box for restart requests. */
close(): void {
for (const project of this.projects.values()) project.run?.close();
}
async finals({ budgetMs = 20_000 }: { budgetMs?: number } = {}): Promise<string[]> {
const done: string[] = [];
const work = (async () => {
for (const sessionId of this.turns.keys()) {
const run = [...this.projects.values()].map((project) => project.run).find((candidate) => candidate?.label(sessionId));
if (!run) continue;
try {
const frozen = await run.freeze("final", { sessionId, chain: this.snapshotDir(sessionId) });
if (frozen) {
await frozen.save(this.snapshotDir(sessionId));
done.push(sessionId);
}
} catch (error) {
this.log("warn", "box final checkpoint failed", { sessionId, error: error instanceof Error ? error.message : String(error) });
}
}
})();
await Promise.race([work, new Promise((resolve) => setTimeout(resolve, budgetMs).unref?.())]);
return done;
}
}
/** A farm prompt's refusal: the line, and when to try again (seconds) for a passing reason only (the image downloading). */
export type FarmRefusal = { line: string; retryAfter?: number };
/** The one line a farm run that cannot use the box is refused with. CLI: src/box/launch.js farmLine. */
export function farmLine(why: string): string {
return `farm mode runs only in the sandbox (it keeps the session offline); this machine has no usable sandbox (${why})`;
}