humanish 0.110.0 → 0.110.2

package/dist/substrates/e2b/sdk.js

@@ -5,27 +5,32 @@
 // E2BDesktopSandbox is the command, file, stream, launch and input subset the participants use; `open` is
 // optional because older SDKs lack it (the computer-use route then falls back to launch). It
 // satisfies the executor's E2BDesktopLike port (src/substrates/e2b/desktop-executor.ts) as is.
-import { sep } from "node:path";
-import { fileURLToPath } from "node:url";
 import { protectDesktopScreenshotCleanup } from "./desktop-screenshot-cleanup.js";
+import { desktopPeerAdvice, humanishInstall } from "./peer-install.js";
 export async function loadE2BDesktopModule() {
     try {
         return guardDesktopSandboxCreate((await import("@e2b/desktop")));
     }
     catch (error) {
         if (isMissingE2BDesktopDependency(error)) {
-            throw new Error(runningFromProject()
-                ? "Live E2B desktop launch requires the optional peer @e2b/desktop. Install it beside humanish " +
-                    "in this project: `npm i -D @e2b/desktop`."
-                : "Live E2B desktop launch requires the optional peer @e2b/desktop, and humanish is running from an " +
-                    "npx cache. Node resolves the peer relative to humanish itself, so a copy installed in this project " +
-                    "is not found. Install both into the project and run it from there: " +
-                    "`npm i -D humanish @e2b/desktop` then `npx humanish run <study>`.");
+            const { where, advice } = desktopPeerAdvice(humanishInstall());
+            throw new Error(`Live E2B desktop launch requires the optional peer @e2b/desktop${where}. ${advice}`);
         }
         throw error;
     }
 }
 export const DESKTOP_CREATE_CLEANUP_TIMEOUT_MS = 10_000;
+const allocationObservers = new WeakMap();
+/**
+ * Call `observer` with the sandbox id as soon as the guarded SDK constructs the handle for a
+ * create made with this exact options object, before desktop startup runs. Startup can take
+ * seconds after E2B created the sandbox; this is the earliest point the id exists in this process.
+ * A module without the guard (a test fake) never calls it, and create's own result still reports
+ * the id.
+ */
+export function observeDesktopAllocation(options, observer) {
+    allocationObservers.set(options, observer);
+}
 /** Startup failed after this call acquired a handle. No credentials/options are included here. */
 export class E2BDesktopStartupError extends Error {
     cleanup;
@@ -67,6 +72,7 @@ export function guardDesktopSandboxCreate(module) {
                 : DESKTOP_CREATE_CLEANUP_TIMEOUT_MS;
             let cleanupOwned;
             let restoreKill;
+            const observeAllocation = createOptions === undefined ? undefined : allocationObservers.get(createOptions);
             // oxlint-disable-next-line typescript/no-this-alias -- the attempt subclasses whichever SDK class was called
             const CallingSandbox = this;
             class AttemptSandbox extends CallingSandbox {
@@ -91,6 +97,12 @@ export function guardDesktopSandboxCreate(module) {
                         else
                             Reflect.deleteProperty(this, "kill");
                     };
+                    try {
+                        observeAllocation?.(this.sandboxId);
+                    }
+                    catch {
+                        // An observer that throws must not fail the create; the resolved handle reports the id.
+                    }
                 }
             }
             try {
@@ -144,18 +156,6 @@ async function reclaimFailedDesktopCreate(kill, timeoutMs) {
             clearTimeout(timer);
     }
 }
-/**
- * Is humanish running from this project's node_modules, or from an npx cache?
- *
- * It decides which advice is true. `npx humanish@latest` resolves its optional peer relative to
- * itself, so "install @e2b/desktop in this project" is advice that cannot work there, and that
- * message cost two cold verification runs before the difference was noticed. A one-shot npx
- * invocation cannot do a live desktop run at all; humanish has to be installed alongside the peer.
- */
-function runningFromProject() {
-    const here = fileURLToPath(import.meta.url);
-    return here.startsWith(`${process.cwd()}${sep}node_modules${sep}`);
-}
 function isMissingE2BDesktopDependency(error) {
     const value = error;
     return value.code === "ERR_MODULE_NOT_FOUND" && value.message?.includes("@e2b/desktop") === true;

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

@@ -9,6 +9,7 @@ import { ownDesktopAllocation, } from "../desktop-session.js";
 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";
 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);
@@ -18,12 +19,12 @@ function checkDesktopOptions(options) {
     if (options.media !== undefined) {
         guestMediaConfigSchema.parse(options.media);
         if (options.assets.media !== true)
-            throw new Error("This local runtime does not include media. Run humanish runtime setup --media.");
+            throw new Error(`This local runtime does not include media. Run ${cli("runtime setup --media")}.`);
     }
     if (options.recording !== undefined) {
         desktopRecordingConfigSchema.parse(options.recording);
         if (options.assets.media !== true)
-            throw new Error("This runtime does not include the recorder. Run humanish runtime setup --media.");
+            throw new Error(`This runtime does not include the recorder. Run ${cli("runtime setup --media")}.`);
     }
     let url;
     try {

package/dist/substrates/local/runtime-host.js

@@ -3,6 +3,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { cli } from "../../cli/invocation.js";
 const exec = promisify(execFile);
 export const LIMA_INSTANCE = "humanish-runtime";
 export const usesLima = (options = {}) => (options.platform ?? process.platform) === "darwin";
@@ -86,11 +87,11 @@ export async function limaStatus(options = {}) {
         version = (await hostExec("limactl", ["--version"], options)).stdout;
     }
     catch {
-        throw new Error("Install Lima 2.2 or newer (brew install lima), then run humanish runtime setup. Docker Desktop is not required.");
+        throw new Error(`Install Lima 2.2 or newer (brew install lima), then run ${cli("runtime setup")}. Docker Desktop is not required.`);
     }
     const match = /\b(\d+)\.(\d+)\.\d+/.exec(version);
     if (!match || Number(match[1]) < 2 || (Number(match[1]) === 2 && Number(match[2]) < 2))
-        throw new Error("Update Lima to 2.2 or newer (brew upgrade lima), then run humanish runtime setup.");
+        throw new Error(`Update Lima to 2.2 or newer (brew upgrade lima), then run ${cli("runtime setup")}.`);
     const output = (await hostExec("limactl", ["list", "--json"], options)).stdout.trim();
     const instance = output
         .split("\n")
@@ -104,8 +105,8 @@ export async function limaStatus(options = {}) {
         ready: instance?.status === "Running",
         exists: !!instance,
         message: instance
-            ? "The humanish Lima host is stopped. Run humanish runtime setup to start it."
-            : "Run humanish runtime setup to create the humanish Lima host and install the browser runtime.",
+            ? `The humanish Lima host is stopped. Run ${cli("runtime setup")} to start it.`
+            : `Run ${cli("runtime setup")} to create the humanish Lima host and install the browser runtime.`,
     };
 }
 export async function prepareLima(options = {}, progress) {

package/dist/substrates/local/runtime.js

@@ -7,6 +7,7 @@ import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { LOCAL_MEDIA_RUNTIME_RELEASES, LOCAL_RUNTIME_RELEASES } from "./runtime-release.js";
 import { limaStatus, loadRuntimeArchive, prepareLima, runtimeArchitecture, runtimeDocker, runtimeExec, usesLima, } from "./runtime-host.js";
+import { cli } from "../../cli/invocation.js";
 const docker = async (args, options) => (await runtimeDocker(args, options)).stdout.trim();
 const runtimeRelease = (options) => options.release ??
     (options.media ? LOCAL_MEDIA_RUNTIME_RELEASES : LOCAL_RUNTIME_RELEASES)[runtimeArchitecture(options) ?? "amd64"];
@@ -80,7 +81,7 @@ export async function localRuntimeStatus(options = {}) {
             installed: false,
             message: lima
                 ? "Docker is unavailable inside the humanish Lima host. Check limactl shell humanish-runtime -- sudo systemctl status docker; Docker Desktop is not used."
-                : "Docker is unavailable. Install/start Docker Engine and give your account access, then run humanish runtime setup.",
+                : `Docker is unavailable. Install/start Docker Engine and give your account access, then run ${cli("runtime setup")}.`,
         };
     }
     const release = runtimeRelease(options);
@@ -108,7 +109,7 @@ export async function localRuntimeStatus(options = {}) {
             : {
                 ok: true,
                 installed: false,
-                message: "Local runtime will download before the first live run. Run humanish runtime setup to prepare it now.",
+                message: `Local runtime will download before the first live run. Run ${cli("runtime setup")} to prepare it now.`,
             };
     }
     const image = images[0];
@@ -161,7 +162,7 @@ export async function prepareLocalRuntime(options = {}) {
     try {
         const response = await fetch(release.url, { signal });
         if (!response.ok || !response.body)
-            throw new Error(`Runtime download failed (HTTP ${response.status}). Run humanish runtime setup to retry.`);
+            throw new Error(`Runtime download failed (HTTP ${response.status}). Run ${cli("runtime setup")} to retry.`);
         let bytes = 0;
         const hash = createHash("sha256");
         await pipeline(Readable.fromWeb(response.body), new Transform({
@@ -181,7 +182,7 @@ export async function prepareLocalRuntime(options = {}) {
         await loadRuntimeArchive(archive, { ...options, signal });
         const after = await localRuntimeStatus(options);
         if (!after.assets)
-            throw new Error("Downloaded runtime did not provide the expected image. Run humanish runtime setup to retry.");
+            throw new Error(`Downloaded runtime did not provide the expected image. Run ${cli("runtime setup")} to retry.`);
         return after.assets;
     }
     finally {

package/dist/substrates/shell.d.ts

@@ -39,6 +39,8 @@ export declare function runOrThrow(shell: Shell, command: string, options?: Shel
 export declare function throwOnExit(result: ShellResult): ShellResult;
 /** Single-quote a value for a Shell command line. */
 export declare function shellQuote(value: string): string;
+/** A command-line argument, single-quoted only when the shell would split or expand it. */
+export declare function shellArg(value: string): string;
 /** Sanitized, whitespace-collapsed, length-capped tail of command output. */
 export declare function tailOf(value: string | undefined): string;
 export {};

package/dist/substrates/shell.js

@@ -16,6 +16,10 @@ export function throwOnExit(result) {
 export function shellQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
+/** A command-line argument, single-quoted only when the shell would split or expand it. */
+export function shellArg(value) {
+    return /^[\w@%+=:,./-]+$/.test(value) ? value : shellQuote(value);
+}
 /** Sanitized, whitespace-collapsed, length-capped tail of command output. */
 export function tailOf(value) {
     return (value ?? "").trim().replace(/\s+/g, " ").slice(-240);

package/dist/tui/contract.js

@@ -12,6 +12,7 @@
 //
 // It also makes the UI testable without a terminal: a test hands `startTui` a fake index and reads
 // the frames back.
+import { cli } from "../cli/invocation.js";
 /** Node version the Ink runtime requires (ink@7 declares `engines.node >= 22`). */
 export const TUI_MIN_NODE_MAJOR = 22;
 /**
@@ -41,12 +42,12 @@ export const TUI_BUNDLE_URL = new URL("../tui-app.js", import.meta.url);
  */
 export function terminalSurfaceMessage(state) {
     if (!state.supported) {
-        return `\`humanish tui\` needs Node ${TUI_MIN_NODE_MAJOR}+ (this is ${state.nodeVersion}); every other command works here`;
+        return `\`${cli("tui")}\` needs Node ${TUI_MIN_NODE_MAJOR}+ (this is ${state.nodeVersion}); every other command works here`;
     }
     if (!state.bundlePresent) {
-        return "`humanish tui` is not built in this checkout; run `pnpm build` (installed packages ship it prebuilt)";
+        return `\`${cli("tui")}\` is not built in this checkout; run \`pnpm build\` (installed packages ship it prebuilt)`;
     }
     return state.interactive
-        ? "`humanish tui` opens the interactive surface for browsing studies and runs"
-        : "`humanish tui` is the interactive screen a person uses to watch and start runs here. This shell is not a terminal, so pass it on to a person at one";
+        ? `\`${cli("tui")}\` opens the interactive surface for browsing studies and runs`
+        : `\`${cli("tui")}\` is the interactive screen a person uses to watch and start runs here. This shell is not a terminal, so pass it on to a person at one`;
 }