humanish 0.104.3 → 0.106.0

package/dist/substrates/detached.d.ts

@@ -0,0 +1,55 @@
+import { type Shell } from "./shell.js";
+export interface DetachedTimers {
+    /** Injected clock (ms) for tests. */
+    now?: () => number;
+    /** Injected sleep for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** The clock and sleep a caller injected, without keys it left absent. */
+export declare function detachedTimersOf(options: DetachedTimers): DetachedTimers;
+export interface DetachedStepOptions extends DetachedTimers {
+    /** Short [a-z0-9-] label; names the script/status/log files under /tmp. */
+    name: string;
+    /** The shell command to run (the lab author's own command — package.json-script trust). */
+    command: string;
+    cwd?: string;
+    /** Wall-clock budget for the step. */
+    timeoutMs: number;
+    pollIntervalMs?: number;
+    requestTimeoutMs?: number;
+}
+export interface DetachedStepResult {
+    ok: boolean;
+    exitCode?: number;
+    timedOut: boolean;
+    /** Capped, UNREDACTED log tail — redact before persisting. */
+    logTail: string;
+}
+/** Read the capped log tail for a step (raw — caller redacts). */
+export declare function readDetachedLog(shell: Shell, name: string, requestTimeoutMs?: number): Promise<string>;
+/**
+ * Run a BOUNDED step (install/build) detached, polling its atomic status file until it
+ * exits or the budget runs out. On timeout the process group is killed and the log tail is
+ * still captured so failures stay diagnosable.
+ */
+export declare function runDetachedStep(shell: Shell, options: DetachedStepOptions): Promise<DetachedStepResult>;
+/**
+ * Launch a LONG-LIVED process (the subject's server) fully detached and return immediately.
+ * No status polling: liveness is the caller's readiness probe, and reclamation belongs to
+ * the sandbox lifecycle (create with kill-on-timeout).
+ */
+export declare function startDetachedProcess(shell: Shell, options: {
+    name: string;
+    command: string;
+    cwd?: string;
+    requestTimeoutMs?: number;
+}): Promise<void>;
+/**
+ * Poll a URL from INSIDE the sandbox until it answers 2xx/3xx or the budget runs out.
+ * Returns true when the subject is ready.
+ */
+export declare function probeUrl(shell: Shell, url: string, options: {
+    timeoutMs: number;
+    intervalMs?: number;
+    requestTimeoutMs?: number;
+} & DetachedTimers): Promise<boolean>;

package/dist/substrates/detached.js

@@ -0,0 +1,139 @@
+// Detached process management over a Shell, the primitive behind serving a subject app in the
+// sandbox. A foreground command hits its deadline on long-running work, so long work runs detached:
+//
+// - Scripts are written via `writeFile`, never heredocs — which eliminates the
+//   sentinel-collision bug class (a command line that equals the heredoc terminator) by
+//   construction.
+// - Bounded steps (install/build) run detached with an ATOMICALLY-written status file
+//   (write tmp + mv), polled by short foreground commands; a timeout kills the process
+//   group and surfaces a capped log tail for the caller to redact and persist.
+// - Long-lived steps (a dev/prod server) launch fully detached through `Shell.start`; the
+//   sandbox lifecycle (kill-on-timeout) owns their reclamation.
+// - Readiness is an explicit curl probe against the declared URL.
+//
+// Log tails are returned RAW; callers must pass them through redaction before persisting
+// (build output can echo env values and paths).
+import { runOrThrow, shellQuote, throwOnExit } from "./shell.js";
+const WORK_ROOT = "/tmp/humanish-subject";
+const DEFAULT_POLL_INTERVAL_MS = 3000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const LOG_TAIL_BYTES = 8192;
+const NAME_PATTERN = /^[a-z0-9-]+$/;
+/** The clock and sleep a caller injected, without keys it left absent. */
+export function detachedTimersOf(options) {
+    return {
+        ...(options.now === undefined ? {} : { now: options.now }),
+        ...(options.sleep === undefined ? {} : { sleep: options.sleep }),
+    };
+}
+function assertName(name) {
+    if (!NAME_PATTERN.test(name)) {
+        throw new Error(`Detached step name must match ${NAME_PATTERN} (got "${name}").`);
+    }
+}
+function stepDir(name) {
+    return `${WORK_ROOT}/${name}`;
+}
+// The wrapper script: runs the command from its own session (Shell.start makes the script the
+// process-group leader, so `kill -- -PID` reclaims the whole tree), logs everything, and
+// writes the exit code atomically so a poller can never read a half-written status.
+function wrapperScript(name, command, cwd) {
+    const dir = stepDir(name);
+    return [
+        "#!/bin/bash",
+        `mkdir -p ${shellQuote(dir)}`,
+        `echo $$ > ${shellQuote(`${dir}/pid`)}`,
+        cwd === undefined
+            ? ": # no cwd override"
+            : `cd ${shellQuote(cwd)} || { echo 127 > ${shellQuote(`${dir}/status.tmp`)}; mv ${shellQuote(`${dir}/status.tmp`)} ${shellQuote(`${dir}/status`)}; exit 127; }`,
+        `( ${command} ) > ${shellQuote(`${dir}/log.txt`)} 2>&1`,
+        "code=$?",
+        `echo $code > ${shellQuote(`${dir}/status.tmp`)}`,
+        `mv ${shellQuote(`${dir}/status.tmp`)} ${shellQuote(`${dir}/status`)}`,
+        "exit $code",
+        "",
+    ].join("\n");
+}
+async function writeAndLaunch(shell, name, command, cwd, requestTimeoutMs) {
+    assertName(name);
+    const dir = stepDir(name);
+    const scriptPath = `${dir}/run.sh`;
+    await runOrThrow(shell, `mkdir -p ${shellQuote(dir)}`, { requestTimeoutMs });
+    await shell.writeFile(scriptPath, wrapperScript(name, command, cwd));
+    throwOnExit(await shell.start(`bash ${shellQuote(scriptPath)}`, { requestTimeoutMs }));
+}
+/** Read the capped log tail for a step (raw — caller redacts). */
+export async function readDetachedLog(shell, name, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+    assertName(name);
+    const result = await runOrThrow(shell, `tail -c ${LOG_TAIL_BYTES} ${shellQuote(`${stepDir(name)}/log.txt`)} 2>/dev/null || true`, { requestTimeoutMs });
+    return result.stdout;
+}
+/**
+ * Run a BOUNDED step (install/build) detached, polling its atomic status file until it
+ * exits or the budget runs out. On timeout the process group is killed and the log tail is
+ * still captured so failures stay diagnosable.
+ */
+export async function runDetachedStep(shell, options) {
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const dir = stepDir(options.name);
+    await writeAndLaunch(shell, options.name, options.command, options.cwd, requestTimeoutMs);
+    const deadline = now() + options.timeoutMs;
+    for (;;) {
+        const status = await runOrThrow(shell, `cat ${shellQuote(`${dir}/status`)} 2>/dev/null || true`, {
+            requestTimeoutMs,
+        });
+        const text = status.stdout.trim();
+        if (text.length > 0) {
+            const exitCode = Number.parseInt(text, 10);
+            const logTail = await readDetachedLog(shell, options.name, requestTimeoutMs);
+            return { ok: exitCode === 0, exitCode, timedOut: false, logTail };
+        }
+        if (now() >= deadline) {
+            // Kill the whole process group (the script is its own session leader via Shell.start).
+            await shell
+                .run(`kill -- -$(cat ${shellQuote(`${dir}/pid`)} 2>/dev/null) 2>/dev/null || true`, {
+                requestTimeoutMs,
+            })
+                .catch(() => undefined);
+            const logTail = await readDetachedLog(shell, options.name, requestTimeoutMs);
+            return { ok: false, timedOut: true, logTail };
+        }
+        await sleep(pollIntervalMs);
+    }
+}
+/**
+ * Launch a LONG-LIVED process (the subject's server) fully detached and return immediately.
+ * No status polling: liveness is the caller's readiness probe, and reclamation belongs to
+ * the sandbox lifecycle (create with kill-on-timeout).
+ */
+export async function startDetachedProcess(shell, options) {
+    await writeAndLaunch(shell, options.name, options.command, options.cwd, options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+}
+/**
+ * Poll a URL from INSIDE the sandbox until it answers 2xx/3xx or the budget runs out.
+ * Returns true when the subject is ready.
+ */
+export async function probeUrl(shell, url, options) {
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const intervalMs = options.intervalMs ?? 1500;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + options.timeoutMs;
+    for (;;) {
+        const result = await shell
+            .run(`curl -sf -o /dev/null --max-time 5 ${shellQuote(url)} && echo READY || echo WAIT`, {
+            requestTimeoutMs,
+        })
+            .catch(() => ({ stdout: "WAIT" }));
+        if (result.stdout.includes("READY")) {
+            return true;
+        }
+        if (now() >= deadline) {
+            return false;
+        }
+        await sleep(intervalMs);
+    }
+}

package/dist/substrates/e2b/cdp-probe.d.ts

@@ -0,0 +1,99 @@
+/** Which target to attribute when the endpoint lists several pages. */
+export type ChromeCdpPagePreference = "pinned" | "active";
+export interface ChromeCdpProbeArgs {
+    /** Launch-time CDP port, if the launch capture caught it. */
+    cdpPort?: number;
+    /** The launched profile dir; the probe re-reads DevToolsActivePort at observe time. */
+    profileDir?: string;
+    /** The URL this lane opened; attributes the page when no target id is pinned yet. */
+    targetUrl: string;
+    /** The pinned page target id from the launch-time geometry capture. */
+    targetId?: string;
+    /**
+     * "pinned" (default): the launch-time target, for launch geometry and emulation attribution.
+     * "active": the tab the participant is driving NOW — Chrome's /json lists page
+     * targets most-recently-focused first. The state observer must follow the participant: a
+     * verification link that opens in a NEW tab left a pinned observer reading the old tab forever,
+     * so the observed URL never changed again and stopWhen/task criteria went blind (a live run's
+     * funnel read reach-dashboard 0/2 under a screenshot OF the dashboard). Final geometry follows
+     * this target too: a closed launch tab is unavailable, and a background tab may report stale
+     * layout dimensions or zero outer bounds after navigation.
+     */
+    prefer?: ChromeCdpPagePreference;
+    /**
+     * "state": url/title/text/scrollY. "geometry": outer window + CSS viewport. "port": resolution
+     * only. "emulate": apply mobile emulation (#221) to the selected page and exit (the overrides that
+     * are session-scoped, UA / touch / DPR, lapse when the socket closes). "hold": the same over a browser-level
+     * socket, then stay attached until killed (how a lane keeps them for its whole life) and attach
+     * to every page target Chrome opens later, sending it the same overrides and a reload the moment
+     * it exists, never pausing it (#623). "fidelity": read
+     * back what the page reports about itself (UA, DPR, viewport, touch), the proof for the bundle.
+     */
+    mode: "state" | "geometry" | "port" | "emulate" | "hold" | "fidelity";
+    /** For "emulate": what to apply. */
+    emulation?: ChromeMobileEmulationRequest;
+}
+/** Mobile emulation request (#221): the CDP Emulation domain applied to one page target. */
+export interface ChromeMobileEmulationRequest {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    touch: boolean;
+    userAgent: string;
+    platform?: string;
+}
+/** What the page reports after emulation: the proof, never copied from the request. */
+interface ChromeFidelityRead {
+    userAgent: string;
+    devicePixelRatio: number;
+    innerWidth: number;
+    innerHeight: number;
+    maxTouchPoints: number;
+    coarsePointer: boolean;
+}
+/** The probe's stdout, before the caller narrows it. */
+export interface ChromeCdpProbeResult {
+    unavailable?: string;
+    cdpPort?: number;
+    url?: string;
+    title?: string;
+    text?: string;
+    scrollY?: number;
+    targetId?: string;
+    browserWindow?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+    };
+    /** "emulate": the CDP methods that returned without error, in order. */
+    applied?: string[];
+    /** "fidelity": the read-back. */
+    fidelity?: ChromeFidelityRead;
+}
+/**
+ * The probe itself. Kept as one string so the shipped command is exactly what the tests execute
+ * (tests/substrates/e2b/cdp-probe.test.ts runs it under the real python3 against a real
+ * headless Chrome).
+ *
+ * WebSocket is hand-rolled because python's stdlib has no client: one masked text frame out, frames
+ * in until the reply with id 1 arrives, 1.5 s budget, and NO Origin header (Chrome refuses
+ * cross-origin DevTools sockets unless --remote-allow-origins is set; a header-less client is a
+ * local one). urllib is opened WITHOUT proxy handlers so a sandbox-wide http_proxy cannot redirect
+ * a loopback read.
+ */
+export declare const CHROME_CDP_PROBE_PY: string;
+/** The exact shell command a sandbox runs for one probe. */
+export declare function chromeCdpProbeCommand(args: ChromeCdpProbeArgs): string;
+/**
+ * Narrow one probe's stdout. A parse failure is reported as unavailable with the reason, never as
+ * an empty success: the difference between "nothing to observe" and "could not observe" is the
+ * whole point of #514.
+ */
+export declare function parseChromeCdpProbeOutput(stdout: string | undefined): ChromeCdpProbeResult;
+export {};